Cannot add Thread over Matter device from Homekit to HA

Hi There,
I’m new to HA and have just setup my HA on a VM in my QNAP VirtualizationStation successfully. Just runs fine and have already added devices. OS 13.1 and Core is v 2024.10.2

Now I want to add my already existing HomeKit devices, that run over Thread via matter (TBR is an AppleTV). These are mostly EVE devices like EVE Energy. I have already read many how-tos and docus and tried to follow that what I found.
like Matter (BETA) - Home Assistant

That is:

  • Add AppleTV to HA
  • Enable Matter Server addon (was automatically added)
  • Send credentials
  • Set preferred Thread Netwok to my existing Network on AppleTV (MyHome2)

When I now generate the paring code in HomeKit and add it via the Companion App it will fail. I see the following logs in the Matter-Server protocols:

2024-10-13 12:22:17.064 (MainThread) INFO [matter_server.server.device_controller] Starting Matter commissioning with code using Node ID 6.
2024-10-13 12:22:17.080 (Dummy-2) CHIP_ERROR [chip.native.-] src/inet/UDPEndPointImplSockets.cpp:416: OS Error 0x02000065: Network is unreachable at src/controller/SetUpCodePairer.cpp:280
2024-10-13 12:22:47.081 (Dummy-2) CHIP_ERROR [chip.native.CTL] Discovery timed out
2024-10-13 12:22:47.081 (Dummy-2) CHIP_ERROR [chip.native.ZCL] Secure Pairing Failed
2024-10-13 12:22:47.082 (Dummy-2) WARNING [chip.ChipDeviceCtrl] Failed to establish secure session to device: src/controller/python/ChipDeviceController-ScriptDevicePairingDelegate.cpp:89: CHIP Error 0x00000003: Incorrect state
2024-10-13 12:22:47.082 (MainThread) ERROR [matter_server.server.client_handler] [139631609197392] Error while handling: commission_with_code: Commission with code failed for node 6.

Any clue what’s the issue here?

This is almost certainly a networking problem. Commissioned Thread devices use a dedicated IPv6 subnet and your HA server seems to have a problem finding or accessing that subnet. Read the pinned helpful hints and let us know if you have any unusual network topologies (multiple vlans, dual-homed servers, etc) that could be complicating things.

BTW there is no need to add the Apple TV or share credentials or make preferred if your Matter devices are already commissioned to Apple Home. You just need to get the add-on and confirm the Thread subnet is reachable, then you can share your Apple Home Matter devices with HA.

I have a flat network with no VLANs. IPv6 is enabled.
I use a Adguard Home for DNS filtering. HA is running in a VM on QNAP NAS which has virtual switch configuration and a firewall, but I already deactivated the firewall to test if it’s an issue. It’s not. The virtual switch is mandatory.

All devices seem to have an ipv6 adress. I see that the AppleTV has 4 v6 adresses:
fe80::1c2b:c489:5a9a:52ea
2a01:41e3:2b48:5500:a4:fd1d:f632:79b2
2a01:41e3:2b48:5500:1c2b:c489:5a9a:52ea
2a01:41e3:2b48:5500:81e1:54f8:b976:22b4
I suspect one of those interfaces is the Thread network ??? How can I find out, what’s the Thread subnet?

Now I’m not an IPv6 expert, my knowledge is limited here. But I can ping all of the above adresses from my PC.

But what I now noticed, that I can’t ping the HA host with its ipv6 adress. HA shows me the adress fe80::3997:f856:9726:8b4b but I can’t ping it from my PC. Is there a way to test if the HA host can reach (ping) the the above IPs from the ATV?

Screenshot 2024-10-18 104553

Curious how you found those Apple TV addresses. I only see three addresses on my Thread-enabled Apple TV, the fe80 link-local, and two fdxx “unique local” (non-globally routable) addresses (ULA).

The 2a01:: address space is a “real” globally-routable IPv6 Internet address, likely provided by your ISP and allocated by your router to devices on your LAN. The Matter spec says that if there are no routable addresses on the LAN, then the controller can create a ULA subnet; I guess since your router is handing out global IPs, there was no need for Apple to hand out fdxx addresses.

Either way, none of those is your Thread subnet. Thread border routers are literally just IP routers that pass traffic between different subnets, so Thread has to have a different address range than your WiFi subnet. For example, my primary LAN uses fdc4:: address space, while my Thread devices use fd98:: addresses behind the border routers. On my HA server, I can see this by looking at the IP routing table, which shows five next-hops (all my Border Routers) to get to the fd98:: network:

