non-technical explanation

What is a Toon?

A Toon is a smart thermostat, developed by Quby (a formerly independent startup that is now part of Eneco). Like any other thermostat, it is a small box that hangs on a wall, measures temperature and controls the heat. It uses Wifi to connect to the Internet. Even without the API, the Toon was already innovative. The thermostat gives people insight into their energy use, because it has a large screen that displays information on past use. The Toon retails for about € 200,- based on its proposition as a premium thermostat and can be bought separately, apart from an energy contract.

Toon core functions

The ambition of Toon is to measure all energy-related functions in a home. At the moment the following functions are implemented:

Temperature. Toon knows the current temperature and a target room temperature, and controls the heating to keep the current temperature close to the target. The temperature is included in the Toon, so the Toon must be placed at the right place in the room. Toon cannot control the temperature in multiple rooms independently. You will need multiple Toons for this functions.

Electricity usage. The Toon constantly measures the use and stores the data for every 5 minute period in the cloud. You can check the current use and also the past use in the last 24 hours.

Natural gas usage. Not every Toon user has a natural gas connection. If the user has natural gas, the Toon measures the flow of gas constantly and stores the data every for every 5 minute period in the cloud. You can check the current use and also the past use in the last 24 hours.

Electricity generation. If a Toon user has solar panels on their roof, the Toon measures the electricity generated and stores it in the cloud for every 5 minute period.

The following functions are under development or under design. You cannot use the following functions yet, but you might see some of these functions in the documentation.

Heat use. Some houses have district heating, were a separate heat pipe delivers excess heat from a power plant to a household (in the form of hot water). We are working on measuring the heat use (it is measured in both water flow and energy/Kwh). This function does not work well enough yet and has not been publicly released.

Ventilation and air conditioning. The current Toon device cannot be used for air conditioning.

Water usage. Most water meters do not work with Toon yet. The Toon device and Toon API cannot be used for water related applications, but some pilots are ungoing.

Z-wave, Bluetooth and Wifi devices. With the exception of Philips Hue and smart plugs (see below), Toon cannot be used yet to control other home devices. It is expected that more and more devices are connected to Toon so that Toon becomes a universal smart hub. There is however no fixed timeline for when these functions become available.

Additional functions: lamps and switches

The current Toon has two additional functions that have been rolled out to users: Philips Hue lamps and smart plugs.

Philips Hue. The Philips Hue lamps are so-called smart lamps that can be controlled via Wifi and can change color. The lamps fit into a regular socket but can be controlled over the Internet. The Toon device is one of the alternative ways to control Philips Hue lamps.

Smart plugs resemble the traditional time switch (Dutch: tijdschakelklok). They are placed on top of traditional wall sockets can will turn the power on and off selectively. The Toon device can be used to program the smart plug or to switch it directly.

How Toon controls temperature

The Toon device uses programs that are based on four different states to control temperature. The user determines the ideal temperature for four states:

State Home: this state should be selected when people are at home. In colder climates or seasons, this will have a high temperature, such as 20 degrees Celsius.

State Away: this state should be selected when nobody is at home. In colder climates or seasons, this will have a lower temperature, such as 15 degrees Celsius.

State Sleep: this state should be selected at night, when people are at home but in their bedroom. In colder climates or seasons, this will have a lower temperature, such as 18 degrees Celsius.

State Comfort: This is similar to at Home, but for even more people or people who like more heat. In colder climates or seasons, this will have a high temperature, such as 22 degrees Celsius.

The Toon device contains a program for an entire week, with a start time and end time for each block. A typical day might look like:

· 7:00 AM to 9:00 AM: Home

· 9:00 AM to 3:00 PM: Away

· 3:00 PM to 6:00 PM: Home

· 6:00 PM to 9:00 PM: Comfort

· 9:00 PM to 7:00 AM: Sleep

The program would be different for week days and weekend days, since people typically wake up later in the weekend.

Programs that use the Toon API can directly change the temperature, but this is not recommended. It is better to change the state (for instance from Away to Home) than to change the temperature directly. This way, you are using the favourite temperatures from the user.

Which functions are available via the API

In principle, any Toon function will eventually be made available via the API. The goal of the Toon API is to open up all home energy functions. In practice there is some additional development time between adding a function to the device and creating an API service. At the moment, all core energy functions are available in the API.

How is security and privacy implemented

The API provides the same level of security and privacy as the Toon device and Toon apps. There are actually two levels of security built in:

· In order to call the API at all, apps need a key and secret. Anyone can get a key and secret for access to test-functions of a virtual Toon. The key and secret for access to real Toons are however closely guarded by Quby and Eneco, and are only handed out to trusted parties

· Apps with a key and secret also need to be connected to a specific account, in order to get access to Toon devices attached to that account. Each owner of a Toon has a unique email address and password. They need to provide the email address and password to a login service in order to give a specific app access to their Toon device.

Eneco and Quby (the people behind the Toon API) will check whether each App meets basic quality standards and does exactly what it says it does, before they hand out a key and secret. The user then decides whether to use a specific app.

Next steps

There is a developer journey article that links to all other documentation in a logical order. You can also jump directly to one of the following: