tado – Terence Eden’s Blog

Two years of home heating data

Terence Eden — Wed, 20 Feb 2019 08:14:07 +0000

I have a Tado smart thermostat - part of my smarthome project. As well as letting me set the temperature from my phone, it records environmental data, and provides a handy API for me to retrieve it.

This blog post will show you why I've gathered the data, let you download the full dataset, and explain what I learned from it.

Why do this?

There's a long-standing plan to use waste-heat from a nearby supermarket to provide communal heat to our neighbourhood.

A low temperature heat main would connect directly to the chillers at the superstore via a heat recovery unit and circulate ~25° hot water around the neighbourhood. The homes will symbiotically draw on the waste heat produced by the supermarket.

A heat pump would be installed in each household, as a replacement to their existing gas boiler.

The properties will use the existing radiators to run their heating longer but at a lower temperature in order to deliver the same level of thermal comfort.

Bioregional's Rose Hill renewable energy feasibility study

In order to assess whether this is feasible, we need to understand heating demand.

This graph shows February 14th 2017 - 2019. The green graph line is the temperature inside my house. The blue graph line is the external temperature as measured by a local weather sensor in Oxford. The vertical lines represent when the heating was on - with yellow, orange, and red representing low-demand, medium-demand, and high-demand.

Fairly obviously, heating demand is highest in winter - but it surprised me just how late it starts.
Internal temperature doesn't vary as much as external.
Even in the depth of winter, with the heating off, the house didn't drop bellow 10°C. That's pretty good insulation!

Zoom!

Let's zoom in on December 2018 (tap for bigger):

We were away over the holidays, so the heating was set to stay off - unless the internal reading was under 10°C. Luckily, that didn't happen!

You can also see how rapidly the house cools when the external temperature drops.

Conversely, the rise in external temperature from 5 to 10 barely raised the internal temperature.

Enhance!

Let's zoom in on a couple of days in December 2018.

Here you can see the heating demand. The theory is that Tado can use the weather forecast to see how much heat it needs to generate. I can't easily assess whether it works in practice, but there are a few instances where the heating cuts off before the house reaches the target temperature. Presumably because it know the environment will provide the rest of the thermal energy.

Get The Data!

There are two datasets available. Both are being released under CC BY-SA 4.0.

The first is a CSV file of heating demand (190KB).

The second is the complete Tado output (2.5MB Zip, 25MB unzipped). It is a series of daily JSON files which contain:

Internal temperature
External temperature
Internal humidity
Whether anyone was at home
What the thermostat was set to
If the heating was on
Heating demand
When the hot water was on

Feel free to use this data for something interesting, or to make beautiful graphs. I make no claims to its accuracy or completeness.

Tado API Guide - updated for 2019

Terence Eden — Thu, 14 Feb 2019 12:22:17 +0000

Tado is a brilliant smart thermostat. But their API is very poorly documented. This is an updated guide for 2019. I am indebted to Stephen C Phillips' original documentation.

Getting started

You will need:

A Tado (duh!)
Your Username (usually your email address)
Your Password
A Client Secret

Getting the client secret

I'm using this client secret: wZaRN7rpjn3FoNyF5IFuxg9uMzYJcvOoQ8QWiIqS3hfk6gLhVlG57j5YNoZL2Rtc This secret may change in the future. In the examples, I'll shorten it to wZa to make it easier to read. You will need to use the full length secret when running this code.

To get the current secret, you can visit https://my.tado.com/webapp/env.js and get the secret from there.

var TD = {
    config: {
        version: 'v587',
        tgaRestApiEndpoint: 'https://my.tado.com/api/v1',
        tgaRestApiV2Endpoint: 'https://my.tado.com/api/v2',
        susiApiEndpoint: 'https://susi.tado.com/api',
        oauth: {
            clientApiEndpoint: 'https://my.tado.com/oauth/clients',
            apiEndpoint: 'https://auth.tado.com/oauth',
            clientId: 'tado-web-app',
            clientSecret: 'wZaRN7rpjn3FoNyF5IFuxg9uMzYJcvOoQ8QWiIqS3hfk6gLhVlG57j5YNoZL2Rtc'
        }
    }
};

If that ever changes, you will need to open your web browser's development tools, and then look in the network tab. Then, log in to https://my.tado.com/webapp/.

You should see the token:

Get Bearer Token

These examples use the curl command on Linux.

Here's how to turn your username and password into a "Bearer Token" - this is needed for every subsequent API call:

curl -s "https://auth.tado.com/oauth/token" -d client_id=tado-web-app -d grant_type=password -d scope=home.user -d username="you@example.com" -d password="Password123" -d client_secret=wZa

The response will be:

{
    "access_token": "abc",
    "token_type": "bearer",
    "refresh_token": "def",
    "expires_in": 599,
    "scope": "home.user",
    "jti": "xyz-123"
}

