Update docker documentation for HomeKit pairing #1206
Conversation
| @@ -51,6 +51,8 @@ docker run -d \ | |||
| --network=host \ | |||
| ghcr.io/home-assistant-libs/python-matter-server:stable --storage-path /data --paa-root-cert-dir /data/credentials --bluetooth-adapter 0 | |||
| ``` | |||
| > [!NOTE] | |||
| > Bluetooth is required for using Multi-Admin via HomeKit through the Turn On Pairing Mode feature in the Apple Home app | |||
There was a problem hiding this comment.
Multi-admin does not require Bluetooth, as the device is already on the network (either via Wi-Fi or Thread).
There was a problem hiding this comment.
I cannot currently get the error logs but I will try to get the error logs to you after I return home.
I was not able to add the device (Aqara U300) to my container running within docker, until I added the Bluetooth device to my container.
Can the container work without a Bluetooth device connected to it?
There was a problem hiding this comment.
If the device was never paired to any other controller and so is not already in Thread or Wifi connection then yes you need BLE to pair it. As soon as the device is paired to one controller and was added to an "operational IP network" that way (or was added there by other mechanisms like Aqara native app) you do not need BLE anymore. Could it be that you mean this?
There was a problem hiding this comment.
Nope, I only connected the Aqara U300 (via Thread) to HomeKit, so the "master" controller should be HomeKit and shared to other controllers via IP. From there, I would try to add it to Home Assistant (docker container) via the Matter Server (also running as a docker container). This operation of adding to Home Assistant would always fail/timeout until I added the Bluetooth receiver to the host machine running the containers.
I would enable this in the iOS Home App to turn on Multi-Admin sharing via HomeKit:
There was a problem hiding this comment.
That still makes no sense, because when the device is already commissioned to HomeKit then BLE is off on device by default.
There was a problem hiding this comment.
It didn't make much sense to me either but it's the only solution that worked. I can't get my original logs since they were a month ago but I have a single line from my google searches:
2025-07-23 18:20:31.181 (Dummy-2) CHIP_ERROR [chip.native.EM] <<5 [E:17994i with Node: <0000000000000000, 0> S:0 M:228449703] (U) Msg Retransmission to 0:0000000000000000 failure (max retries:4)
There was a problem hiding this comment.
This would basically point to an MDNX or network issue, or - depending if you run the docker variant of the server on HA OS or not you might not have followed the linux config guide - if the device is a thread device
There was a problem hiding this comment.
So or so I will close the PR now. if you experience the issue again please open an issue on the Home assistant repo and we can research that
No description provided.