Tado X Support Plan for tadoasync (Strategy Split + Canonical Models)

[micsco]

Hi @erwindouna — I put together this RFC after seeing how well other projects document bigger changes and because I wanted to sanity-check my own approach. I leaned on LLMs for some of the research/writing scaffolding, but everything here is heavily edited and I’ve done my best to keep it free of AI-slop. Please treat this as a friendly proposal rather than a finished spec; I’m keen to hear what you think. I originally hoped to land this in the upstream pyTado library, but given your ongoing Home Assistant core work (especially home-assistant/core#151933), I figured it made more sense to collaborate directly here. Selfishly, I just finished a home renovation and switched my entire house over to Tado X, so I’m motivated to help unblock support.

1. TL;DR

• Split tadoasync into a shared engine plus plug-in strategies so it can talk to both my.tado.com and hops.tado.com without exposing branching to callers.
• Make the Tado X naming (“rooms”, “room state”, etc.) the canonical interface, keeping the existing zone helpers as temporary aliases for downstream projects.
• Let Home Assistant (and anyone else) pass home_id + generation during setup, skipping redundant discovery calls while picking up the new canonical helpers (with caching/instrumentation hooks to respect Tado’s rate limits).

2. Background & Goals

Tado confirmed in GitHub issue #151223 that Tado X is the long-term platform and that cloud usage will be rate-limited. Right now Home Assistant only talks to the legacy API via tadoasync, so brand-new Tado X installs show nothing. The missing pieces:

• Discovery: Tado X “rooms” never map to HA climates.
• Control: Manual overrides, resume schedule, and quick actions live only on hops.tado.com.
• Schedules & modes: Matter lacks schedule, holiday, away-mode, and DHW management, so users lose core automation features.

Goals

1. Add full support for hops.tado.com without breaking existing consumers.
2. Adopt Tado X terminology as the canonical API, with adapters and a clear deprecation path for the legacy helpers.
3. Keep rate-limit guardrails (measurement, caching, throttling hooks) in mind so HA can stay within Tado’s published limits once the refactor ships.

Non-goals Firmware reverse-engineering, Matter/HomeKit feature parity, or UX redesign beyond collecting home_id + generation.

3. Architecture Overview

Here’s how I picture the moving parts fitting together.

3.1 Shared Engine

• Tado stays the public entry point and now owns authentication, the master _request, caching hooks, and instrumentation.
• The engine performs startup tasks once (token exchange, bootstrap calls) and shares the responses with whichever strategy is active so duplicated requests are avoided.

3.2 Pluggable Strategies

• TadoHomeStrategy defines the contract for home-scoped actions (async_get_rooms, async_set_manual_control, etc.).
• LegacyHomeStrategy keeps the current my.tado.com logic.
• HopsHomeStrategy adds the hops.tado.com implementation.
• Both strategies must emit canonical “room” models so downstream code stops branching on hardware generation.

flowchart LR
    Client(["Client (Home Assistant)"]) --> Engine["Tado Engine<br/>(auth, cache, metrics)"]
    Engine --> Detect{"Strategy selection"}

    Detect -->|"Caller supplied<br/>home_id + generation (legacy)"| Legacy["LegacyHomeStrategy<br/>(my.tado.com)"]
    Detect -->|"Caller supplied<br/>home_id + generation (LINE_X)"| Hops["HopsHomeStrategy<br/>(hops.tado.com)"]
    Detect -->|"Need metadata"| MeAPI["GET /api/v2/me<br/>+ /api/v2/homes/{id}"]

    MeAPI --> Gen{"generation == LINE_X?"}
    Gen -- yes --> Hops
    Gen -- no --> Legacy

    Hops -->|"canonical rooms, etc."| Engine
    Legacy -->|"canonical rooms, etc."| Engine
    Engine --> Client

Loading

3.3 Strategy Selection Flow

The selection logic mirrors the Tado web client: rely on the generation flag exposed by GET /api/v2/me (and the follow-up GET /api/v2/homes/{id}), which always comes from my.tado.com regardless of hardware generation. No calls to hops.tado.com/homes/{id} are required for detection.

Input available	Decision	Extra calls?
Caller supplies home_id + home_generation	Instantiate the matching strategy immediately.	None
GET /api/v2/me / GET /api/v2/homes/{id} reports generation == "LINE_X"	Choose HopsHomeStrategy and mark supports_tadox = True.	Baseline bootstrap calls (already required)
generation exists but is not LINE_X	Choose LegacyHomeStrategy.	Baseline bootstrap calls

The chosen strategy flag is cached on the Tado instance so detection happens once per session, and trusted clients can avoid even that by supplying metadata up front.

4. Capability Coverage

Core capabilities (derived from the Tado web-client capture) that both strategies must expose:

Capability	Legacy Surface	Tado X Surface	Notes
Room list / room state	/api/v2/homes/{id}/zones, /zones/{id}/state	/homes/{id}/rooms, /rooms/{id}	Legacy zones helpers adapt canonical Room models. New rooms helpers return canonical models directly.
Manual control & resume schedule	/zones/{id}/overlay, /zones/{id}/overlay DELETE	/rooms/{id}/manualControl, /rooms/{id}/resumeSchedule, /quickActions/*	Legacy overlay methods are adapted from new manualControl and quickActions canonical methods.
Smart schedule CRUD	/zones/{id}/schedule	/rooms/{id}/schedule	A unified schedule API will abstract the different PATCH/PUT behaviors.
Domestic hot water	/hotWater/* endpoints	/programmer/domesticHotWater/*	A unified DHW API will call the correct underlying strategy.
Away / holiday / OWD / flow-temp settings	/homes/{id}/settings/*	/homes/{id}/settings/*	A unified settings API will abstract host and endpoint differences.
Presence lock / quick actions	/presenceLock	/quickActions/{action}	A unified quick actions API will map to legacy presenceLock where applicable.

5. Model Strategy & Open Questions

Tado have stated in multiple forums that legacy devices are not being deprecated today, although the feature velocity clearly favours Tado X. I propose leaning toward Tado X terminology, but I also want feedback on whether that is the right long-term bet or whether a “neutral” naming scheme would serve the community better.

5.1 Proposed approach

• Default behaviour (non-breaking): Every strategy converts its native responses into the existing legacy data classes (e.g., Zone, ZoneState) via adapters. This keeps Home Assistant and downstream projects stable while I introduce the new nomenclature in parallel.
• Canonical helpers: I propose exposing async_get_rooms(), async_get_room_state(), etc., returning new Room, RoomState, ManualControlRequest models that match the Tado X payloads and aggregate the superset of fields.
• Legacy aliases and deprecation: Legacy methods such as async_get_zones() would call the canonical helpers and down-convert. I propose marking the legacy names as deprecated once Home Assistant and other major consumers migrate, targeting removal in a future major release.
• Transparency for Home Assistant: Home Assistant would switch to the canonical helpers as soon as they land so both hardware generations appear consistently as “rooms” and no HA-side branching is required.

5.2 Open question

• Given Tado’s stance (legacy supported but not evolving), should the canonical naming lean fully into Tado X terms, or should the project define a neutral naming layer (e.g., HomeRoom) to avoid picking sides? Feedback here will shape the adapter and deprecation timeline.

The adapters, canonical dataclasses, and aliasing utilities will live beside the new tadox_models package described earlier.

6. Implementation Plan

PR	Objective	Key outputs
1	Core refactor & instrumentation	TadoHomeStrategy, LegacyHomeStrategy, shared cache + metrics hooks, baseline call-count doc
2	Detection & feature flagging	Detection via GET /api/v2/me + GET /api/v2/homes/{id}, cached supports_tadox, constructor overrides (home_id, home_generation), detection tests
3	HopsHomeStrategy + canonical models	HopsHomeStrategy, tadox_models, canonical room dataclasses, *_canonical() helpers, adapters
4	Capability rollout	Iterative support for quick actions, DHW, settings, schedules, room ordering (with fixtures + tests)
5	Consumer guidance	Docs covering constructor changes, canonical API usage, rate-limit considerations, migration checklist
6	Home Assistant migration & deprecation	HA integration updated to canonical APIs, deprecation warnings for zone methods, removal timeline

I welcome all feedback on this proposal.

8. Appendices

Appendix A – Data source

All capability notes in this RFC come from a fresh capture of the official Tado web client while operating a Tado X installation. The raw capture is private, but I’m happy to share an anonymised version if anyone needs it; key findings are summarized here and fixtures will ship with the implementation PRs.

Appendix B – Example usage (post-refactor)

from tado import Tado, HomeGeneration

tado = Tado(
    username="user@example.com",
    password="secret",
    home_id=1721801,
    home_generation=HomeGeneration.TADO_X,
)

rooms = await tado.async_get_rooms()
living_room = next(room for room in rooms if room.name == "Living Room")

await tado.async_set_manual_control(
    room_id=living_room.id,
    control=tado.manual_control(
        temperature_c=21.5,
        termination="NEXT_TIME_BLOCK",
    ),
)
await tado.async_resume_room_schedule(living_room.id)

Legacy consumers can continue calling async_get_zones() until they switch to the canonical helpers.

[erwindouna]

You really put some great effort in this RFC, thanks @micsco ! I'll have to find time to read through and give it the time it deserves - but it's on my list! :)

[micsco]

No worries, thanks @erwindouna

[erwindouna]

Overall I think this makes sense and there's a long desire from the community to integrate Tado X. From the library's perspective that's a technical capability we can facilitate. It will put a burden on ones API rate limit, but that's the personal choice people can make. :)
From HA's perspective that brings in a bit more sensitivity and complexity: Tado's biggest wish is to leverage on the Matter protocol as much as possible and before being able to utilize the Tado X in the Tado integration we need something to map it with. That something being the MAC address and it's on a list to get into Tado's API one day.

I do have a question on the home ID and generation: why do users need to supply this manually? From a library point of view this could make sense, but from a user experience if integrated in HA, it would be another step to manually perform. Provided we update the instructions, there are some users who're tech savy enough to easily obtain it, others will have difficulties. The goal should be that the more we can automate, the better. :)