OpenADR 2.0b VEN

Enrols GEM as a Virtual End Node on an OpenADR 2.0b demand-response program, either directly against a utility VTN or through an on-prem gateway such as an eisy/ISY.

The driver owns the wire only — XML framing, mutual TLS, the registration ceremony and polling. Event interpretation, load curtailment, restore and history are shared with the OpenADR 3.0 driver; see the OpenADR console for everything on that side.

tip

For a new program enrolment, prefer the OpenADR 3.0 driver. Use this one for an existing 2.0b program or to talk to a gateway.

Prerequisites

• Enrolment with the utility or Energy Services Provider, which supplies the VTN URL, the VEN name, and usually a client certificate.
• Outbound HTTPS from the controller to the VTN.
• For gateway mode: an eisy/ISY on the LAN with OpenADR configured, plus its admin credentials.

Setup steps

1. System → Devices → Add Device, choose OpenADR 2.0b VEN (key openadr2).
2. Set oadr_mode — vtn for a direct connection, gateway for an eisy/ISY.
3. Direct: set vtn_url and ven_name, and paste client_cert, client_key and ca_cert if the program uses mutual TLS. Gateway: set gateway_url, gateway_username and gateway_password.
4. Configure the response on the console's Response tab: curtailable resources for kW-targeted shedding, and/or level-mapped macros.

Or add it from Integrations → OpenADR, which walks the same steps and then opens the console against the new VEN.

Attribute reference

Scope	Attribute	Direction	Notes
device	oadr_mode	optional	vtn (default) or gateway.
device	vtn_url	required in vtn mode	Base URL; GEM appends the /OpenADR2/Simple/2.0b/ service paths.
device	ven_name	optional	Name presented at registration. Default GEM-VEN.
device	ven_id	read-only	Assigned by the VTN on first registration. Do not edit.
device	registration_id	read-only	Assigned by the VTN. Do not edit.
device	client_cert / client_key	optional, secure	PEM material for mutual TLS.
device	ca_cert	optional	PEM CA chain used to verify the VTN.
device	allow_insecure	optional	Disables TLS verification. Lab VTNs only.
device	gateway_url	required in gateway mode	Full URL of the eisy/ISY, e.g. https://192.168.1.100.
device	gateway_username	optional	Default admin.
device	gateway_password	optional, secure	Gateway password.
device	poll_interval	optional	Milliseconds between polls. Default 60000, floored at 5000.
device	response_mode	optional	auto (default), resources, macro, both.
device	price_thresholds	optional	Maps a price signal onto shed levels.
device	restore_spread_ms	optional	Window over which curtailed load is returned. Default 120000.
device	telemetry_enabled	optional	Measure and report readings to the VTN. Off by default.
device	telemetry_sample_ms	optional	How often readings are taken. Default 30000, floored at 5000.
device	shed_macro_id, restore_macro_id, event_level_1..3_macro_id	optional	Level-mapped macros.
device	event_status	read-only	idle or active.
device	last_event_id, last_signal_level	read-only	Most recent event and the level in force.
device	dr_directive	read-only	Normalized reading of what the site is being asked to do.
device	opted_out	read-only	Tracking events but not acting on them.
device	dr_active_events	read-only	Persisted event and curtailment state. Managed by the driver.
zone	dr_event_active	read-only	1 while an event is active.
zone	dr_signal_level	read-only	Level in force.
zone	dr_event_id	read-only	Current event id.

Zones do not need an address — assigning one to the VEN simply gives it the DR attributes above.

Commands

Command	Description
register	Register with the VTN or gateway.
poll	Poll for events now.
opt_in / opt_out	Resume or suspend automatic load control.
test_shed / test_restore	Run the shed or restore macro directly, without an event.
get_events	Events currently tracked.
get_status	Connection, registration and event state.
get_response_status	Curtailable capacity and the current shed plan.
get_trace	Recent protocol exchanges.
get_telemetry	Streams, VTN report subscriptions and latest readings.
send_reports	Send any due telemetry reports now.

