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.

1. Messages from the VTN in response to requests made by the VEN node
2. 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:

1. 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)
2. 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.

Authors

Bryan Nystrom

Argonne National Laboratory