The real access_token will be very long. I've shortened it to abc make things easier to read in these examples.

The access token expires after 600 seconds. You can either request a new one with the username and password, or use the provided refresh_token like so:

curl -s "https://auth.tado.com/oauth/token" -d grant_type=refresh_token -d refresh_token=def -d client_id=tado-web-app -d scope=home.user -d client_secret=wZa

Get your details

The next step is to get your homeId - this will also be needed for subsequent API calls:

curl -s "https://my.tado.com/api/v1/me" -H "Authorization: Bearer abc"

You'll get back your data, like this:

{
    "name": "Terence Eden",
    "email": "you@example.com",
    "username": "your_user_name",
    "enabled": true,
    "id": "987654321",
    "homeId": 123456,
    "locale": "en_GB",
    "type": "WEB_USER"
}

Your homeId is what's important here. I'm going to use the example 123456 - you should use your own.

Check it all works

This request will check that you've got the right details.

curl -s "https://my.tado.com/api/v2/homes/123456" -H "Authorization: Bearer abc"

You'll get back information about your installation. I've redacted mine for privacy.

{
    "id": 123456,
    "name": " ",
    "dateTimeZone": "Europe/London",
    "dateCreated": "2015-12-18T19:21:59.315Z",
    "temperatureUnit": "CELSIUS",
    "installationCompleted": true,
    "partner": " ",
    "simpleSmartScheduleEnabled": true,
    "awayRadiusInMeters": 123.45,
    "usePreSkillsApps": true,
    "skills": [],
    "christmasModeEnabled": true,
    "contactDetails": {
        "name": "Terence Eden",
        "email": " ",
        "phone": " "
    },
    "address": {
        "addressLine1": " ",
        "addressLine2": null,
        "zipCode": " ",
        "city": " ",
        "state": null,
        "country": "GBR"
    },
    "geolocation": {
        "latitude": 12.3456789,
        "longitude": -1.23456
    },
    "consentGrantSkippable": true
}

Get your data

OK, here's where the fun begins. This gets the data about your installation - including firmware details, device names, etc.

curl -s "https://my.tado.com/api/v2/homes/123456/zones" -H "Authorization: Bearer abc"

Here's what you get back - I've redacted some of my details.

[{
    "id": 1,
    "name": "Heating",
    "type": "HEATING",
    "dateCreated": "2015-12-21T15:46:45.000Z",
    "deviceTypes": ["RU01"],
    "devices": [{
        "deviceType": "RU01",
        "serialNo": " ",
        "shortSerialNo": " ",
        "currentFwVersion": "54.8",
        "connectionState": {
            "value": true,
            "timestamp": "2019-02-13T19:30:52.733Z"
        },
        "characteristics": {
            "capabilities": ["INSIDE_TEMPERATURE_MEASUREMENT", "IDENTIFY", "OPEN_WINDOW_DETECTION"]
        },
        "batteryState": "NORMAL",
        "duties": ["ZONE_UI", "ZONE_LEADER"]
    }],
    "reportAvailable": false,
    "supportsDazzle": true,
    "dazzleEnabled": true,
    "dazzleMode": {
        "supported": true,
        "enabled": true
    },
    "openWindowDetection": {
        "supported": true,
        "enabled": true,
        "timeoutInSeconds": 1800
    }
}, {
    "id": 0,
    "name": "Hot Water",
    "type": "HOT_WATER",
    "dateCreated": "2016-10-03T11:31:42.272Z",
    "deviceTypes": ["BU01", "RU01"],
    "devices": [{
        "deviceType": "BU01",
        "serialNo": " ",
        "shortSerialNo": " ",
        "currentFwVersion": "49.4",
        "connectionState": {
            "value": true,
            "timestamp": "2019-02-13T19:36:17.361Z"
        },
        "characteristics": {
            "capabilities": []
        },
        "isDriverConfigured": true,
        "duties": ["ZONE_DRIVER"]
    }, {
        "deviceType": "RU01",
        "serialNo": " ",
        "shortSerialNo": " ",
        "currentFwVersion": "54.8",
        "connectionState": {
            "value": true,
            "timestamp": "2019-02-13T19:30:52.733Z"
        },
        "characteristics": {
            "capabilities": ["INSIDE_TEMPERATURE_MEASUREMENT", "IDENTIFY", "OPEN_WINDOW_DETECTION"]
        },
        "batteryState": "NORMAL",
        "duties": ["ZONE_UI", "ZONE_LEADER"]
    }],
    "reportAvailable": false,
    "supportsDazzle": false,
    "dazzleEnabled": false,
    "dazzleMode": {
        "supported": false
    },
    "openWindowDetection": {
        "supported": false
    }
}]

State

This command will tell you if you're home or not. Or, in other words, whether the Tado thinks you're nearby:

