This release is a pre-release and may not be stable for production use.
matter-ble-proxy
Python client library for the OHF Matter Server BLE proxy WebSocket protocol.
The matter-server can run on a host with no BLE adapter and delegate every BLE operation to a separate process or device. This library implements the client side of that protocol so that any Python process with access to a BLE adapter (via Bleak, Home Assistant's bluetooth component, an ESPHome BLE proxy, ...) can act as the BLE bridge.
The protocol is documented in docs/ble-proxy-protocol.md.
Install
pip install matter-ble-proxy
Python 3.12+ required.
Standalone CLI
The package ships a reference CLI mirroring the JS noble-ble-proxy example.
Useful for testing the matter-server's /ble endpoint without Home Assistant
in the loop.
# Start the matter-server with --ble-proxy in one terminal, then:
matter-ble-proxy --server ws://localhost:5580/ble
The CLI uses Bleak directly against the local OS bluetooth adapter.
Library API
For integrators (Home Assistant, custom add-ons, etc.) wire your own BLE source in by implementing two ABCs:
from matter_ble_proxy import (
AdvertisementData,
BleDeviceResolver,
BleScanSource,
MatterBleProxy,
)
class MyScanSource(BleScanSource):
async def start(self, callback): ... # call `callback(AdvertisementData(...))`
async def stop(self): ...
class MyDeviceResolver(BleDeviceResolver):
async def resolve(self, address): ... # return a bleak.BLEDevice / address / None
proxy = MatterBleProxy(
ws_url="ws://localhost:5580/ble",
scan_source=MyScanSource(),
device_resolver=MyDeviceResolver(),
)
await proxy.connect()
await proxy.run_until_closed()
await proxy.disconnect()
The default Bleak-backed implementations (BleakScanSource,
BleakDeviceResolver) live in matter_ble_proxy.bleak_backend.
Reconnection
MatterBleProxy does not reconnect on its own. When the WebSocket closes — server
restart, network blip, or the caller calling disconnect() — run_until_closed()
returns after the library releases all BLE resources (active scan stopped, every
peripheral disconnected). The caller decides whether to reconnect:
- The bundled CLI exits on disconnect; restart it manually.
- Home Assistant ties the BLE proxy lifecycle to the matter-server WebSocket: when
HA reconnects to the matter-server it constructs and connects a fresh
MatterBleProxyfor the new session. - A custom integration can wrap
connect()+run_until_closed()in a retry loop with whatever backoff and cancellation policy fits its supervisor.
The library deliberately stays out of this decision so it can plug into hosts that already own reconnect logic (HA, systemd, etc.) without fighting them.
Development
This package lives inside the matter-js/matterjs-server repo and shares its release pipeline. From the repo root:
npm run python-ble-proxy:install # create venv + install editable + test deps
npm run python-ble-proxy:lint # ruff
npm run python-ble-proxy:typecheck # mypy
npm run python-ble-proxy:test # pytest
npm run python-ble-proxy:build # build sdist+wheel
1 maintainer
Metadata
1 maintainer
Release files for matter-ble-proxy 1.4.0a0.dev20260802
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| matter_ble_proxy-1.4.0a0.dev20260802.tar.gz | 17.4 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| matter_ble_proxy-1.4.0a0.dev20260802-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 33.9 kB
Release files / matter_ble_proxy-1.4.0a0.dev20260802.tar.gz
| Download URL | matter_ble_proxy-1.4.0a0.dev20260802.tar.gz |
|---|---|
| Size | 17.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
34925eb5ecc2916dc9002e53c115aa96b980ae0995420adb22afbb45f1eb2338
|
|
BLAKE2b-256 checksum How to use checksums |
5e7f237a08a1bae3a5ab2ab1ce20ead2498fd7a81d52fa7c35d838143975eeb5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 2, 2026.
Transparency logRelease files / matter_ble_proxy-1.4.0a0.dev20260802-py3-none-any.whl
| Download URL | matter_ble_proxy-1.4.0a0.dev20260802-py3-none-any.whl |
|---|---|
| Size | 16.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
736f671920c38034cbd33a09c0768508a01df96cc57cd7a39bab04923f8f67d6
|
|
BLAKE2b-256 checksum How to use checksums |
c77d9211f0a3e357160d94e898f5925880beb9c8987faab076f3b77e732e1ceb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 2, 2026.
Transparency log
