Stan Janssen 4964b2e5e3 Transitioned service to aiohttp instead of python-responder. | 4 years ago | |
---|---|---|
pyopenadr | 4 years ago | |
schema | 5 years ago | |
test | 5 years ago | |
.gitignore | 4 years ago | |
MANIFEST.in | 5 years ago | |
README.md | 5 years ago | |
openadr.md | 5 years ago | |
setup.py | 4 years ago | |
test_requirements.txt | 5 years ago |
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 ven_id
and registration_id
. The former is used for many messages, the latter is used if you wish to 'unregister' from the VTN.
The 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_event
and 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 "optIn"
or "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 oadrCreateReport
message.
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.
Methods dealing with events
on_created_event(payload)
method is called whenever the VEN sends an oadrCreatedEvent
message, 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 oadrResponse
will 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 oadrReport
or a oadrDistributeEvent
message.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 oadrCreateReport
message, requesting you to periodically generate reports for the VEN.on_register_report(payload)
method is called whenever the VEN sends an oadrRegisterReport
message, 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 oadrCreatedReport
message, 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.
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):
on_ven_online(ven_id)
on_ven_offline(ven_id)
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:
oadrRegisterReport
message.oadrRegisteredReport
message, optionally including an oadrReportRequest
section that tells party A which party B is interested in.oadrCreatedReport
message 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 oadrPoll
or oadrRequestReport
mechanisms. The VTN will respond with an oadrUpdateReport
message containing the actual report. The VEN should then respond with a oadrUpdatedReport
message.
The VEN should actively supply the reports to the VTN using oadrUpdateReport
messages, to which the VTN will respond with oadrUpdatedReport
messages.
OpenADR has a pretty flexible event modeling, which can nessecarily make things quite complex. The mechanism is pretty simple, and follows the following logic:
oadrRequestEvent
or oadrPoll
methods.oadrDistributeEvent
message.oadrCreatedEvent
message.An OpenADR Event is built up of the following properties (more or less):
(To be added)