Possible confusion in HomeKit local control setup documentation

[clude86]

Hi,

I think the documentation for enabling HomeKit local control might be slightly misleading or incomplete.

Current documentation:

1. In the Tado app: Settings → Home Information → HomeKit — enable HomeKit and note the 8-digit pairing code.
2. In Home Assistant: Settings → Devices & Services → Add Integration → HomeKit Device, then enter the code.
3. Open Tado CE's Configure → General Settings → Hardware Connections → HomeKit, enable it, and restart Home Assistant.

In my setup, this only worked when I did not add the Tado Internet Bridge as a HomeKit Device in Home Assistant first.

If the bridge was already paired with Home Assistant via the standard HomeKit integration, Tado CE still requested the HomeKit pairing code again and could not connect properly.

What worked for me was:

1. Enable HomeKit in the Tado app
2. Do NOT add the bridge as a separate HomeKit Device in Home Assistant
3. Enter the HomeKit pairing code directly in Tado CE under:
   Configure → General Settings → Hardware Connections → HomeKit
4. Restart Home Assistant

This suggests that Tado CE manages the HomeKit connection itself and that pairing the bridge separately in Home Assistant may conflict with it.

Maybe the documentation could be clarified to avoid confusion for other users.

Thanks for the great project!

[hiall-fyi]

Cheers @clude86 , you're right, and thank you for taking the time to write it up so clearly. The README setup steps were wrong: step 2 (adding the bridge to Home Assistant's standard HomeKit Device integration) shouldn't be there at all.

What's actually happening under the hood: the Tado bridge only allows one HomeKit controller at a time. If you pair it to HA HomeKit Device first, that pairing claims the slot, and when Tado CE goes looking for an unpaired bridge to pair with, it can't see yours any more, so the PIN form keeps coming back at you. Tado CE drives its own pairing flow directly with the bridge (the FEATURES_GUIDE.md section had the correct version), so the right sequence is the one you ended up using: enable HomeKit in the Tado app, then enter the code straight into Tado CE's Configure form.

I've just rewritten the README setup section and the FAQ entry on Apple Home compatibility (which was misleading in the same direction), and the fix will be in the next patch release. The restart Home Assistant line is also gone, saving the form reloads the integration on its own, no full restart needed.

Really appreciate the heads up, this had been wrong since the v4.0 GA went out and you're the first person to spot it.

[Prodeguerriero]

Hi both,

Small sidebar, as I have been trying to get to control Tado via HomeKit for a while, and failed miserably. One of my troubleshooting attempts can be found here (the docker image for the Omada controller).

Anyway, I am 99.9% sure my issue is with mDNS not working properly with wired connections like the Tado Bridge. To confirm my theory, I'd need to know what kind of mDNS protocol the Tado Bridge uses. Would either of you be so kind as to help me figure this out?
One way of doing this would be to use the app listed here by one user who was trying to help me. Otherwise, using avahi on your laptop (assuming you have macOS or Linux) should also work.

In the meantime, I'll try to get this working with my ISP's router to see if I can get that to work somehow.

Cheers,

P.S. I can create a dedicated discussion if you prefer.

[Prodeguerriero]

Hi @hiall-fyi,

I have not added the bridge to Tado CE yet, as I wanted to sus out any more network weirdness, and I think I did.

Today I opened Home Assistant and opened the integration tab. To my surprise, nothing showed up as "Discovered", which is where Tado showed up when I wrote to you 4 days ago.
I then remoted into my server (where Home Assistant runs) and executed in this order:

1. avahi-browse --all
2. avahi-browse -prtv _hap._tcp 2>&1

After running the first command, Matter showed up as "Discovered". After running the second command, the tado bridge showed up. See below:

I am a tad confused as to why this is the case.

P.S. NOTE: I am running Home Assistant as a docker container.

[hiall-fyi]

Hi @Prodeguerriero, glad the factory reset sorted it. Two good questions, both have clean answers.

Why avahi-browse --all doesn't show the Tado bridge but avahi-browse -prtv _hap._tcp does.

--all works by querying a special meta-record at _services._dns-sd._udp.local. to ask "what service types are anyone advertising on this network?" and then iterating each one. It's the DNS-SD service-type enumeration mechanism from RFC 6763 §9. The catch is that advertising into that meta-record is optional, and Apple's HomeKit Accessory Protocol spec doesn't require accessories to do it. Most HomeKit gear including the Tado bridge skips the meta-record advertisement and only announces the actual _hap._tcp.local. service. Querying _hap._tcp directly bypasses the meta-record entirely and goes straight to the service-type query, which is why your second command saw it.

