Tado Hijack for Home Assistant 🏴‍☠️

An optimized Tado integration designed to handle strict API limits through intelligent quota management and command batching.

🆚 Comparison • 🚀 Highlights • 📊 API Strategy • 🛠️ Architecture
📦 Installation • ⚙️ Configuration • 📱 Entities • ⚡ Services
📋 Constraints • 🐛 Troubleshooting • ❓ FAQ • 📚 Docs • ☕ Support

Overview

Tado Hijack is engineered to maintain your smart home functionality regardless of strict API limits. It uses adaptive polling and command batching to stay within quota constraints.

It is designed to work alongside your local HomeKit (v3) or Matter (Tado X) integrations. Use local protocols for temperature control, and Tado Hijack for cloud-only features (Schedules, Hot Water, AC Pro, Hardware Settings, and Indoor Climate Sensors).

Note

High API Usage is Expected: Auto Quota dynamically consumes the available quota to provide the fastest possible updates. If the daily limit is reduced by Tado, the system will automatically slow down to prevent account locks.

Key Features:

Auto API Quota: Dynamically adjusts polling intervals based on your remaining daily API calls and detects your account's specific reset time.
Command Batching: Fuses multiple concurrent commands into a single API call.
Multi-Generation Support: Full support for V2 (GW bridges), V3 Classic (HomeKit), and Tado X (Matter) within a unified architecture.
Device Unification: Injects cloud features into existing HomeKit devices (V3 only).
Indoor Climate Sensors: Calculates dew point, absolute humidity, and mold risk per zone.
Night-Savings (Economy Window): Slows down polling during the night to save API calls for daytime use.

Feature Comparison

Feature	Official Tado	HomeKit (v3)	Tado Hijack
Temperature Control	✅	✅	🔗 (HK/Matter) / ☁️ (V2 Cloud Mode)
Boiler Load / Modulation	✅	❌	✅ Yes
Hot Water Power & Temp	✅	❌	✅ Full
Smart Schedules Switch	✅	❌	✅ Yes
AC Pro (Fan/Swing)	✅	❌	✅ v3 only
Child Lock / OWD / Early	✅	❌	✅ Yes
Indoor Climate Sensors	❌	❌	✅ All Gens
Local Control (v3)	❌	✅	✅ (via HK Link)
Tado X Support	❌	✅ (Matter)	✅ Local + Cloud
Multi-Generation Support	❌	v3 only	✅ v3 / X / v2
Device Unification	❌	❌	✅ V3 only
Dynamic Presence-Aware Overlay	❌	❌	✅ Exclusive
Auto Quota (Weighted)	❌	N/A	✅ Yes
Economy Window (Night Mode)	❌	N/A	✅ Yes
Command Batching	❌	N/A	✅ Extreme (1 Call)
API Quota Visibility	❌	N/A	✅ Real-time
Privacy Redaction (Logs)	❌	N/A	✅ Strict

Important

🌟 Local Matter Control for Tado X: Tado Hijack is the first and only integration that combines Matter local control with Tado X cloud features!

Other integrations: Support Tado X only via full cloud (no local control, 100% API dependent)
Tado Hijack: Uses Matter for local temperature control + cloud API for advanced features (Schedules, QuickActions, etc.)

We support BOTH Tado v3 Classic (HomeKit) AND Tado X (Matter) through a unified architecture. Note: Some features are v3-specific (Hot Water, AC, Early Start) due to hardware limitations.

Generation Support: V2, V3 Classic & Tado X

Quick Reference: This integration supports V2 (GW bridges), V3 Classic (HomeKit), and Tado X (Matter).

Feature Category	V2 (GW)	v3 Classic	Tado X	Notes
Temperature Control	☁️	✅	✅	All: Cloud mode available / V3: HomeKit / X: Matter
Hot Water	✅	✅	❌	Cloud API + water_heater entity
AC Pro (Fan/Swing)	✅	✅	❌	Cloud API + climate entity
QuickActions (Bulk)	✅	✅	✅	boost/off/resume = 1 call
set_mode_all (Bulk)	✅	✅	❌	v3=1 call, X=N calls
Hardware Settings	✅	✅	✅	Child Lock, Offset, etc.
Indoor Climate Sensors	❌	✅	✅	Dew point, mold risk, AH, ventilation. v3: built-in fallback. Tado X: link temperature source on zone device.

See FAQ for detailed setup instructions and temperature source configuration.

Key Highlights

Extreme Batching Technology

While other integrations waste your precious API quota for every tiny interaction, Tado Hijack features Deep Command Merging. We collect multiple actions and fuse them into a single, highly efficient bulk request.

Tip

Maximum Fusion Scenario: Triggering a "Party Scene": AC living_room (Temp + Fan + Swing) + AC kitchen (Temp + Fan) + Hot Water (ON).

❌ Standard Integrations: 6-8 API calls (Half your hourly quota gone). ✅ Tado Hijack: 1 single API call for everything.

Note: This works within your configurable Debounce Window. Every action is automatically fused.

Important

Universal Batching: This applies to manual dashboard interactions AND automated service calls (like set_mode). 10 changes at once? Still only 1 API call.

The Local "Missing Link"

We don't replace local control. We enhance it.

For V3 (HomeKit): Tado Hijack detects your existing HomeKit devices and injects cloud-only features directly into them — creating one unified device with both local control and cloud power-features.

For Tado X (Matter): Matter doesn't expose serial numbers for device linking, so Tado Hijack features appear as separate entities alongside your Matter climate entities.

Important

Hybrid Architecture: This integration is designed to work alongside native local control:

