Categories:
OpenAPI
Thermostat API
Demand Control Attributes
UPDATED
Pelican thermostats use a variety of inputs to determine when to initiate or end heating, cooling, or fan cycles. In certain cases, it may be desirable to prevent these cycles based on external factors, such as during real-time peak electrical demand events.
Demand management can be enabled on a per-thermostat basis and can be applied selectively to heating, cooling, or ventilation cycles. When enabled, the thermostat will request to initiate a specific cycle but will wait for external authorization before starting. Authorization can be updated at any time, even during an active cycle. Demand authorization integrates seamlessly with the thermostat’s standard sequencing logic and built-in safety protocols.
All demand control functionality is accessed through the Pelican API using the Thermostat object.
Demand Control Attributes
Attribute names are not case-sensitive; attribute values are case-sensitive.
| Name | Value | Set | Description |
|---|---|---|---|
| demandControl | Heat, Cool, Fan, Off | Y | Configures which thermostat cycles are being managed. |
| demandRequest | Heat, Cool, Fan, None | N | Indicates which cycle the thermostat is currently requesting. |
| demandAllow | Heat, Cool, Fan, None | Y | Sets the authorized cycle. |
| runStatus | Heat Request, Cool Request, Fan Request | N | In addition to the standard runStatus values defined in the Pelican Thermostat API, three additional values are used for demand management. |
Enabling Demand Management
Demand management is enabled using the demandControl attribute. If set to Off, demand management is disabled and the thermostat will not require authorization. The values: Heat, Cool, and Fan can be combined (space separated) to enable demand management for those cycles.
The following https request would enable heat and cool management for the thermostat
named Sample1:
https://sitename.officeclimatecontrol.net/api.cgi?
username=myname@gmail.com&password=mypassword&object=Thermostat&request=set&
selection=name:Sample1;&value=demandControl:Heat%20Cool;
Monitoring Demand Requests
The runStatus attribute can be monitored to determine whether a thermostat is waiting for authorization. If it is waiting for authorization the runStatus will have one of the following
values:
Heat Request – The thermostat is waiting for authorization to start a heating cycle.
Cool Request – The thermostat is waiting for authorization to start a cooling cycle.
Fan Request – The thermostat is waiting for authorization to start a fan/ventilation cycle.
The demandRequest value provides the most recent cycle requested by the thermostat.
Responding to Demand Requests
The demandAllow attribute sets the authorized cycle. For the thermostat to begin a requested cycle, the demandAllow attribute needs to be set to the same value as the demandRequest attribute.
For example, a runStatus of “Heat Request” would mean the demandRequest is “Heat” and the demandAllow is not currently set to “Heat”. The following https request would authorize the requested heat cycle:
Example demandAllow Heat for thermostat Sample1:
https://sitename.officeclimatecontrol.net/api.cgi?
username=myname@gmail.com&password=mypassword&object=Thermostat&request=set&
selection=name:Sample1;&value=demandAllow:Heat;
Design Considerations
1. Authorizations remain active until canceled or the thermostat is power cycled.
2. Changing authorization requires a real-time connection to the thermostat including an active Internet connection and connectivity through the mesh network. If connectivity is lost, the thermostat will wait until an authorization is received before it will start the desired cycle.