feat(ble-proxy): end-to-end BLE proxy commissioning + matter-ble-proxy Python lib

[Apollon77]

Summary

End-to-end BLE proxy commissioning support, plus a brand-new
matter-ble-proxy Python client library that the Home Assistant Matter
integration consumes (see companion HA core PR).

This is two logical changes squashed onto one branch:

1. End-to-end BLE proxy commissioning — Use an external BLE proxy to commission Matter devices directly into the Matter server. This lifts the limitation to only support local ble adapters. Matter device commissioning over the proxy now completes end-to-end (PASE → CASE → operational).

2. matter-ble-proxy Python package — new top-level python_ble_proxy/ package. Ships protocol logic + Bleak-based default backend + CLI. Used by the HA Matter integration to integrate with this new BLE proxy feature of the matter server, and provides a standalone reference CLI for testing.

matter server BLE Proxy support

• When enabled with --ble-proxyCLI option it supports a dedicated BLE proxy websocket protocol at the /ble path of the matter server. Details see https://github.com/matter-js/matterjs-server/blob/590e85dcfa560d03c55f3f3db2aeaf3efd74433c/docs/ble-proxy-protocol.md

JavaScript example using noble

• CLI example including an example in JS which implements a ble-proxy client using "noble" to do the BLE logic and interacts with the server

matter-ble-proxy Python library

• Public API: `MatterBleProxy`, `BleScanSource` /
  `BleDeviceResolver` ABCs, `AdvertisementData` dataclass,
  `BleakScanSource` / `BleakDeviceResolver` defaults.
• Resource-optimized: scanner only runs between
  matter-server's `start_scan` / `stop_scan`. Fully torn down on
  proxy disconnect. No idle scanning.
• All command handlers surface spec-defined error codes
  (`read_failed`, `write_failed`, `subscribe_failed`,
  `not_subscribed`, …) instead of bucketing into
  `internal_error`.
• INFO-level command logging mirroring the JS `noble-ble-proxy`
  example (`[←CMD] id=… command …`), with base64 payloads stripped
  for readability.
• `matter-ble-proxy` console entry: same flag set as the JS
  reference (`--server`, `--log-level`).
• Package is published with the same versioning in sync with the matter server

Docs

• Top-level `README.md` — added "BLE Proxy mode" section pointing
  at both reference clients + the protocol spec.
• `packages/ble-proxy/README.md` — links to the Python package.
• `python_ble_proxy/README.md` — install, CLI, library API.
• `docs/ble-proxy-protocol.md` — new UUID-format section, clarified
  `response` field on `write_characteristic`, and the ATT Write
  Request requirement on `WRITE_DATA` binary frames.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds end-to-end BLE proxy commissioning to the Matter server by introducing a dedicated /ble WebSocket endpoint plus a new @matter-server/ble-proxy package, and ships a new matter-ble-proxy Python library/CLI intended for Home Assistant and standalone bridging.

Changes:

• Add BLE proxy server endpoint support (/ble) and wire it into commissioning via a ProxyBle implementation.
• Introduce new packages/ble-proxy workspace (protocol, handler, ProxyBle transport, noble reference client) with tests.
• Add new python_ble_proxy/ package (library + Bleak CLI) plus CI workflow, docs, and release pipeline updates.

Reviewed changes