curl -s https://my.tado.com/api/v2/homes/123465/state -H "Authorization: Bearer abc"

This is what you'll get back if you're at home

{"presence":"HOME"}

Zones

My Tado has two "Zones". 0 is for Hot Water, 1 is for Heating. Yours may be different.

Hot Water Information

curl -s https://my.tado.com/api/v2/homes/123456/zones/0/state -H "Authorization: Bearer abc"

Here's information about your hot water:

{
    "tadoMode": "HOME",
    "geolocationOverride": false,
    "geolocationOverrideDisableTime": null,
    "preparation": null,
    "setting": {
        "type": "HOT_WATER",
        "power": "OFF",
        "temperature": null
    },
    "overlayType": null,
    "overlay": null,
    "openWindow": null,
    "nextScheduleChange": {
        "start": "2019-02-13T19:00:00Z",
        "setting": {
            "type": "HOT_WATER",
            "power": "ON",
            "temperature": null
        }
    },
    "link": {
        "state": "ONLINE"
    },
    "activityDataPoints": {},
    "sensorDataPoints": {}
}

Heating

It's much the same for Heating information:

curl -s https://my.tado.com/api/v2/homes/123456/zones/1/state -H "Authorization: Bearer abc"

This also gets you humidity data etc:

{
    "tadoMode": "HOME",
    "geolocationOverride": false,
    "geolocationOverrideDisableTime": null,
    "preparation": null,
    "setting": {
        "type": "HEATING",
        "power": "ON",
        "temperature": {
            "celsius": 15.00,
            "fahrenheit": 59.00
        }
    },
    "overlayType": null,
    "overlay": null,
    "openWindow": null,
    "nextScheduleChange": {
        "start": "2019-02-13T17:30:00Z",
        "setting": {
            "type": "HEATING",
            "power": "ON",
            "temperature": {
                "celsius": 18.00,
                "fahrenheit": 64.40
            }
        }
    },
    "link": {
        "state": "ONLINE"
    },
    "activityDataPoints": {
        "heatingPower": {
            "type": "PERCENTAGE",
            "percentage": 0.00,
            "timestamp": "2019-02-13T10:19:37.135Z"
        }
    },
    "sensorDataPoints": {
        "insideTemperature": {
            "celsius": 16.59,
            "fahrenheit": 61.86,
            "timestamp": "2019-02-13T10:30:52.733Z",
            "type": "TEMPERATURE",
            "precision": {
                "celsius": 0.1,
                "fahrenheit": 0.1
            }
        },
        "humidity": {
            "type": "PERCENTAGE",
            "percentage": 57.20,
            "timestamp": "2019-02-13T10:30:52.733Z"
        }
    }
}

Weather

Tado also provides you with data about the external weather:

curl -s https://my.tado.com/api/v2/homes/123456/weather -H 'Authorization: Bearer abc'

You get back a basic weather report for your location:

{
    "solarIntensity": {
        "type": "PERCENTAGE",
        "percentage": 68.10,
        "timestamp": "2019-02-10T10:35:00.989Z"
    },
    "outsideTemperature": {
        "celsius": 8.00,
        "fahrenheit": 46.40,
        "timestamp": "2019-02-10T10:35:00.989Z",
        "type": "TEMPERATURE",
        "precision": {
            "celsius": 0.01,
            "fahrenheit": 0.01
        }
    },
    "weatherState": {
        "type": "WEATHER_STATE",
        "value": "CLOUDY_PARTLY",
        "timestamp": "2019-02-10T10:35:00.989Z"
    }
}

Controlling your home

It's possible to turn the heating and hot water on / off.

Turn Heating On

This is a PUT request

curl -s 'https://my.tado.com/api/v2/homes/123456/zones/1/overlay' -X PUT -H 'Authorization: Bearer abc' -H 'Content-Type: application/json;charset=utf-8' --data '{"setting":{"type":"HEATING","power":"ON","temperature":{"celsius":21,"fahrenheit":69.8}},"termination":{"type":"MANUAL"}}'

Just to make it easier to read, this is the JSON data that you have to PUT:

{
    "setting": {
        "type": "HEATING",
        "power": "ON",
        "temperature": {
            "celsius": 21,
            "fahrenheit": 69.8
        }
    },
    "termination": {
        "type": "MANUAL"
    }
}

If it has worked, you'll get back this response:

{
    "type": "MANUAL",
    "setting": {
        "type": "HEATING",
        "power": "ON",
        "temperature": {
            "celsius": 21.00,
            "fahrenheit": 69.80
        }
    },
    "termination": {
        "type": "MANUAL",
        "projectedExpiry": null
    }
}

End Manual Heading Mode

This is a simple DELETE command:

curl -s 'https://my.tado.com/api/v2/homes/123456/zones/1/overlay' -X DELETE -H 'Authorization: Bearer abc'

