About a month ago I moved into my new home. As I wrote a month earlier I was planning to put some nice home automation in it. Right now I’ve got two running Raspberry Pis; one for the home automation (PiLight) and one for the music (Mopidy-Mopify). The home automation already has some nice features like turning on my light when I’m at home and the sun is set, as well as some scenes to watch a movie or have a ‘comfy evening’.

Controlling the thermostat

So besides controlling my music and lights I would also like to be able to control my thermostat (HoneyWell Round). Right now I can do this with the Android application provided by Honeywell, but to be honest: I’ve seen better apps. To bad for us Honeywell doesn’t provide a public documented API, so we have to put in some extra digging to find out how it all works. Luckily for me some people already wrote Python and NodeJS wrappers for it.

In this post I’ll write how to simply change your thermostats temperature. Mostly as a reference for myself, but maybe I can make someone else happy with it too. I’ve tested this API on my Honeywell Round, but there’s a big change it will also work on other Honeywell products (like EvoHome) which you can control with their apps.

API Endpoints

• Default headers
• Authentication
• Retrieving locations
• Changing the temperature
• Set a location action
• Getting a task’s status

Default headers

Make sure you add a Content-type: application/json to each request, otherwise it won’t work.

Authentication

The first thing we have to do is getting a sessionId. This ID is used in all further requests to authenticate the user. To get a sessionId we have to make a POST request to:

curl -X POST -H "Content-Type: application/json" -d '{
        "username": "user@email.com", 
        "password": "pass!word123", 
        "ApplicationId": "91db1612-73fd-4500-91b2-e63b069b185c" 
    }' 'https://rs.alarmnet.com/TotalConnectComfort/WebAPI/api/Session'

In the POST body we have to put a raw JSON object containing our username, password and ApplicationId:

Accepted parameters

After you execute the request it should respond with an userInfo object and sessionId. Make sure you store the sessionId and userId somewhere, cause we need it in our next requests.

Retrieving locations

Each thermostat is part of a location. To get a list of all available locations and their registered thermostats you have to make a GET request to the following endpoint:

curl -X GET -H "sessionId: $sessionId" -H "Content-Type: application/json" \
    'https://rs.alarmnet.com/TotalConnectComfort/WebAPI/api/locations?userId=$userId&allData=True'

Make sure you add an extra sessionId header to these requests containing your sessionId from the authentication request.

After you execute the request it will respond with an array of your registered locations. Each location object contains information about the location and its registered devices. Each device has a deviceId, which you’ll need in your requests to make changes to your thermostat.

Changing the temperature

Now we have our deviceId we can finally change our thermostat’s temperature. To do this execute a PUT request to the following endpoint:

curl -X PUT -H "sessionId: $sessionId" -H "Content-Type: application/json" \
    -d '{"Value":"18.0","Status":"hold","NextTime":"2016-01-16T22:00:00Z"}' \
    'https://rs.alarmnet.com/TotalConnectComfort/WebAPI/api/devices/$deviceId/thermostat/changeableValues/heatSetpoint'

In the PUT body we have to put a raw JSON object containing at least three parameters:

Accepted parameters

Example body in case you want to set the temperature to 19.5 degrees till 10PM (assuming today is the 16th of January).

{"Value":"19.5","Status":"Temporary","NextTime":"2016-01-16T22:00:00Z"}

Reset temperature

By setting status: Scheduled you can cancel the temperature override and let it go back to the scheduled temperature. In this case you have to leave the value and NextTime parameters null.

Setting a location action

The Honeywell thermostats come with some predefined actions. These actions can be used to quickly change a location to the desired temperature. To set our location’s action we can make a PUT request to the following endpoint:

curl -X PUT -H "sessionId: $sessionId" -H "Content-Type: application/json" \
    -d '{ "QuickAction": "Away", "QuickActionNextTime": "2016-01-15T00:00:00Z" }' \
    'https://rs.alarmnet.com/TotalConnectComfort/WebAPI/api/evoTouchSystems?locationId=$locationId'

Accepted parameters

Available actions are:

• Auto
• Custom
• AutoWithEco
• Away
• DayOff
• HeatingOff

Getting a task’s status

Some requests, like changing the temperature, respond with a TaskId. We can use this ID to get the status of the Task. To get the status of a task we have to make a GET request to the following endpoint:

curl -X GET -H "sessionId: $sessionId" -H "Content-Type: application/json" \
    'https://rs.alarmnet.com/TotalConnectComfort/WebAPI/api/commTasks?commTaskId=$taskId' 

The request returns an object containing the status of the task, start time and finish time. An example of a response:

{
  "state": "Succeeded",
  "started": "2016-01-16T14:09:36.147",
  "finished": "2016-01-16T14:09:42.507"
}

To be continued

This ‘documentation’ is based on my own findings and experience as well as other existing wrappers. I’m planning to update this post every time I stumble upon something new.