Overview

Pelican Wireless Systems provides an open standards based real-time interface to all of the management features of their Internet Programmable Thermostats. The interface uses simple Http GET and POST commands torequest thermostat settings or change active parameters. All responses are provided using standard XMLnotation. Transactions are only allowed over Secure Socket Layer (SSL) connections using password protection. These standard protocols are easily implemented by developers on all types of computing platforms using modern scripting and programming languages.

Provided Software

Because the API uses standard protocols, there is no restriction on what type of systems or software may access the Pelican system. The client software simply establishes an SSL connection to their private web server address and initiates an http request. To further simplify access to the API, Pelican has developed a Perl module which provides an easy to use wrapper which gives Perl developers an even more simplified interface to the API. This Perl module can also be used by developers as a reference on how to construct valid requests and how to process API responses.

Constructing an API Request

Http requests are constructed with a list of named values. The Pelican API requires 6 elements in each request. These values are:

username “ This is the Email ID of a valid Pelican Site Manager user. This Email ID is created using the administrative interface of the Pelican Web App.

password “ This is the password for the Email ID specified above. Since the Pelican system only allows SSL connections, the password is automatically encrypted for each request.

request “ The value of this parameter should be either “set” or “get”. This identifies the type of request being made. “get” requests are intended to provide the current values of attributes being requested. “set” requests are intended to change the values of attributes.

object “ This is the type of object to which the “get” or “set” is being applied. The currently supported object types are: “Thermostat”, or “ThermostatSchedule”.  See the section titled “Object Attributes” for a list of attributes support by each object type.

selection “ This is a set of attribute/value pairs which should be used as a query match for the “set” or “get” request. In a “get” request, items matching the selection will be returned in the XML reply. In a “set” request, items matching the selection will be modified in the Pelican system. Pairs are separated by semicolons (;) and attributes are separated from their values by colons (:) (See example below).

value “ For “get” requests, this is a semicolon (;) separated list of attributes which are being requests. For a “set” request, this is a semicolon (;) separated list of attribute/value pairs to be modified. The attribute names are separated from their values by a colon (:). Semicolons and colons are invalid characters for either the attribute or the value.

When using HTTP GET, the 6 required elements must be formatted using standard http notation with the element name as shown above followed by an equal sign and then that elements value. The first element is preceded by a question mark (?) and the elements are separated by the ampersand (&) character. Standard http character escaping is supported. When using HTTP POST, standard encoding is supported.

The web address of the API interface is the full web address of the site followed by “/api.cgi”.  Therefore, a valid API request would be as follows:

https://demo.officeclimatecontrol.net/api.cgi?username=myname@gmail.com&password=mypassword&request=get&object=Thermostat&selection=name:TestThermostat;&value=heatSetting;coolSetting;temperature;

The API Result

The API will return a properly formatted XML version 1.0 reply. The first XML element will be named “response” and will contain a status element named “success” with a numeric result code. If an error is encountered, an element named “message” with a human readable text message will be returned with an explanation of the error. In addition, if the request type is “get” a set of elements will be returned for each item which matched the selection criteria.

Examples

The following XML reply would be returned from the HTTP request shown above:

<?xml version=”1.0″ encoding=”UTF-8″?>

<result>

<Thermostat>

<name>TestThermostat</name>

<heatSetting>68</heatSetting>

<coolSetting>72</coolSetting>

<temperature>70</temperature>

</Thermostat>

<success>1</success>

</result>

If “TestThermostat” wasn’t found by the system, the following reply would be returned:

<?xml version=”1.0″ encoding=”UTF-8″?>

<result>

<success>0</success>

<message>No thermostats found matching selection criteria.</message>

</result>

User Defined Attributes

There are two types of attributes supported for “Thermostat” objects. The first types are reserved and predefined. These attributes are defined below in the section titled “Object Attributes”. In addition to the predefined attributes users can define, set and retrieve their own attributes.

Any attribute name which is not reserved will be treated like a User Defined Attribute. Defining a new attribute is accomplished by setting its value through a set request. Once set, these attributes can be accessed using get requests. There is no restriction on the number of user defined attributes or their values. User defined attributes can also be used as part of the selection criteria. For example, if the user wants to manage a group of thermostats through the API, they could define an attribute named “managed” and set its value to “yes” for the thermostats in the user’s group. Then they could include “managed:yes;” in their selection criteria to only affect their special group of thermostats.

Object Attributes

The currently supported object types are: “Thermostat”, or “ThermostatSchedule”. Attribute names are not case sensitive. Attribute values are case sensitive.

Thermostat Object

