tado° Smart Thermostat / AC
Control tado° heating and air-conditioning zones through the my.tado.com cloud API. tado° is a large-install-base residential and light-commercial climate system — wireless smart thermostats, smart radiator thermostats (TRVs), and IR-based AC control — with per-room smart schedules and geofencing managed in the tado° app.
One tado° home is the GEM device. Each zone in that home (a heating loop, a radiator
group, or an AC unit) becomes a GEM zone, addressed by its tado° zone id. GEM issues
overlays — manual overrides of the smart schedule — for power and setpoint, and can hand a
zone back to its schedule with resume_schedule.
Authentication
tado° uses OAuth2. In 2025 tado deprecated username/password login in favour of a device-code flow, so the driver's primary credential is a refresh token:
- Run tado's device-code authorization once — request a device code, open the returned verification URL in a browser, and approve access for the account.
- The flow returns an access token and a refresh token. Paste the refresh token into the driver.
- The driver exchanges the refresh token for a short-lived bearer token and rotates the refresh token automatically on every refresh, persisting the new value back to the device row. You should not need to touch it again unless the token is revoked.
The default client_id and token_url target tado's current device-code login host. tado has
changed these before. If a refresh fails with invalid_client, set client_id / token_url
to match the flow your refresh token was minted against — see tado's current OAuth
documentation.
Older accounts may still authenticate with username + password (OAuth2 password grant)
against the legacy https://auth.tado.com/oauth/token host using the tado-web-app client and
its public client secret. Set username, password, client_id, client_secret, and
token_url accordingly. tado deprecated this path and it may stop working without notice —
prefer the refresh-token flow.
Prerequisites
- A tado° account with at least one Heating or Air Conditioning zone configured in the tado° app.
- An OAuth2 refresh token for the account (see Authentication above).
- Outbound HTTPS from the GEM server to
my.tado.comand the tado login host.
Setup steps
- Go to Devices → Add Device and choose the tado° (Smart Thermostat / AC) driver.
- Paste the OAuth Refresh Token. Leave Home Id blank to auto-detect the first home on the account.
- Set Temperature Unit to match how you want setpoints expressed (
celsiusorfahrenheit). - Save. The driver exchanges the refresh token for a bearer token and resolves the home id.
- Run get_devices to list the tado° zones and their ids.
- Create a GEM zone per tado° zone and set the zone Address to the tado° zone id.
Attributes
Device
| Attribute | Type | Required | Description |
|---|---|---|---|
refresh_token | string (secure) | yes | OAuth2 refresh token from the device-code flow. Rotated automatically. |
home_id | string | no | tado° home id. Blank → auto-detect the first home via /me. Set explicitly for multi-home accounts. |
temperature_unit | string | no | celsius (default) or fahrenheit — the unit for setpoints and readings. |
username | string | no | Account email — legacy password-grant fallback only. |
password | string (secure) | no | Account password — legacy password-grant fallback only. |
client_id | string | no | OAuth client id. Default targets the device-code flow; override for legacy grant. |
client_secret | string (secure) | no | OAuth client secret — legacy password-grant client only. Blank for device-code. |
token_url | string | no | OAuth2 token endpoint. Default is tado's current login host; use https://auth.tado.com/oauth/token for legacy grant. |
status_interval | int | no | Poll interval per zone, in ms. Default 30000, minimum 10000. |
Zone
Zones need only an Address. The driver writes these read-only state attributes as it polls:
| Attribute | Meaning |
|---|---|
state | on or off — the zone's current overlay/schedule power. |
system_mode | For AC zones: cool / heat / dry / fan / auto. For heating zones: heat when on, off when off. |
setpoint | Target temperature in the configured unit. |
temperature | Measured room temperature (inside sensor). |
humidity | Measured relative humidity (%). |
Zone address format
The zone Address is the tado° zone id — a small integer unique within the home. Run
get_devices to list each zone's id, name, and type (HEATING, HOT_WATER, or
AIR_CONDITIONING).
Commands
| Command | Args | Notes |
|---|---|---|
on | address, temperature | Manual overlay ON. Heating uses temperature if given, else the zone's last setpoint (falling back to 21 °C / 70 °F). AC preserves its current mode. |
off | address | Manual overlay OFF (frost protection on heating). |
set_temperature | address, value | Manual overlay ON at value, in the zone's temperature unit. |
set_mode | address, mode | AC zones only: cool / heat / dry / fan / auto. |
resume_schedule | address | Removes the overlay and returns the zone to its tado° smart schedule. |
get_devices | — | List the tado° zones in the home. |
get_status | address | Read live state for one zone, or all zones when address is omitted. |
All overlays are created with MANUAL termination — they hold until changed or until
resume_schedule is issued. (Timer- and schedule-scoped terminations are a possible future
addition.)
Known limitations
- Heating needs a setpoint to turn on. A tado° heating overlay cannot be "ON" without a
target temperature.
onreuses the zone's last setpoint when you do not pass one; if the zone has never had one, it defaults to 21 °C (70 °F). - Fan / dry AC modes take no temperature.
set_mode fan/set_mode dryomit the setpoint, as tado° expects. - Cloud-only. tado° exposes no documented local API, so control depends on the my.tado.com cloud and outbound internet from the GEM server. There is no LAN fallback.
- Smart-schedule edits are out of scope. This driver overrides the schedule with overlays and can clear them; editing the weekly schedule blocks themselves is not implemented.
- No hot-water / boiler control yet.
HOT_WATERzones are enumerated but only the heating/AC overlay shape is wired; dedicated hot-water commands are a follow-up.
Troubleshooting
| Symptom | Check |
|---|---|
invalid_grant on connect | The refresh token expired or was already rotated by another client. Re-run the device-code flow and update refresh_token. |
invalid_client on connect | client_id / token_url do not match the flow the token was minted against. Align them with tado's current OAuth docs. |
get_devices returns empty | home_id points at a home with no zones, or the account has multiple homes. Set home_id explicitly. |
| Heating zone will not turn on | Pass a temperature on set_temperature, or ensure the zone has a prior setpoint for on to reuse. |
| State never updates | Confirm outbound HTTPS to my.tado.com is allowed and status_interval is not set unreasonably high. |
Related Documentation
- Devices
- Zones
- Sensibo — a comparable single-setpoint cloud AC integration.