Turn on Hot Water

Much the same as before

curl -s 'https://my.tado.com/api/v2/homes/123456/zones/0/overlay' -X PUT -H 'Content-Type: application/json;charset=utf-8' -H 'Authorization: Bearer abc'--data '{"setting":{"type":"HOT_WATER","power":"ON"},"termination":{"type":"MANUAL"}}'

Turn off Hot Water

Again, a DELETE

curl -s 'https://my.tado.com/api/v2/homes/123456/zones/0/overlay' -X DELETE -H 'Authorization: Bearer abc'

Historic Information

You can get a complete view of historic data with:

curl -s 'https://my.tado.com/api/v2/homes/123456/zones/1/dayReport?date=2018-02-14' -H 'Authorization: Bearer abc'

The date at the end is in ISO8601 format. You'll receive info on internal and external temperature, humidity levels, whether the heating and hot water were on, and a few other bits and bobs.

What's Next?

There are a bunch of other things you can do with the API, like setting a schedule etc. Sadly, I don't have time to document them all. But this should be enough to get you detailed information, and basic control.

I'd love it if someone could make OpenAPI documentation for this.

The "Make Everything Better" Button

Terence Eden — Tue, 20 Mar 2018 07:49:22 +0000

Back when I used to help people design mobile phone apps, I would talk about the platonic ideal of an app. It's quite simple and effective.

You press the button in the middle of your screen - and it makes everything better! You push that button and a taxi arrives, or a pizza is delivered, or your photos are backed up, or you fall in love, or you learn a language.

Life is rarely that simple - and apps are rarely that smart. But let's look at what comes next.

Anticipatory User Interfaces

The most boring app I have is Tado - it controls my central heating. I never need to use the app! It sits in the background requiring no interaction. When it sees I am home, it sets the temperature accordingly. If I'm away overnight, it doesn't bother turning on the hot water. If it sees me travelling home, and it is cold, it pre-heats the house.

Other than my initial set up, I don't have to press any buttons. The app becomes the perfect Butler.

(To clarify - this isn't about learning. Most people's lives are too chaotic for a machine to adequately learn. We very rarely all fit the 9-to-5 grind, with 2.4 kids, and brunch every Sunday. It's one of the problems the Nest thermostat has with its "learning" feature - and why people disable it - our lives are too noisy.)

The app anticipates what you need and delivers it without asking.

Boring is Beautiful

I don't want your app. But if I have to have it - I certainly don't want to interact with it. I don't want your notifications cluttering up my screen. I know your brand-manager harps on about "engagement" and "eyeballs" - but I don't care. Prove to me that you are useful by never interrupting me.

There are so many things competing for our attention. Too many things. It's really easy to make your app noisy and engaging. It looks great on a PowerPoint when you can show how often people open your app, I get that. But every time I get a perky email from my smoke-alarm telling me how wonderful it is, I want to rip it from my wall. Do your job and leave me alone.

So, dear app designers, refrain from sending constant, pleading emails in the vain hope that your click-through-rate will inch ever-closer to perfection.

No. Refine your service so that it can work silently. Let the absence of interaction be a selling point.

How do you move out of a smarthome?

Terence Eden — Thu, 30 Nov 2017 12:05:57 +0000

I've an unhealthy amount of smart gadgets at home. Enough so that it's worth running an orientation session when friends come to visit.

This is what the Alexa does, here's which light switches not to use, don't be scared if the Roomba attacks. That sort of thing.

I don't know how long we'll live in this place. It's more than likely we'll move at some point. So what happens to the smarthome stuff we've accumulated?

When we hand over the keys to the new residents - do we hand over all the cloud passwords as well? Or do we factory reset everything and let them go through the dull process of setting up new accounts?

Some stuff is probably easy to move. Unplug the LIFX bulbs and replace with poundshop lights.

Some stuff is probably hard. Do I unwire the Tado Thermostat and replace with a generic version?

Tado, to their credit, have a procedure for people moving house. You need to provide them with:

A copy of your ID (photo or scan)
Your signature
Firstname & Surname of the new user
Your Email address associated with your tado° account
Email address of the new user
Telephone number of the new user

A bit of a faff - and possibly annoying to the new occupiers to not be able to easily set the heating until they've moved in, configured the WiFi, and registered for an account.

Now imagine doing that for every hardwired gadget you have - the light switches, the connected cooker, the smoke alarms, the doorbell, the security system. A nightmare which adds to the stress of an already fraught situation for both parties.

The Nest Protect smoke alarm suggests that you should factory reset alarms you inherit and then manually add them. When I move into a house, do I want to spend the first day looking up manuals online to try and work out which buttons to hold down in order to claim the devices as my own?

This is, of course, the epitome of "first-world problems" - but it is one that most people will have to face in the coming years.