So it's not a Tado bug or an Omada filtering issue, it's just how HomeKit accessories advertise. AirPlay devices announce themselves more chattily into the service-type record, which is why Apple gear shows up in --all and Tado doesn't.

Why HA's "Discovered" tab showed Tado four days ago, then disappeared, then reappeared after the avahi commands.

mDNS records carry a TTL, typically 75 minutes for Bonjour-style announcements. Once a record's TTL expires, the cached entry is stale, and unless the device sends an unsolicited re-announcement or someone actively queries the service type, the entry quietly drops from the resolver's cache. The Tado bridge isn't very chatty about re-announcing (the Apple convention of frequent goodbye / hello packets isn't universal), so a cached entry can age out without anything obvious happening on the network.

When you ran the avahi commands, those issued fresh multicast queries on _hap._tcp. The bridge replied, Avahi's cache repopulated, and HA's zeroconf listener picked the response up off the same multicast traffic. That's why the Discovered entry came back right after.

The Docker context probably amplifies this. If HA is on the default docker bridge network rather than --network=host or macvlan, the container's zeroconf socket has limited visibility of host-level multicast traffic. Some images / setups work around it with mDNS reflectors or by binding to the host network namespace, but in a standard bridge-network setup the listener can miss passive announcements and only catch responses to active queries. Worth checking your HA container's network mode if you want the Discovered list to track bridge presence reliably without manual avahi pokes.

For what it's worth, none of this affects Tado CE once the bridge is paired. The pairing flow drives its own discovery against the bridge's IP rather than relying on the HA Discovered tab, so the cache aging isn't a runtime concern. It's mostly a Discovery-tab UX thing.

[Prodeguerriero]

Thanks for the clarification @hiall-fyi, much appreciated.

Everything seems to be working as intended now, bar my Android device's Home/Away status not being recognized correctly, and being listed as Unknown. I'll keep an eye on it.

Sidebar: where would one look for documentation related to the information you just shared? Networking is a bit of blind spot for me, and sometimes it feels like I am dealing with dark magic rather than IT. :D

Cheers

[hiall-fyi]

@Prodeguerriero, two things.

First on the Android Home/Away showing Unknown — I've added a location_status attribute to the mobile device tracker entity in v4.0.2, which I'm tagging in the next day or two. When Tado's geo-tracking is enabled in the app but the cloud isn't receiving location updates from a specific device, the entity will now expose location_status: no_location_reported instead of leaving you to guess why the state reads Unknown. On Android the usual cause is OS-level background restriction on the Tado app — battery optimisation, Doze mode, App Standby Bucket dropping the app to "rare", or the "Always" location permission being downgraded to "While in use". Once you have the v4.0.2 entity attribute to point at, the diagnosis is "Android side, not Tado CE side", and the fix is in your phone's OS settings (whitelist Tado from battery optimisation, confirm location permission is on "Allow all the time"). The other 1% of cases is Tado's app itself crashing or being force-stopped, which the same OS-level whitelist usually rules out as well.

For the networking corner of the thread — the answers I gave you sit across a few standards rather than one tidy doc, but here's the map I keep in my head:

