OpenADR
The OpenADR page configures GEM as an OpenADR Virtual End Node (VEN) for automated demand response. GEM connects to a utility's Virtual Top Node (VTN) server — either through a gateway device or directly — and responds to demand response events by running macros to shed or restore loads.
Open OpenADR
Tabs
The page has three tabs: Settings, Macros, and Status.
Device Selection
At the top of the page, select an existing OpenADR device or choose <New> to create one. Each device represents one OpenADR connection. Use the Delete button to remove a device.
Settings Tab
Mode
| Field | Description |
|---|---|
| Mode | Gateway (eisy / ISY) — connect through a pre-certified OpenADR gateway device. Direct VEN — connect directly to a VTN as a Virtual End Node. |
The remaining settings change based on the selected mode.
Gateway Mode Settings
| Field | Description |
|---|---|
| Gateway URL | IP or hostname of the eisy/ISY device (e.g., https://192.168.1.100). Required. |
| Username | Gateway login username. Default: admin. |
| Password | Gateway login password (stored encrypted). |
| Poll Interval | Seconds between polls to the gateway for new events. Minimum: 10. Default: 60. |
| Enabled | Toggle to enable or disable the device. |
Direct VEN Mode Settings
| Field | Description |
|---|---|
| Profile | OpenADR protocol version. 2.0a supports basic DR events only. 2.0b (default) is the full profile with opt-in/opt-out services. |
| VTN URL | Base URL of the VTN server (e.g., https://vtn.example.com). Required. |
| VEN Name | Name used to identify this VEN during registration. Default: GEM-VEN. |
| Poll Interval | Seconds between polls to the VTN for new events. Minimum: 10. Default: 60. |
| Enabled | Toggle to enable or disable the device. |
mTLS Certificates (Direct VEN Only)
Mutual TLS (mTLS) is used for secure communication with the VTN. Paste PEM-encoded certificates and keys in the text areas.
| Field | Description |
|---|---|
| Client Certificate | PEM certificate for client authentication. |
| Client Key | PEM private key matching the client certificate. |
| CA Certificate | PEM CA certificate to verify the VTN server. |
| Allow Insecure | Disables TLS certificate verification. Only use for testing. |
Enabling Allow Insecure disables all TLS verification. Never use this in production.
Click Save to persist connection settings and create the device if new.
Macros Tab
Configure which macros run in response to demand response events.
When a DR event arrives, the driver runs the macro matching the signal level. If no level-specific macro is configured, the Shed Macro runs as a fallback. When all events end, the Restore Macro runs to return to normal operation.
| Field | Description |
|---|---|
| Restore Macro | Runs when all events end — returns the building to normal operation. |
| Shed Macro | Fallback macro for any signal level without a level-specific macro. |
| Level 1 Macro | Runs for moderate / pre-event signals (signal level 1). |
| Level 2 Macro | Runs for high-priority signals (signal level 2). |
| Level 3 Macro | Runs for critical signals (signal level 3 or higher). |
Macro Context Variables
Event macros receive context variables that can be used in macro steps:
| Variable | Description |
|---|---|
event_id | The VTN event identifier |
signal_level | Current signal level (numeric) |
previous_signal_level | Previous signal level (on updates only) |
start_time | Event start time (ISO 8601) |
end_time | Event end time (ISO 8601) |
Click Save to persist macro assignments.
Status Tab
Save a device first to view status.
The status tab shows real-time connection and event information, refreshing automatically every 10 seconds.
Status Fields
| Field | Description |
|---|---|
| Mode | Gateway or Direct VEN. |
| Connection | Connected (green) or Disconnected (red). |
| Gateway | Gateway connection status (gateway mode only). |
| Event Status | Current event state: idle, active, etc. |
| VEN ID | ID assigned by the VTN during registration. |
| Registration ID | Registration identifier from the VTN. |
| Last Event ID | Most recent event ID received. |
| Last Signal Level | Signal level of the most recent event. |
| Opted Out | Whether the VEN has opted out of events. |
| Active Events | Number of currently active DR events. |
Actions
| Button | Description |
|---|---|
| Register | (Re-)register with the VTN server (direct mode only). |
| Poll Now | Immediately poll for new events. |
| Opt In | Opt in to future events. |
| Opt Out | Opt out of future events. |
| Test Shed | Manually trigger the shed macro for testing. |
| Test Restore | Manually trigger the restore macro for testing. |
| Refresh | Refresh the status display. |
How It Works
Gateway Mode
- Polling — GEM polls the gateway device at the configured interval for OpenADR event data.
- Event Processing — When an event arrives, GEM evaluates the signal level and runs the appropriate macro.
- Event End — When all active events end, the restore macro runs.
The gateway device handles VTN registration and event acknowledgment on its own.
Direct VEN Mode
- Registration — GEM registers with the VTN as a VEN, providing its profile and transport details.
- Polling — GEM polls the VTN at the configured interval for demand response events.
- Event Processing — When an event arrives, GEM evaluates the signal level and runs the appropriate macro.
- Acknowledgment — GEM acknowledges events back to the VTN. Duplicate acknowledgments for the same event version are suppressed.
- Event End — When all active events end, the restore macro runs.
Zone Attributes
If zones are assigned to the OpenADR device, the driver updates demand response attributes on each zone:
| Attribute | Description |
|---|---|
dr_active | 1 if a DR event is active, 0 otherwise |
dr_signal_level | Current signal level |
dr_event_id | Current event ID |
These attributes can be used in Triggers for additional automation logic.