The Toon MagicMirror Module

A few weeks ago I got in touch with Eneco, one of the biggest energy suppliers of Holland and makers of the Toon smart thermostat. They were pretty excited about my Magic Mirror project and had a nice challenge for me.

With over 275.000 Toon Thermostats up and running, the Toon smart thermostat is the most popular smart thermostat in the Netherlands. To stay ahead of the competition, and just to make an awesome smart device, Eneco decided to open up the API for the Toon Thermostat.

As a real world test, Eneco challenged me to use the Toon API in a MagicMirror module and share my experience along the way. This way, they can learn from the issues I’m running into and I have yet an other cool MagicMirror Module to offer. And good to know: they agreed on paying my regular development fee.

Using the developers documentation available on ToonAPI.com I soon figured out they use OAuth for authentication. To use this, you need an API Key and Secret you can obtain from the same site.

Luckily they offer a Node.js demo app. Which is pretty convenient, since the MagicMirror modules are also based on Node.js/Javascript. This demo app contains an OAuth login example which was a perfect base for my own implementation.

With the authentication in place I was able to request an access token allowing me to start doing my first Toon API requests. A full list of available endpoints is also available on their site. So soon I was able to start fetching the first pieces of data from my Toon.

After some playing around (and a bit of cussing), I discovered I first need to set an active “Agreement”, since an account can be connected to multiple Toon devices. In my opinion it would make more sense if the active agreement would be part of the resource url in stead of a mandatory POST request. But overall, this really wasn’t a showstopper. So, to make the API requests, I need to take the following steps:

1. Obtain an access token by doing an OAuth authentication.
2. Set the active agreement by doing a POST request to the /agreements endpoint.
3. Make a request to the desired API endpoint.

Of course, manually doing this for every API request would make no sense, so I decided on making a simple Node.js module which automatically does step 1 and 2 before step 3 is executed.

This module allows me to simply access the Toon data using a few convenient methods. For example, if I want to access the display’s status data, all I need to do is:

// Include the module.
var ToonAPI = require("./ToonAPI.js");

// Set the API Key & Secret:
ToonAPI.setApiKeySecret("API_KEY", "API_SECRET");

// Set the Username & Password:
ToonAPI.setUsernamePassword("USERNAME", "PASSWORD");

// Request the status:
ToonAPI.getStatus(function(status) {
    // Print the received status.
    console.log(status);
});

Before the status is requested, the ToonAPI module will request an access token and activate the first available agreement.

And with this piece of script in place, the rest of the MagicMirror module was pretty straight forward. I was actually pretty impressed about the amount of data that is available in the /status object. This really offers a lot of opportunities for great apps extending the Toon ecosystem.

Of course, I ran into a few points of improvement for the Toon API. The previously mentioned /agreements POST is one of the issues I prefer to be changed. But most of all, I’d like to see a lot of improvements in the available documentation. For example: there currently isn’t any documentation available describing all the data fields of the /status object. An easy fix which is exactly the reason why Eneco asked me to look into their API.

But most of all, I’d like to see a change in their approach on the supplied API keys. The sandbox keys you can obtain from the website won’t allow you to connect to your personal Toon thermostat. So if you want to use the MagicMirror Toon Module, you need to officially request a production key. Luckily Eneco understands this issue and together we’re looking into an other approach as a short term solution.

Overall I can honestly say I’m impressed by the power of their API. But what I’m most impressed by, is the fact that Eneco is reaching out developers and makers like you and me. A great way to improve their API and support Open Source projects in that process.

Want to try out the Toon MagicMirror Module? Check it out on GitHub.