Tado v3 Classic: Works with HomeKit Device integration (provides climate entity for local temperature control)
Tado X: Works with Matter integration (provides climate entity for local temperature control)
Tado Hijack: Provides the "Missing Links" for both generations (Schedules, Hot Water, AC Modes, Hardware Settings)
- V3 Bonus: Device Unification (features injected into HomeKit devices)

Note: Full Cloud Mode provides climate entities via API polling but consumes API quota for temperature changes. See Full Cloud Mode for details.

Note

No Redundancy (Default Mode): By default, Tado Hijack does not create climate entities, as local protocols (HomeKit/Matter) already handle temperature control efficiently. We focus on cloud-only features: Schedules, Hot Water, AC Modes, Hardware Settings.

Full Cloud Mode: Optionally enables cloud-polling climate entities, but consumes API quota for every temperature change. Only recommended for V2 bridges (20k calls/day) or users without HomeKit/Matter access.

Cloud Features (Non-HomeKit)

🚿 Professional Hot Water Platform: Native water_heater entity with standardized auto, heat, and off modes. Full Pre-Validation ensures you never send invalid configurations.
❄️ AC Pro Features: Precise Fan Speed and Swing (Horizontal/Vertical) selection.
📅 Schedule Transparency: View the target temperature of your active Smart Schedule directly via the auto_target_temperature attribute while in auto mode (available for Heating, AC and Hot Water).
🕵️‍♂️ Expert-Level Error Capturing: Captures the actual response body from Tado's API (e.g. "temperature must not be null"), giving precise feedback for troubleshooting.
🔥 Valve Opening Insight: View the percentage of how far your valves are open (updated during state polls).
🔋 Real Battery Status: See the actual health of every valve.
🌡️ Temperature Offset: Interactive calibration for your thermostats.
✨ Dazzle Mode: Control the display behavior of your V3+ hardware.
🏠 Presence Lock: Force home or away globally via the presence_mode select entity. Set to auto to hand control back to Tado's own geofencing. Note: Handing control back to Tado via auto requires a Tado Auto-Assist subscription. If you don't have Auto-Assist, use home or away to manually lock the presence state via your own HA automations.
🔥 Dynamic Presence-Aware Overlay: Set temperatures specifically for the current presence state — automatically resets once your home presence changes.
🌡️ Indoor Climate Intelligence: Per-zone sensors for dew point, mold risk (level + binary), indoor absolute humidity, and ventilation recommendation. Calculated from room temperature and humidity using the Magnus formula and EU building-physics thresholds. Available for both v3 Classic and Tado X.
🔓 Rate Limit Bypass: Support for local tado-api-proxy.

State Integrity & Robustness

Tado Hijack implements enterprise-grade state management to ensure your settings never get lost or overwritten:

💾 State Memory: AC fan speed, swing positions, and target temperatures survive Home Assistant restarts. No more "reset to default" frustration.
🔒 Field Locking: Prevents concurrent API calls from overwriting each other. Change fan speed, then swing, then temperature in rapid succession — all settings are preserved.
🎯 Pending Command Tracking: Rapidly clicking temperature buttons (+/-) or dragging a slider? Multiple UI events collapse into 1 API call with the final value. Zero waste, zero duplicates.
⏮️ Rollback on Error: If an API call fails (e.g., invalid payload), the UI automatically reverts to the previous state with a clear error message. No "ghost states" where the UI lies about what's active.
🧵 Thread-Safe Queue: All write operations pass through a single serialized queue. Automations, dashboard changes, and service calls never conflict or race.

Tip

tado-api-proxy TL;DR: The proxy acts as a local cache and authentication handler. It allows you to use your integration without being strictly bound to Tado's cloud limits.

