I want to use the ESPHome Bluetooth Proxy feature to commission Matter over Thread devices (e.g. IKEA Myggbett). Matterjs-server 0.7.x supports this feature as an alternative to using the host's Bluetooth directly, but the documentation is somewhat vague imho.
I've already added this configuration to an esp32-c3-devkitm-1 device, an Athom LS8P LED strip controller.
esp32_ble_tracker:
bluetooth_proxy:
active: true
First question: Is the BLE tracker needed for my usecase?esphome run does not error if I leave it out. For now, I have kept it in because it seems to follow ESPHome documentation.
On the matterjs-server side, I've added the BLE_PROXY=true environment variable. This enables commissioning of Thread devices in the web UI, which was previously greyed out. However when I try to commission, it fails after a long timeout and I see this in the logs:
matterjs-server-1 | 2026-05-27 22:52:15.333 INFO MatterServer BLE proxy mode enabled
matterjs-server-1 | 2026-05-27 22:52:15.631 INFO Controller~ndHandler BLE is enabled (proxy mode)
matterjs-server-1 | 2026-05-27 22:52:20.560 INFO BleProxyHandler BLE proxy WebSocket endpoint registered on /ble
matterjs-server-1 | 2026-05-27 23:20:13.106 INFO ProxyBleClient BLE proxy not connected, waiting up to 30000ms for client
...
ESC[2Kmatterjs-server-1 | ESC[2m2026-05-27 23:23:13.114 ERROR ESC[0;1;90mWebSocketC~erHandler ESC[0;31m[1] WebSocket error response (commis
sion_with_code) 2009082749 Commission failed: discovery of node with discriminator 83 failed
ESC[2Kmatterjs-server-1 | ESC[2;39mat ESC[0mFunction.nodeCommissionFailedESC[2m (/app/node_modules/@matter-server/ws-controller/src/type
s/WebSocketMessageTypes.ts:99:16)
ESC[2Kmatterjs-server-1 | at ESC[0mControllerCommandHandler.commissionNodeESC[2m (/app/node_modules/@matter-server/ws-controller/src/con
troller/ControllerCommandHandler.ts:959:31)
ESC[2Kmatterjs-server-1 | at ESC[0masync WebSocketControllerHandler.#handleCommissionWithCodeESC[2m (/app/node_modules/@matter-server/ws
-controller/src/server/WebSocketControllerHandler.ts:698:28)
ESC[2Kmatterjs-server-1 | at ESC[0masync WebSocketControllerHandler.#handleWebSocketRequestESC[2m (/app/node_modules/@matter-server/ws-c
ontroller/src/server/WebSocketControllerHandler.ts:471:30)
ESC[2Kmatterjs-server-1 | ESC[0mCaused by: ESC[31m[ESC[1mdiscovery-aggregateESC[0;31m] discovery of node with discriminator 83 failed
ESC[2Kmatterjs-server-1 | ESC[2;39mat ESC[0mFunction.allSettledESC[2m (/app/node_modules/@matter/general/src/MatterError.ts:256:19)
ESC[2Kmatterjs-server-1 | at ESC[0masync Promise.allESC[2m (index 1)
ESC[2Kmatterjs-server-1 | at ESC[0masync withTimeoutESC[2m (/app/node_modules/@matter/general/src/util/Promises.ts:141:5)
ESC[2Kmatterjs-server-1 | ESC[0mCause #0: ESC[31m[ESC[1mbleESC[0;31m] BLE proxy client did not connect within 30000ms — cannot start sca
n
ESC[2Kmatterjs-server-1 | ESC[2;39mat ESC[0mProxyBleClient.startScanningESC[2m (/app/node_modules/@matter-server/ble-proxy/src/ProxyBleClient.ts:80:23)
ESC[2Kmatterjs-server-1 | at ESC[0masync ProxyBleScanner.findCommissionableDevicesContinuouslyESC[2m (/app/node_modules/@matter/protocol/src/common/BleScanner.ts:346:9)
ESC[2Kmatterjs-server-1 | at ESC[0masync Promise.allSettledESC[2m (index 0)
ESC[2Kmatterjs-server-1 | at ESC[0masync Function.allSettledESC[2m (/app/node_modules/@matter/general/src/MatterError.ts:252:25)
ESC[2Kmatterjs-server-1 | at ESC[0masync Promise.allESC[2m (index 1)
ESC[2Kmatterjs-server-1 | (see parent frames)ESC[0m
Sorry about the formatting. But I think it's clear the ESPHome bluetooth proxy doesn't connect to the matterjs-server /ble WebSocket endpoint.
Question: How does ESPHome discover that /ble endpoint? I could not find any URL or IP/host configuration. Is it supposed to happen automatically, e.g. via mDNS?
My environment:
ESPHome 2026.5.1
matterjs-server 0.7.1 running in Docker version 26.1.5+dfsg1
I should add that adding the above config to my ESPHome implicitly added a Bluetooth device category to my Home Assistant which has already collected tons of advertisements of nearby devices. I've ignored the Apple iBeacon tracker because I assume I don't need it for commissioning of Thread devices.
However the Bluetooth integration shows 0 connections, and I still have not found a way to connect the Bluetooth Proxy (or its Home Assistant integration) to matterjs-server /ble WebSocket endpoint.
From my understanding, the ble proxy option is not done directly by the Matter server but via the HA Core Matter Integration over a websocket starting in HA Core 2026.6 (now in Beta). Couple of datapoints:
From the Developer:
The newly added "BLE Proxy" feature can be used later in HA 2026.06
From the HA Core 2026.6 Beta Release Notes:
Matter can onboard new devices over Bluetooth proxies.The Matter integration can now act as a Bluetooth bridge for the Matter Server, so devices that only expose their commissioning interface over Bluetooth LE can be paired even when the server itself has no Bluetooth adapter. ESPHome Bluetooth proxies count too, which means a new Matter device tucked away in the garage can be onboarded through the proxy in your kitchen.
As far as any special configuration/setup, other than enabling the option in Matter Server, that I'm not sure about
That's a good hint, thanks! Using HA 2026.6.0b0 seem to enable the feature and I see traces of Bluetooth comm in the matterjs-server log. For now, it fails though. FWIW, I've opened an issue here: