Tado exporter
Introduction
This is a simple Prometheus exporter for Tado° smart home installations, scraping temperatures, humidity etc. from the Tado° API and presenting them in a Prometheus compatible format.
Idea taken from this python variant.
Since the python exporter failed to scrape the API quite often, and I wanted to experiment with Micronaut anyway, I decided to rebuild this in Kotlin/Micronaut. Meanwhile I switched to Spring Boot.
Building
- Check out this repository with
git clone https://github.com/easimon/tado-exporter.git. - Change to the checkout folder with
cd tado-exporter.
You can either build the JAR only, or a Docker image containing the application.
Executable JAR
- Install a JDK (tested with OpenJDK 17).
- Run
./mvnw packageto create an executable JAR (to be found intado-exporter/targetthen).
Docker Image
- Install Docker.
- Run
docker build . -t ghcr.io/easimon/tado-exporter:latestto create the Docker image.
Running
Choose one of the options below to run the exporter. The server then listens on port 8080 (plain HTTP), prometheus
metrics are available at http://host:8080/prometheus.
Executable JAR
Build the application as described above, and then run the following command:
$ TADO_USERNAME=your_username TADO_PASSWORD=your_password java -jar tado-exporter/target/tado-exporter-6.3.0.jar # x-release-please-versionDocker Container
Either build the application as described above, or download the Docker image.
$ export TADO_EXPORTER_IMAGE=ghcr.io/easimon/tado-exporter:6.3.0 # x-release-please-version
$ docker run -e TADO_USERNAME=your_username -e TADO_PASSWORD=your_password $TADO_EXPORTER_IMAGEConfiguration
The minimal required configuration is a valid Tado° username and password. For complete list of configurable items and their defaults, see the application.yml
| Environment variable | Description | Default | Required |
|---|---|---|---|
| TADO_USERNAME | Tado° account username | (none) | yes |
| TADO_PASSWORD | Tado° account password | (none) | yes |
| TADO_CLIENT_ID | API OAuth client ID | application.yml | no |
| TADO_CLIENT_SECRET | API OAuth client secret | application.yml | no |
| TADO_SCOPE | API OAuth Scope | application.yml | no |
| TADO_ZONE_DISCOVERY_INTERVAL | Interval to refresh home and zone (room) information for the given account | PT5m (5 min) | no |
OAuth client id, secret and scope do not need configuration, since they have defaults found at other projects listed in References.
Prometheus scraping config
scrape_configs:
- job_name: tado-exporter
metrics_path: /prometheus
scheme: http
static_configs:
- targets:
- tado-exporter:8080Grafana dashboard
There's a simple Grafana dashboard you can import. Since I don't know of a way to do I18N in Grafana, it's in German.
Available metrics
Defined in TadoMeterFactory.kt. There are also some other metrics (automatically provided by Micronaut framework), but these are the ones this application is about.
| Name | Tags | Cardinality | Description |
|---|---|---|---|
| is_resident_present | home_id | per home | whether there is a resident present in the home |
| solar_intensity_percentage | home_id | per home | solar intensity at your home's location, in percent |
| temperature_outside_celsius | home_id | per home | outside temperature at your home's location, in deg. celsius |
| temperature_outside_fahrenheit | home_id | per home | outside temperature at your home's location, in fahrenheit |
| temperature_measured_celsius | home_id, zone_id, zone_name, zone_type | per zone | measured temperature in this zone, in deg. celsius |
| temperature_measured_fahrenheit | home_id, zone_id, zone_name, zone_type | per zone | measured temperature in this zone, in fahrenheit |
| humidity_measured_percentage | home_id, zone_id, zone_name, zone_type | per zone | measured humidity in this zone, in percent |
| temperature_set_celsius | home_id, zone_id, zone_name, zone_type | per zone | target temperature in this zone, in deg. celsius |
| temperature_set_fahrenheit | home_id, zone_id, zone_name, zone_type | per zone | target temperature in this zone, in fahrenheit |
| heating_power_percentage | home_id, zone_id, zone_name, zone_type | per zone | heating power in this zone, in percent |
| is_window_open | home_id, zone_id, zone_name, zone_type | per zone | window open detection (presence of an "openWindow" object in the zone state, translated to 0, 1) |
| is_zone_powered | home_id, zone_id, zone_name, zone_type | per zone | power state (ON, OFF, translated to 0, 1) |
How it works
The exporter discovers all homes attached to a single Tado° account at startup, and refreshes the home and zone layout every 5 minutes by default. Then, metrics are collected for all discovered zones whenever they are requested by calling the prometheus metrics endpoint (at most every 55 seconds by default). I.e. the metrics are only refreshed on demand -- when the exporter is not scraped, it will only make the home/zone discovery requests every now and then.
References
- Tadoº exporter for Prometheus by Davide Ferrari
- OpenHAB Tado° Binding for Swagger API definition and OAuth client credentials.
- Tado API Guide by Terence Eden
- The Tado API v2 by Stephen C. Phillips
Known Issues and TODOs
- Test coverage is incomplete.
- Does not work on OpenJ9 variants of OpenJDK (Runs into stack overflows in tests, Jackson serialization yields empty Strings)
Disclaimer
This project is not affiliated with Tado° in any way. The API used here is not a public one, but reverse engineered by multiple people (see above). While it is used by quite a few other projects already, it might change incompatibly or vanish at any time.