• mDNS / DNS-SD basics: RFC 6762 (mDNS) and RFC 6763 (DNS-SD). RFC 6763 §9 is the bit on the _services._dns-sd._udp.local. meta-record that explains why avahi-browse --all doesn't see the bridge — it's the optional service-type-enumeration mechanism most HomeKit accessories don't bother announcing into. Apple's Bonjour Conformance Test docs sit on top of this if you want the Apple-flavoured view.
• HomeKit on top: Apple publishes the HomeKit Accessory Protocol Specification for non-commercial use after a free developer-account login. The IP-accessory transport section is what defines _hap._tcp.local. and the sf flag (sf=0 paired, sf=1 unpaired) you saw in the avahi output. The spec is dense, but the discovery / pairing chapters are the readable third of it.
• TTL behaviour and cache aging: RFC 6762 §10 covers the cache eviction logic. The 75-minute default Bonjour TTL isn't in the spec itself, it's an Apple convention documented in their Bonjour overview — most third-party implementations follow it because Avahi and the HA zeroconf listener cache against the announced TTL.
• Docker bridge networking and multicast: Docker's own networking overview is the start, but the relevant detail is in drivers/bridge — the default bridge driver doesn't forward multicast across the host boundary, which is why _hap._tcp announcements arriving on the host's wired interface don't reach a container on bridge mode. The fixes are --network=host (simplest, gives the container the host's network stack), --network=macvlan (gives the container its own MAC on the LAN), or running an mDNS reflector like mdns-repeater on the host.

For learning purposes, the readable order is RFC 6762 → RFC 6763 → the HAP discovery chapter → Docker's bridge networking page. Each one is a few hours' reading and gets you 90% of what you need to debug HomeKit on a non-trivial network. The "dark magic" feeling fades pretty quickly once you've seen the layering — most of it is small standards stacked on each other rather than anything complicated on its own.

Cheers for the BMC, much appreciated.

[Prodeguerriero]

Cheers for the BMC, much appreciated.

My pleasure. Thanks a lot for the help.

[MacrosorcH]

Does Tado CE's HomeKit local control work also for Smart A/C V3+ devices or only for the Tado bridge and the thermostats/valves that connect through it? How does HomeKit setup work for Smart A/C devices?
Btw, thanks for the fantastic work on Tado CE!

[hiall-fyi]

@MacrosorcH, good question. The README's temperature only line is a bit misleading on its own, so quick unpack of what HomeKit local control covers for Smart AC Control V3+ today.

Setup-wise there's nothing AC-specific to do. Smart AC Control units pair through the same Internet Bridge V3+ as your thermostats and TRVs; there's no separate HomeKit code on the AC unit itself. Once you've followed the bridge pairing steps in the README (enable HomeKit in the Tado app, enter the 8-digit code in Tado CE → Configure → Hardware Connections → HomeKit), every AC zone in that home gets picked up automatically alongside the heating zones.

What goes local vs what goes through the cloud:

Action	Path	Latency
Target temperature changes	HomeKit (local)	~2 seconds
HVAC mode (Cool / Heat / Auto / Off)	HomeKit (local)	~2 seconds
Current temperature + humidity reads	HomeKit (local)	Real-time push
Swing mode (any axis, any value)	Cloud	Next poll, 5–30 minutes
Fan speed	Cloud	Next poll, 5–30 minutes
Timer overlays	Cloud	Next poll
Schedules + geofencing	Cloud-only (no HomeKit equivalent)	N/A

So temperature only was shorthand for "the two writes that matter most for a thermostat-style use case go local", but it undersells mode switching, which also goes local. I'll tighten the wording in the next doc patch.

The interesting part for the cooling season just starting is the swing + fan row. Tado's bridge advertises HomeKit's standard accessory protocol, which carries a binary SwingMode characteristic (on/off) but no axis dimension and no fine-grained position values. That maps cleanly onto simple ON/OFF AC units, by far the largest segment, but I haven't yet confirmed the bridge actually exposes that characteristic for AC zones rather than just thermostats. v4.1.0-beta.1 (out yesterday) split the swing dropdown into vertical and horizontal axes, which is the structural prerequisite; the HomeKit fast-path on top of it is the obvious follow-up if the bridge cooperates.

This is where some hardware-side help would be genuinely useful. I don't have a Smart AC Control V3+ in my own setup, so the next step depends on log dumps from people who do. If you've got HomeKit paired (or can pair it), drop the snippet below into configuration.yaml:

logger:
  logs:
    custom_components.tado_ce.homekit_provider: debug
    aiohomekit: debug

Then restart HA once and grab the ~50 lines around the bridge's first connect. That would tell us whether the bridge advertises characteristic UUID B6 (full form: 000000B6-0000-1000-8000-0026BBxxxxxx) inside any AC zone's Heater Cooler service. If it does, swing local-path becomes a v4.1.x patch. If it doesn't, the swing dropdown stays cloud-only and we know to stop scoping it.

Same offer if anything in your AC zone reports unusual capability values, fan modes, or HVAC modes. Drop a debug log and I'll factor it into the v4.1 capability handling. Cooling season is the right window to iron these out.

[MacrosorcH]

@hiall-fyi Thanks for your reply. Smart AC Control V3+ units do not pair through the same Internet Bridge V3+ as the thermostats and TRVs. In fact, each Smart AC Control V3+ unit is an autonomous WiFi device, it doesn't need the bridge to communicate, it has its own HomeKit code and it needs to be paired separately. That's why I was asking what's the pairing procedure with Tado CE, since only the Internet Bridge is mentioned in the docs.
I can help test Smart AC Control V3+ units - I do have a few of them. Let me know what you would find most useful first. Thanks!

[hiall-fyi]

@MacrosorcH, thanks for the correction. I went back and read our HomeKit code afterwards to be certain. Two confirmations:

• homekit_provider.py only consumes HAP Thermostat-service characteristics (the UUIDs Tado's Internet Bridge advertises for heating zones). Smart AC Control units expose the HAP HeaterCooler service instead, with completely different characteristics for active state, heating/cooling thresholds, swing mode, and fan rotation speed. None of those are wired up.
• homekit_mapping.py hardcodes a single bridge accessory dump as the entry point and skips the bridge's own model entry. There's no second pairing to standalone accessories.

So today every Smart AC Control operation goes through the cloud, regardless of whether the bridge is paired locally. The README's ✅ (temperature only) cell had been wrong since v4.0.0 GA; nobody had hands-on Smart AC Control hardware to spot it before you did. I've corrected the docs (README table cell, FEATURES_GUIDE Known Limitations entry, ROADMAP) and the change is in the next release.

On supporting standalone Smart AC Control HomeKit pairing properly: it's a real piece of work. Separate pairing flow per unit, multi-pairing controller management, and HAP HeaterCooler service handling on top of the existing Thermostat path. The blocker isn't the code shape, it's that I don't have Smart AC Control hardware. HomeKit-side bugs are the kind that need real dumps and live testing to catch (the original temperature only claim is the canonical example), and remote-only debugging across timezones tends to lose people after the second roundtrip. I'd rather not lead you through that than ship something half-working, so this one stays in the Future Consideration list rather than being scoped against a beta-tester.

If your Smart AC Control units do anything quirky on the cloud side though, things like fan modes, HVAC modes, or capability values that don't translate cleanly into the climate card, those reports are gold and I can act on them without needing the hardware in front of me. The split-axis swing dropdown that just shipped in v4.1.0-beta.1 was driven by exactly that kind of report from another user. Adding you to CREDITS for the catch on this one.

[rvernout]

@hiall-fyi I use your Tado CE integration since yesterday, because I want to cancel Tado’s ridiculous paid subscription at the next opportunity (January 2027). Before yesterday I had several thousands calls per day, now it appears to have significantly dropped, but not yet under 100. I have a bridge with two thermostats connected via the local HomeKit pairing, and three Smart AC Controls which unfortunately cannot yet pair via HomeKit. Local control of these devices would be really appreciated!

[hiall-fyi]

@rvernout, welcome aboard, and good timing with the January cut-off.

You've read the limitation right: each Smart AC Control pairs over HomeKit as its own standalone WiFi accessory with a separate code, and Tado CE only drives the bridge's pairing today. So all three of your AC units fall through to the cloud for every read and write. That's almost certainly why you're still sitting above 100 calls: the two thermostats read locally off the bridge, but the three AC zones keep polling the cloud.

Local control for those units isn't built, and the honest blocker is hardware. I don't own a Smart AC Control, and HomeKit work is the kind that needs real dumps and live testing to get right, so I'd rather not ship something half-working built blind. The full reasoning is in the ROADMAP under the Smart AC Control entry.

Where you can actually help: would you open a separate Feature Request for Smart AC Control V3+ local control? This thread started as a docs fix and the AC question is buried halfway down, so a dedicated request is the cleanest way for other AC owners to find it and add a 👍. If the demand's clearly there, I'm willing to buy some Smart AC Control units and have a proper go at supporting it officially. @MacrosorcH up-thread has the hardware and offered to test, so the pieces aren't far off.

When you open it, and for anyone adding a 👍, it'd help me scope if you note three things: how many Smart AC Control units you run, the AC model (and whether they're all the same one, mine is purely Daikin Stylish setup), and that they're V3+ rather than an older generation. The unit count matters because AC isn't like heating, where one bridge covers the whole home. Each Smart AC Control is its own accessory with its own pairing, so a three-unit home is three pairings and three cloud-polling zones today. That tells me both the real quota saving on offer and how much multi-pairing work a proper implementation needs. I'll do some reading in the meantime on what these units actually expose over HomeKit, to scope how much local control is even on the table.

#Joe