v4.0.2 — Smarter polling, cloud failure modes, user-action consistency

[hiall-fyi]

In short: Tado CE now uses fewer of your daily Tado API calls when polling fast, and it handles a Tado cloud outage gracefully instead of quietly leaving your entities stuck on old values. When something you do in Home Assistant doesn't go through, the dashboard now tells you instead of pretending it worked. Nothing to set up, no new features to learn. Just update and carry on. The rest of these notes are the detail if you want it.

A stable patch on the v4.0 line, rolling up the v4.1.0-beta.2 work plus two passes scoped for v4.1.0-beta.3 and pulled forward so v4.0.x users don't have to wait for the v4.1.0 beta cycle to finish.

The headline is an adaptive-polling reframe. A 1,000-call-tier home with HomeKit connected was collapsing to 1-minute polling and burning through its daily quota. Polling now matches how fast each kind of data actually changes: weather and presence refresh on their own slower schedule instead of riding the zone-state cadence, the adaptive floor is a flat 5 minutes regardless of how big your quota is (zone temperature doesn't change any faster on a bigger plan), and HomeKit-connected setups follow your Cloud Data Refresh dial. If you want faster than 5 minutes, a custom polling interval still gets you there.

The other half is how the integration behaves when something goes wrong with Tado's cloud. Previously several classes of failure (refresh token revoked, persistent 403, rate-limit window) silently froze your entities on stale data with no UI cue. The integration now responds to each in the way Home Assistant expects: a re-authentication prompt for a dead token, a Repairs notice (and the wait time honoured) for a rate-limit, a clear error toast on any action you take that hits either. Programmer bugs that the old code wrapped and silent-retried forever now surface as actual errors so they can be fixed.

If your installation has been running fine, this release should be largely invisible to you. If it hasn't been, you'll find out faster.

No new features and nothing to reconfigure. It's bug fixes, lighter API use, and the integration coping better when Tado's cloud has a bad day.

⚠️ Upgrade Notes

Upgrading from v4.0.1 (stable) or v4.1.0-beta.2 (beta channel)? Pick up via HACS, restart, no config changes needed. The persistence reshape, user-action consistency layer, and new error-routing all turn on automatically.

Polling cadence changes if you're on HomeKit or a fast custom interval: with HomeKit local control connected, cloud polling now follows your Cloud Data Refresh dial rather than an automatic faster rate. If you relied on the old behaviour being faster than your dial, set a custom polling interval (Configure → Advanced Settings → Polling & API) to pin it back. Presence and mobile-device locations now refresh at most every 5 minutes in cloud-only mode (they used to update every poll), so if you need tighter presence latency, lean on Home Assistant's own device_tracker or person integration. A custom polling interval now governs zone updates only; weather and presence keep their own slower schedule regardless.

Behavioural change worth knowing: in cloud-only setups (no HomeKit local pairing), entities will now go unavailable for the duration of a Tado-cloud rate-limit window instead of staying on stale cached values. They recover automatically on the first successful sync after the Retry-After window passes. Automations that compare temperature attributes (>, <) during this window may behave differently than before. HomeKit-paired setups are unaffected — the local stream keeps entities live through cloud trouble.

One thing that might fire reauth more often: a transient 403 burst from Tado's CDN that lasts past three retries (about 14 seconds with backoff) now triggers a reauth prompt. Previously the integration silently swallowed this. The trade-off is intentional: silent stale data is the worse failure mode. Recovery is one button-press in the Settings → Devices & Services page if the prompt appears unexpectedly.

Mold Risk sensor name change: the numeric humidity sensor's friendly name changes from Mold Risk % to Mold Risk Indicator across all seven locales. Existing installs are unaffected on the data side — entity_id, unique_id, device_class=HUMIDITY, and all attribute names stay the same. Only the UI label changes. If you've titled a dashboard card by typing the name out, you'll want to retype it. Fresh installs from this release onward also get a clean auto-generated slug without the _2 suffix.

Service-call automations from v4.0.x continue to work. The tado_ce.turn_off_all_zones, resume_schedule, set_open_window_mode, and restore_previous_state services keep the same call shape; only their internal write path changed.

When the cloud goes wrong, you see it

• Reauth flow triggers when your refresh token is revoked — if Tado invalidates your token (password change, manual revoke, persistent CDN block past three retries), the integration now raises a reauth prompt in Home Assistant. Previously the cloud calls returned silently, your entities stayed on stale data, and you had to notice and reload manually. The same flow also fires when a 401 hits a non-retryable POST (meter reading submission etc.) or when the home ID is missing from your config.
• Rate-limit window honoured properly — when Tado returns HTTP 429 with a Retry-After header, the integration now waits for exactly that long before the next poll instead of polling on its configured interval and re-burning the 429. The 429 also surfaces as a Repairs issue ("Tado CE: Cloud rate-limited") with the recovery time, plus a rate_limited_until attribute on the API Usage sensor so dashboards can show it. The repair clears itself on the first successful sync after recovery.
• Service calls during cloud trouble show the right error — pressing "set temperature" or running tado_ce.resume_schedule while your token is dead now triggers reauth (with a toast saying "Tado authentication required") instead of a generic "set failed". Hitting the same service during a rate-limit window shows "Tado API rate-limited. Try again in N min." with the actual cooldown. Six service handlers (set_temperature_offset, add_meter_reading, identify_device, set_away_configuration, activate_open_window, deactivate_open_window) that previously bypassed this routing now flow through the same path.
• HomeKit-connected installations stay live during cloud trouble — if HomeKit local control is paired and the cloud is rate-limited or having a transient blip, your entities now stay live on HomeKit data instead of going unavailable. The Repairs entry still appears so you know cloud is down, but the dashboard isn't disrupted. Cloud-only setups (no HomeKit pairing) keep the existing behaviour: entities go unavailable and recover on the next successful sync.

Persistence

• Auto-detect Tado-side zone changes (Discussion #280 - @Trebor87) — re-pair, hardware swap, and zone add/remove on the Tado side now triggers cache invalidation automatically. The integration picks up the change on the next quick poll (5–30 min depending on cadence) and refetches the affected entries. The Refresh AC Capabilities hub button stays as a manual escape hatch.
• Stale zone cleanup — when a zone is removed in the Tado app, the integration now drops every cached reference to it on the next poll rather than carrying stale data until the next HA restart.
• Device state stays current (#286 - @Fred224) — the Connection, firmware version, and battery sensors used to freeze at boot-time values until you restarted HA. They now refresh on a periodic cadence (hourly on the 1,000-call transitional tier and the 20,000-call legacy tier, every 4 hours on the 100-call free tier), so an AC controller that drops Tado's cloud uplink (E04 errors, mains blip, Wi-Fi flap) actually shows up as Disconnected within the cycle, and reconnections clear it the same way.

Bug fixes

• tado_ce_ready event now reaches boot-time automations (#287 - @Newreader) — the event was firing as soon as the integration finished its setup, which on a cold HA start happens before automation triggers register their listeners. Anyone with an automation triggered by tado_ce_ready saw it never run after a restart, only after a manual reload. Fixed by deferring the fire until HA has fully started; reload behaviour is unchanged.
• Refresh AC Capabilities button now actually refreshes — since v4.0.0-beta.5's storage migration, the button was deleting a legacy file path that no longer exists, so the cache stayed populated and the re-fetch was silently skipped. Pressing the button now properly invalidates the cache and forces a fresh fetch from Tado, which is what you needed it to do all along after re-pairing a Smart AC controller.
• Mobile device trackers explain the Unknown state (Discussion #271 - @Prodeguerriero) — when a phone's Tado-app geo-tracking is on but the Tado cloud isn't receiving its location, the device tracker entity now exposes a location_status attribute reading no_location_reported instead of leaving you guessing why the entity reads Unknown. On Android the most common cause is battery optimisation killing the Tado app's background location service — the attribute names that scenario explicitly so you know where to look in the OS settings rather than chasing it as a Tado CE bug.

State Restore

• Captures only persist on successful cloud writes (#278 - @Newreader, root-cause companion to v4.0.1's defensive 2-poll gate) — previously a snapshot was saved before the cloud write fired, so a failed write left a stale entry that could be replayed by a later overlay-cleared event. Captures now correspond to known-applied state changes only.

User-action consistency

• Every user action updates the dashboard immediately and rolls back on failure — temperature sliders already worked this way; HVAC mode dropdowns, timer buttons, water-heater on/off, boost/smart-boost buttons, and the tado_ce.turn_off_all_zones, tado_ce.resume_schedule, tado_ce.set_open_window_mode, and tado_ce.restore_previous_state services now match. The dashboard updates the moment you click. If the cloud rejects or times out, the dashboard rolls back and an error toast surfaces in the UI.

Quota handling

• Polling now matches how fast each kind of data actually changes (#289 - @driagi) — weather, presence, and mobile-device locations used to refresh on the same cadence as your zone temperatures, so a fast polling interval fetched them far more often than they ever change. Presence and mobile locations had no rate limit at all and fired on every single poll. They now refresh at most every 30 minutes (weather) or 5 minutes (presence and locations) no matter how fast your zones poll. The adaptive polling floor is now a flat 5 minutes for everyone, whatever your daily call limit. The old logic let a big quota buy a faster automatic cadence (down to 1-minute polling), which is what was quietly burning through the day's calls for no real gain: zone temperature doesn't change any faster just because your plan is bigger. If you genuinely want faster than 5 minutes, set a custom polling interval and it's honoured as-is. And when HomeKit local control is connected, the cloud cadence follows your Cloud Data Refresh setting instead of an automatic faster rate. A custom polling interval now governs your zone updates only; weather and presence keep their own slower schedule. The API Usage sensor gained weather_last_fetched_min_ago, presence_last_fetched_min_ago, and mobile_devices_last_fetched_min_ago attributes so you can see which data type is using calls.
  What it saves you, concretely: if you're on the default 30-minute interval, your call count barely moves, because the slow-changing data was already only fetched every 30 minutes at that cadence. The saving shows up when your zones poll fast. At a 1-minute zone cadence with weather, presence, and Frequent Mobile Sync all on, the auxiliary cloud calls (the bits that aren't zone temperature) drop from roughly 2,900 a day to about 430, because weather now refreshes every 30 minutes and presence / locations every 5, instead of all three riding the 1-minute zone cadence. Zone temperatures themselves have arrived locally over HomeKit since v4.0.0 if you've paired the bridge, which takes the single biggest call off the cycle. Full per-version breakdown in FEATURES_GUIDE → Smart Polling.
• Low-quota gate now scales with your tier — three places in the integration back off optional cloud work when remaining quota is low: the offset drift refresh, the calendar schedule fetch on first load, and the Smart Day/Night polling switch. All three used a hardcoded 100-call threshold, sized for the 100-call free tier. On the 1,000-call transitional tier that fires at 10% remaining (sensible). On the 20,000-call legacy tier it fires at 0.5% remaining (way too late — manual actions had no cushion). The threshold is now tier-aware: 10% of your daily limit, with a 100-call absolute floor. Free tier unchanged. Transitional tier unchanged at the boundary. Legacy tier now backs off at 2,000 remaining instead of 100, leaving 1,900 calls of headroom for manual actions.

i18n

• Mold Risk % renamed to Mold Risk Indicator (#90 - @ChrisMarriott38) — the numeric humidity sensor (added in v2.0.1) used to display as Mold Risk %, which read like "percentage of mold risk" but is actually surface relative humidity. The trailing % also caused a slug collision on fresh installs because HA's slugify drops it, so the entity was landing as sensor.<zone>_mold_risk_2. The friendly name is now Mold Risk Indicator across all seven locales (DE, ES, FR, IT, NL, PT translated via DeepL).

Home Assistant compatibility

• Removed a HA Core deprecation warning — Tado CE was using a device-tracker import path that HA Core marked deprecated and is removing in HA 2027.6. Switched to the current path. The "deprecated alias TrackerEntity was used from tado_ce" warning that appeared on every startup is gone. No behavioural change.

Internal hardening (no user-visible change)

• Programmer bugs no longer silent-retry forever — a number of except Exception catches across the API client, Smart Valve Control, services helpers, and rate-limit gate were swallowing programmer bugs (KeyError on a malformed response, AttributeError after a refactor, etc.) and silent-retrying them on every poll. Each catch is now scoped to the specific exception types it actually needs to handle, so bugs surface as real errors with full tracebacks. If something regresses in a future Tado API change, you should see it as a failed-to-load integration rather than a silently degraded one.
• Cloud-unreachable log gets quieter — the warning that fired every poll when HomeKit was carrying entities through a cloud outage now logs once when the cloud goes unreachable and once when it recovers, instead of on every cycle. Same information, no log spam.
• Settings descriptions corrected — the bridge auth code is described as 4-digit (it is; the 8-digit figure was the HomeKit pairing code creeping in). The Mobile Device Tracking description now spells out that Frequent Mobile Sync lives under Advanced Settings → Polling & API and only appears once tracking is turned on and saved. The Device Sync Delay description gained its range. A couple of stale labels that pointed at controls which had moved were dropped.
• Four unused feature toggles removed — zone_diagnostics, device_controls, boost_buttons, and environment_sensors config keys had no UI anywhere and sat permanently on. The features they gated still run exactly as before; only the dead config keys are gone.

How to Update

From v4.0.1 stable, v4.1.0-beta.1, or v4.1.0-beta.2: HACS → Tado CE → ⋮ → Redownload → tick "Need a different version?" → select v4.0.2 → Restart HA. No config changes needed.

Fresh install: See Quick Start in the README.

---

Thanks to everyone who supported the project through Buy Me a Coffee — it genuinely helps.

Full changelog: v4.0.1...v4.0.2

---

This discussion was created from the release Smarter polling, cloud failure modes, user-action consistency.