OpenADR
The OpenADR page configures GEM as an OpenADR 2.0b 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
OpenADR is a premium integration. Adding an OpenADR device — and using this page — requires the OpenADR product in your license. Existing devices keep running if a license later changes. See License.
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 an OpenADR 2.0b Virtual End Node. |
The remaining settings change based on the selected mode. New devices open in Gateway (eisy / ISY) mode by default.
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 |
|---|---|
| VTN URL | Base URL of the VTN server (e.g., https://vtn.example.com). Required. GEM speaks OpenADR 2.0b against /OpenADR2/Simple/2.0b/ service paths. |
| 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. If the VTN requests a specific poll frequency during registration (oadrRequestedOadrPollFreq), GEM honors the VTN's value instead. |
| Enabled | Toggle to enable or disable the device. |
Only the OpenADR 2.0b profile is supported. Devices previously configured for 2.0a are treated as 2.0b.
TLS Client Certificates (Direct VEN Only)
This section appears only in Direct VEN mode. Mutual TLS (mTLS) secures communication with the VTN — paste PEM-encoded certificates and keys into the text areas. The client certificate and client key are stored encrypted.
| Field | Description |
|---|---|
| Client Certificate | PEM certificate for client authentication (stored encrypted). |
| Client Key | PEM private key matching the client certificate (stored encrypted). |
| CA Certificate | PEM CA certificate used 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, create the device if new, and reload it — changes take effect immediately, no restart needed.
Macros Tab
Configure which macros run in response to demand response events. Each field is a searchable picker listing every macro defined in Macros. Save the Settings tab first — the Macros tab needs a saved device.
Macros run when an event actually starts — its VTN-scheduled start time — not when the notification arrives. A day-ahead event notification is tracked as pending and sheds nothing until its start time (randomized inside the VTN-allowed window when the event specifies one). When the last active event ends, the Restore Macro runs to return to normal operation.
| Field | Description |
|---|---|
| Restore Macro | Runs when the last active event ends — returns the building to normal operation. |
| Shed Macro | Fallback macro for any signal level without a level-specific macro. |
| Level 1 Macro | Runs for signal level 1 (Moderate). |
| Level 2 Macro | Runs for signal level 2 (High). |
| Level 3 Macro | Runs for signal level 3 or higher (Special / critical). |
The signal level comes from the event's simple signal (other signals in the same event — prices, setpoints — are ignored for macro mapping), rounded to the nearest whole number. Signal level 0 means normal operations: the event is tracked and attributes update, but no shed macro runs. Events whose signal defines multiple intervals (e.g., level 1 for the first hour, level 2 for the second) re-run the matching macro at each interval boundary.
While the VEN is opted out, GEM still tracks events and updates the status and zone attributes, but it does not run the shed, level, or restore macros. Use Opt In on the Status tab to resume automatic load control. The opt state survives restarts, and in Direct VEN mode the new opt type is pushed to the VTN immediately for every in-flight event.
Macro Context Variables
Macros receive context variables you can read in macro steps. Which variables are present depends on which macro fired.
Shed / Level macros (event start, or signal-level change on an update/interval boundary):
| Variable | Description |
|---|---|
event_id | The VTN event identifier |
signal_level | Current signal level (numeric) |
previous_signal_level | Previous signal level — present only on a level change, not on the first activation |
start_time | Event start time, ISO 8601 (empty if the VTN sent no timing) |
end_time | Event end time, ISO 8601 (empty if the VTN sent no timing) |
Restore macro (last active event ended):
| Variable | Description |
|---|---|
event_id | The event whose end triggered the restore |
reason | Why it ended: completed, cancelled, or expired |
A Test Shed or Test Restore action (Status tab) runs the same macro with test set to true instead of live event data.
Click Save to persist macro assignments — they apply to the running device immediately.
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 or active. |
| 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 tracked DR events (pending + started). |
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. |
Register is shown only in Direct VEN mode; gateway devices register through the gateway itself. In Gateway mode the opt state is tracked locally by GEM.
How It Works
Gateway Mode
- Polling — GEM polls the gateway device at the configured interval for OpenADR event data.
- Event Scheduling — When an event arrives, GEM tracks it and waits for its scheduled start time; events already inside their active window (or with no timing) start immediately.
- Event Start — At start time, GEM evaluates the simple-signal level and runs the matching macro.
- Event End — An event ends when the gateway stops distributing it, the VTN marks it completed/cancelled, or its scheduled end time passes (checked about every 30 seconds). When the last active event ends, the restore macro runs. After 5 consecutive failed polls the device shows Disconnected.
The gateway device handles VTN registration and event acknowledgment on its own.
Direct VEN Mode
- Registration — GEM registers with the VTN as a 2.0b VEN (
EiRegisterParty), then registers its report metadata (an empty set — GEM does not stream telemetry reports). If registration fails at boot, GEM keeps retrying on every poll tick until the VTN is reachable. - Polling — GEM polls the VTN (
OadrPoll) at the configured interval — or at the VTN-requested frequency — for demand response events and service requests. The effective interval never drops below 5 seconds. - Event Scheduling — Distributed events are tracked as pending until their start time (randomized inside the
startafterwindow when the VTN provides one); events flaggedactiveby the VTN start immediately. - Acknowledgment — GEM acknowledges each event back to the VTN with its current opt state (
optIn/optOut), unless the event is marked response-not-required. Duplicate acknowledgments for the same event version are suppressed. - Event End — An event ends when the VTN marks it cancelled or completed, when it drops out of the event distribution, or when its scheduled end time passes (checked about every 30 seconds). When the last active event ends, the restore macro runs.
- Recovery — After 5 consecutive failed polls the device shows Disconnected; after 10 it periodically re-registers. GEM also re-registers when the VTN requests it (
oadrRequestReregistration) or cancels the registration (oadrCancelPartyRegistration), so a VTN restart recovers on its own. - Restart Survival — In-flight event state and the opt state persist as device attributes. If GEM restarts mid-event, tracking resumes; if the event ended while GEM was down, the restore macro runs on the first check after boot.
VTN-initiated report requests (oadrRegisterReport, oadrCreateReport, oadrCancelReport) are answered with well-formed empty responses. XML signatures are not supported — programs that mandate signed payloads should use a certified gateway.
Zone Attributes
Assign zones to the OpenADR device (no address is required) and GEM keeps three read-only demand-response attributes up to date on each zone — these update even while the VEN is opted out:
| Attribute | Type | Description |
|---|---|---|
dr_event_active | bool | 1 while a DR event is active, 0 otherwise |
dr_signal_level | int | Current signal level |
dr_event_id | string | Current event ID (empty when no event is active) |
Use these in Triggers to drive additional automation — for example, dim a lighting zone whenever its dr_event_active becomes 1.