Documentation

Supported features for OpenADR 2.0a BOG and OpenADR 3.0 BOG

Overview

The OpenADR VEN provides native Niagara 4 integration with utility demand response programs through two BOG (Building Object Galleon) modules: OpenADR 2.0a BOG and OpenADR 3.0 BOG.

Both modules are pull-based Virtual End Nodes (VENs) that connect to a utility's Virtual Top Node (VTN) to receive Demand Response (DR) events and price signals. They are deployed as .bog files in the Niagara 4 Workbench.

Choose the version that matches your utility's OpenADR standard — 2.0a for legacy systems using XML/SIMPLE profile, or 3.0 for modern REST-based systems using OAuth 2.0 and JSON.

OpenADR 2.0a BOG

2.0a

OpenADR 2.0a Simple profile VEN for Niagara 4.10+

General

Feature	Details
OpenADR Standard	2.0a — Simple profile
Architecture	Pull-based (no registration phase)
Distribution Format	.bog file for Niagara 4
Platform	Niagara 4.10+

Transport & Authentication

Feature	Details
Protocol	HTTP POST (no XMPP)
Authentication	NONE, BASIC
Content Type	XML (manual parsing, no JAXB)
Endpoint	/OpenADR2/Simple/EiEvent

Event Handling

Feature	Details
Polling	oadrRequestEvent → oadrDistributeEvent → oadrCreatedEvent
Event State Machine	PENDING → ACTIVE → COMPLETED / CANCELLED
Multi-Event Processing	Handles multiple events in a single response
Individual Response Codes	Per-event response codes (200, 450–463)
Modification Number Validation	Monotonic ordering check (E1_0392)
State Transition Validation	Prevents illogical transitions (E1_0384)
Inconsistent Event Detection	Detects disappeared-and-reappeared events (E1_0370)

Targeting & Filtering

Feature	Details
venID Targeting	✅
resourceID Targeting	✅
groupID Targeting	✅
partyID Targeting	✅
Market Context Filtering	Optional matching (E1_0285)
VTN ID Validation	Optional, returns error 452 on mismatch (E1_0390)

Timing & Randomization

Feature	Details
Randomization Offsets	x-oadrStartAfter / x-oadrStopAfter
Adjacent Event Detection	Back-to-back event awareness (E1_0292)

Opt-Out

Feature	Details
Async Opt-Out	Supports optOut after initial optIn (E1_0280)

Licensing & Security

Feature	Details
License Type	RSA-SHA256 signed license per Host ID
Trial Period	2 hours per station restart (no license required)
License Duration	Perpetual

OpenADR 3.0 BOG

3.0

OpenADR 3.0 VEN for Niagara 4.13+

General

Feature	Details
OpenADR Standard	3.0 (IETF RFC)
Architecture	Pull-based (REST/JSON)
Distribution Format	.bog file for Niagara 4
Platform	Niagara 4.13+

Transport & Authentication

Feature	Details
Protocol	REST/JSON HTTP (GET/POST)
Authentication	OAuth 2.0 client_credentials grant
Token Caching	In-memory token cache with pre-emptive refresh (30s skew)
401 Retry	Retries once on 401 before failing
Public VTN Mode	No-auth mode when credentials are blank

Program & Event Resolution

Feature	Details
Program Discovery	Resolves program by name (or takes first available)
Event Fetching	Paged GET with skip/limit (max 50 per page)
Target Filtering	Server-side ?targets= CSV filter
Event Selection	Selects highest-priority active event

Interval Timing

Feature	Details
dtstart / duration	ISO-8601 format
Contiguous Chaining	Back-to-back intervals when no explicit start
Infinity Sentinel	P9999Y duration support
"Now" Sentinel	Real-time interval resolution

Randomization

Feature	Details
randomizeStart	Uniform random offset within [-max, +max] window

Signal Types

Feature	Details
Primary Numeric	Main numeric payload value
Alert Payload	String-based alert signals
String Payload	Arbitrary string payloads
Sub-Interval Serial Types	PRICE, EXPORT_PRICE, GHG multi-value splitting
Payload Summary	TYPE=value;TYPE2=value2 format for all payloads

Reporting

Feature	Details
3.1.0 Reports	eventID + clientName + resource payloads

Error Handling

Feature	Details
OAuth Errors	RFC 6749 error response parsing
API Errors	Zalando problem+json format parsing

Licensing & Security

Feature	Details
License Type	RSA-SHA256 signed license per Host ID
License Duration	Perpetual

Feature Comparison

Feature	2.0a BOG	3.0 BOG
Standard	2.0a Simple	3.0
Transport	HTTP POST (XML)	REST (JSON)
Authentication	NONE / BASIC	OAuth 2.0
Architecture	Pull, no registration	Pull, OAuth2
Event Format	XML (manual parse)	JSON (manual parse)
Event Polling	oadrRequestEvent	GET with pagination
Event State Machine	PENDING→ACTIVE→COMPLETED	Interval-based timing
Multi-Event	✅	✅ (priority-based)
Target Filtering	venID/resourceID/groupID/partyID	Server-side ?targets= CSV
Market Context	✅	N/A
Randomization	Start/stop offsets	Uniform randomizeStart
Opt-Out	Async opt-out	N/A (no opt for 3.0 pull)
Reporting	❌	✅ (3.1.0 reports)
Signal Types	Simple only	Numeric, alert, string, sub-intervals
Error Format	OpenADR response codes	problem+json
Min Platform	Niagara 4.10+	Niagara 4.13+

System Requirements

OpenADR 2.0a BOG

Niagara Version: 4.10 or later
Java: Bundled with Niagara (JVM 11 compatible)
Memory: Minimal — runs within Niagara process
Network: Outbound HTTPS to VTN endpoint

OpenADR 3.0 BOG

Niagara Version: 4.13 or later
Java: Bundled with Niagara (JVM 11 compatible)
Memory: Minimal — runs within Niagara process
Network: Outbound HTTPS to VTN OAuth2 and API endpoints

Licensing

Each VEN module requires a perpetual license bound to a Host ID. Licenses are RSA-SHA256 signed and validated at runtime by the VEN module.

Free Trial

The OpenADR 2.0a BOG includes a 2-hour demo mode per station restart that requires no license — download and test immediately. The timer resets every time the Niagara station is restarted.

Purchasing

Licenses are purchased per Host ID. Volume discounts are available for enterprise deployments. After purchase, credits are added to your account which can be redeemed for license keys at any time.