matter-ble-proxy

What it is and what it does

matter-ble-proxy is a Python client library that implements the OHF Matter Server's BLE proxy protocol, enabling a Matter Server running on a host without a BLE adapter to delegate Bluetooth operations to a separate process or device. It sits between a local BLE source and a remote Matter Server's `/ble` WebSocket endpoint, translating BLE scan results and device operations into the proxy protocol.

The library provides both a standalone CLI tool for testing and a pluggable library API. Integrators implement two abstract base classes—BleScanSource (to feed BLE advertisements) and BleDeviceResolver (to resolve device addresses)—then instantiate MatterBleProxy with a WebSocket URL and those implementations. The library deliberately does not manage reconnection; it releases all BLE resources and returns control when the WebSocket closes, leaving retry logic to the caller's supervisor.

Use it for:

• Run a Matter Server on a host with no Bluetooth adapter while delegating BLE operations to a separate device with a BLE radio.
• Integrate Matter BLE bridging into Home Assistant by wiring its native Bluetooth component as the scan source and device resolver.
• Build a custom Matter gateway that aggregates BLE devices from multiple physical locations by running proxy instances on each site.
• Test a Matter Server's `/ble` endpoint in isolation without a full Home Assistant deployment using the bundled CLI.
• Implement a BLE proxy for home automation systems that need to speak Matter protocol over a network boundary.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

A Python client library that bridges BLE operations to a remote Matter Server via WebSocket, allowing any process with a BLE adapter to act as a BLE proxy for Matter protocol communication.

Yes, if you are building or integrating with a Matter Server and need to separate BLE hardware from the server host. The library is actively maintained, has low install friction, carries a permissive Apache-2.0 license, and is designed for exactly this delegation pattern. Not relevant if your Matter Server and BLE adapter are on the same machine or if you do not need Matter protocol support.

Install

matter-ble-proxy on PyPI

pip install matter-ble-proxy

uv add matter-ble-proxy

poetry add matter-ble-proxy

Installing matter-ble-proxy

Before you install

Low friction: pure Python wheel with only two runtime dependencies (aiohttp, bleak). Active maintenance with a release 7 days old. Requires Python 3.12+, which is a hard constraint but clearly stated.

License in practice

Apache-2.0 permissive license allows commercial and private use with minimal restrictions; suitable for most integration scenarios including proprietary systems.

Quickstart

pip install matter-ble-proxy

from matter_ble_proxy import MatterBleProxy, BleScanSource, BleDeviceResolver

proxy = MatterBleProxy(
    ws_url="ws://localhost:5580/ble",
    scan_source=MyScanSource(),
    device_resolver=MyDeviceResolver(),
)
await proxy.connect()
await proxy.run_until_closed()

Requires Python 3.12+. Caller must implement BleScanSource and BleDeviceResolver abstract base classes; default Bleak-backed implementations are available in matter_ble_proxy.bleak_backend.

Verify before relying

• Whether the library handles reconnection automatically or requires caller-managed retry logic.
• Performance characteristics and latency overhead of the WebSocket proxy layer compared to direct BLE access.
• Compatibility with specific Matter Server versions or protocol versions.

Package facts

Evidence: matter_ble_proxy-1.4.0-py3-none-any.whl

Tags

More Home Automation packages