Categories:
OpenAPI
Demand Response API
Demand Response Attributes
UPDATED
The Pelican OpenAPI allows for the scheduling and management of Demand Response (DR) events, helping optimize energy consumption across Pelican-controlled HVAC systems. Using specific API requests, you can start, modify, and cancel DR events while monitoring thermostat participation.
Predefined system-managed attributes for Thermostat objects, used for essential functions like temperature control, system status, and scheduling. They follow a fixed structure and cannot be renamed or redefined by users.
Reserved Attributes
User Defined Attributes
Custom attributes that users can create, set, and retrieve for Thermostat objects. Any attribute name that is not reserved is treated as user-defined. These attributes are created by assigning a value via a SET request and can be accessed using GET requests. There is no restriction on the number of user-defined attributes, allowing flexibility for custom data storage and retrieval.
User-defined attributes can also be used as selection criteria. For example, if a user wants to manage a specific group of thermostats via the API, they could define an attribute named “managed” and SET its value to “yes” for the thermostats in that group. Then, by including “managed:yes;” in their selection criteria, they can filter and control only those thermostats within the designated group.
Scheduling a Demand Response Event
drEvent - Request Attributes
Attribute names are not case-sensitive; attribute values are case-sensitive.
| Name | Value | Description |
|---|---|---|
| startDateTime | Date/Time | ISO 8601 formatted date and time specifying when the event should start. |
| duration | isoDuration | ISO 8601 formatted duration indicating how long the event will run (e.g., 15 minutes = PT15M, 1 hour = PT1H). |
| level | Integer |
The level of the event:
- 0 = Normal - 1 = Moderate - 2 = High - 3 = Special |
Example drEvent HTTPS Request
The following request schedules a 2-hour high-level setback event for August 1, 2022, at 3:00 PM:
https://sitename.officeclimatecontrol.net/api.cgi?username=myname@gmail.com&password=mypassword&object=Site&request=drEvent&value=startDateTime:2022-08-01T15:00;duration:PT2H;level:2;
Scheduled drEvent
- Only one Demand Response event can be scheduled at a time.
- Scheduling a new drEvent will override and delete any existing scheduled event.
- To cancel an active or scheduled Demand Response event, send a request with request=drEventCancel.
- If an event is not manually canceled, it will automatically terminate at the specified duration.
Canceling a Demand Response Event
Example drEventCancel HTTPS request:
https://sitename.officeclimatecontrol.net/api.cgi?username=myname@gmail.com&password=mypassword&object=Site&request=drEventCancel
Setting Which Thermostats Will Setback
- Through the Pelican App, site administrators can configure:
- Which thermostats participate in a Demand Response event.
- How much setback should be applied to thermostat settings based on the scheduled
drEventlevel.
- These settings cannot be modified via the API—they must be configured within the Pelican App.
Important Note: Pelican does not manage Demand Response contracts, relationships, or agreements between customers and their demand response aggregators.
- It is the responsibility of the Pelican customer and the demand response aggregator to clearly define which thermostats will participate and how they will adjust during a Demand Response event.
- Ensure that both parties agree on the setback levels and participation rules before scheduling an event.
Monitoring Thermostat Demand Response Participation
- Check Active Participation: Use the Thermostat object and check the setback attribute to see if a thermostat is actively participating in a DR event.
- Retrieve Historical DR Participation: Use ThermostatHistory to retrieve past DR events and the duration thermostats were affected.
- Analyze Pre- and Post-Event Conditions: Retrieve historical thermostat data before, during, and after an event using the ThermostatHistory attributes.