# Welcome to OpenLEADR

A friendly and compliant OpenADR implementation for Python 3.

## Key Features

- Fully compliant OpenADR 2.0b implementation for both servers (Virtual Top Node) and clients (Virtual End Node)

- Fully asyncio: you set up the coroutines that can handle certain events, and they get called when needed.

- Fully pythonic: all messages are represented as simple Python dictionaries. All XML parsing and generation is done for you.

Take a Feature Tour!

## Project Status

The current version is 0.5.34.

This project is still a work in progress. Please see our Project Roadmap for information.

## License

This project is licensed under the Apache 2.0 license.

## Development and contributing

The source code of this project can be found on GitHub. Feature requests, bug reports and pull requests are most welcome and can be posted there.

## Library Installation

    $ pip install openleadr

OpenLEADR is compatible with Python 3.7 and higher.

## Getting Started

Client example:

    from openleadr import OpenADRClient
    import asyncio

    async def main():
        client = OpenADRClient(ven_name="Device001",
                               vtn_url="http://localhost:8080/OpenADR2/Simple/2.0b")
        client.add_handler('on_event', handle_event)
        await client.run()

    async def handle_event(event):
        """
        This coroutine will be called
        when there is an event to be handled.
        """
        print("There is an event!")
        print(event)
        # Do something to determine whether to Opt In or Opt Out
        return 'optIn'

    loop = asyncio.get_event_loop()
    loop.create_task(main())
    loop.run_forever()

This will connect to an OpenADR server (indicated by the vtn_url parameter), handle registration, start polling for events and reports, and will call your coroutines whenever an event or report is created for you.

## Table of Contents

- Feature Tour
  - Automatic registration
  - Automatic reporting
  - Event-driven
  - Dict-style representations
  - Message Signing for secure communications
- Client
  - Example VEN
  - Dealing with Events
  - Dealing with Reports
  - Signing outgoing messages
  - Validating incoming messages
  - A word on polling
  - Hooks
- Server
  - 1-minute VTN example
  - Registration
  - Events
  - Reports
  - Things you should implement
  - Signing Messages
  - Message Handlers
- Reporting
  - A brief overview of reports in OpenADR
  - Offering reports (VEN to VTN)
  - Requesting Reports (VTN to VEN)
  - Delivering Reports (VEN to VTN)
  - Receiving Reports (VTN)
  - Identifying a data stream
- Logging
  - Log to standard output
  - Setting the logging level
  - Redirecting logs to a different file
  - More info
- Message Signing
  - Overview
  - Generating certificates
  - Replay Protection
  - Certificate Fingerprints
- Project Roadmap
  - Upcoming releases
  - Changelog
- API Reference
  - openleadr package
- Payload Representations
  - oadrCanceledOpt
  - oadrCanceledPartyRegistration
  - oadrCanceledReport
  - oadrCanceledReport
  - oadrCancelOpt
  - oadrCancelPartyRegistration
  - oadrCancelReport
  - oadrCreatedEvent
  - oadrCreatedReport
  - oadrCreatedEvent
  - oadrCreatedPartyRegistration
  - oadrCreatedReport
  - oadrCreateOpt
  - oadrCreatePartyRegistration
  - oadrCreateReport
  - oadrDistributeEvent
  - oadrPoll
  - oadrQueryRegistration
  - oadrRegisteredReport
  - oadrRequestEvent
  - oadrRequestReregistration
  - oadrRegisterReport
  - oadrRegisterReport
  - oadrResponse
  - oadrResponse
  - oadrUpdatedReport
  - oadrUpdateReport

## Representations of OpenADR payloads

OpenLEADR uses Python dictionaries and vanilla Python types (like datetime and timedelta) to represent the OpenADR payloads. These pages serve as a reference to these representations.

For example, this XML payload:

    <?xml version="1.0" encoding="utf-8"?>
    <oadrPayload xmlns="http://openadr.org/oadr-2.0b/2012/07">
      <oadrSignedObject>
        <oadrResponse ei:schemaVersion="2.0b" xmlns:ei="http://docs.oasis-open.org/ns/energyinterop/201110">
          <ei:eiResponse>
            <ei:responseCode>200</ei:responseCode>
            <ei:responseDescription>OK</ei:responseDescription>
            <requestID xmlns="http://docs.oasis-open.org/ns/energyinterop/201110/payloads" />
          </ei:eiResponse>
          <ei:venID>o57b65be83</ei:venID>
        </oadrResponse>
      </oadrSignedObject>
    </oadrPayload>

is represented in OpenLEADR as:

    {'response': {'response_code': 200,
                  'response_description': 'OK'},
     'ven_id': 'o57b65be83'}

Read more about the representations at Payload Representations

## Indices and tables

- Index

- Module Index

- Search Page