Previous Example
Example 5: Creating a temperature hold
Note on token authentication:
If you have completed the authentication process from Example 1, your access token will be pre-populated in all requests throughout every example.
To specify a different access token, please paste it in the form below and press 'Update'. Alternatively, you can go back to the first example here to re-authenticate. Doing either will save your access token for all future examples.
Before we dive into how to create a temperature hold, it is important to understand how the thermostat's behaviour is governed by its settings, program, and events. Below is a diagram providing a high level view on how these objects are related to each other.
The thermostat's running behaviour is determined by settings within the Settings and the Program objects. The settings are general configurations for the thermostat. They may be user preferences or thermostat parameters. The program is an overall comfort specification detailed as a weekly schedule.
While the thermostat is running, events can be generated. Each event is represented by an Event object. These events can be hold actions created by the user. They can be scheduled events such as a vacation event. A utility company can also send a Demand Response event. The common theme to these events, is that each one represent a change or override to the original program for a duration (could be indefinite).
Optional events can be cancelled by the user or by the API, while mandatory events must run its course.
To demonstrate the interoperability between these objects, we will create a temperature hold event, and then cancel the hold (in our next example).
Before we instruct the thermostat to hold, we want to know the high and low temperature range for heat and cool modes. This will let us know range limits which we can set our hold temperatures. We get these values by getting the Settings object from the thermostat.
curl -s -H 'Content-Type: text/json' -H 'Authorization: Bearer ACCESS_TOKEN' 'https://api.ecobee.com/1/thermostat?format=json&body=\{"selection":\{"selectionType":"registered","selectionMatch":"","includeSettings":true\}\}'
{
"page": {
"page": 1,
"totalPages": 1,
"pageSize": 1,
"total": 1
},
"thermostatList": [
{
"identifier": "318324666667",
"name": "Main Floor",
"thermostatRev": "150212154942",
"isRegistered": true,
"modelNumber": "athenaSmart",
"lastModified": "2015-02-12 15:49:42",
"thermostatTime": "2015-02-12 15:36:43",
"utcTime": "2015-02-12 20:36:43",
"settings": {
"hvacMode": "heat",
"lastServiceDate": "2014-01-03",
...snipped...
"heatRangeHigh": 734,
"heatRangeLow": 450,
"coolRangeHigh": 920,
"coolRangeLow": 650,
...snipped...
"heatCoolMinDelta": 50,
...snipped...
"groupRef": "",
"groupName": "",
"groupSetting": 0
}
}
],
"status": {
"code": 0,
"message": ""
}
}
The heatRangeHigh and heatRangeLow represents the high and low range of the heat set temperature as user preferences set on the thermostat set by the user. We will need to conform to this range. Remember in example 2, we learned how to use temperature values in the JSON object. The heat can be set between 45.0℉ and 73.4℉. The cool temperature can be set between 65.0℉ and 92.0℉ We will now create a new heat hold for 70.0℉, and cool hold for 75.0℉. Note that when creating a temperature hold, both heat and cool temperatures must be specified.
In addition to the user preferences, we should also consider the current mode of the thermostat. As you recall in this example, the mode is determined by the hvacMode property in the settings. Depending on the mode, below is the recommendation for setting the heat and cool temperatures.
It is good practice to set the heat and cool hold temperatures to be the same, if the thermostat is in either heat, cool, auxHeatOnly, or off mode. If the thermostat is in auto mode, an additional rule is required. The cool hold temperature must be greater than the heat hold temperature by at least the amount in the heatCoolMinDelta property, which can be found in Settings .
Create a file called json.txt. The file should contain the following contents. The JSON contains a selection property which determines which thermostat(s) we will apply the hold to. To create the hold, we have to use the SetHold function. To learn the basics of calling functions, the process is thoroughly described in Using Functions .
{
"selection": {
"selectionType":"registered",
"selectionMatch":""
},
"functions": [
{
"type":"setHold",
"params":{
"holdType":"nextTransition",
"heatHoldTemp":700,
"coolHoldTemp":700
}
}
]
}
We will then use cURL to perform the POST request.
curl -s --request POST --data-urlencode @json.txt -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Bearer ACCESS_TOKEN" "https://api.ecobee.com/1/thermostat?format=json"
If the post is successful, you should see this.
{
"status": {
"code": 0,
"message": ""
}
}
Let us verify that the thermostat has adopted the hold. We use the GET Thermostat request again but this time we will set the includeEvents property.
curl -s -H 'Content-Type: text/json' -H 'Authorization: Bearer ACCESS_TOKEN' 'https://api.ecobee.com/1/thermostat?format=json&body=\{"selection":\{"selectionType":"registered","selectionMatch":"","includeEvents":true\}\}'
Note that there are two events. The first event is the hold that we have just placed and its running value is set to true. The second event is the _Default_ event. We will leave this for a later example, when we create a vacation event.
{
"page": {
"page": 1,
"totalPages": 1,
"pageSize": 1,
"total": 1
},
"thermostatList": [
{
"identifier": "318324666667",
"name": "Main Floor",
"thermostatRev": "150213150322",
"isRegistered": true,
"modelNumber": "athenaSmart",
"lastModified": "2015-02-13 15:03:22",
"thermostatTime": "2015-02-13 10:04:26",
"utcTime": "2015-02-13 15:04:26",
"events": [
{
"type": "hold",
"name": "auto",
"running": true,
"startDate": "2015-02-13",
"startTime": "10:03:22",
"endDate": "2015-02-13",
"endTime": "23:30:00",
"isOccupied": true,
"isCoolOff": false,
"isHeatOff": false,
"coolHoldTemp": 700,
"heatHoldTemp": 700,
"fan": "auto",
"vent": "off",
"ventilatorMinOnTime": 5,
"isOptional": true,
"isTemperatureRelative": false,
"coolRelativeTemp": 0,
"heatRelativeTemp": 0,
"isTemperatureAbsolute": true,
"dutyCyclePercentage": 255,
"fanMinOnTime": 0,
"occupiedSensorActive": false,
"unoccupiedSensorActive": false,
"drRampUpTemp": 0,
"drRampUpTime": 3600,
"linkRef": "",
"holdClimateRef": ""
},
{
"type": "template",
"name": "_Default_",
...snipped...
"holdClimateRef": ""
}
]
}
],
"status": {
"code": 0,
"message": ""
}
}
You can see that the thermostat's effective set points is governed through a combination of its program and the events that the thermostat is processing. Use the Runtime object demonstrated in this example to get the effective desirable comfort settings. For example the desiredHeat and desiredCool properties of the runtime object already factor in the program and all events.
Congratulations in creating your first temperature hold, and changing the thermostat behaviour. In our next example, we will show you how to cancel the hold and have the thermostat resume its original Program.