Skip to content

Update docker documentation for HomeKit pairing #1206

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from
Closed

Update docker documentation for HomeKit pairing #1206

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions docs/docker.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Multi-admin does not require Bluetooth, as the device is already on the network (either via Wi-Fi or Thread).

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Author

@alams154 alams154 Aug 27, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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:
image

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That still makes no sense, because when the device is already commissioned to HomeKit then BLE is off on device by default.

Copy link
Author

@alams154 alams154 Aug 27, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


## Running using Docker compose

Expand Down