OpenADR VTN Implementation

The current implementation of the OpenADR protocol used was initially developed by Battelle Memorial Institute and released under an open source license. Carbon Co-op have adapted and enhanced this software and re-released it under the same open source licence.

VTN Server Application

Details are available at https://carboncoop.gitlab.io/pyoadr-vtn/

Based on the original code, Carbon Co-op have made many improvements including:

  • Updated the code base to the newest versions of Python and Django

  • Overhauled and radically simplified the frontend UI.

  • Added PKI functionality, enabling the management of client/CA certificates for use in the OpenADR deployment.

  • Created a management API which enables the service to be easily integrated with other systems.

The deployment of the server application is complex due to the need for mutual TLS certificate checking. The VTN server is deployed from a separate repository found at: https://gitlab.com/carboncoop/vtn-deployment

  • In line with best practice TLS termination is done on a secure gateway rather than the application servers. Currently this is an nginx reverse proxy.

  • The server CA (used to sign the certificate used by the server) and the client CA (used to sign client certificates) is not the same. The server CA is a letsencrypt certificate which is baked into the image of the nginx. The client CA is a private CA generated by django-x509.

VEN Client Application

Details are available at https://carboncoop.gitlab.io/pyoadr-ven/

Based on the original code, Carbon Co-op have made many improvements including:

  • Updated the code base to Python 3

  • Made a stand alone package

  • Released the package on PyPi

The VEN client is not used on its own but as part of an integration for Home Assistant.

OpenADR Notes

These are intended as a human-readable summary of key parts of the OpenADR specification.

Reporting

An OpenADR ‘report’ is either ‘created’ or ‘cancelled’. If it is ‘created’ then the VEN is sending the data. If it is ‘cancelled’ then the data is not being sent. The terminology is confusing - it’s useful to think of these as ‘active’ and ‘inactive’.

Once a report is ‘created’, the VEN ‘updates’ the report - using the oadrUpdateReport payload.

To confuse things further, the VTN can also send reports to the VEN. But here I will refer to the thing sending data as the VEN and the thing that requests the reports as the VTN, for clarity (and to avoid the confusing ‘source/target party’ language of the spec). But it can be the other way around.

Process

When the VEN powers up, it sends a list of reports it can generate to the VTN using a oadrRegisterReport payload. Each report is uniquely identified by a ‘report specifier ID’.

Note

This list of potential reports is referred to in the spec as a ‘METADATA’ report, caps included. Why it’s capitalised is unclear - METADATA does not have to be present in any payload for it to qualify as a metadata report. It seems as if a metadata report is simply whatever is sent as part of an oadrRegisterReport payload.

The VTN acknowledges that this list was sent using an oadrRegisteredReport payload. In its response it can tell the VEN which reports it is interested in, by sending back one or more oadrReportRequest elements.

If at a later date the VTN wants to move a report to the ‘created’ state, it can send a oadrCreateReport payload, which also contains oadrReportRequest elements.

Report Requests

A ‘report request’ contains two pieces of data: the ‘report specifier’ and a ‘report request ID’.

The report specifier tells the receiver what report is being asked for. This includes:

  • the ‘report specifier ID’ (which the VEN gave the VTN above)

  • when the report should start

  • how long it should go on for (or forever)

  • how frequent reports should be

When an OpenADR report is ‘created’, it is assigned the ‘report request ID’ by the VTN. This then uniquely identifies the report to the VTN going forward. The VEN must use this when sending in data (‘updating the report’).