Skip to content

A Prometheus exporter for Tado° smart thermostats

Notifications You must be signed in to change notification settings

easimon/tado-exporter

Repository files navigation

Tado exporter

Docker Build

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 package to create an executable JAR (to be found in tado-exporter/target then).

Docker Image

  • Install Docker.
  • Run docker build . -t ghcr.io/easimon/tado-exporter:latest to 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-version

Docker 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_IMAGE

Configuration

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:8080

Grafana 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.

Grafana Dashboard

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

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.