@anl-ioc/node-red-contrib-oadr-ven NPM

node-red-contrib-oadr-ven

Open ADR VEN for Node-Red

A Node-Red node that allows users to easily implement an Open OpenADR ( Open Automated Demand Response) VEN (Virtual End Node) by making communication between it and a VTN (Virtual Top Node) easier. Users only need to deal with json since the node handles converting incoming and outgoing XML messages for them. It also support communication over a secured TCP connection to the VTN.

For more information about OpenADR, please visit the OpenADR Alliance website.

Implementation

The Node-Red OADR2 VEN implementation only supports the simpleHttp transport protocol. XMPP is not supported at this time. It also only supports standard security and does not at this time support XML Signatures.

This implementation attempts to allow users to create OADR 2.0a or 2.0b compatible VEN implementations. Support for earlier OADR releases, or the upcoming 2.0c and future profiles is not supported.

All auto/default Ids (unique ids/ request ids) are generated as V4 UUIDs. Users can override this and provide their own unique ids and pass them to the commands.

In cases where a command being returned from the VTN has data that can have one or more items (an array), please keep the following in mind: The node attempts to convert incoming XML data structures into json objects. The logic behind this has no way of knowing when an XML path that supports multiple items but is only returning a single item is an array of one item. Therefore the conversion for a single item behaves as if it is not an array. When multiple items are returned however, the items are put into an array. You should always check if an item is an array or not.

Assumptions

It is not the intention of this document to explain the workings or specification of OADR and its commands. Please refer to the OpenADR profile specification documents provided by the OpenADR Alliance for details about call parameter requirements and sequences.

Supported Commands

All commands are sent to the OADR2 VEN node via msg.payload. This is done in order to support simply using an inject node for simple commands. Many of the commands support default and optional parameters.

All payloads MUST contain a requestType parameter. This is set to the actual oadr command listed below. For simplicity, the commands are given without their 'oadr' prefix. For example, to make a 2.0b specification call oadrQueryRegistraion, set msg.payload.requestType = 'QueryRegistration'.

Most of the commands let you define the requestID of the command in case you need to track the responses or later requests from the VTN. However, if no requestID is submitted with the payload, one will be auto-generated for you. Keep in mind, some commands require you to explicitly return the requestID received from another command, for example in the RegisteredReport or CreatedEvent. Also, some commands have arrays of parameters which may require additional ids.

For 2.0b setups, the OADR2 VEN node also attempts to track the venID for you upon receiving it from a CreatePartyRegistration call. There is also a configuration parameter for the node which allows you to "hard set" the venID. This is necessary for 2.0a setups, but if set will override the node's saved venID. Optionally, you can pass in the venID as a parameter with the commands.

OADR2_VEN support the following commands:

QueryRegistration
CreatePartyRegistration
CancelPartyRegistration
RequestEvent
CreatedEvent
RegisterReport
RegisteredReport
Poll
Response
CreateOpt
CancelOpt
UpdateReport

`QueryRegistration`

requestID

Example: (Set this up in a function node and pass it to the OADR2 VEN node)

msg.payload = {};
msg.payload.requestType = 'QueryRegistration';
send(msg);

Optionally, you can pass in your own requestID

msg.payload = {
    requestType: 'QueryRegistration',
    requestID: '1111-22222-3333-QR'
};
send(msg);

`CreatePartyRegistration`

requestID
oadrProfileName (currently defaults and only uses '2.0b' since this command is only supported for 2.0b implementations)
oadrReportOnly (true/false defaults to false)
oadrHttpPullModel (true/false defaults to true)
oadrTransportAddress (requires URL + port, otherwise it is taken from the config settings)

Example: Register with PUSH

msg = {};
msg.payload = {};

msg.payload = { 
    requestType: "CreatePartyRegistration",
    oadrHttpPullModel: false,
    oadrTransportAddress: 'http://192.168.1.100:8843'
};

return msg;

`CancelPartyRegistration`

requestID
registrationID
venID

`RequestEvent`

requestID
venID

Example: Request Event for 2.0a

msg = {};
msg.payload = {};
// Optionally set the venID, otherwise use what is stored in the config
let venID = '48ac6ed956e1f1f4fdbe';

msg.payload = { 
    requestType: "RequestEvent",
    venID
};

return msg;

