Skip to content

Implementing Events with the default plugin

This guide will explain the ways to receive, process and respond to events using the default plugin.

First, it is helpful to understand how OpenADR treats events. For that, please refer to the OpenADR events guide. Once you are familiar with that, it is time to implement them in Plaid.

Another useful reference will be the Event function overview in the plugin reference guide, for a description of the functionality.

Event Flow

This shows how events propagate through Plaid.

Event Flow

  1. VTN creates a new event
  2. VTN creates an oadrDistributeEvent and sends to Plaid on the next poll
  3. Plaid logs that new event is processing and posts event parameters json object (and continues to log ongoing event activities, not detailed here)
  4. Plaid plugin triggers startDistributeEvent function with all events sent by VTN
  5. Plaid responds to VTN with oadrCreatedEvent
  6. VTN acknowledges Plaid's created event with an oadrResponse
  7. Plaid plugin triggers event function for each event sent by the VTN (and cancelEvent for each cancelled event sent by VTN)
  8. Plaid plugin triggers completeDistributeEvent function
  9. When event start time comes, Plaid default plugin triggers startEvent and the the first startEventInterval functions
  10. If there are more intervals, Plaid will continue to trigger startEventInterval function when the next interval starts
  11. When the event is over, Plaid plugin triggers endEvent function

Implementing events

There are two main strategies for dealing with event execution in Plaid (assuming you are using the default plugin that ships with Plaid)

  1. Simple strategy - let Plaid handle the event scheduling, and react as start and end messages are send
  2. Get all event information as Plaid receives it from the VTN, and execute the event correctly based on your own logic

Strategy 1 is best for getting started quickly, and you may want to use some parts of it so you don't need to duplicate the scheduling logic. For production implementations, you will want to have some event information as early as possible, so you can send event notifications to users and initiate pre-event strategies such as charging batteries, pre-cooling spaces, etc.

Strategy 1 - let Plaid handle scheduling

To implement #1, all you need to implement is the startEventInterval and endEvent functions. Your system should start control when receiving the OnStartEventInterval message, and end it when receiving the OnCompleteEvent message. In this scenario, Plaid will handle complexities around scheduling, randomization, interval parsing (and corner cases, described below).

Implementing strategy 1 is the fastest way to achieve OpenADR compliance.

Strategy 2 - get all information up front and execute event

In this strategy, you get all the information about events as soon as it is received from the VTN and use your logic to execute the event.

You can either use:

  • startDistributeEvent function, which will give you information about all of the events, each time it is called.

Or

  • Event function to receive information about new and updated events individually
  • Cancel event function to know when an event is cancelled, and
  • Archive event function to know if an event is deleted

In practice, we expect #2 to become necessary. Even if you would like to rely on Plaid's OnEventStartInterval to kick off events in your system you would still want to receive the OnEvent message as early as it becomes available, so that you may notify customers that an event is coming up and/or optimize your system accordingly. We suggest the default option be #1 for simplicity at first, and as your system requirements grow you can get information up front and act accordingly.

Event modification

Event modification can be detected by comparing the event_modification_number. If the number has increased, the event was modified and should be replaced in the external system.

Event Handling Corner Cases

These corner cases are important to understand regardless of how you choose to implement. They need to be explicitly factored in to your implementation if you are implementing Strategy 2.

Event randomization

If the VTN calls for a randomization window, Plaid will pick an offset within that window and apply it to the start time. It will pass this along in the Event object as randomizedDtStartTimet. It will also pass along a randomization field, including whether the event is randomized, the randomization period in seconds, and the offset chosen by Plaid.

The corner case to watch for is that this offset applies to every part of the event. The event should end that same offset after official end time, and if the event is cancelled while it is active, control should not end right away but run for the offset period before ending control.

Zero length events

Events with a duration of 0 are active indefinitely: until either modified with a real duration, or canceled.

Implicit Event Cancellation

An explicit cancel is when an event status is changed to "cancelled" in the VTN.

An implicit cancel occurs when an event disappears from the events payload sent to the VEN (this could be because it was deleted in the VTN). Plaid will detect this case and issue an OnEventCancel (if the event is active) and then OnEventArchive.

However, if Plaid is stopped and later started, and an event that was previously in the payload disappears, Plaid will not recognize that an event had existed and then disappeared, so nothing else related to the event will be sent. If you're relying on plaid callbacks to start and end events, plaid will correctly handle this case. However, if the external system is responsible for scheduling events, in this siutation it will continue executing the event as planned even though it no longer exists in the VTN. One way to handle this is to use the StartDistributeEvent callback to match events in the payload to events in your system to catch events that were dropped. Then, if they disappear from the list of events sent by the VTN, you will be able to tell not to execute the event.

Implicitly cancelled events is a corner case that is normally not used, but your system should be aware that they can happen and handle them accordingly.

Event responses

startDistributeEvent, event and cancelEvent require a response that Plaid will use to opt in or out of the event by default. See the implementing opt guide for more information on how best to handle opting in and out of events.