NameValuesSetDescription
nameString
Y
The configured name of the thermostat.
groupNameString
Y
The configured group name of the thermostat.
serialNoString
N
The thermostat serial number.
systemOff, Auto, Heat, Cool
Y
The active system mode.
heatSettingInteger
Y
The active Heat Setting.
coolSettingInteger
Y
The active Cool Setting.
fanAuto, On
Y
The active Fan Mode.
statusOccupied, Vacant
Y
Normally Occupied. Vacant when vacation schedule is active.
temperatureDecimal
N
The current measured temperature.
humidityInteger
N
The current measured humidity: % RH. Zero (0) if humidity is not supported.
humidifySettingInteger
Y
The minimum humidity setting.
dehumidifySettingInteger
Y
The maximum humidity setting.
setByStation, Remote, Schedule
N
Indicates how the active thermostat settings were set.
frontKeypadOn, Off
Y
Thermostat keypad status.
runStatusOff, Cool-Stage1, Cool-Stage2, Heat-Stage1, Heat-Stage2, Fan, Fan2
N
The currently active Heating or Cooling status.
auxStatusOn, Off
N
The active Auxiliary Heat status.
slavesString
Y
List of remote temperature sensors assigned to this thermostat and their values.
descriptionString
Y
Free form description stored with configuration.
cycleRateInteger
Y
Configured target cycle rate.
anticipationDegreesDecimal
Y
Configured anticipation degrees.
calibrationOffetDecimal
Y
Configured calibration degrees.
heatStagesInteger
Y
Number of heat stages.
coolStagesInteger
Y
Number of cool stages.
fanStagesInteger
Y
Number of fan stages.
HeatNeedsFanYes, No
Y
Turn on Fan during heating.
temperatureFormatFahrenheit, Celsius
Y
Active temperature format.
systemTypeConventional, Heat Pump
Y
Active system type.
reversingValveString
Y
One of: Heat or Cool. Energizes reversing valve in this mode. Only valid for systemType of Heat Pump.
minHeatSettingInteger
Y
Lowest user settable heat setting.
maxHeatSettingInteger
Y
Highest user settable heat setting.
minCoolSettingInteger
Y
Lowest user settable cool setting.
maxCoolSettingInteger
Y
Highest user settable cool setting.
fanCirculationTimeInteger
Y
Minutes/hour to circulate the fan.
heatingTypeString
Y
Size of heating system.
heating2TypeString
Y
Size of second stage heating system.
heatingAuxTypeString
Y
Size of auxiliary heating system.
coolingTypeString
Y
Size of cooling system.
cooling2TypeString
Y
Size of second stage cooling system.
humidityControlString
Y
One of: None, Humidify, Dehumidify, Full Control Cool, Only.
minSafeHumidityInteger
Y
Lowest allowed humidity before notification is sent.
maxSafeHumidityInteger
Y
Highest allowed humidity before notification is sent.
allowKeypadDisableYes, No
Y
Display keypad On/Off button.
weightInteger
Y
Weighted value when used with Remote Sensors
notificationSensitivityInteger
Y
One of: Off, Low, Medium, High, Custom. Note: When setting Custom notificationSetpoint and notificationUnreachable should also be set.
notificationSetpointInteger
Y
Degrees from setpoint before receiving notification. Forces notificationSensitivity to Custom.
notificationUnreachableYes, No
Y
Send notification if thermostat becomes unreachable. Forces notificationSensitivity to Custom.
minSafeTempInterger
Y
Lowest allowed temperature before notification is sent.
maxSafeTempInterger
Y
Highest allowed temperature before notification is sent.
scheduleOn, Off, Name
Y
Whether the schedule is active or the Name of the shared schedule.
scheduleRepeatWeekday, Weekly
Y
Schedule repeat.
scheduleSetTimes2, 3, 4, Variable
Y
Number of set times per day in the schedule.
scheduleMultipleSystemYes, No
Y
System mode for each schedule set time.
scheduleMultipleFanYes, No
Y
Fan mode for each schedule set time.

ThermostatSchedule Object

NameValuesSetDescription
nameString
N
The configured name of the thermostat.
serialNoString
N
The thermostat serial number.
dayOfWeekSunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Vacation
Y
The day of the week for this schedule set time.
setTimeInteger
Y
The indexed set time for this schedule entry.
startTimeString
Y
The time of day (24 hr format) for this schedule entry.
systemAuto, Heat, Cool, Off
Y
The system mode.
heatSettingInteger
Y
The heat setting.
coolSettingInteger
Y
The cool setting.
fanAuto, On
Y
The fan setting.
keypadOn, Off
Y
The keypad setting.
deleteNone
Y
Delete the specified schedule entry.
deleteAllNone
Y
Delete the schedule for the entire day.

ThermostatHistory Object

NameValuesSetDescription
nameString
N
The configured name of the thermostat.
groupNameString
N
The configured group name of the thermostat.
serialNoString
N
The thermostat serial number.
systemOff, Auto, Heat, Cool
N
The active system mode.
heatSettingInteger
N
The active Heat Setting.
coolSettingInteger
N
The active Cool Setting.
fanAuto, On
N
The active Fan Mode.
statusOccupied, Vacant
N
Normally Occupied. Vacant when vacation schedule is active.
temperatureDecimal
N
The measured temperature.
humidityInteger
N
The measured humidity: %RH. Zero (0) if humidity is not supported.
humiditySettingInteger
N
The minimum humidity setting.
humiditySettingInteger
N
The minimum humidity setting.
dehumidifySettingInteger
N
The maximum humidity setting.
frontKeypadOn, Off
N
Thermostat keypad status.
runStatusOff, Cool-Stage1, Cool-Stage2, Heat-Stage1, Heat-Stage2, Fan, Fan2
N
The currently active Heating or Cooling status.
auxStatusOn, Off
N
The active Auxiliary Heat status.
timestampDate/Time
N
ISO 8601 Formatted Date Time.
startDateTimeDate/Time
N
ISO 8601 Formatted Date Time. Used for selecting the history date range to retrieve.
endDateTimeDate/Time
N
ISO 8601 Formatted Date Time. Used for selecting the history date range to retrieve. A maximum of 30 days of history can be retrieved in a single request.