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.5.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| matter_ble_proxy-1.5.0.tar.gz | 20.9 kB | With provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| matter_ble_proxy-1.5.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 38.3 kB
Release files / matter_ble_proxy-1.5.0.tar.gz
| Download URL | matter_ble_proxy-1.5.0.tar.gz |
|---|---|
| Size | 20.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9eb2007acd15bbfef1a40d69dc9d9ad1608fe7c0e59067da62bfc34b72018a64
|
|
BLAKE2b-256 checksum How to use checksums |
71ba22ec46337312012584d7f00075efa879544b4fd5473a33b1e6eb152f21af
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.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 Oct 20, 2026.
Transparency logRelease files / matter_ble_proxy-1.5.0-py3-none-any.whl
| Download URL | matter_ble_proxy-1.5.0-py3-none-any.whl |
|---|---|
| Size | 17.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b2548547fc38ea9a5fad47582c622c378416acfa515d07340a1a75d6d17641c3
|
|
BLAKE2b-256 checksum How to use checksums |
35ff3545aaf934e41a62d71abcd20fa5bbe783884f9c878b04d523b449f33994
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.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 Oct 20, 2026.
Transparency logSecurity for matter-ble-proxy 1.5.0
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.
Full provenance
All 2 files in this release have been uploaded with provenance metadata.
Attestation for matter_ble_proxy-1.5.0.tar.gz
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 Oct 20, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