note

test_shed and test_restore only prove that a macro executes. To exercise the whole chain — scheduling, signal interpretation, resource planning, curtailment and staggered restore — use Simulate event on the console.

Signal handling

Only a level-typed signal sets a shed level. The 2.0b signalName is checked first (simple, ELECTRICITY_PRICE, LOAD_DISPATCH, LOAD_CONTROL), then signalType (level, price, priceRelative, setpoint, delta, x-loadControlCapacity).

A price or setpoint signal is a number in units that have nothing to do with shed levels, so it is recorded and displayed but never read as one. Price signals drive load only when price_thresholds is configured. Signals GEM cannot classify are shown on the event detail and never acted on.

Telemetry (EiReport)

The report exchange is a negotiation in three stages, and a VEN that registers successfully but never gets asked for data has usually stalled at stage two:

1. METADATA — after registration GEM sends oadrRegisterReport describing what it can measure, each stream with its own rID and itemBase (powerReal, energyReal).
2. Request — the VTN replies, or later sends oadrCreateReport, naming a reportSpecifierID, a granularity and a reportBackDuration. Only now does GEM know what to send and how often.
3. Update — GEM sends oadrUpdateReport on that cadence until the VTN cancels with oadrCancelReport.

A request naming no rIDs means "everything in that specifier". A request naming only streams this VEN does not publish is logged and refused rather than silently accepted — a promise of data that never arrives is worse than a refusal.

Known quirks

• 2.0b only. Devices previously configured with oadr_profile=2.0a are treated as 2.0b with a warning — the old 2.0a mode never spoke valid 2.0a.
• XML signatures are not supported. Programs that mandate signed payloads need a certified gateway in front.
• Telemetry is opt-in. With telemetry_enabled off the VEN registers an empty METADATA set, which is what tells a VTN not to ask for data it will not receive. Turn it on and the VEN offers site real power, site energy, operating state, and per-resource power for any resource declaring a measured_attribute.
• The VTN owns the report cadence. It subscribes with oadrCreateReport and names its own granularity and reportBackDuration; GEM clamps both to sane bounds (1 minute minimum granularity) but does not otherwise override them.
• poll_interval is milliseconds. Legacy values under 1000 are read as seconds. A VTN-requested poll frequency (oadrRequestedOadrPollFreq) overrides the configured value.
• ven_id and registration_id are owned by the VTN and persisted as read-only attributes. Editing them by hand breaks the registration.
• Gateway mode acknowledges events itself. GEM tracks the opt state locally in that mode and does not send oadrCreatedEvent.

Troubleshooting

Symptom	Check
Registration rejected with a non-200 responseCode	ven_name must match what the VTN expects, the certificate CN must match the registered VEN, and the VTN must speak 2.0b. The Monitor tab shows the exact rejection.
Log shows "no ven_id, attempting registration"	Registration has not completed. The driver retries on every poll; the Monitor tab shows the 4xx/5xx from the VTN.
mTLS handshake fails with self-signed certificates	Paste the VTN's CA chain into ca_cert. allow_insecure bypasses validation but should never be used in production.
Event arrives but nothing sheds	Open the event on the console — the audit trail records the reason. Common causes are a price-only event with no price_thresholds, a level-0 event, the VEN being opted out, or every resource sitting below its min_level.
Shed falls short of the requested kW	The Response tab shows available capacity against the target, and the shortfall is written to the event audit trail.
Telemetry enabled but nothing is sent	The Telemetry tab shows whether the VTN ever subscribed. An empty subscriptions table means the VTN has not sent oadrCreateReport — check the Monitor tab that the METADATA offer was accepted with a 200.
Reports rejected by the VTN	The Monitor tab holds the exact oadrUpdateReport body and the rejection. A failed send is retried rather than skipped, so the window is not lost.

Related

• OpenADR console — events, resources, monitoring and the simulator
• OpenADR 3.0 driver — the newer REST/JSON profile, same response engine