# SPDX-FileCopyrightText: 2026 Brad Barnett
#
# SPDX-License-Identifier: MIT
"""CPython backend over bleak: Windows, Linux and macOS. Central only.
from bledev.bleak import BleakBLE
ble = BleakBLE()
Needs bleak (``pip install "omnipython[ble]"``). A laptop can scan and connect
but can't advertise, so ``advertise()`` and ``register_services()`` raise
`bledev.UnsupportedError`; ``capabilities()`` says so up front.
Where bleak and the operating system differ from the contract, this backend
translates:
* bleak hands every notification to a callback. Here each subscribed
characteristic gets a queue of ``queue_limit`` entries, and an overflow
raises from the next ``notified()`` rather than dropping data.
* The OS negotiates the MTU on its own. ``exchange_mtu()`` waits briefly for
that negotiation to finish and returns the result; it can't ask for a
particular value. BlueZ always reports 23 through bleak, so on Linux the MTU
comes from the characteristics' write-without-response size instead.
* A write longer than ``mtu - 3`` raises `bledev.BLEError` before it
reaches the OS, as on every backend, even though a write with response
could go out as a long write.
* bleak can't tell a notification from an indication. Data goes to
``indicated()`` when you subscribed with ``indicate=True`` alone, and to
``notified()`` otherwise.
* On Windows, ``connect(pair=True, passkey=...)`` pairs before it connects,
on a link Windows opens for the pairing. A bledev board asks a host to pair
the moment it connects, and once a link is up Windows answers that on its
own, out of sight, so a later ``pair()`` fails without asking for the
passkey. `bledev.connect_and_set_up` (and so ``nus``, ``repl`` and
``filetransfer`` with ``pair=True``) pairs this way.
* On Windows, ``connect(priority="throughput")`` (or asking for a connection
interval of 15 ms or less, as ``nus.connect()`` does on a board) asks WinRT
for its throughput-optimized parameters, which roughly quarters the time a
GATT round trip takes. Other hosts ignore it.
"""
import asyncio
import sys
from bleak import BleakClient, BleakScanner
from bleak.exc import BleakError
try:
from bleak.exc import BleakGATTProtocolError
except ImportError: # bleak < 3
BleakGATTProtocolError = None
from . import (
ClientDescriptor,
BLE,
BLEError,
ClientCharacteristic,
ClientService,
Connection,
DEFAULT_MTU,
Device,
DisconnectedError,
FLAG_INDICATE,
FLAG_NOTIFY,
FLAG_READ,
FLAG_WRITE,
FLAG_WRITE_NO_RESPONSE,
GattError,
MAX_MTU,
PairingError,
ScanResult,
Scanner,
UnsupportedError,
UUID,
passkey_value,
wait_ms,
)
_PROPERTIES = {
"read": FLAG_READ,
"write-without-response": FLAG_WRITE_NO_RESPONSE,
"write": FLAG_WRITE,
"notify": FLAG_NOTIFY,
"indicate": FLAG_INDICATE,
}
# How long exchange_mtu() waits for the OS to finish its own negotiation.
_MTU_SETTLE_MS = 1000
# How long connect(pair=True) gives a pairing, which may wait on a person.
_PAIR_MS = 30000
# How many times connect(pair=True) tries a pairing that Windows fails at once,
# without asking anything, and how long it waits between tries.
_PAIR_TRIES = 3
_PAIR_RETRY_MS = 1000
class _Unasked(PairingError):
"""Windows failed the pairing without asking for anything."""
def _flags(properties):
flags = 0
for name in properties:
flags |= _PROPERTIES.get(name, 0)
return flags
class _Inbox:
"""An ordered queue that raises instead of dropping data."""
def __init__(self, limit, what):
self.items = []
self.event = asyncio.Event()
self.limit = limit
self.what = what
self.overrun = 0
self.closed = False
def put(self, item):
if len(self.items) >= self.limit:
self.overrun += 1
else:
self.items.append(item)
self.event.set()
def close(self):
self.closed = True
self.event.set()
async def get(self, timeout_ms):
while True:
if self.overrun:
raise BLEError(
"{} queue overran: {} item(s) dropped because the reader fell "
"{} behind".format(self.what, self.overrun, self.limit)
)
if self.items:
return self.items.pop(0)
if self.closed:
raise DisconnectedError("{}: disconnected".format(self.what))
self.event.clear()
await wait_ms(self.event.wait(), timeout_ms, self.what)
[docs]
class BleakBLE(BLE):
"""The host's Bluetooth adapter, through bleak. Central only.
``queue_limit`` bounds each notification queue. ``mtu`` is recorded for
``config("mtu")``; the OS picks the real value. Extra keyword arguments in
``scanner_args`` and ``client_args`` go to ``BleakScanner`` and
``BleakClient`` (for example ``{"bluez": {"adapter": "hci1"}}``).
"""
backend = "bleak"
#: ``connect()`` takes ``pair`` and ``passkey``, and pairs before the
#: link is up where the OS needs that (Windows).
pairs_on_connect = True
def __init__(self, *, queue_limit=1024, mtu=MAX_MTU, scanner_args=None, client_args=None):
self.queue_limit = queue_limit
self._mtu = mtu
self._scanner_args = dict(scanner_args or {})
self._client_args = dict(client_args or {})
self._connections = []
[docs]
def capabilities(self):
caps = BLE.capabilities(self)
caps.update(central=True, peripheral=False, mtu=self._mtu, max_mtu=MAX_MTU, indicate=True)
return caps
[docs]
def config(self, *names, **settings):
for key, value in settings.items():
if key == "mtu":
if not DEFAULT_MTU <= value <= MAX_MTU:
raise ValueError("mtu must be {}..{}".format(DEFAULT_MTU, MAX_MTU))
self._mtu = value
else:
raise UnsupportedError("bleak has no setting {!r}".format(key))
if names:
if len(names) != 1:
raise ValueError("read one setting at a time")
if names[0] == "mtu":
return self._mtu
raise UnsupportedError("bleak has no setting {!r}".format(names[0]))
return None
[docs]
def close(self):
"""Drop every connection. The OS disconnects in the background; ``aclose()`` waits for it."""
for connection in list(self._connections):
connection._drop()
try:
asyncio.get_running_loop().create_task(connection._client.disconnect())
except RuntimeError:
pass
self._connections = []
[docs]
async def aclose(self):
"""``close()``, waiting until the OS has let go of every connection."""
connections = list(self._connections)
self.close()
for connection in connections:
try:
await connection._client.disconnect()
except Exception:
pass
# -- central
[docs]
def scan(self, duration_ms, *, active=False, interval_us=None, window_us=None):
return _BleakScanner(self, duration_ms, active, interval_us, window_us)
async def _connect(self, device, timeout_ms, pair=False, passkey=None, **options):
target = device.native if device.native is not None else device.address
connection = None
paired = None
if pair and sys.platform == "win32":
paired = await wait_ms(_pair_address(device.address, passkey), _PAIR_MS, "pair")
def on_disconnect(client):
if connection is not None:
connection._drop()
args = dict(self._client_args)
if timeout_ms is not None:
args.setdefault("timeout", timeout_ms / 1000)
client = BleakClient(target, disconnected_callback=on_disconnect, **args)
try:
await wait_ms(client.connect(), timeout_ms, "connect to {}".format(device.address))
except BleakError as e:
raise BLEError("connect to {}: {}".format(device.address, e))
connection = _BleakConnection(self, device, client)
self._connections.append(connection)
if _wants_throughput(options):
connection.request_throughput()
if paired is not None:
connection._adopt(*paired)
elif pair:
try:
await connection.pair(passkey=passkey)
except BaseException:
await connection.disconnect()
raise
return connection
def _wants_throughput(options):
if options.get("priority") == "throughput":
return True
interval = options.get("max_conn_interval_us") or options.get("min_conn_interval_us")
return interval is not None and interval <= 15000
class _BleakScanner(Scanner):
async def _start(self):
mode = "active" if self.active or sys.platform == "darwin" else "passive"
self._scanner = BleakScanner(self._detected, scanning_mode=mode, **self._ble._scanner_args)
try:
await self._scanner.start()
except BleakError as e:
raise BLEError("scan: {}".format(e))
self._timer = asyncio.get_running_loop().create_task(self._run_out())
async def _run_out(self):
await asyncio.sleep(self.duration_ms / 1000)
self._timer = None
await self.cancel()
async def _stop(self):
timer = getattr(self, "_timer", None)
if timer is not None and timer is not asyncio.current_task():
timer.cancel()
self._timer = None
scanner = getattr(self, "_scanner", None)
if scanner is not None:
self._scanner = None
try:
await scanner.stop()
except BleakError:
pass
def _detected(self, native, adv):
if self._done:
return
name = adv.local_name or None
self._push(
ScanResult(
Device(self._ble, native.address, name=name or native.name, native=native),
rssi=adv.rssi,
name=name,
services=[UUID(u) for u in adv.service_uuids],
manufacturer=[(k, bytes(v)) for k, v in adv.manufacturer_data.items()],
service_data=[(UUID(k), bytes(v)) for k, v in adv.service_data.items()],
)
)
def _translate(e, connection, what):
"""A bleak or OS exception, as the bledev error it means."""
if isinstance(e, BLEError):
return e
if BleakGATTProtocolError is not None and isinstance(e, BleakGATTProtocolError):
return GattError(int(e.args[0]), "{}: {}".format(what, e))
if not connection.is_connected():
return DisconnectedError("{}: disconnected".format(what))
return BLEError("{}: {}".format(what, e))
class _BleakConnection(Connection):
def __init__(self, ble, device, client):
Connection.__init__(self, ble, device, "central")
self._client = client
self._dropped = asyncio.Event()
self._inboxes = []
self._wwr = 0 # the largest write-without-response size seen in discovery
self._paired = False
self._authenticated = False
#: True when pair() found the OS already paired and paired nothing new.
self.reused_bond = False
def _drop(self):
if self._dropped.is_set():
return
self._dropped.set()
for inbox in self._inboxes:
inbox.close()
if self in self._ble._connections:
self._ble._connections.remove(self)
@property
def mtu(self):
mtu = DEFAULT_MTU
try:
mtu = max(mtu, int(self._client.mtu_size))
except Exception:
pass
if self._wwr:
mtu = max(mtu, self._wwr + 3)
return mtu
def is_connected(self):
if self._dropped.is_set():
return False
try:
return bool(self._client.is_connected)
except Exception:
return False
async def disconnect(self, timeout_ms=2000):
try:
await wait_ms(self._client.disconnect(), timeout_ms, "disconnect")
except BleakError:
pass
finally:
self._drop()
async def disconnected(self, timeout_ms=None):
if self.is_connected():
await wait_ms(self._dropped.wait(), timeout_ms, "disconnected")
@property
def encrypted(self):
return self._paired
@property
def authenticated(self):
return self._authenticated
async def pair(self, bond=True, timeout_ms=30000, passkey=None):
"""Pair through the OS, which keeps the bond.
On Windows this uses WinRT's custom pairing, so no system dialog
appears: "just works" when the board has no display, and ``passkey``
(a value, or a callable asked when Windows wants it) when the board
shows one. A board already paired with Windows is only checked, not
paired again; Windows encrypts the link with the stored keys when a
protected characteristic is first used. Elsewhere it's bleak's
``pair()``, where the OS may ask for the passkey itself.
On Windows, pair a bledev board when you connect, with
``device.connect(pair=True, passkey=...)``: the board asks to pair as
soon as the link is up, Windows answers that itself, and pairing here
then fails without asking for the passkey.
Windows keeps the pairing until `unpair` (or Settings, Remove
device). Never pair a board serving HID with the computer you test
from: Windows then uses it as a keyboard.
"""
self._live("pair")
requester = getattr(getattr(self._client, "_backend", None), "_requester", None)
try:
if requester is not None:
try:
self._adopt(*await wait_ms(_pair_device(requester, passkey, self.device.address), timeout_ms, "pair"))
except _Unasked as e:
raise PairingError("{}: Windows can't pair over a link that's already up; connect with pair=True".format(e))
else:
await wait_ms(self._client.pair(), timeout_ms, "pair")
self._authenticated = passkey is not None
self._paired = True
except (BleakError, OSError) as e:
raise _translate(e, self, "pair")
def _adopt(self, reused, authenticated, result):
# What a Windows pairing found, from pair() or from connect(pair=True).
self._paired = True
self.reused_bond = reused
self._authenticated = authenticated
if result is not None:
#: What Windows reported: the status, the protection level it
#: used, and the ceremonies it asked for.
self.pairing_result = result
async def unpair(self):
"""Remove the OS's pairing with this board. Windows also drops the link."""
try:
await self._client.unpair()
except (BleakError, OSError) as e:
raise _translate(e, self, "unpair")
self._paired = False
self._authenticated = False
async def exchange_mtu(self, mtu=None, timeout_ms=1000):
"""The OS negotiates on its own; wait briefly for it and return the result."""
self._live("exchange_mtu")
if mtu:
self._ble.config(mtu=mtu)
waited = 0
limit = min(timeout_ms if timeout_ms is not None else _MTU_SETTLE_MS, _MTU_SETTLE_MS)
while self.mtu == DEFAULT_MTU and waited < limit and self.is_connected():
await asyncio.sleep(0.02)
waited += 20
return self.mtu
def request_throughput(self):
"""Ask the OS for a short connection interval. Windows 11 only; returns whether it asked."""
requester = getattr(getattr(self._client, "_backend", None), "_requester", None)
if requester is None:
return False
try:
from winrt.windows.devices.bluetooth import BluetoothLEPreferredConnectionParameters
requester.request_preferred_connection_parameters(
BluetoothLEPreferredConnectionParameters.throughput_optimized
)
return True
except Exception:
return False
def _live(self, what):
if not self.is_connected():
raise DisconnectedError("{}: not connected".format(what))
async def _discover_services(self, uuid, timeout_ms):
self._live("service discovery")
found = []
for service in sorted(self._client.services, key=lambda s: s.handle):
wrapped = _BleakClientService(self, service)
if uuid is None or wrapped.uuid == uuid:
found.append(wrapped)
return found
class _BleakClientService(ClientService):
def __init__(self, connection, native):
ClientService.__init__(self, connection, native.uuid)
self._native = native
async def _discover_characteristics(self, uuid, timeout_ms):
self.connection._live("characteristic discovery")
found = []
for native in sorted(self._native.characteristics, key=lambda c: c.handle):
try:
wwr = native.max_write_without_response_size
except Exception:
wwr = 0
if wwr > self.connection._wwr:
self.connection._wwr = wwr
wrapped = _BleakClientCharacteristic(self, native)
if uuid is None or wrapped.uuid == uuid:
found.append(wrapped)
return found
class _BleakClientCharacteristic(ClientCharacteristic):
def __init__(self, service, native):
ClientCharacteristic.__init__(self, service, native.uuid, _flags(native.properties))
self._native = native
self._client = service.connection._client
limit = service.connection._ble.queue_limit
self._notify_inbox = _Inbox(limit, "notify {}".format(self.uuid))
self._indicate_inbox = _Inbox(limit, "indicate {}".format(self.uuid))
service.connection._inboxes.extend((self._notify_inbox, self._indicate_inbox))
self._route = None
self._subscribed = False
def _live(self, what):
self.connection._live(what)
async def read(self, timeout_ms=1000):
self._check(FLAG_READ, "read")
self._live("read")
try:
return bytes(await wait_ms(self._client.read_gatt_char(self._native), timeout_ms, "read"))
except (BleakError, OSError) as e:
raise _translate(e, self.connection, "read")
async def _discover_descriptors(self, uuid, timeout_ms):
self._live("descriptor discovery")
found = []
for native in sorted(self._native.descriptors, key=lambda d: d.handle):
d = _BleakClientDescriptor(self, native)
if uuid is None or d.uuid == uuid:
found.append(d)
return found
async def write(self, data, response=None, timeout_ms=1000):
data = bytes(data)
response = self._want_response(response)
self._live("write")
mtu = self.connection.mtu
if len(data) > mtu - 3:
raise BLEError(
"write of {} bytes exceeds the ATT payload of {} (mtu {} - 3)".format(len(data), mtu - 3, mtu)
)
try:
await wait_ms(self._client.write_gatt_char(self._native, data, response=response), timeout_ms, "write")
except (BleakError, OSError) as e:
raise _translate(e, self.connection, "write")
def _received(self, sender, data):
inbox = self._indicate_inbox if self._route == "indicate" else self._notify_inbox
inbox.put(bytes(data))
async def subscribe(self, notify=True, indicate=False):
if notify:
self._check(FLAG_NOTIFY, "notify")
if indicate:
self._check(FLAG_INDICATE, "indicate")
self._live("subscribe")
try:
if self._subscribed:
await self._client.stop_notify(self._native)
self._subscribed = False
if not notify and not indicate:
return
self._route = "indicate" if indicate and not notify else "notify"
kwargs = {}
if self._route == "indicate" and sys.platform == "win32":
kwargs["force_indicate"] = True
await self._client.start_notify(self._native, self._received, **kwargs)
self._subscribed = True
except (BleakError, OSError) as e:
raise _translate(e, self.connection, "subscribe")
async def notified(self, timeout_ms=None):
self._check(FLAG_NOTIFY, "notify")
return await self._notify_inbox.get(timeout_ms)
async def indicated(self, timeout_ms=None):
self._check(FLAG_INDICATE, "indicate")
return await self._indicate_inbox.get(timeout_ms)
class _BleakClientDescriptor(ClientDescriptor):
def __init__(self, characteristic, native):
ClientDescriptor.__init__(self, characteristic, native.uuid)
self._native = native
async def read(self, timeout_ms=1000):
client = self.connection._client
self.connection._live("descriptor read")
try:
return bytes(await wait_ms(client.read_gatt_descriptor(self._native.handle), timeout_ms, "descriptor read"))
except (BleakError, OSError) as e:
raise _translate(e, self.connection, "descriptor read")
async def _pair_address(address, passkey):
"""Pair Windows with ``address`` while no link to it is up.
With no link, the pairing opens one of its own and asks for the passkey
itself. Once bleak holds a link, a board that asked for security as it
connected has already started a pairing Windows answers out of sight; the
custom pairing then fails in milliseconds, and the link stays up until a
bledev board hangs up on a host that hasn't paired, 30 s later.
"""
from winrt.windows.devices.bluetooth import BluetoothLEDevice
# Even with no link up, Windows now and then fails a pairing at once
# without asking anything (about one in four, on an Intel adapter), and
# the same pairing a second later goes through.
for attempt in range(_PAIR_TRIES):
device = await BluetoothLEDevice.from_bluetooth_address_async(int(address.replace(":", ""), 16))
if device is None:
raise PairingError("pair: Windows can't find {}".format(address))
try:
return await _pair_winrt(device.device_information, passkey, address)
except _Unasked:
if attempt == _PAIR_TRIES - 1:
raise
finally:
device.close()
await asyncio.sleep(_PAIR_RETRY_MS / 1000)
async def _pair_device(requester, passkey, address):
from winrt.windows.devices.enumeration import DeviceInformation
info = await DeviceInformation.create_from_id_async(requester.device_information.id)
return await _pair_winrt(info, passkey, address)
async def _pair_winrt(info, passkey, address):
"""Pair through WinRT's custom pairing. Returns ``(reused, authenticated,
result)``; ``reused`` is True when Windows was already paired."""
from winrt.windows.devices.enumeration import (
DevicePairingKinds,
DevicePairingProtectionLevel,
DevicePairingResultStatus,
)
pairing = info.pairing
if pairing.is_paired:
# Windows encrypts with the stored keys when a protected
# characteristic is first used; if the board lost its half, that
# fails and Windows drops the link (see connect_and_set_up).
return True, pairing.protection_level == DevicePairingProtectionLevel.ENCRYPTION_AND_AUTHENTICATION, None
if not pairing.can_pair:
raise PairingError("pair: Windows says {} can't pair".format(address))
loop = asyncio.get_running_loop()
asked = []
async def provide(args, deferral):
try:
value = await passkey_value(passkey)
if value is not None:
args.accept_with_pin("{:06d}".format(value))
except Exception as e: # a cancelled prompt: leave it unaccepted
asked.append(e)
finally:
deferral.complete()
def handler(sender, args):
# On a WinRT thread. Just works needs only a yes; a passkey waits
# on the provider, which may be slow (a person), behind a deferral.
kind = args.pairing_kind
asked.append(kind)
if kind == DevicePairingKinds.CONFIRM_ONLY:
args.accept()
elif kind == DevicePairingKinds.PROVIDE_PIN and passkey is not None:
deferral = args.get_deferral()
loop.call_soon_threadsafe(lambda: loop.create_task(provide(args, deferral)))
kinds = DevicePairingKinds.CONFIRM_ONLY
level = DevicePairingProtectionLevel.ENCRYPTION
if passkey is not None:
kinds |= DevicePairingKinds.PROVIDE_PIN
level = DevicePairingProtectionLevel.ENCRYPTION_AND_AUTHENTICATION
custom = pairing.custom
token = custom.add_pairing_requested(handler)
try:
result = await custom.pair_with_protection_level_async(kinds, level)
if result.status == DevicePairingResultStatus.PROTECTION_LEVEL_COULD_NOT_BE_MET and passkey is not None:
# A board without a display pairs just works; the board, not
# this side, decides whether that's enough.
result = await custom.pair_with_protection_level_async(kinds, DevicePairingProtectionLevel.ENCRYPTION)
finally:
custom.remove_pairing_requested(token)
status = result.status
if status not in (DevicePairingResultStatus.PAIRED, DevicePairingResultStatus.ALREADY_PAIRED):
raise (PairingError if asked else _Unasked)("pair: {} ({})".format(status.name, ", ".join(str(a) for a in asked) or "no ceremony"))
# A passkey that was asked for and typed in is what authenticates;
# Windows' reported level is the second opinion.
authenticated = (
DevicePairingKinds.PROVIDE_PIN in asked
or result.protection_level_used == DevicePairingProtectionLevel.ENCRYPTION_AND_AUTHENTICATION
)
return False, authenticated, (status.name, result.protection_level_used, [int(a) for a in asked if isinstance(a, int)])
[docs]
async def unpair(address):
"""Remove the OS's pairing with ``address`` without connecting: the recovery
step when a board has lost its bond (its keys were erased) and Windows
still holds the other half."""
try:
await BleakClient(address).unpair()
except (BleakError, OSError) as e:
raise BLEError("unpair {}: {}".format(address, e))
async def _main(argv):
"""``python -m bledev.bleak pair NAME`` / ``unpair NAME``: pair this computer
with a board once, typing in the passkey its display shows. mcuctl, bledev
and anything else on this computer then use the bond."""
if len(argv) != 2 or argv[0] not in ("pair", "unpair"):
print("usage: python -m bledev.bleak pair|unpair NAME")
return 2
what, name = argv
ble = BleakBLE()
try:
device = await ble.find(name=name, timeout_ms=15000)
if what == "unpair":
await unpair(device.address)
print("unpaired", name, device.address)
return 0
async def ask():
loop = asyncio.get_running_loop()
text = await loop.run_in_executor(None, input, "Passkey shown on {}: ".format(name))
return int(text.replace(" ", "")) if text.strip() else None
try:
connection = await device.connect(timeout_ms=15000, pair=True, passkey=ask)
except PairingError as e:
print("not paired:", e)
return 1
await connection.disconnect()
print("paired", name, device.address, "(passkey)" if connection.authenticated else "(just works)")
return 0
finally:
await ble.aclose()
if __name__ == "__main__":
import sys
sys.exit(asyncio.run(_main(sys.argv[1:])))