v4.0.1 — AC swing split, turn_off_all_zones service, defensive fixes

[hiall-fyi]

The biggest user-visible change is the AC swing dropdown split into separate vertical and horizontal axes, which already shipped to beta testers as v4.1.0-beta.1. AC users on fine-grained swing units (Mitsubishi, Fujitsu, similar) can now park each axis independently instead of being forced into a single sweeping motion.

Beyond the swing change, this release rolls up swing-fix polish, an AC HomeKit documentation correction (Smart AC Control V3+ units don't go through the bridge), and several defensive fixes raised by beta testers and v4.0 users. All v4.0.0 users get this via HACS auto-update.

⚠️ Upgrade Notes

Upgrading from v4.0.0? Update through HACS and restart, no config changes needed. The new split-axis swing dropdowns appear automatically; existing automations using the old unified swing_mode keep working through v4.1.x with a deprecation warning per call.

Dashboard templates and Lovelace conditions reading state_attr('climate.X', 'swing_mode') and matching 'both', 'vertical', or 'horizontal' need updating, since the compat shim covers service calls but not state reads. After v4.0.1 the attribute holds raw values like 'on', 'off', 'up', 'auto'. Cards should check swing_mode and swing_horizontal_mode separately.

HomeKit users with AC zones: temperature and HVAC mode still update locally via HomeKit (typically within 2 seconds). Swing changes still go through Tado's cloud, so picking a swing position uses cloud quota and confirms on the next cloud poll (typically 5–30 minutes). Same as v4.0, not a regression.

Heads-up on the next beta: the numeric humidity sensor's friendly name is changing from Mold Risk % to Mold Risk Indicator in v4.1.0-beta.2. Background: it was added in v2.0.1 by #90 to give the text-state Mold Risk sensor a numeric companion for HA history graphs and threshold automations. The % in the name reads like "percentage of mold risk" but is actually surface relative humidity, and the trailing % causes a slug collision on fresh installs. Existing installs are unaffected: entity_id, unique_id, attribute names, and state values all stay the same. Only the UI label changes for everyone, and on fresh v4.1.0-beta.2+ installs the auto-generated slug also changes (no _2 suffix). If you've titled a dashboard card by typing the name out, you'll want to retype it to Mold Risk Indicator after the beta lands.

What's New

• Split AC swing into vertical and horizontal axes (#270 - @Ralf84) — AC zones now expose a Swing (vertical) and a Swing (horizontal) dropdown, each populated from the cloud-reported capability set for your specific unit. Pick a fixed louver position on either dropdown to stop oscillation on that axis, useful in bedrooms or children's rooms where a constantly moving louver is disruptive. Simple On / Off units keep a two-value dropdown.
• Fine-grained louver positions for capable AC units — Units that report values like Up, Mid (down), Left, Mid (right) now expose those values directly in the dropdowns. Translations land in German, Spanish, French, Italian, Dutch, and Portuguese alongside English.
• tado_ce.turn_off_all_zones service (#283 - @hapklaar) — Mirrors the Tado app's "Turn OFF all rooms" button. One call places every climate zone (heating + AC) into a manual OFF overlay; schedules stay suppressed until you resume each zone manually. Designed for "outside temperature above 15°C, turn off everything" automations where the next schedule block would otherwise override the off state.

Bug Fixes

• State Restore: defensive 2-poll confirmation gate before firing the restoration event (#278 - @Newreader) — The State Restore Manager was firing tado_ce_state_restoration_available the moment a single poll reported overlay=null on a zone that previously had an overlay. A single observation can be a transient (quota-reset window, partial poll response, brief upstream blip) rather than a real overlay clear. The integration now requires two consecutive polls reporting overlay=null on the same zone before firing the event, filtering out transients without changing steady-state behaviour. The event still fires on real overlay clears (timer expiry, user resume from Tado app), just one polling cycle later (~5–12 minutes depending on cadence). FEATURES_GUIDE adds a defensive listener pattern (delay + re-check) for any automation subscribed to this event.
• Polling resume log line no longer fires when never paused — should_pause_polling was logging "expected reset time XX:XX UTC has passed, resuming polling" on every poll cycle once last_reset_utc + 24h had elapsed, even on tiers where polling was never paused (anyone on 1000+ tier under normal load). The line now only fires on an actual paused → unpaused transition. Cosmetic fix; no behavioural change.
• Drift refresh log line surfaces per-cycle quota cost (#277 - @wrowlands3) — Offset Sync: drift refresh complete now ends with ... N cloud call(s) used this cycle so users can audit drift refresh quota usage without inferring N from rate-limit decrement traces. FEATURES_GUIDE Smart Polling adds a worked daily-total formula and notes the LOW_QUOTA pause threshold.
• Adaptive polling now scales correctly across quota tiers (#276 - @churchofnoise) — The narrowing direction of the adaptive math was capped at 5 minutes regardless of available quota, leaving 20K legacy-tier users polling 1/3 of what their quota afforded. The cap is now 1 minute (Tado's cloud doesn't update faster than that anyway), so high-quota users get sub-5-minute polling automatically. 100-call free tier and 1,000-call transitional tier unchanged because the math widens well above the floor on those budgets.
• Swing changes no longer silently drop the off-axis on OFF-less units (#270 - @Ralf84) — Picking "Vertical" on a Mitsubishi or Fujitsu unit (which doesn't report OFF as a swing value) used to send only verticalSwing=ON and omit horizontalSwing from the payload, leaving the bridge to keep whatever horizontal state it last had. Each axis now writes its own value independently.
• Picking "On" from a swing dropdown no longer silently moves the off-axis — On was incorrectly being translated as a legacy v4.0 unified value, which set the opposite axis to Off and logged a deprecation warning the user hadn't earned. On is now treated as a v4.1 raw axis value and only the axis you picked moves.
• Swing dropdowns now follow physical louver order (#270 - @BirbByte) — On units that report fine-grained positions, the dropdown was alphabetical (Down / Mid / Mid (down) / Mid (up) / Up), which doesn't map to where the louver actually sits. Vertical now reads top-to-bottom, horizontal reads left-to-right.
• Swing dropdown icons are now consistent (#270 - @BirbByte) — Each swing value now ships its own icon (directional arrows for positions, the auto-mode glyph for Auto, the swap glyphs for continuous On, and a small dot for Off).

Improvements

• One log line per AC write failure, not two — Temperature, HVAC mode, fan mode, and swing writes used to log the specific failure reason and then a generic "write failed" warning right after. The generic line now fires only when no specific reason was logged.
• DeepL polysemy fixes for swing translations — DeepL guessed the wrong sense for several context-free single-word labels (On → preposition or article in all six locales, Right → "correct" in four, Auto → "car" in Spanish/Portuguese, Italian's Up → "scroll up" sense). 21 hand-fixed strings across the six locales. Thanks to @Ralf84 for catching the German pair on first install.

Documentation

• Smart AC Control V3+ HomeKit support corrected (Discussion #271 - @MacrosorcH) — Smart AC Control units are standalone WiFi accessories with their own HomeKit pairing code, not bridged through the Internet Bridge. Tado CE only handles the bridge pairing flow today, so AC zones go through the cloud path for every operation regardless of whether the bridge is paired locally. The Supported devices table cell, FEATURES_GUIDE Known Limitations entry, and ROADMAP entry all corrected together.
• HomeKit local control setup steps fixed (Discussion #271 - @clude86) — The README setup section incorrectly told users to add the Tado bridge as an HA HomeKit Device first, which claims the bridge's single HomeKit-controller slot and stops Tado CE from finding it. Setup now starts directly from the Tado app's HomeKit pairing code straight into Tado CE's Configure form.
• TRV LED feedback after a HomeKit-routed write (#281 - @amplitur) — Documented that the HomeKit Accessory Protocol doesn't carry a feedback channel for the LED-flash visual confirmation, with tado_ce.identify_device shown as a manual workaround.
• Hub-level buttons documented in FEATURES_GUIDE (Discussion #280 - @Trebor87) — New "Hub Buttons" section covers Resume All Schedules, Refresh AC Capabilities, and Refresh Schedule. Refresh AC Capabilities is the existing recovery path for AC zones whose HVAC modes show as [OFF] only after re-pairing; it was hard to find before, now it's documented properly.
• Quota Reserve switch surfaced in Smart Polling docs — The switch.tado_ce_{home_id}_quota_reserve_enabled entity is now named in the Quota Reserve section so users know which switch toggles the protection.
• Child Lock and Early Start switches dedicated section — New entry explains the per-device (Child Lock) vs per-zone (Early Start) distinction.
• Event-listener safety patterns — New "Event listeners for automation builders" section lists the 5 events Tado CE fires and shows a defensive listener pattern (delay + re-check) for tado_ce_state_restoration_available.
• add_meter_reading and identify_device services documented — both have been live since v3.x but only had handler-level wiring, no user docs. FEATURES_GUIDE now covers both with automation examples.
• v5.0.0 upgrade-path notice — A future v5.0.0 will drop the in-place migration code that upgrades v3.x option keys, entity IDs, and storage layouts. README and FEATURES_GUIDE now flag this early so any v3.x install still around can upgrade through v4.x first.

i18n

• Hub button display names renamed for clarity — Resume All → Resume All Schedules; Refresh AC → Refresh AC Capabilities. The entity name itself now tells users what the button does. DeepL pass for DE/ES/FR/IT/NL/PT, with hand-fixes for two polysemy cases (DE "anzeigen" → "fortsetzen"; ES "Volver a" → "Reanudar").

Internal

• Codebase cleanup, no user-visible behaviour change. Removed EntityMeta.legacy_name (a pre-translation_key holdover with 67 dead callsites and zero consumers), the one-time Test Mode entity-cleanup pass that's been a no-op since v4.0.0-beta.7 ran on every install, and async_create_deprecated_config_issue (a YAML-deprecation repair helper that was never called). Net 111 lines of dead code dropped.

How to Update

HACS detects v4.0.1 automatically. Open HACS → Tado CE → ⋯ → Update. Restart Home Assistant when prompted.

If you're already running v4.1.0-beta.1 (the swing axis split shipped earlier as a beta), updating to v4.0.1 is a no-op for the swing change itself (same code), but you pick up everything else in this release.

---

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

Full changelog: v4.0.0...v4.0.1

---

This discussion was created from the release AC swing split, turn_off_all_zones service, defensive fixes.