BLE passkey pairing: register a BlueZ agent so create_ble(pin=) actually pairs

[awolden]

Problem

create_ble(pin=...) / BLEConnection(pin=...) stores the PIN and calls client.pair() (ble_cx.py:113-116), but on BlueZ the default agent (no input/output) can't answer the RequestPasskey/RequestPinCode that pair() triggers. Pairing fails with AuthenticationFailed, the connection logs a warning and continues (ble_cx.py:118-122), so pin= is effectively a no-op on Linux/BlueZ today.

This is masked because tests/test_ble_pin_pairing.py mocks pair() and never exercises a real agent.

Fix

Register a short-lived org.bluez.Agent1 (via dbus_fast) that answers RequestPasskey/RequestPinCode with the configured PIN, around the pair() call in ble_cx.py:

• gate on if pin is not None
• lazy-import dbus_fast (already pulled in by bleak on Linux; no cost elsewhere)
• register before pair(), unregister in finally
• degrade gracefully where DBus/BlueZ isn't present (non-Linux), same as today

A working reference implementation already exists in the Home Assistant integration PR meshcore-dev/meshcore-ha#294 (ble_pairing_agent.py). It's pure BLE-transport plumbing with no HA dependencies, so it belongs here next to pair() rather than in each consumer. Once it lands, meshcore-ha (and meshcore-cli, bots, the SDK's own examples/ble_pin_pairing_example.py) just pass pin= and get working passkey pairing.

@drewmccal authored the reference implementation and is best placed to port it; happy to review.

Affects

• HA integration doesnt work, error: Failed to connect meshcore-ha#265, BLE Pin meshcore-ha#83 (BLE passkey radios unusable over direct BLE)
• any consumer using a passkey-protected companion radio over BLE

[fdlamotte]

Hi Awol, This seems simpler than I thought. I would probably revise my judgement on adding this ;) Regards -- Florent

…

On Fri Jun 26, 2026 at 2:42 PM AST, Alex Wolden wrote: awolden created an issue (meshcore-dev/meshcore_py#92) ## Problem `create_ble(pin=...)` / `BLEConnection(pin=...)` stores the PIN and calls `client.pair()` (`ble_cx.py:113-116`), but on BlueZ the default agent (no input/output) can't answer the `RequestPasskey`/`RequestPinCode` that `pair()` triggers. Pairing fails with `AuthenticationFailed`, the connection logs a warning and continues (`ble_cx.py:118-122`), so `pin=` is effectively a no-op on Linux/BlueZ today. This is masked because `tests/test_ble_pin_pairing.py` mocks `pair()` and never exercises a real agent. ## Fix Register a short-lived `org.bluez.Agent1` (via `dbus_fast`) that answers `RequestPasskey`/`RequestPinCode` with the configured PIN, around the `pair()` call in `ble_cx.py`: - gate on `if pin is not None` - lazy-import `dbus_fast` (already pulled in by `bleak` on Linux; no cost elsewhere) - register before `pair()`, unregister in `finally` - degrade gracefully where DBus/BlueZ isn't present (non-Linux), same as today A working reference implementation already exists in the Home Assistant integration PR meshcore-dev/meshcore-ha#294 (`ble_pairing_agent.py`). It's pure BLE-transport plumbing with no HA dependencies, so it belongs here next to `pair()` rather than in each consumer. Once it lands, meshcore-ha (and meshcore-cli, bots, the SDK's own `examples/ble_pin_pairing_example.py`) just pass `pin=` and get working passkey pairing. @drewmccal authored the reference implementation and is best placed to port it; happy to review. ## Affects - meshcore-dev/meshcore-ha#265, meshcore-dev/meshcore-ha#83 (BLE passkey radios unusable over direct BLE) - any consumer using a passkey-protected companion radio over BLE