`CreatedEvent`

Generally sent after receiving a oadrDistributeEvent from the VTN.

requestID
venID
responseCode
responseDescription
eventResponses
- responseCode
- responseDescription
- requestID
- eventID
- modificationNumber
- optType

`RegisterReport`

requestID
duration
rID
resourceID
reportType
readingType
marketContext
oadrMinPeriod
oadrMaxPeriod
oadrOnChange
reportRequestID
reportSpecifierID
reportName
createdDateTime
venID

`RegisteredReport`

requestID
responseCode
responseDescription

`Poll`

requestID
venID

example:

`Response`

requestID
responseCode
responseDescription

`CreateOpt`

requestID
optID
optType
optReason
marketContext
resourceID
components
dtstart
dtduration

Single OptOut example set to today+15 days:

msg = {};
msg.payload = {};

let d1 = new Date();
d1.setDate(15);

msg.payload = { 
    requestType: "CreateOpt",
    optType: 'optOut',
    optID: '111111111-OUT',
    optReason: 'economic',
    marketContext: 'http://MarketContext1',
    resourceID: 'XYZ',
    dtstart: d1.toISOString(),
    duration: 'PT1H15M'
};

return msg;

Multiple OptIn example for 3 days:

msg = {};
msg.payload = {};

let d1 = new Date();
let d2 = new Date();
let d3 = new Date();
d2.setDate(d1.getDate() + 1);
d3.setDate(d2.getDate() + 1);

let components = [];

let available = {
        properties: {
            dtstart: {
                'date-time': d1.toISOString()
            },
            duration: {
                duration: 'PT5M'
            }
        }
            
    };

available.properties.dtstart['date-time'] = d1.toISOString();
available.properties.duration.duration = 'PT5M';
available.properties['ei:x-eiRampUp'] = {
    duration: 'PT2M'
};
components.push(JSON.parse(JSON.stringify(available)));

available.properties.dtstart['date-time'] = d2.toISOString();
available.properties.duration.duration = 'PT10M';
available.properties['ei:x-eiRampUp'] = {
    duration: 'PT12M'
};
components.push(JSON.parse(JSON.stringify(available)));

available.properties.dtstart['date-time'] = d3.toISOString();
available.properties.duration.duration = 'PT15M';
available.properties['ei:x-eiRampUp'] = {
    duration: 'PT22M'
};
components.push(JSON.parse(JSON.stringify(available)));

msg.payload = { 
    requestType: "CreateOpt",
    optType: 'optIn',
    optReason: 'economic',
    marketContext: 'http://MarketContext1',
    components: components
};

return msg;

`CancelOpt`

requestID
optID
venID

`UpdateReport`

NOTE: Not yet fully supported

Message output from the OADR2 VEN node

There are two types of messages sent out from the VEN node.

Messages from the VTN in response to requests made by the VEN node
Requests pushed from the VTN requiring a response from the VEN.

The second type of message should only occur in cases where you set up your VEN to support PUSH from the VTN by providing a URL address into the VEN. This can be for either 2.0a or 2.0b setups.

Messages output from the OADR2 VEN generally contain two structures in the message:

msg.oadr (which contains...)
- requestID: (the request id associated with the output message)
- requestType: (the request command type, for example CreatePartyRegistrtaion)
- ResponseType: (the returned command type, for example oadrCreatedPartyREgistration)
- pollFreqSeconds: (calculated oadrRequestedOadrPollFreq in seconds. Only returned in oadrCreatedPartyRegistration commands)
msg.payload.data
- this structure contains command specific data in json format returned from the VTN. Refer to the OADR 2.0a/b Profile Specifications for parameter details.

Provided Examples

The package provides a basic example to get you going. In the node-red-contrib-openadr-ven folder is a subfolder named example-flows. The example provides a working flow along with a simple UI page on the "OADR Dash" tab. This is by no means a fully functional VEN setup but it should help illustrate how to use the node.

example flow

Authors

Bryan Nystrom

Argonne National Laboratory

node-red OpenADR VEN OADR VEN

axios body-parser data2xml debug express fast-xml-parser request uuid xml-js

@infinitebrahmanuniverse/nolb-_anl @everything-registry/sub-chunk-68 @zalastax/nolb-_anl

3 years ago

3 years ago

5 years ago

5 years ago