Copilot reviewed 43 out of 48 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
tsconfig.json	Adds TS project reference for the new packages/ble-proxy workspace.
README.md	Documents “BLE Proxy mode” and links to protocol + reference clients.
python_ble_proxy/tests/test_protocol.py	Adds unit tests for protocol constants and UUID normalization.
python_ble_proxy/tests/init.py	Initializes Python test package.
python_ble_proxy/README.md	Documents install, CLI usage, and library API for matter-ble-proxy.
python_ble_proxy/pyproject.toml	Defines Python package metadata, deps, and tooling (ruff/mypy/pytest).
python_ble_proxy/matter_ble_proxy/py.typed	Marks package as typed.
python_ble_proxy/matter_ble_proxy/protocol.py	Adds protocol constants/types for the Python client.
python_ble_proxy/matter_ble_proxy/example/cli.py	Adds Bleak-based reference CLI entrypoint.
python_ble_proxy/matter_ble_proxy/example/init.py	Documents example module purpose.
python_ble_proxy/matter_ble_proxy/client.py	Implements core Python BLE proxy client and command handling.
python_ble_proxy/matter_ble_proxy/bleak_backend.py	Provides default Bleak-backed scan + resolve backend.
python_ble_proxy/matter_ble_proxy/init.py	Exposes public Python API symbols.
python_ble_proxy/.gitignore	Adds Python package-local ignores (venv, caches, dist).
packages/ws-controller/src/server/WebSocketControllerHandler.ts	Switches /ws to noServer upgrade handling to avoid breaking other WS endpoints.
packages/ws-controller/package.json	Bumps Matter.js SDK versions and optional @matter/nodejs-ble.
packages/ws-client/package.json	Bumps @matter/testing version.
packages/matter-server/src/MatterServer.ts	Adds --ble-proxy mode, registers /ble handler, and installs ProxyBle into the environment.
packages/matter-server/src/cli.ts	Adds --ble-proxy CLI option + env var mapping.
packages/matter-server/package.json	Adds dependency on @matter-server/ble-proxy and bumps Matter.js SDK versions.
packages/dashboard/package.json	Bumps @matter/main version.
packages/custom-clusters/package.json	Bumps @matter/main version.
packages/ble-proxy/tsconfig.json	Adds composite TS config for the new workspace.
packages/ble-proxy/test/tsconfig.json	Adds test TS config and references.
packages/ble-proxy/test/MockBleDevice.ts	Adds mock peripheral generator used by BLE proxy integration tests.
packages/ble-proxy/test/BleProxyTestClient.ts	Adds a test WS client that simulates the proxy side.
packages/ble-proxy/test/BleProxyProtocolTest.ts	Adds unit tests for binary frame codec.
packages/ble-proxy/test/BleProxyIntegrationTest.ts	Adds integration tests for /ble handler + ProxyBle flows.
packages/ble-proxy/src/tsconfig.json	Adds library TS config and references.
packages/ble-proxy/src/ProxyBleScanner.ts	Implements scanner wrapper using the proxy client.
packages/ble-proxy/src/ProxyBleClient.ts	Implements proxy-side discovery client for server-side scanning.
packages/ble-proxy/src/ProxyBleChannel.ts	Implements BLE central interface + BTP channel over the proxy protocol.
packages/ble-proxy/src/ProxyBle.ts	Implements Ble environment provider that routes via the proxy.
packages/ble-proxy/src/index.ts	Exports public API for @matter-server/ble-proxy.
packages/ble-proxy/src/example/NobleBleProxyClient.ts	Adds noble-based reference implementation of the client side.
packages/ble-proxy/src/example/noble-ble-proxy.ts	Adds CLI wrapper for the noble reference client.
packages/ble-proxy/src/BleProxyProtocol.ts	Defines protocol messages/types and binary frame codec for TS.
packages/ble-proxy/src/BleProxyHandler.ts	Implements /ble WebSocket handler (handshake + command routing).
packages/ble-proxy/README.md	Documents server enablement and reference clients (JS + Python).
packages/ble-proxy/package.json	Adds new published workspace package definition and scripts.
package.json	Adds workspace entry + helper scripts for noble + python BLE proxy workflows.
package-lock.json	Updates lockfile for new workspace, deps, and version bumps.
docs/docker.md	Documents new BLE_PROXY env var.
docs/cli.md	Documents new --ble-proxy CLI option and exclusivity with --bluetooth-adapter.
docs/ble-proxy-protocol.md	Adds full BLE proxy protocol specification and clarifications.
.gitignore	Ignores local AI-tooling scratch directories.
.github/workflows/test-python-ble-proxy.yml	Adds CI workflow for Python BLE proxy lint/typecheck/tests.
.github/workflows/release-npm.yml	Extends release pipeline to optionally publish matter-ble-proxy to PyPI.

[Copilot]

Pull request overview

Copilot reviewed 48 out of 53 changed files in this pull request and generated 4 comments.

Comments suppressed due to low confidence (1)

packages/ble-proxy/src/BleProxyHandler.ts:202

• sendCommand() has no timeout, so if the proxy client never responds (e.g., BLE stack stalls) the returned promise stays pending and the entry remains in #pendingCommands until disconnect. This can hang commissioning flows indefinitely. Consider adding a per-command timeout (and clearing the pending map entry on timeout) similar to packages/ws-client/src/client.ts's sendCommand implementation.

    async sendCommand<C extends BleProxyCommandName>(
        command: C,
        ...rest: BleProxyCommandMap[C]["args"] extends undefined ? [] : [args: BleProxyCommandMap[C]["args"]]
    ): Promise<BleProxyCommandMap[C]["result"]> {
        if (!this.connected || !this.#client) {
            throw new Error("BLE proxy client not connected");
        }

        const args = rest[0];
        const id = this.#nextCommandId;
        this.#nextCommandId = (this.#nextCommandId + 1) & 0xffff;
        const message: CommandMessage = { id, command };
        if (args !== undefined) {
            message.args = args as Record<string, unknown>;
        }

        const { promise, resolver, rejecter } = createPromise<Record<string, unknown> | undefined>();
        this.#pendingCommands.set(id, { resolver, rejecter });

        this.#client.send(JSON.stringify(message), err => {
            if (err) {
                this.#pendingCommands.delete(id);
                rejecter(new Error(`Failed to send command ${command}: ${err.message}`));
            }
        });

        return promise as Promise<BleProxyCommandMap[C]["result"]>;
    }

[Copilot]

Pull request overview

Copilot reviewed 48 out of 54 changed files in this pull request and generated 5 comments.

Files not reviewed (1)

• .idea/ha-matterjs-server.iml: Language not supported

[Copilot]

Pull request overview

Copilot reviewed 48 out of 54 changed files in this pull request and generated 4 comments.

Files not reviewed (1)

• .idea/ha-matterjs-server.iml: Language not supported