peter@felix:~$ ip -6 route show
::1 dev lo proto kernel metric 256 pref medium
fd98:c4e1:4d6e::/64 proto ra metric 1024 expires 1723sec pref medium
	nexthop via fe80::8ef:f64:47de:c907 dev vlan.1 weight 1 
	nexthop via fe80::14ec:f356:bd9b:2df6 dev vlan.1 weight 1 
	nexthop via fe80::8df:77d1:4e27:3823 dev vlan.1 weight 1 
	nexthop via fe80::1083:bb8e:87a0:d296 dev vlan.1 weight 1 
	nexthop via fe80::ad:f719:8883:b087 dev vlan.1 weight 1 
fdc4:4aab:e77f:e44c::/64 dev vlan.1 proto ra metric 1024 expires 1789sec pref medium

Thread device IPs are pretty well hidden, however. To view them, you need a mDNS browser such as “Flame” (iOS) or “Discovery” for MacOS, or avahi-browse on linux, and at least one provisioned Matter-over-Thread device online. For example, in the first screenshot below (from the “Discovery” app), you can see my Apple TV has three IPv6 addresses, two on the local fdc4:: subnet, and is a Thread border router (it is advertising _meshcop._udp service). But none of these IPs is the Thread subnet. Update: on second look, the last address ends in “fd98:c4e1:4d6e”, which is the beginning of the Thread subnet, which can’t possibly be a coincidence, I will keep a closer eye on this in the future.

meshcop

In the next screenshot you see the same IPs in the _matter._tcp section has hostname 344851A4BBC2.local — that’s the Apple TV Matter controller. While another Matter device, 0A18B5D4FAD7546D.local, has an IP address starting with fd98:: which suggests it is on the Thread subnet.

matter-tcp

Again on HA server, at the command prompt I can ping6 this Thread device and confirm the pings stop succeeding when it’s unplugged. I can also run traceroute6 and see that there is a hop through one of my HomePod border routers to get to the device.

peter@felix:~$ traceroute6 0A18B5D4FAD7546D.local
traceroute to 0A18B5D4FAD7546D.local (fd98:c4e1:4d6e:0:c367:4d65:5e96:5215) from fdc4:4aab:e77f:e44c:b645:6ff:fe5b:9d68, port 33434, from port 59640, 30 hops max, 60 bytes packets
 1  Bedroom-HomePod-0499B9786562.local (fdc4:4aab:e77f:e44c:4ad:5f0a:2036:c714)  5.170 ms  6.781 ms  5.718 ms 
 2  0A18B5D4FAD7546D.local (fd98:c4e1:4d6e:0:c367:4d65:5e96:5215)  1748.502 ms  * 1172.088 ms 

That said, all this is working on my network and I still cannot share an Apple Home Matter-over-Thread device with HA. The HA Matter Server must be using some alternative routing scheme that ignores the host Linux route table, or there is some other reason why I am getting the same “Incorrect state” error that you are getting. I’m still troubleshooting, so if you have any tips please let me know. I will probably compile a troubleshooting guide once I finally figure out the problem.

I have a similar problem. My HAOS also runs in a VM on QNAP.
All firmware up to date.
Until 2 weeks ago, the EVE Energy devices were visible and switchable in both systems via Thread/Matter.
I can’t say whether an update of HA or replacing the Fritzbox meant that the EVE are no longer visible in HA.
When I factory reset the devices, I can add them to Home without any problem, but pairing always ends in error.
Adding directly to HA via the Matter integration brings the same error message.

2024-11-05 16:44:14.943 (MainThread) ERROR [matter_server.server.client_handler] [140104323054800] Error while handling: commission_with_code: Commission with code failed for node 124.
2024-11-05 16:53:10.498 (MainThread) INFO [matter_server.server.device_controller] Starting Matter commissioning with code using Node ID 125.
2024-11-05 16:53:10.599 (Dummy-2) CHIP_ERROR [chip.native.-] src/inet/UDPEndPointImplSockets.cpp:416: OS Error 0x02000065: Network is unreachable at src/controller/SetUpCodePairer.cpp:280
2024-11-05 16:53:40.529 (Dummy-2) CHIP_ERROR [chip.native.CTL] Discovery timed out
2024-11-05 16:53:40.529 (Dummy-2) CHIP_ERROR [chip.native.ZCL] Secure Pairing Failed
2024-11-05 16:53:40.530 (Dummy-2) WARNING [chip.ChipDeviceCtrl] Failed to establish secure session to device: src/controller/python/ChipDeviceController-ScriptDevicePairingDelegate.cpp:89: CHIP Error 0x00000003: Incorrect state
2024-11-05 16:53:40.560 (MainThread) ERROR [matter_server.server.client_handler] [140104323054800] Error while handling: commission_with_code: Commission with code failed for node 125.

Guys, I’m sorry. I’ve given up. I couldn’t get it to work on my QNAP VM. And as a test with a HA on a VirtualBox on Windows showed, that it DOES work, I got myself a Raspberry Pi 5 with NVMe SSD and installed my HA there. No troubles, adding Matter over Thread devices!

So it must be related to a networking issue somewhere in the hypervisor stack of QNAP.