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

[!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).

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.

1. Run the Docker Container.
2. Set your API Proxy URL in Hijack Options (e.g., http://192.168.1.10:8080).
3. 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