matter-ble-proxy 0.7.1__tar.gz

matter_ble_proxy-0.7.1/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: matter-ble-proxy
+Version: 0.7.1
+Summary: Python client library for the OHF Matter Server BLE proxy protocol
+Author-email: Open Home Foundation <hello@openhomefoundation.io>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/matter-js/matterjs-server
+Project-URL: Source, https://github.com/matter-js/matterjs-server/tree/main/python_ble_proxy
+Project-URL: Bug Tracker, https://github.com/matter-js/matterjs-server/issues
+Project-URL: Changelog, https://github.com/matter-js/matterjs-server/blob/main/CHANGELOG.md
+Platform: any
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Home Automation
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: aiohttp
+Requires-Dist: bleak
+Provides-Extra: test
+Requires-Dist: codespell==2.4.1; extra == "test"
+Requires-Dist: isort==7.0.0; extra == "test"
+Requires-Dist: mypy==1.19.1; extra == "test"
+Requires-Dist: pylint==4.0.4; extra == "test"
+Requires-Dist: pytest>=9.0; extra == "test"
+Requires-Dist: pytest-asyncio>=0.24; extra == "test"
+Requires-Dist: pytest-aiohttp>=1.0; extra == "test"
+Requires-Dist: pytest-cov>=7.0; extra == "test"
+Requires-Dist: ruff==0.14.9; extra == "test"
+
+# matter-ble-proxy
+
+Python client library for the [OHF Matter Server](https://github.com/matter-js/matterjs-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](https://github.com/hbldh/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`](https://github.com/matter-js/matterjs-server/blob/main/docs/ble-proxy-protocol.md).
+
+## Install
+
+```bash
+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.
+
+```bash
+# 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:
+
+```python
+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
+  `MatterBleProxy` for 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](https://github.com/matter-js/matterjs-server) repo
+and shares its release pipeline. From the repo root:
+
+```bash
+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
+```

matter_ble_proxy-0.7.1/README.md

@@ -0,0 +1,97 @@
+# matter-ble-proxy
+
+Python client library for the [OHF Matter Server](https://github.com/matter-js/matterjs-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](https://github.com/hbldh/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`](https://github.com/matter-js/matterjs-server/blob/main/docs/ble-proxy-protocol.md).
+
+## Install
+
+```bash
+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.
+
+```bash
+# 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:
+
+```python
+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
+  `MatterBleProxy` for 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](https://github.com/matter-js/matterjs-server) repo
+and shares its release pipeline. From the repo root:
+
+```bash
+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
+```

matter_ble_proxy-0.7.1/matter_ble_proxy/__init__.py

@@ -0,0 +1,40 @@
+"""Python client library for the OHF Matter Server BLE proxy protocol.
+
+This package implements the client side of the BLE proxy WebSocket protocol
+exposed by the matter-server's `/ble` endpoint. It bridges a Matter
+commissioning controller running on the server to a local BLE adapter on the
+client side (Bleak directly, Home Assistant's bluetooth component, ESPHome BLE
+proxies, etc.).
+
+The core protocol logic lives in :mod:`matter_ble_proxy.client` and is BLE-
+transport-agnostic via the :class:`BleScanSource` and :class:`BleDeviceResolver`
+abstractions. A default :class:`BleakScanSource` + :class:`BleakDeviceResolver`
+implementation is provided in :mod:`matter_ble_proxy.bleak_backend` for
+standalone use; integrators (e.g. Home Assistant) supply their own backend.
+"""
+
+from .bleak_backend import BleakDeviceResolver, BleakScanSource
+from .client import BleDeviceResolver, BleScanSource, ConnectionState, MatterBleProxy
+from .protocol import (
+    BINARY_FRAME_HEADER,
+    BLE_PROXY_PROTOCOL_VERSION,
+    OPCODE_NOTIFICATION,
+    OPCODE_READ_RESPONSE,
+    OPCODE_WRITE_DATA,
+    AdvertisementData,
+)
+
+__all__ = [
+    "BINARY_FRAME_HEADER",
+    "BLE_PROXY_PROTOCOL_VERSION",
+    "OPCODE_NOTIFICATION",
+    "OPCODE_READ_RESPONSE",
+    "OPCODE_WRITE_DATA",
+    "AdvertisementData",
+    "BleDeviceResolver",
+    "BleScanSource",
+    "BleakDeviceResolver",
+    "BleakScanSource",
+    "ConnectionState",
+    "MatterBleProxy",
+]

matter_ble_proxy-0.7.1/matter_ble_proxy/bleak_backend.py

@@ -0,0 +1,108 @@
+"""Default Bleak-based backend for the BLE proxy client.
+
+Use these when the host process owns its own BLE adapter directly via Bleak
+(CLI tools, integration tests, single-tenant servers). Home Assistant supplies
+a different backend that wires into its bluetooth component.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+from bleak import BleakScanner
+
+from .client import BleDeviceResolver, BleScanSource
+from .protocol import AdvertisementData
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from bleak.backends.device import BLEDevice
+    from bleak.backends.scanner import AdvertisementData as BleakAdvertisementData
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class BleakScanSource(BleScanSource):
+    """Scan source backed by a directly-managed `BleakScanner`.
+
+    The scanner is created on each :meth:`start` and torn down on :meth:`stop`,
+    so the BLE adapter sits idle whenever the matter-server is not actively
+    scanning. The first `start_scan` after a process boot pays the native
+    cold-start cost (CoreBluetooth state transition to `powered_on`, DBus
+    handshake) — typically tens to hundreds of milliseconds.
+    """
+
+    def __init__(self) -> None:
+        """Initialize."""
+        self._scanner: BleakScanner | None = None
+        self._callback: Callable[[AdvertisementData], None] | None = None
+        # Cache the most recent BLEDevice per address so BleakDeviceResolver
+        # can hand a fully-formed device to BleakClient (more reliable than
+        # connecting by address alone on some platforms).
+        self._device_cache: dict[str, BLEDevice] = {}
+
+    @property
+    def device_cache(self) -> dict[str, BLEDevice]:
+        """Read-only access for paired :class:`BleakDeviceResolver`."""
+        return self._device_cache
+
+    async def start(self, callback: Callable[[AdvertisementData], None]) -> None:
+        """Start the scanner if not already running."""
+        self._callback = callback
+        if self._scanner is not None:
+            return
+        self._scanner = BleakScanner(detection_callback=self._on_detection)
+        await self._scanner.start()
+
+    async def stop(self) -> None:
+        """Stop the scanner and release the BLE adapter."""
+        scanner = self._scanner
+        self._scanner = None
+        self._callback = None
+        if scanner is not None:
+            try:
+                await scanner.stop()
+            except Exception:
+                _LOGGER.debug("Error stopping BleakScanner", exc_info=True)
+
+    def _on_detection(self, device: BLEDevice, advertisement: BleakAdvertisementData) -> None:
+        self._device_cache[device.address] = device
+        cb = self._callback
+        if cb is None:
+            return
+        ad = AdvertisementData(
+            address=device.address,
+            name=advertisement.local_name or device.name,
+            rssi=advertisement.rssi,
+            connectable=True,  # Bleak does not expose this directly; assume true.
+            service_data=dict(advertisement.service_data),
+            manufacturer_data=dict(advertisement.manufacturer_data),
+            service_uuids=list(advertisement.service_uuids),
+        )
+        try:
+            cb(ad)
+        except Exception:
+            _LOGGER.exception("BLE proxy advertisement callback raised")
+
+
+class BleakDeviceResolver(BleDeviceResolver):
+    """Default resolver: prefer a cached `BLEDevice`, fall back to the address.
+
+    When paired with :class:`BleakScanSource`, the resolver reuses the device
+    object the scanner observed. Without a paired source it returns the raw
+    address — Bleak then performs its own short scan inside `connect()`.
+    """
+
+    def __init__(self, scan_source: BleakScanSource | None = None) -> None:
+        """Initialize."""
+        self._scan_source = scan_source
+
+    async def resolve(self, address: str) -> BLEDevice | str | None:
+        """Return cached `BLEDevice` if available, else the address."""
+        if self._scan_source is not None:
+            device = self._scan_source.device_cache.get(address)
+            if device is not None:
+                return device
+        return address

matter_ble_proxy-0.7.1/matter_ble_proxy/cli.py

@@ -0,0 +1,105 @@
+"""Reference Bleak-based CLI for the matter-ble-proxy client library.
+
+Connects to a matter-server `/ble` WebSocket endpoint and bridges a local
+Bleak adapter into it. Useful for:
+
+- exercising the BLE proxy protocol end-to-end without Home Assistant
+- reproducing protocol bugs against a controlled BLE adapter
+- smoke-testing matter-server BLE commissioning from another machine
+
+Usage:
+    matter-ble-proxy --server ws://localhost:5580/ble
+
+The same flag set as the JS `noble-ble-proxy` example.
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import contextlib
+import logging
+import signal
+import sys
+
+from matter_ble_proxy.bleak_backend import BleakDeviceResolver, BleakScanSource
+from matter_ble_proxy.client import MatterBleProxy
+
+_LOGGER = logging.getLogger("matter_ble_proxy.cli")
+
+
+def _parse_args(argv: list[str] | None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Bleak-based BLE proxy client for matter-server's /ble endpoint",
+    )
+    parser.add_argument(
+        "--server",
+        default="ws://localhost:5580/ble",
+        help="matter-server BLE proxy URL (default: %(default)s)",
+    )
+    parser.add_argument(
+        "--log-level",
+        default="INFO",
+        choices=["DEBUG", "INFO", "WARNING", "ERROR"],
+        help="Logging level (default: %(default)s)",
+    )
+    return parser.parse_args(argv)
+
+
+async def _run(server_url: str) -> int:
+    scan_source = BleakScanSource()
+    device_resolver = BleakDeviceResolver(scan_source)
+    proxy = MatterBleProxy(server_url, scan_source, device_resolver)
+
+    _LOGGER.info("Connecting to %s...", server_url)
+    try:
+        await proxy.connect()
+    except ConnectionError:
+        _LOGGER.exception("Failed to connect")
+        return 1
+
+    _LOGGER.info("Connected. BLE proxy active. Press Ctrl+C to stop.")
+
+    stop_event = asyncio.Event()
+
+    def _request_stop() -> None:
+        _LOGGER.info("Shutting down...")
+        stop_event.set()
+
+    loop = asyncio.get_running_loop()
+    for sig in (signal.SIGINT, signal.SIGTERM):
+        # add_signal_handler raises NotImplementedError on Windows and inside
+        # some restricted async runtimes; fall back to KeyboardInterrupt there.
+        with contextlib.suppress(NotImplementedError):
+            loop.add_signal_handler(sig, _request_stop)
+
+    try:
+        await asyncio.wait(
+            [
+                asyncio.create_task(proxy.run_until_closed()),
+                asyncio.create_task(stop_event.wait()),
+            ],
+            return_when=asyncio.FIRST_COMPLETED,
+        )
+    finally:
+        await proxy.disconnect()
+
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Console entry point for the `matter-ble-proxy` script."""
+    args = _parse_args(argv)
+    logging.basicConfig(
+        level=args.log_level,
+        format="%(asctime)s.%(msecs)03d %(levelname)s %(name)s: %(message)s",
+        datefmt="%H:%M:%S",
+    )
+    try:
+        return asyncio.run(_run(args.server))
+    except KeyboardInterrupt:
+        return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())