Monitor & control utility Tadoº Smart Thermostat devices.
The binary tado-monitor
has been renamed to tado
and now offers multiple subcommands. The Docker image built as part of the release
continues to run the exporter/monitoring function. So if you're using the Docker image, this will be transparent to you.
With the introduction of "Home" rules, the syntax for zone rules has been reworked. See the section Controlling your Tado devices
for details. If you're not using the rules-based controller, this will be transparent to you.
tado offers two types of functionality:
tado monitor
runs an exporter to expose metrics to Prometheus and, if configured, a controller to manage the thermostat settings in your home & rooms.tado config
displays the different zones & mobile devices for your account.
Docker images for tado monitor
are available on ghcr.io.
The following command-line arguments can be passed:
Usage:
tado [command]
Available Commands:
completion Generate the autocompletion script for the specified shell
config Show Tado configuration
help Help about any command
monitor Monitor Tado thermostats
The configuration file option specifies a yaml file to control the behaviour:
# Set to true to enable debug logging
debug: false
# Section for Prometheus exporter functionality
exporter:
# Listener address for the Prometheus metrics server
addr: :9090
# Section related to polling Tado for new metrics
poller:
# How often we should poll for new metrics
interval: 30s
# Section related to the /health endpoint
health:
# Listener address for the /health endpoint
addr: :8080
# Section containing Tado credentials
tado:
username: ""
password: ""
clientsecret: ""
# Section for controller functionality
controller:
tadobot:
# When set, the controller will start a slack bot. See below for details
enabled: true
# Slackbot token value
token: ""
If the filename is not specified on the command line, the program looks for a file config.yaml
in the following directories:
/etc/tado-monitor
$HOME/.tado-monitor
.
Any value in the configuration file may be overriden by setting an environment variable with a prefix TADO_MONITOR_
.
E.g. to avoid setting your Tado credentials in the configuration file, set the following environment variables:
export TADO_MONITOR_TADO.USERNAME="username@example.com"
export TADO_MONITOR_TADO.PASSWORD="your-password"
In case you run into authentication problems, you may need to retrieve your CLIENT_SECRET
and add it to the "tado" configuration section
(or set it as a environment variable). To get your CLIENT_SECRET
, log into tado.com and visit https://my.tado.com/webapp/env.js.
The client secret can be found in the oauth section:
var TD = {
config: {
...
oauth: {
...
clientSecret: 'verylongclientsecret'
}
}
};
tado monitor
will look for a file rules.yaml
in the same directory it found the config.yaml
file described above.
This file defines the rules to apply for your home:
# Home rules control the state of your home (i.e. "home" or "away").
home:
# autoAway sets the home to "away" mode when all defined users are away from home.
autoAway:
delay: 1h
users: [ "A", "B"]
# Zone rules control the state of a rooom within your home. Rules will either switch heating off when all users are away,
# or move the room to automatic mode when the room's been in manual mode for a while (think someone switching the bathroom
# to a manual temperature setting and then forgetting to switch it back to automatic mode).
zones:
- name: "room 1"
rules:
# autoAway switches off the heating in a room when all defined users are away from home
autoAway:
delay: 1h
users: ["A"]
# limitOverlay removes a manual temperature control after a specified amount of time
limitOverlay:
delay: 1h
# nightTime removes any manual temperature control at a specified time of day
nightTime:
time: "23:30:00"
If the file does not exist, tado monitor
will only run as a Prometheus exporter.
Add tado as a target to let Prometheus scrape the metrics into its database.
This highly depends on your particular Prometheus configuration. In its simplest form, add a new scrape target to prometheus.yml
:
scrape_configs:
- job_name: tado
static_configs:
- targets: [ '<tado host>:<port>' ]
where is the Prometheus listener port configured in exporter.addr in the configuration file (the default being 9090).
tado exposes the following metrics:
metric | type | help |
---|---|---|
tado_outside_temp_celsius | GAUGE | Current outside temperature in degrees celsius |
tado_solar_intensity_percentage | GAUGE | Current solar intensity in percentage (0-100) |
tado_weather | GAUGE | Current weather. Always one. See label 'tado_weather' |
The following metrics are reported for each discovered zone. The zone name is added as 'zone_name' label.
metric | type | help |
---|---|---|
tado_zone_device_battery_status | GAUGE | Tado device battery status |
tado_zone_device_connection_status | GAUGE | Tado device connection status |
tado_zone_heating_percentage | GAUGE | Current heating percentage in this zone in percentage (0-100) |
tado_zone_humidity_percentage | GAUGE | Current humidity percentage in this zone |
tado_zone_open_window_duration | GAUGE | Duration of open window event in seconds |
tado_zone_open_window_remaining | GAUGE | Remaining duration of open window event in seconds |
tado_zone_power_state | GAUGE | Power status of this zone |
tado_zone_target_manual_mode | GAUGE | 1 if this zone is in manual temp target mode |
tado_zone_target_temp_celsius | GAUGE | Target temperature of this zone in degrees celsius |
tado_zone_temperature_celsius | GAUGE | Current temperature of this zone in degrees celsius |
Tado reports the home/away status of registered mobile devices. See device name is added as 'name' label.
metric | type | help |
---|---|---|
tado_mobile_device_status | GAUGE | Tado mobile device status. 1 if the device is "home" |
The repo contains a sample Grafana dashboard to visualize the scraped metrics.
Feel free to customize as you see fit.
tado monitor
can run a Slack bot that will report on any rules being triggered:
Users can also interact with the bot:
TadoBot supports the following commands:
- rules: show any activated rules
- rooms: show temperature & settings on each room
- users: show the status of each user (home/away)
- set: sets the room's target temperature, optionally for a limited duration:
- set Bathroom 23.5: sets the bathroom's target temperature to 23.5ºC
- set Bathroom 23.5 1h: same, but switches back to automatic mode after 1 hour
- set Study auto: sets the study to automatic temperature control
- version: show version
- help: show all available commands
To enable the bot, add a bot to the workspace's Custom Integrations and add the API Token in the configuration file above (controller.tadobot.token).
The Tado Client API implementation can be found in GitHub. The API should be fairly stable at this point, so feel free to reuse for your own projects.
- Christophe Lambin
- Max Rosin for his Python implementation of the Tado API
- vide/tado-exporter for some inspiration
This project is licensed under the MIT License - see the LICENSE.md file for details.