Python library for dealing with OpenADR
PyOpenADR is a Python 3 module that provides a convenient interface to OpenADR systems. It contains an OpenADR Client that you can use to talk to other OpenADR systems, and it contains an OpenADR Server (VTN) with convenient integration possibilities.
It's easy to hook up your own pieces of functionality while having as little to do with the OpenADR protocol and intricacies as possible. If you want, everything can be coroutine and event-based, and your coroutines will be called whenever something of interest happens.
If you want to get up to speed on how the basic OpenADR communication flows happen, please read the OpenADR Basics section.
You can use the OpenADR Client (Virtual End Node) to talk to OpenADR Virtual Top Nodes.
If you want to use the client in manual mode, you can instantiate the OpenADRClient with just a
ven_name and a
vtn_url, and then call the
create_party_registration() once, and the
poll() method repeatedly. The OpenADR client will keep track of the VTN-assigned
registration_id. The former is used for many messages, the latter is used if you wish to 'unregister' from the VTN.
poll() method will return a tuple of (message type, message payload) for you to interpret. The message payload is a dict that contains native Python types as much as possible.
The client can handle the automatic polling and call your own functions or coroutines whenever there is an event or report that your application needs to see or needs to respond to. If you want to use automatic polling, implement the
on_report handlers, and call
client.run() to start. All handlers can be implemented as regular methods or coroutines; the coroutines having the advantage of not blocking the rest of the client (polling for example).
To link your own event handler, populate the
on_event method in the OpenADRClient. This method or coroutine will be once for each event that comes in, event if these events are supplied in a single message from the VTN. You can decide what your response to each event is, by supplying the contents of the
oadrCreatedEvent message. Mostly, you will want to either Opt In or Opt Out of the event by returning the strings
"optOut". The client will perform the neccessary requests to the VTN.
To link your own report handler, implement the
on_report method in the OpenADRClient. Your method or coroutine is called once for each report, supplying the contents of the report to your function.
If you want to supply reports to the VTN on an automated basis, implement the
next_report method in the OpenADRClient. Your method or coroutine should supply the contents of the
The Virtual Top Node is the "server" that the VENs connect to. The pyopenadr server implements most of the behavior, but you have to connect it to the backend that provides the data.
Connecting to your data sources
Responding to queries
Methods dealing with events
on_created_event(payload)method is called whenever the VEN sends an
oadrCreatedEventmessage, probably informing you of what they intend to do with the event you gave them.
on_request_event(ven_id): this should return the next event (if any) that you have for the VEN. If you return
None, a blank
oadrResponsewill be returned to the VEN.
on_request_report(ven_id): this should return then next report (if any) that you have for the VEN. If you return None, a blank oadrResponse will be returned to the VEN.
on_poll(ven_id): this should return the next message in line, which is usually either a new
Methods dealing with reports
Please read the OpenADR Basics: reporting section if you are unsure of the correct message flow involved in OpenADR Reporting.
on_create_report(payload)method is called whenever the VEN sends an
oadrCreateReportmessage, requesting you to periodically generate reports for the VEN.
on_register_report(payload)method is called whenever the VEN sends an
oadrRegisterReportmessage, probably to register their reporting capabilities with you.
on_update_report(payload)method is called whenever the VEN sends an
oadrUpdateReport, probably including an actual report from the VEN.
on_registered_report(payload)method is called whenever the VEN confirms your communication of reporting capabilities.
on_created_report(payload)method is called whenever the VEN sends an
oadrCreatedReportmessage, probably informing you that they will be preparing periodic reports for you.
You have to supply your own classes for these. Each of the backends will be explained below.
Getting meta-information on connected VENs
The Server can also call methods or coroutines if a VEN comes online, or when they go offline (having missed three polling intervals, which is configurable):
OpenADR revolves around the VEN polling for messages from the VTN.
(To be added)
Reporting is probably the most complicated of interactions within OpenADR. It involves the following steps:
- Party A makes its reporting capabilities known to party B using a
- Party B responds with an
oadrRegisteredReportmessage, optionally including an
oadrReportRequestsection that tells party A which party B is interested in.
- Party A reponds with an
oadrCreatedReportmessage telling party B that it will periodically generate the reports.
This ceremony is performed once with the VTN as party A and once with the VEN as party A.
The VEN party can collect the reports it requested from the VTN using either the
oadrRequestReport mechanisms. The VTN will respond with an
oadrUpdateReport message containing the actual report. The VEN should then respond with a
The VEN should actively supply the reports to the VTN using
oadrUpdateReport messages, to which the VTN will respond with
OpenADR has a pretty flexible event modeling, which can nessecarily make things quite complex. The mechanism is pretty simple, and follows the following logic:
- The VEN asks the VTN if there are any Events for the VEN. This can be done using the
- The VTN will supply an Event to the VEN using an
- The VEN can decide whether to 'opt in' or 'opt out' of the event, which is included in the
An OpenADR Event is built up of the following properties (more or less):
- A specification of when this EVent is active, and what tolerances around the activation of the event are permissible (ActivePeriod)
- A list of Targets to which the event applies. THis can be VENs, groups, assets, geographic areas, and more.
- A list of Signals that have a name, a type and multiple Intervals that contain start dates and some payload value.
(To be added)
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
|Filename, size||File type||Python version||Upload date||Hashes|
|Filename, size pyopenadr-0.2.3.tar.gz (22.3 kB)||File type Source||Python version None||Upload date||Hashes View hashes|