Run the Docker Container.
Set your API Proxy URL in Hijack Options (e.g., http://192.168.1.10:8080).
Enjoy unlimited local-like polling (safety floor still applies).

API Consumption Strategy

Tado's API limits are restrictive. That's why Tado Hijack uses a Zero-Waste Policy.

API Consumption Table

Action	Cost	Frequency	Description	Detailed API Calls
Zone Poll	1	Adaptive	HVAC, Valve %, Humidity.	`GET /homes/{id}/zoneStates`
Presence Poll	1	12h (Default)	Home/Away presence state.	`GET /homes/{id}/state`
Hardware Sync	2+	24h (Default)	Syncs battery, firmware and device list.	`GET /homes/{id}/zones` `GET /homes/{id}/devices` `GET /zones/{id}/capabilities`
Refresh Zones	2	On Demand	Updates zone/device metadata.	`GET /homes/{id}/zones` `GET /homes/{id}/devices`
Refresh Offsets	1–N	On Demand	Fetches device offsets. 1 call with `entity_id`, N without.	`GET /devices/{s}/temperatureOffset` (×1 or ×N)
Refresh Away	1–M	On Demand	Fetches zone away temps. 1 call with `entity_id`, M without.	`GET /zones/{z}/awayConfiguration` (×1 or ×M)
Zone Overlay	1	On Demand	Fused: All zone changes in 1 call.	`POST /homes/{id}/overlay`
Presence	1	On Demand	Force presence lock (home/away=PUT, auto=DELETE).	`PUT /homes/{id}/presenceLock` `DELETE /homes/{id}/presenceLock`

Note: Endpoints shown are v3 API. Tado X uses different endpoints (Hops API) but similar polling logic. See Generation Support for differences.

Tip

API Optimization Features:

Zero Waste Writes: Commands don't trigger a poll. We use Local State Patching to update the UI instantly without confirmation calls.
Throttled Mode: When quota runs low, periodic polling auto-disables to preserve quota for your automations.
Granular Refresh: Hardware configs (Offsets, Away Temps) are never fetched automatically — only on-demand when you need them.

Auto API Quota & Economy Window

Tado Hijack features a self-optimizing quota management system that distributes your available API calls across the day.

Core Mechanics

Adaptive Polling: Automatically calculates and adjusts the background polling interval based on your remaining daily API quota and the time left until the next reset.
Threshold Protection: You can configure a "Throttle Threshold" (default: 20 calls). This quota is reserved exclusively for external automations, scripts, and manual app usage. Background polling will pause if this threshold is reached, ensuring manual actions still work.
Night-Savings (Economy Window): Configure an Economy Window (e.g., 23:00 - 07:00) to slow down or pause polling during sleep hours. The system reinvests these saved calls into faster updates during your active hours.
Adaptive Reset Learning: Tado's quota reset time varies by user. The integration learns your specific reset schedule by observing reset patterns and optimizes the budget distribution accordingly (planning at least 20 hours ahead).
Proxy Support: Fully compatible with the local tado-api-proxy. The system will automatically optimize polling for the higher quota limits provided by the proxy.

Adaptive Behavior & Safety

Your polling interval scales dynamically:

Performance Phase: While active, updates can arrive as fast as every 20s (or 120s if using a proxy).
Economy Phase: During your sleep window, polling drops to a heartbeat or pauses completely.
Safety Floor: To protect your account, minimum intervals are strictly enforced (Standard: 5s, Proxy: 120s).

Batching Capability Matrix

Not all API calls are created equal. Tado Hijack optimizes everything, but physics (and the Tado API) sets limits.

Action Type	Examples	Strategy	API Cost
State Control	Target Temp, Turn Off All, Resume Schedule, Hot Water Power, AC Fan	FUSED	1 Call Total (regardless of zone count)
Global Mode	Home/Away Presence	DIRECT	1 Call
Zone Config	Early Start, Open Window, Dazzle Mode	DEBOUNCED	1 Call per Zone (Sequentially executed)
Device Config	Child Lock, Temperature Offset	DEBOUNCED	1 Call per Device (Sequentially executed)

Fused (True Batching): Multiple actions across multiple zones are merged into a single API request. Example: Turning off 10 rooms at once = 1 API Call.

Debounced (Rapid Update Protection): Prevents spamming the API during rapid interactions (like clicking buttons or dragging sliders). Only the final value is sent. Example: Rapidly clicking a temperature button or dragging a slider from 18°C to 22°C generates multiple events, but only 1 API Call is sent.

Note

Exceptions: Device configs (Child Lock, Offset) require individual API calls per device. See Services table for complete API impact breakdown.

Architecture

Physical Device Mapping & Resolution

Unlike other integrations that group everything by "Zone", Tado Hijack maps entities to their physical devices (Valves/Thermostats).

Matched via Serial Number: Automatic injection into existing HomeKit devices.
EntityResolver: A specialized engine that deep-scans the Home Assistant registry to perfectly link HomeKit climate entities with Tado's cloud logical zones.
No HomeKit? We create dedicated devices containing only the cloud features (Battery, Offset, Child Lock, etc.), but no temperature control.

Robustness & Security

JIT Poll Planning: Uses high-precision timestamps instead of simple flags to decide exactly when a data fetch is required (Zero-Waste).
Monkey-Patching Utilities: We actively fix tadoasync library limitations at runtime, including robust deserialization for tricky cloud states (like nextTimeBlock null errors).
Custom Client Layer: Extended underlying library via inheritance to handle API communication reliably and fix common deserialization errors.
Safety Throttle (Anti-Spam): If the Tado API reports an invalid limit (e.g., <= 0 during outages), the integration automatically throttles to a 5-minute safety interval and logs a warning to prevent rapid re-polling.
Authenticated Proxy Support: Fully supports path-based authentication for the API Proxy, ensuring your external communication remains secure and private.
Persistent Reconnect & Recovery: When the API quota is exhausted (throttled), the system performs a recovery check every 15 minutes (reduced from 1h) to ensure immediate resumption of services as soon as the API becomes available or the quota resets.
Privacy by Design: All standard logs and diagnostic reports are automatically redacted. Sensitive data is stripped before any output is generated. (See Expert-Level Diagnostics for details).
🎭 Pattern Obfuscation: Multi-Level Jitter (Poll & Call) breaks temporal correlation between Home Assistant triggers and API requests to avoid pattern-based throttling (Proxy only).

Installation

Caution

Remove the Official Tado Integration: You MUST remove the official Home Assistant Tado integration before installing Tado Hijack. Keeping both active will cause conflicting commands and double your API quota consumption, likely leading to account locks.

Via HACS (Recommended)

Tado Hijack is now an official HACS integration! No custom repository needed.

Open HACS -> Integrations.
Search for "Tado Hijack" and click Download.
Restart Home Assistant.
Go to Settings -> Devices & Services -> Add Integration -> Search for "Tado Hijack".
Select your hardware generation (determined by your physical Tado bridge):
- Tado v3 Classic - If you own an IB01 or GW01 bridge (black square box)
- Tado X - If you own a Bridge X (IB02) (newer Matter-based system)

Important

Hardware Generation: Select your generation during setup based on your physical bridge: IB01/GW01 = v3 Classic, IB02 = Tado X. If unsure, choose v3 Classic (most common). See Generation Support for feature differences.

Configuration

Option	Default	Description
Status Polling	`30m`	Base interval for room states. Note: Dynamically overridden by Auto API Quota when enabled; serves as fallback during throttling or budget exhaustion.
Presence Polling	`12h`	Interval for Home/Away state. High interval saves mass quota. (1 API call)
Auto API Quota	`80%`	Target X% of FREE quota. Note: The official API is currently limited to 1,000 calls/day. Using the API Proxy bypasses this limitation, granting 3,000 calls per account. Uses a weighted profile to prioritize performance hours.
Reduced Polling Active	`Off`	Enable the time-based weighted polling profile.
Reduced Polling Start	`22:00`	Start time for the economy window (e.g. when you sleep).
Reduced Polling End	`07:00`	End time for the economy window.
Reduced Polling Interval	`3600s`	Polling interval during the economy window. Set to 0 to pause polling entirely.
Hardware Sync	`86400s`	Interval for battery, firmware and device metadata. Set to 0 for initial load only.
Offset Update	`0` (Off)	Interval for temperature offsets. Costs 1 API call per valve.
Min Polling Window	`20s`	Performance Floor: The absolute fastest speed Auto Quota will poll (5s-12h, default: 20s).
Debounce Time	`5s`	Batching Window: Fuses actions into single calls.
Refresh After Resume	`On`	Auto-refresh target temperature/state after resume schedule (HVAC AUTO). Required because schedules are Tado cloud-side. Uses 1s grace period to merge multiple resumes. Costs 1 API call.
Throttle Threshold	`20`	External Protection Buffer: Reserve N calls for everything outside of Hijack's periodic background polling (External Automations, Scripts, Manual App use). Polling stops when remaining quota hits this floor to ensure your automations never stall.
Quota Safety Reserve	`2`	Reset Window Bridge: API calls reserved from quota percentage for the ±1h window around the expected reset time. Distributed evenly during the window to bridge uncertainty when reset time varies (e.g., 11:05 vs 11:30 UTC). Set to 0 to disable (not recommended).
Disable Polling When Throttled	`Off`	Stop periodic polling entirely when throttled.
API Proxy URL	`None`	Advanced: URL of local `tado-api-proxy` workaround.
API Proxy Token	`None`	Security: Authentication token for your proxy. Injected into the path (`/token/api/v2`).
Call Jitter	`Off`	Anti-Ban Protection: Adds random delays before API calls to obfuscate automation patterns (Proxy only).
Jitter Strength	`10%`	The percentage of random variation applied to intervals and delays (Proxy only).
Log Level	`INFO`	Control integration verbosity (DEBUG, INFO, WARNING, ERROR).
Show Version in Logs	`On`	Prepends `[vX.Y.Z]` to every log message from this integration. Makes the running version immediately visible in any log snippet — useful when sharing logs for support.
Suppress Redundant Calls	`Off`	API Optimization: Skip API calls when target state matches cached state (temperature, mode, presence, power). Saves quota on accidental double-clicks or UI interactions. Only sends when actual change detected. Values not in cache always send.
Suppress Redundant Buttons	`Off`	Aggressive Optimization: Also skip button actions (resume_all, boost_all, turn_off_all, set_mode_all) when ALL zones already match target state. Requires 'Suppress Redundant Calls' to be enabled. Individual explicit actions always send.
Dew Point Sensor	`On`	Create a dew point temperature sensor per zone (Magnus formula, T + RH). v3: falls back to cloud zone state. Tado X: requires a linked temperature source on the zone device.
Mold Risk Sensors	`On`	Create a mold risk level sensor (`none`/`low`/`medium`/`high`) and a binary moisture sensor per zone. Uses dew point spread — correctly distinguishes cold-but-dry from cold-and-humid rooms.
Outdoor Weather Entity	`None`	Select a weather entity providing outdoor temperature + humidity. When set, creates an indoor absolute humidity sensor (g/m³) and a ventilation recommendation binary sensor per zone.
Ventilation Threshold	`1.0 g/m³`	Minimum indoor-outdoor AH difference required before Ventilation Recommended turns ON. Prevents automation chatter from negligible differences.
Temperature Source (per zone)	`Automatic`	Optional: link a temperature `sensor` or `climate` entity as the data source for indoor climate sensors. Set via `select.zone_temp_source` on each zone device. Required for Tado X (cloud has no temp in Full-Matter mode).
Humidity Source (per zone)	`Automatic`	Optional: link a `climate` entity (reads `current_humidity`) or a humidity `sensor` as the data source for indoor climate sensors. Set via `select.zone_humidity_source` on each zone device. Fallback: cloud zone state humidity.

Zone Temperature & Humidity Sources (All Generations)

Each zone device exposes two optional source selectors that override the data used for indoor climate calculations (dew point, mold risk, absolute humidity, ventilation recommendation):

Select Entity	Purpose	Accepted types
`select.zone_temp_source`	Temperature override for the zone	Any `climate` or temperature `sensor`
`select.zone_humidity_source`	Humidity override for the zone	Any `climate` (reads `current_humidity`) or humidity `sensor`

Fallback chain when no source is selected:

Priority	Temperature fallback	Humidity fallback
1. Select Entity	Entity chosen in `select.zone_temp_source`	Entity chosen in `select.zone_humidity_source`
2. Connected Climate	Associated Climate Entity (Full-Cloud or mapped HomeKit)	Tado Hijack Humidity Sensor (`sensor.X_humidity`)
3. Cloud API	`sensor_data_points.inside_temperature` (All Gens)	`sensor_data_points.humidity` (All Gens)

Tip

For Tado X: The integration falls back to cloud temperature data out-of-the-box. However, because Matter devices hide their serial numbers in Home Assistant, they cannot be auto-linked like v3 HomeKit devices. We highly recommend manually linking your Matter climate entity (e.g., climate.living_room) via the select.zone_temp_source. This ensures your indoor climate sensors update in real-time via local Matter push updates, rather than waiting for slower API polling.

Note

For v3 Classic, linking sources is optional. The built-in HomeKit linkage and zone state provides both temperature and humidity automatically. Link an external sensor only if you want higher precision or a different measurement point.

Changes take effect on the next coordinator update — no integration reload required.

Full Cloud Mode (All Generations)

Warning

Full Cloud Mode: When to Use It

Full Cloud Mode creates climate entities via cloud polling instead of HomeKit/Matter integration.

✅ RECOMMENDED FOR:

V2 Bridges (GW) - These lack HomeKit/Matter support, making Full Cloud Mode the only option for climate entities
V2 bridges have ~20,000 calls/day which makes cloud polling viable

⚠️ USE WITH CAUTION:

V3 Bridges (IB01/GW01) - Currently 1k calls/day, reducing to 100 soon
Tado X (IB02) - Currently 1k calls/day, reducing to 100 soon
Recommendation: Use HomeKit (V3) or Matter (X) integration instead — no API cost, local control
Full Cloud Mode is technically supported for all generations but not recommended for V3/X due to quota limits

⚠️ API QUOTA IMPACT:

Every temperature change = 1 API call
V2: ~20k calls/day makes cloud polling sustainable
V3/X: 1k calls/day (soon: 100) exhausted quickly by temperature changes
Best Practice: Use HomeKit/Matter for V3/X to preserve quota for advanced features

Configuration:

Enable during setup: Config Flow → Full Cloud Mode toggle

Entities & Controls

Home Device (Internet Bridge)

Global controls and elite transparency for your home. Linked to your Internet Bridge.

Entity	Type	Description
`select.tado_{home}_presence_mode`	Select	Presence lock: `home` / `away` = manual override, `auto` = hand control back to Tado's own geofencing.
`switch.tado_{home}_polling_active`	Switch	Master Switch: Instantly stop/start all periodic API polls.
`switch.tado_{home}_reduced_polling_logic`	Switch	Logic Switch: Toggle the timed "Economy" profile.
`button.tado_{home}_resume_all_schedules`	Button	Restore Smart Schedule across all zones (1 bulk call).
`button.tado_{home}_turn_off_all_zones`	Button	Turn off all zones instantly (1 bulk call).
`button.tado_{home}_boost_all_zones`	Button	Boost all zones to 25°C (1 bulk call).
`button.tado_{home}_full_manual_poll`	Button	Expensive: Forced synchronization of all metadata and states.
`sensor.tado_{home}_api_limit`	Sensor	Total daily API quota limit (1000 standard, 3000 with proxy).
`sensor.tado_{home}_api_remaining`	Sensor	API Gold: Your remaining daily call budget.
`sensor.tado_{home}_api_status`	Sensor	Real-time health (`connected`, `throttled`, `rate_limited`).
`sensor.tado_{home}_home_mode`	Sensor	Aggregate zone mode across all heating/AC zones: `schedule`, `manual`, `boost`, `off`, or `mixed` (zones differ). Useful for automations — e.g. trigger "resume schedule" when `mixed`.

Diagnostic Entities (Home)

Advanced monitoring sensors available under the Internet Bridge device diagnostics section:

Quota Reset Learning (NEW in v5.0):

sensor.quota_reset_last - Last observed reset timestamp
sensor.quota_reset_next - Predicted next reset (learned pattern)
sensor.quota_reset_expected_window - Learned reset window in local time (e.g., "13:30 (learned)")
sensor.quota_reset_pattern_confidence - Pattern confidence (low/medium/high/confirmed)
sensor.quota_reset_history_count - Number of observed resets

Polling Intervals:

sensor.current_zone_interval - Current dynamic polling interval
sensor.min_interval_configured - User-configured minimum
sensor.min_interval_enforced - Actual enforced minimum (proxy-aware)
sensor.reduced_polling_interval - Economy window interval
sensor.debounce_time - Batching window duration
sensor.presence_poll_interval, sensor.slow_poll_interval, sensor.offset_poll_interval

Configuration Status:

sensor.auto_quota_percent, sensor.throttle_threshold, sensor.jitter_percent
sensor.reduced_polling_start, sensor.reduced_polling_end
sensor.suppress_redundant_calls, sensor.suppress_redundant_buttons
binary_sensor.reduced_polling_active, binary_sensor.call_jitter_enabled
binary_sensor.disable_polling_when_throttled, binary_sensor.refresh_after_resume

System Info:

sensor.outdoor_absolute_humidity - Calculated absolute humidity (g/m³) from external weather entity
sensor.tado_generation - Detected hardware ("Tado X" or "Tado Classic (v3)")
sensor.proxy_url, sensor.proxy_token - Proxy configuration status
sensor.log_level - Current logging level

Manual Refresh Buttons:

button.refresh_metadata - Force hardware sync
button.refresh_offsets - Force offset sync
button.refresh_away - Force away config sync
button.refresh_presence - Force presence sync

Zone Devices (Rooms / Hot Water / AC)

Cloud-only features that HomeKit does not support.

Entity	Type	Description
`switch.schedule`	Switch	ON = Smart Schedule, OFF = Manual. Simple way to resume schedule. Supports heating and AC zones (v3).
`climate.ac_{room}`	Climate	v3 AC Only: Full HVAC mode control (`cool`, `heat`, `dry`, `fan`, `auto`) with native slider.
`water_heater.hot_water`	WaterHeater	v3 Only: Modes: `auto` (schedule), `heat` (manual), `off`.
`binary_sensor.hot_water_power`	Binary Sensor	v3 Only: Boiler heating status.
`binary_sensor.hot_water_overlay`	Binary Sensor	v3 Only: Manual override active status.
`binary_sensor.hot_water_connectivity`	Binary Sensor	v3 Only: Zone connectivity based on device connections.
`switch.early_start`	Switch	v3 Only: Toggle pre-heating before schedule block.
`number.open_window_timeout`	Number	Config: Open window timeout (0=OFF, 5-1439min=ON). Requires Tado subscription for detection.
`number.target_temperature`	Number	v3 HW Only: Set hot water target temp (manual mode).
`number.away_temperature`	Number	v3 Only: Set away mode temperature.
`select.zone_temp_source`	Select	Config: Optional temperature source for indoor climate sensors. Link any `climate` or temperature `sensor`. Required for Tado X (no cloud temp in Full-Matter mode).
`select.zone_humidity_source`	Select	Config: Optional humidity source for indoor climate sensors. Link a `climate` entity (reads `current_humidity`) or a humidity `sensor`. Fallback: cloud zone state.
`select.fan_speed`	Select	v3 AC Only: Full fan speed control.
`select.vertical_swing`	Select	v3 AC Only: Vertical swing control (ON/OFF or position modes).
`select.horizontal_swing`	Select	v3 AC Only: Horizontal swing control (ON/OFF or position modes).
`sensor.zone_mode`	Sensor	Mode: Current operating mode: `schedule`, `manual`, `boost`, `off`. Classic: boost detected via 25°C setpoint. Tado X: native boost field. Heating and AC zones only.
`sensor.heating_power`	Sensor	Insight: Valve opening % or Boiler Load %.
`sensor.humidity`	Sensor	Zone humidity (faster than HomeKit).
`sensor.dew_point`	Sensor	Climate: Dew point temperature (°C) via Magnus formula. Sources: linked `zone_temp_source` → zone state (v3) → unavailable (Tado X). Enabled via Dew Point Sensor feature flag.
`sensor.mold_risk_level`	Sensor	Climate: Mold risk level: `none` / `low` / `medium` / `high`. Uses dew point spread — cold-but-dry rooms correctly show `none`. Enabled via Mold Risk Sensors feature flag.
`binary_sensor.mold_risk`	Binary Sensor	Climate: `ON` when mold risk is `medium` or `high`. Ideal for automations and alerts.
`sensor.indoor_absolute_humidity`	Sensor	Climate: Indoor absolute humidity (g/m³). Shown when Outdoor Weather Entity is configured.
`binary_sensor.ventilation_recommended`	Binary Sensor	Climate: `ON` when indoor AH exceeds outdoor AH by ≥ threshold — opening windows reduces moisture. Shown when Outdoor Weather Entity is configured.
`sensor.next_schedule_change`	Sensor	Planning: Timestamp of next schedule transition (diagnostic).
`sensor.next_schedule_temp`	Sensor	Planning: Target temp of the upcoming schedule block.
`sensor.next_schedule_mode`	Sensor	Planning: Mode (HEAT/OFF) of the upcoming schedule block.
`sensor.next_time_block_start`	Sensor	Planning: Start time of the next schedule block.
`button.resume_schedule`	Button	Force resume schedule (stateless). Supports heating and AC zones (v3).
`attribute.auto_target_temperature`	Metadata	Transparency: Current schedule setpoint visible in attributes during `auto` mode (Heating, AC & HW).

Note

Schedule Planning Sensors: The next_schedule_* sensors provide a peek into the future without extra polling. However, during Away Mode, Tado often disables the standard schedule, causing these sensors to report Unknown. This is normal behavior as there is no active "next block" counting down.

Physical Devices (Valves/Thermostats)

Hardware-specific entities. These entities are injected into your existing HomeKit devices (V3 only). For Tado X, they appear as separate entities (Matter lacks serial numbers for linking).

Entity	Type	Description
`binary_sensor.battery`	Binary Sensor	Battery health (Normal/Low).
`binary_sensor.connection`	Binary Sensor	Device connectivity to Tado cloud.
`switch.child_lock`	Switch	Toggle Child Lock on the device.
`switch.dazzle_mode`	Switch	v3 Only: Control display brightness/behavior.
`number.temperature_offset`	Number	Interactive temperature calibration (-10 to +10°C).

Services

For advanced automation, use these services. All manual control services feature Pre-Validation: Invalid combinations (e.g. auto + temperature) are blocked immediately with a clear error message in the Home Assistant UI.

Service	Description	API Impact (v3)	API Impact (Tado X)
`tado_hijack.turn_off_all_zones`	Turn off all zones instantly.	1 call (bulk)	1 call (bulk)
`tado_hijack.boost_all_zones`	Boost every zone to 25°C.	1 call (bulk)	1 call (bulk)
`tado_hijack.resume_all_schedules`	Restore Smart Schedule across all zones.	1 call (bulk)	1 call (bulk)
`tado_hijack.set_mode`	Set mode, temperature, and termination. Supports `hvac_mode` (auto, heat, off) and `overlay` (manual, next_block, presence).	1 call (batched)	1 call (batched)
`tado_hijack.set_mode_all_zones`	Targets all HEATING and/or AC zones at once using `hvac_mode`.	1 call (bulk)	N calls (per zone)
`tado_hijack.set_water_heater_mode`	Set `operation_mode` and temperature for hot water (v3 only).	1 call	N/A (no HW zones)
`tado_hijack.add_meter_reading`	Upload a meter reading (integer) to Tado Energy IQ (v3 only).	1 call	N/A (unsupported)
`tado_hijack.manual_poll`	Force immediate data refresh. Use `refresh_type` to control scope. Add `entity_id` for a targeted single-entity fetch (saves quota).	1-N (depends)	1-N (depends)

Tip

Intelligent Post-Action Polling (refresh_after): When active, the integration uses a smart decision engine to save API quota:

Immediate Refresh: Triggered for auto (Resume Schedule) or permanent manual changes. Since the target state is reached immediately, an instant GET request confirms the cloud synchronization.
Intelligently Deferred: For timed modes (duration), the refresh is deferred until the timer actually expires. Polling immediately during a timer is wasteful; we wait for the "expiry event" to fetch the new post-timer state.
Event-Aware: For next_block or presence overlays, immediate polling is suppressed as the cloud state transition depends on external time/events.

Tip

Targeting Rooms: You can use any Tado zone entity (climate, switch, sensor) or even device entities (battery, connection, child_lock) as the entity_id. Device entities automatically resolve to their zone via serial number lookup. This includes your existing HomeKit climate entities (e.g. climate.living_room).

Targeted Fetch: When using manual_poll with an entity_id, the refresh is limited to that single entity — offsets costs 1 API call instead of N, away costs 1 instead of M. capabilities uses the lazy cache and only drops that zone's entry. Bulk types (zone, metadata, presence, all) always fall back to a full refresh.

Tip

Multi-Home Service Routing: Have multiple Tado Homes configured? Our service routing is fully multi-account aware!

Global Execution (Default): Call tado_hijack.resume_all_schedules with empty data {} -> The command is sent to all configured Tado homes automatically.
Targeted Execution: Use the new config_entry parameter in your service call (available in the UI) to select a specific home. -> The command is routed exclusively to the selected home.
Batched Entity Routing: When sending multiple entity_ids to set_mode that belong to different homes, Tado Hijack automatically sorts the entities and batches the API requests to their respective homes in parallel.

`set_mode` Examples (YAML)

Hot Water Boost (30 Min):

service: tado_hijack.set_water_heater_mode
data:
  entity_id: water_heater.hot_water
  operation_mode: "heat"
  temperature: 55
  overlay: "manual"
  duration: 30
  refresh_after: false

Quick bathroom Heat (15 Min at 24°C):

service: tado_hijack.set_mode
data:
  entity_id: climate.bathroom
  hvac_mode: "heat"
  temperature: 24
  overlay: "manual"
  duration: 15
  refresh_after: false

Manual Override (Indefinite):

service: tado_hijack.set_mode
data:
  entity_id: climate.living_room
  hvac_mode: "heat"
  temperature: 21
  overlay: "manual"
  refresh_after: false

Resume Schedule (Auto):

service: tado_hijack.set_mode
data:
  entity_id: climate.kitchen
  hvac_mode: "auto"
  overlay: "manual" # Required by schema, ignored for 'auto'
  refresh_after: true

Auto-Return to Schedule (Next Time Block):

service: tado_hijack.set_mode
data:
  entity_id: climate.kitchen
  hvac_mode: "heat"
  temperature: 22
  overlay: "next_block"
  refresh_after: false

Known Constraints

API Limitations (Tado Backend)

While Tado Hijack optimizes every possible interaction, some operations are inherently limited by Tado's server-side architecture:

No Bulk Device Config: Tado does not provide bulk API endpoints for hardware-specific settings. Temperature Offsets, Child Lock, and Window Detection must be sent individually (1 API call per device). If you change these for 10 devices, it will always cost 10 calls.
Schedule Logic is Cloud-Side: When you "Resume Schedule", the actual target temperature is determined by Tado's servers. To show the correct value in HA immediately, a single confirmatory poll is required (if Refresh After Resume is enabled).
Sequential Execution: To prevent account locks and respect the backend, device configuration commands are executed sequentially with a small delay.

Hybrid Cloud Dependency

While Tado Hijack uses the cloud for its power-features, your basic smart home remains resilient:

Local Resilience: Temperature control and heating state via HomeKit remain fully functional even during internet outages or Tado server issues.
Cloud-Only Features: Access to Smart Schedules, Hot Water control, and AC-Pro features requires a connection to Tado's servers.
Why Cloud? Tado does not expose a local API for advanced logic. Tado Hijack bridges this gap while keeping your local core intact.

Troubleshooting

If you encounter issues, please check the following steps before opening a GitHub issue or asking on Discord.

Expert-Level Diagnostics

Sharing diagnostics should be safe. Our built-in Diagnostic Report uses Multi-Layer Anonymization to protect your privacy while providing all necessary technical data. However, you should always verify the content yourself before posting it publicly. If in doubt, send the report via DM to an administrator.

🔑 Key Pseudonymization: Home Assistant Entity-IDs in JSON keys are transformed into unique anonymized hashes (e.g. sensor.entity_8a3f). This protects your room names while maintaining machine-readability for debugging.
🛡️ PII Masking: All sensitive names (Zones, Homes, Mobile Devices, Titles) are replaced with "Anonymized Name".
🕵️‍♂️ Serial Number Protection: Every hardware identifier (VA, RU, IB, etc.), E-mail address, and cryptographic secret (Tokens, Hashes) is automatically masked via intelligent Regex everywhere in the document.
📊 Pure Debug Power: Despite maximum privacy, the report contains all technical insights needed for support:
- Detailed Quota & Adaptive Interval math.
- API Queue & Action status.
- Internal Entity Mappings (Anonymized but uniquely identifiable).
- Device Metadata (Firmware, Battery, Connection status).

Tip

How to get the report: Go to Settings -> Devices & Services -> Tado Hijack -> Click the three dots (⋮) -> Download diagnostics.

Debug Logging

Enable verbose logging in your configuration.yaml to see what happens behind the scenes:

logger:
  default: info
  logs:
    custom_components.tado_hijack: debug

Frequently Asked Questions (FAQ)

Where are my climate entities and current temperature?

In the default mode, Tado Hijack does not create climate entities for heating zones — HomeKit (v3) or Matter (Tado X) already handle local temperature control efficiently at zero API cost.

Full Cloud Mode (enabled during setup) creates cloud-polled climate entities. This is required for V2 bridges (GW) that have no HomeKit/Matter support, and optional for V3/X.

Why prefer local protocols over cloud API?

Reason	Explanation
API Quota	Accurate temp polling needs 720-1,440 calls/day → quota exhausted. Current limit is 1,000 calls/day.
Speed	HomeKit/Matter = instant response. Cloud API = latency + polling delays.
Reliability	Local protocols work offline. Cloud API requires internet.
Cost	HomeKit/Matter = zero API calls. Cloud API = every action costs quota.

What each integration provides:

Integration	Temperature Control	Cloud Features	API Calls
HomeKit/Matter	✅ (`climate` entities, current temp)	❌	0
Tado Hijack	❌	✅ (Schedules, Hot Water, AC Pro, Hardware)	Optimized

Setup: Install HomeKit/Matter first → then Tado Hijack → V3: Features get injected into HomeKit devices | Tado X: Features appear as separate entities (Matter limitation).

Why are my Tado X dew point / mold risk sensors unavailable?

For Tado X (without Full Cloud Mode), the cloud API does not deliver room temperature because the TRV measures it locally and reports it directly via Matter. Since Matter devices do not expose serial numbers in Home Assistant, Tado Hijack cannot auto-link them.

You must use the Temperature Source selector (select.zone_temp_source) on your Tado X zone device and select the corresponding Matter climate entity or a temperature sensor (e.g. climate.living_room_tado). Once set, the dew point, mold risk, and absolute humidity sensors activate for that zone immediately.

See Zone Temperature & Humidity Sources for details.

Documentation

Looking for more technical details or want to contribute?

🎯 Features Guide

FEATURES.md — User-friendly guide to all smart features:

Smart Batching & Debouncing (quota savings explained)
Auto Quota Management (weighted intervals, adaptive polling)
Optimistic Updates (instant UI response)
Multi-Track Polling (fast/slow/medium/away/presence)
Bulk Operations (1 API call for all zones)
Reset Window Detection (learns Tado's quota reset time)
Economy Mode, Throttle Protection, Proxy Support
Privacy & Security (automatic PII redaction)

🏗️ Multi-Generation Architecture

ARCHITECTURE.md — Complete technical overview of multi-generation support:

Unified architecture supporting Tado v3 Classic (HomeKit) and Tado X (Matter)
Provider pattern and generation abstraction (TadoV3 vs TadoX executors)
Generation-specific API layers (my.tado.com vs hops.tado.com)
Duck typing strategy for data model compatibility
Feature matrix comparing v3 Classic and Tado X implementations
API layer architecture with mermaid diagrams

📐 Design & System Pipeline

DESIGN.md — Deep dive into the integration's design:

Complete system pipeline and execution flow
Specialized managers (Coordinator, DataManager, ApiManager, CommandMerger, RateLimitManager, OptimisticManager)
Auto quota calculation with weighted profiles
State integrity mechanisms (Field Locking, Pending Commands, Rollback Context)
Error handling and resilience patterns
Concurrency control and thread-safety

🚀 Compatibility & Tado X

COMPATIBILITY.md — Library patches and Tado X integration details:

Runtime patches for tadoasync library bugs
Fixes for ZoneState deserialization and Energy IQ URI issues
Architecture of the Tado X (Hops API) bridge
Duck typing for multi-generation data model support
Integration strategy for Matter alongside Cloud features

Support the Project

Tado Hijack is developed entirely in my free time to fight back against API restrictions and keep our smart homes running freely.

If this integration saved you from buying a Tado subscription, fixed your API headaches, or you just love the advanced features, please consider supporting the ongoing development!

Every coffee helps to keep the motivation high, fund test hardware for new features, and fuels the late-night coding sessions required to outsmart the API limits. Thank you! ❤️

Disclaimer: This is an unofficial integration. Built by the community, for the community. Not affiliated with Tado GmbH. Use at your own risk.

Name		Name	Last commit message	Last commit date
Latest commit History 50 Commits
.github		.github
custom_components/tado_hijack		custom_components/tado_hijack
docs		docs
scripts		scripts
.gitignore		.gitignore
.gitleaks.toml		.gitleaks.toml
.pre-commit-config.yaml		.pre-commit-config.yaml
.prettierignore		.prettierignore
.releaserc		.releaserc
.yamllint		.yamllint
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
hacs.json		hacs.json
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt

Folders and files

Latest commit

History

Repository files navigation

Tado Hijack for Home Assistant 🏴‍☠️

Overview

Key Features:

Feature Comparison

Generation Support: V2, V3 Classic & Tado X

Key Highlights

Extreme Batching Technology

The Local "Missing Link"

Cloud Features (Non-HomeKit)

State Integrity & Robustness

API Consumption Strategy

API Consumption Table

Auto API Quota & Economy Window

Core Mechanics

Adaptive Behavior & Safety

Batching Capability Matrix

Architecture

Physical Device Mapping & Resolution

Robustness & Security

Installation

Via HACS (Recommended)

Configuration

Zone Temperature & Humidity Sources (All Generations)

Full Cloud Mode (All Generations)

Entities & Controls

Home Device (Internet Bridge)

Diagnostic Entities (Home)

Zone Devices (Rooms / Hot Water / AC)

Physical Devices (Valves/Thermostats)

Services

set_mode Examples (YAML)

Known Constraints

API Limitations (Tado Backend)

Hybrid Cloud Dependency

Troubleshooting

Expert-Level Diagnostics

Debug Logging

Frequently Asked Questions (FAQ)

Where are my climate entities and current temperature?

Why are my Tado X dew point / mold risk sensors unavailable?

Documentation

🎯 Features Guide

🏗️ Multi-Generation Architecture

📐 Design & System Pipeline

🚀 Compatibility & Tado X

Support the Project

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 30

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`set_mode` Examples (YAML)

Packages