Source code for bledev

# SPDX-FileCopyrightText: 2026 Brad Barnett
#
# SPDX-License-Identifier: MIT

"""Portable Bluetooth Low Energy: the contract every bledev backend implements.

You write a BLE program once against this module, and it runs on a board
(`bledev.mpble`), on a laptop (``bledev.bleak``), in a browser
(``bledev.webble``), or against the in-process loopback in tests
(`bledev.fake`). The guide is ``docs/guides/bluetooth-le.md``.

The shape is aioble's, and it is async throughout. The pieces:

* `UUID`, the errors, and the ``FLAG_*`` property bits.
* `BLE`, the adapter. A backend subclasses it. ``capabilities()`` says
  which roles it can take, because roles aren't symmetric: bleak and Web
  Bluetooth are central only, and a board can be either.
* The peripheral side: `Service` and `Characteristic` describe a
  GATT server, ``ble.register_services()`` installs it, and
  ``await ble.advertise()`` returns a `Connection` when a central
  connects.
* The central side: ``ble.scan()`` yields `ScanResult`, ``ble.find()``
  returns a `Device`, and ``await device.connect()`` returns a
  `Connection`, whose services and characteristics you discover as
  `ClientService` and `ClientCharacteristic`.

Nothing here imports a backend, and nothing here imports `bledev.auto`.
"""

import asyncio

import struct

__version__ = "0.1.0"

# GATT characteristic property bits. The values are the Bluetooth spec's, and
# the same ones MicroPython's bluetooth module and aioble use.
FLAG_READ = 0x0002
FLAG_WRITE_NO_RESPONSE = 0x0004
FLAG_WRITE = 0x0008
FLAG_NOTIFY = 0x0010
FLAG_INDICATE = 0x0020

#: Every connection starts at this ATT MTU. One ATT packet carries ``mtu - 3``
#: bytes of value.
DEFAULT_MTU = 23
MAX_MTU = 517

ADDR_PUBLIC = 0
ADDR_RANDOM = 1

#: Which address this radio uses on the air, for ``ble.config(addr_mode=...)``.
#: ``ADDR_MODE_RPA`` is a resolvable private address: it changes every few
#: minutes, and a phone that bonded with the board can still recognise it.
ADDR_MODE_PUBLIC = 0
ADDR_MODE_RANDOM = 1
ADDR_MODE_RPA = 2
ADDR_MODE_NRPA = 3


# ---------------------------------------------------------------- errors


[docs] class BLEError(Exception): """Base of every error bledev raises."""
[docs] class UnsupportedError(BLEError): """This backend cannot do that: a role it can't take, or a missing feature."""
[docs] class DisconnectedError(BLEError): """The connection dropped, or was already closed, before the operation finished."""
[docs] class BLETimeoutError(BLEError): """An operation given ``timeout_ms`` did not finish in time."""
[docs] class BusyError(BLEError): """The controller's transmit buffers are full. Wait a moment and send again. Only `Characteristic.notify` raises it, because it is synchronous; every async send waits for room instead. """
#: ATT error codes a :class:`GattError` can carry that apps act on. INSUFFICIENT_AUTHENTICATION = 0x05 INSUFFICIENT_ENCRYPTION = 0x0F
[docs] class PairingError(BLEError): """Pairing failed: a wrong passkey, a refusal, or a peer that lost its keys."""
#: What to tell someone whose host kept a bond the board no longer has. STALE_BOND = ( "the board refused this host's keys: it has probably lost its bond (a chip " "erase, or bledev.security.forget()). Unpair it on this host " "(bledev.bleak.unpair(address), or Settings > Bluetooth > Remove device) " "and pair again" ) #: The GATT statuses that mean "pair first". NEEDS_PAIRING = (INSUFFICIENT_AUTHENTICATION, INSUFFICIENT_ENCRYPTION)
[docs] class GattError(BLEError): """The peer answered a GATT request with an error ``status``.""" def __init__(self, status, message=None): super().__init__(message or "GATT error 0x{:02x}".format(status)) self.status = status
[docs] async def sleep_ms(ms): """``asyncio.sleep_ms`` on every interpreter.""" await asyncio.sleep(ms / 1000)
[docs] async def wait_ms(awaitable, timeout_ms, what="operation"): """Await ``awaitable``, raising `BLETimeoutError` after ``timeout_ms``. ``timeout_ms=None`` waits forever. Backends use this so every timeout in bledev is the same exception. """ if timeout_ms is None: return await awaitable try: return await asyncio.wait_for(awaitable, timeout_ms / 1000) except asyncio.TimeoutError: raise BLETimeoutError("{} timed out after {} ms".format(what, timeout_ms))
# ---------------------------------------------------------------- UUID _BASE_TAIL = bytes((0x00, 0x00, 0x10, 0x00, 0x80, 0x00, 0x00, 0x80, 0x5F, 0x9B, 0x34, 0xFB)) _HEX = "0123456789abcdef" def _hex(data): return "".join(_HEX[b >> 4] + _HEX[b & 15] for b in data) def _unhex(text): if len(text) % 2: raise ValueError("odd-length hex") return bytes(int(text[i : i + 2], 16) for i in range(0, len(text), 2))
[docs] class UUID: """A Bluetooth UUID, the same value on every host. Accepts a 16- or 32-bit ``int`` (``UUID(0x180F)``), a string in any of the usual spellings (``"180f"``, ``"0x180F"``, ``"6e400001-b5a3-f393-e0a9-e50e24dcca9e"``), another UUID, MicroPython's ``bluetooth.UUID``, or 2, 4 or 16 bytes in Bluetooth's little-endian wire order. A short UUID equals its 128-bit expansion. ``str()`` is always the 128-bit lowercase form, which is what bleak and Web Bluetooth use. ``short`` is the 16/32-bit value, or ``None``. ``to_bytes()`` is the wire form, shortest first. """ def __init__(self, value): if isinstance(value, UUID): self._be = value._be return if isinstance(value, int): self._be = self._from_short(value) return if isinstance(value, str): text = value.strip().lower() if text.startswith("0x"): self._be = self._from_short(int(text[2:], 16)) return text = text.replace("-", "") if len(text) in (4, 8): self._be = self._from_short(int(text, 16)) return if len(text) != 32: raise ValueError("not a UUID: {!r}".format(value)) self._be = _unhex(text) return try: raw = bytes(value) except TypeError: raise ValueError("not a UUID: {!r}".format(value)) if len(raw) in (2, 4): self._be = self._from_short(int.from_bytes(raw, "little")) elif len(raw) == 16: self._be = bytes(reversed(raw)) else: raise ValueError("a UUID is 2, 4 or 16 bytes, not {}".format(len(raw))) @staticmethod def _from_short(value): if not 0 <= value <= 0xFFFFFFFF: raise ValueError("short UUID out of range: {}".format(value)) return value.to_bytes(4, "big") + _BASE_TAIL @property def short(self): """The 16- or 32-bit value when this is a Bluetooth-base UUID, else ``None``.""" if self._be[4:] == _BASE_TAIL: return int.from_bytes(self._be[:4], "big") return None
[docs] def to_bytes(self): """Little-endian wire bytes: 2 for a 16-bit UUID, 4 for 32-bit, else 16.""" short = self.short if short is not None: return short.to_bytes(2 if short <= 0xFFFF else 4, "little") return bytes(reversed(self._be))
def __bytes__(self): return self.to_bytes() def __str__(self): h = _hex(self._be) return "-".join((h[:8], h[8:12], h[12:16], h[16:20], h[20:])) def __repr__(self): short = self.short if short is not None: return "UUID(0x{:04x})".format(short) return "UUID('{}')".format(self) def __eq__(self, other): if not isinstance(other, UUID): try: other = UUID(other) except (ValueError, TypeError): return False return self._be == other._be def __ne__(self, other): return not self.__eq__(other) def __hash__(self): return hash(self._be)
# ---------------------------------------------------------------- advertising payloads ADV_TYPE_FLAGS = 0x01 ADV_TYPE_UUID16_INCOMPLETE = 0x02 ADV_TYPE_UUID16_COMPLETE = 0x03 ADV_TYPE_UUID32_INCOMPLETE = 0x04 ADV_TYPE_UUID32_COMPLETE = 0x05 ADV_TYPE_UUID128_INCOMPLETE = 0x06 ADV_TYPE_UUID128_COMPLETE = 0x07 ADV_TYPE_SHORT_NAME = 0x08 ADV_TYPE_NAME = 0x09 ADV_TYPE_SERVICE_DATA16 = 0x16 ADV_TYPE_APPEARANCE = 0x19 ADV_TYPE_SERVICE_DATA32 = 0x20 ADV_TYPE_SERVICE_DATA128 = 0x21 ADV_TYPE_MANUFACTURER = 0xFF ADV_PAYLOAD_MAX = 31
[docs] def pack_advertisement(name=None, services=None, appearance=0, manufacturer=None, service_data=None): """Build ``(adv_data, resp_data)``, in aioble's field order. Fields go into the 31-byte advertisement in this order (flags, services, service data, name, appearance, manufacturer) and overflow into the scan response, which only an *active* scan sees. That is why a long name can be invisible to a passive scan. The fake backend and mpble both advertise what this returns, so tests see what a board sends. ``manufacturer`` is ``(company_id, data)``; ``service_data`` is a list of ``(uuid, data)``. """ adv = bytearray() resp = bytearray() def append(adv_type, value): field = bytes((len(value) + 1, adv_type)) + bytes(value) if len(adv) + len(field) <= ADV_PAYLOAD_MAX: adv.extend(field) elif len(resp) + len(field) <= ADV_PAYLOAD_MAX: resp.extend(field) else: raise ValueError("advertising payload too long") append(ADV_TYPE_FLAGS, b"\x06") if services: uuids = [UUID(s).to_bytes() for s in services] for size, code in ((2, ADV_TYPE_UUID16_COMPLETE), (4, ADV_TYPE_UUID32_COMPLETE), (16, ADV_TYPE_UUID128_COMPLETE)): group = b"".join(u for u in uuids if len(u) == size) if group: append(code, group) if service_data: codes = {2: ADV_TYPE_SERVICE_DATA16, 4: ADV_TYPE_SERVICE_DATA32, 16: ADV_TYPE_SERVICE_DATA128} for uuid, data in service_data: raw = UUID(uuid).to_bytes() append(codes[len(raw)], raw + bytes(data)) if name: append(ADV_TYPE_NAME, name.encode() if isinstance(name, str) else name) if appearance: append(ADV_TYPE_APPEARANCE, struct.pack("<H", appearance)) if manufacturer: append(ADV_TYPE_MANUFACTURER, struct.pack("<H", manufacturer[0]) + bytes(manufacturer[1])) return bytes(adv), bytes(resp)
[docs] def decode_fields(*payloads): """Yield ``(adv_type, value)`` for every field in the given payloads.""" for payload in payloads: if not payload: continue i = 0 while i + 1 < len(payload): length = payload[i] if length == 0: break yield payload[i + 1], bytes(payload[i + 2 : i + length + 1]) i += 1 + length
[docs] def decode_advertisement(*payloads): """``(name, services, appearance, manufacturer)`` from raw payloads. ``manufacturer`` is a list of ``(company_id, data)``. """ name = None services = [] appearance = 0 manufacturer = [] sizes = { ADV_TYPE_UUID16_INCOMPLETE: 2, ADV_TYPE_UUID16_COMPLETE: 2, ADV_TYPE_UUID32_INCOMPLETE: 4, ADV_TYPE_UUID32_COMPLETE: 4, ADV_TYPE_UUID128_INCOMPLETE: 16, ADV_TYPE_UUID128_COMPLETE: 16, } for adv_type, value in decode_fields(*payloads): if adv_type in (ADV_TYPE_NAME, ADV_TYPE_SHORT_NAME): if name is None or adv_type == ADV_TYPE_NAME: name = value.decode() elif adv_type in sizes: size = sizes[adv_type] for i in range(0, len(value) - size + 1, size): services.append(UUID(value[i : i + size])) elif adv_type == ADV_TYPE_APPEARANCE and len(value) >= 2: appearance = struct.unpack("<H", value[:2])[0] elif adv_type == ADV_TYPE_MANUFACTURER and len(value) >= 2: manufacturer.append((struct.unpack("<H", value[:2])[0], value[2:])) return name, services, appearance, manufacturer
[docs] def decode_service_data(*payloads): """``[(UUID, data), ...]`` from the service-data fields of raw payloads.""" sizes = {ADV_TYPE_SERVICE_DATA16: 2, ADV_TYPE_SERVICE_DATA32: 4, ADV_TYPE_SERVICE_DATA128: 16} found = [] for adv_type, value in decode_fields(*payloads): size = sizes.get(adv_type) if size and len(value) >= size: found.append((UUID(value[:size]), value[size:])) return found
# ---------------------------------------------------------------- the adapter
[docs] class BLE: """One radio. Backends subclass this; apps receive one from a board config. Methods a backend can't support raise `UnsupportedError`, so a central-only host fails loudly at ``advertise()`` rather than doing nothing. Check ``capabilities()`` first when your app can take either role. """ backend = "base" # -- what this host can do
[docs] def capabilities(self): """A dict describing this backend. Keys every backend provides: ``backend`` (its module name), ``central`` and ``peripheral`` (which roles it can take), ``mtu`` (the ATT MTU it asks for), ``max_mtu``, ``indicate``, ``pairing`` and ``l2cap`` (bools), ``long_read``: whether a read returns values longer than one packet (``mtu - 1``), and ``write_notifies``: whether setting a served characteristic's value already notifies its subscribers (CircuitPython's ``_bleio``). """ return { "backend": self.backend, "central": False, "peripheral": False, "mtu": DEFAULT_MTU, "max_mtu": DEFAULT_MTU, "indicate": False, "pairing": False, "write_notifies": False, "l2cap": False, "long_read": True, }
[docs] def config(self, *names, **settings): """Read or set adapter settings, like ``bluetooth.BLE.config``. ``config(mtu=247)`` sets the ATT MTU this side asks for; ``config("mtu")`` reads it. ``gap_name`` is the device name in the GAP service. ``addr_mode`` is the address the radio uses on the air: `ADDR_MODE_PUBLIC`, `ADDR_MODE_RANDOM`, `ADDR_MODE_RPA` (a resolvable private address that rotates, so a phone can't follow the board except through a bond) or `ADDR_MODE_NRPA`. Set it before you advertise or scan. A setting the backend doesn't have raises `UnsupportedError`. """ raise UnsupportedError("{} has no settings".format(self.backend))
[docs] def close(self): """Stop advertising and scanning, drop connections, and turn the radio off."""
# -- peripheral role
[docs] def register_services(self, *services): """Install the GATT server. Replaces whatever was registered before. Call it before ``advertise()``. Each `Characteristic` is bound to this adapter from here on. """ raise UnsupportedError("{} cannot be a peripheral".format(self.backend))
[docs] async def advertise( self, interval_us=100000, *, name=None, services=None, appearance=0, manufacturer=None, connectable=True, timeout_ms=None, service_data=None, ): """Advertise until a central connects, and return that `Connection`. ``service_data`` is a list of ``(uuid, data)`` (Improv uses it). Raises `BLETimeoutError` if nobody connects within ``timeout_ms``. Cancelling the task stops advertising. Advertising stops when a central connects; call again to accept another. """ raise UnsupportedError("{} cannot advertise".format(self.backend))
# -- central role
[docs] def scan(self, duration_ms, *, active=False, interval_us=None, window_us=None): """Scan for ``duration_ms``. Use as:: async with ble.scan(5000, active=True) as scanner: async for result in scanner: ... A device can be yielded more than once as its data arrives. An *active* scan also asks for scan responses, which is where a long name ends up. """ raise UnsupportedError("{} cannot scan".format(self.backend))
[docs] async def find(self, name=None, service=None, *, timeout_ms=10000, active=True): """Scan until a device matching ``name`` and/or ``service`` appears. Returns its `Device`, or raises `BLETimeoutError`. """ if service is not None: service = UUID(service) async with self.scan(timeout_ms, active=active) as scanner: async for result in scanner: if name is not None and result.name() != name: continue if service is not None and service not in result.services(): continue return result.device raise BLETimeoutError( "no device matching name={!r} service={} in {} ms".format(name, service, timeout_ms) )
async def _connect(self, device, timeout_ms, **options): raise UnsupportedError("{} cannot connect".format(self.backend))
# ---------------------------------------------------------------- peripheral side
[docs] class Service: """A GATT service you serve. Add characteristics by constructing them with it.""" def __init__(self, uuid): self.uuid = UUID(uuid) self.characteristics = [] def __repr__(self): return "Service({!r})".format(self.uuid)
[docs] class Characteristic: """A characteristic in a `Service` you serve. The flags are aioble's. ``max_len`` is the largest value a central may write; MicroPython's default buffer is 20 bytes, so raise it for anything that takes whole MTU-sized writes. With ``capture=True``, ``written()`` returns every write as ``(connection, data)``, in order, instead of just the last writer. ``encrypted=True`` refuses a central that hasn't paired (``GattError`` with status ``INSUFFICIENT_ENCRYPTION``) until it does; ``authenticated=True`` also refuses one that paired without a passkey (``INSUFFICIENT_AUTHENTICATION``). """ def __init__( self, service, uuid, read=False, write=False, write_no_response=False, notify=False, indicate=False, initial=None, capture=False, max_len=20, encrypted=False, authenticated=False, ): service.characteristics.append(self) self.service = service self.uuid = UUID(uuid) flags = 0 if read: flags |= FLAG_READ if write: flags |= FLAG_WRITE if write_no_response: flags |= FLAG_WRITE_NO_RESPONSE if notify: flags |= FLAG_NOTIFY if indicate: flags |= FLAG_INDICATE self.flags = flags self.capture = bool(capture) and bool(flags & (FLAG_WRITE | FLAG_WRITE_NO_RESPONSE)) self.max_len = max(max_len, len(initial) if initial else 0) self._initial = bytes(initial) if initial is not None else None #: True when a central must pair (an encrypted link) before it may #: read, write or subscribe. HID keyboards serve their reports this way. self.encrypted = bool(encrypted) or bool(authenticated) #: True when only a link paired with a passkey (or numeric #: comparison) may use it: "just works" isn't enough. self.authenticated = bool(authenticated) #: :class:`Descriptor` objects, in the order they were made. self.descriptors = [] # Set by the backend's register_services(); it does the real work. self._impl = None def __repr__(self): return "Characteristic({!r}, flags=0x{:02x})".format(self.uuid, self.flags) def _bound(self): if self._impl is None: raise BLEError("{!r} is not registered; call ble.register_services() first".format(self)) return self._impl
[docs] def read(self): """The local value, as bytes.""" if self._impl is None: return self._initial or b"" return self._impl.read()
[docs] def write(self, data, send_update=False): """Set the local value. ``send_update`` also notifies or indicates subscribers.""" if self._impl is None: self._initial = bytes(data) return self._impl.write(bytes(data), send_update)
[docs] def notify(self, connection, data=None): """Send ``data`` (or the current value) to ``connection`` as a notification. Synchronous, like aioble. ``data`` must fit in ``connection.mtu - 3`` bytes. Raises `BusyError` when the transmit buffers are full; await a moment and send again (``bledev.nus`` shows the loop). """ if not self.flags & FLAG_NOTIFY: raise UnsupportedError("{!r} was not created with notify=True".format(self)) return self._bound().notify(connection, None if data is None else bytes(data))
[docs] async def indicate(self, connection, data=None, timeout_ms=1000): """Send an indication and wait for the central to acknowledge it.""" if not self.flags & FLAG_INDICATE: raise UnsupportedError("{!r} was not created with indicate=True".format(self)) return await self._bound().indicate(connection, None if data is None else bytes(data), timeout_ms)
[docs] async def written(self, timeout_ms=None): """Wait for a central to write this characteristic. Returns the writer's `Connection`, or ``(connection, data)`` with ``capture=True``. It serves every connection, so it does not end when one disconnects; pass ``timeout_ms`` or cancel the task. """ if not self.flags & (FLAG_WRITE | FLAG_WRITE_NO_RESPONSE): raise UnsupportedError("{!r} is not writable".format(self)) return await self._bound().written(timeout_ms)
[docs] class Descriptor: """A read-only descriptor on a `Characteristic` you serve. HID uses these: each Report characteristic carries a Report Reference (0x2908) saying which report it is. The value is fixed once registered. Don't make a CCCD (0x2902); every backend adds that itself for a characteristic with ``notify`` or ``indicate``. """ def __init__(self, characteristic, uuid, initial=b""): characteristic.descriptors.append(self) self.characteristic = characteristic self.uuid = UUID(uuid) self.value = bytes(initial) def __repr__(self): return "Descriptor({!r})".format(self.uuid)
# ---------------------------------------------------------------- central side
[docs] class Device: """A peer found by a scan, or named by address. ``connect()`` it. ``address`` is a string: ``"aa:bb:cc:dd:ee:ff"`` on a board, and whatever the OS uses on a host (macOS and browsers hide real addresses). ``addr`` holds the six raw bytes where the backend knows them, else ``None``. """ def __init__(self, ble, address, addr_type=ADDR_PUBLIC, name=None, native=None): self._ble = ble if isinstance(address, (bytes, bytearray)): self.addr = bytes(address) address = ":".join(_hex(bytes((b,))) for b in self.addr) else: self.addr = None self.address = address self.addr_type = addr_type self.name = name #: The backend's own object for this device (aioble Device, bleak BLEDevice, ...). self.native = native def addr_hex(self): return self.address def __eq__(self, other): return isinstance(other, Device) and self.address == other.address def __ne__(self, other): return not self.__eq__(other) def __hash__(self): return hash(self.address) def __repr__(self): return "Device({!r}, name={!r})".format(self.address, self.name)
[docs] async def connect(self, timeout_ms=10000, **options): """Connect as central and return the `Connection`. Options a backend understands (``min_conn_interval_us``, ``max_conn_interval_us`` on a board) pass through; others are ignored. """ return await self._ble._connect(self, timeout_ms, **options)
[docs] class ScanResult: """One device's advertisement, as aioble reports it. ``name()``, ``services()`` and ``manufacturer()`` are methods, as in aioble. ``services()`` returns a list of `UUID`. """ def __init__( self, device, rssi=None, name=None, services=(), appearance=0, manufacturer=(), connectable=True, service_data=() ): self.device = device self.rssi = rssi self._name = name self._services = [UUID(s) for s in services] self.appearance = appearance self._manufacturer = list(manufacturer) self._service_data = [(UUID(u), bytes(d)) for u, d in service_data] self.connectable = connectable def name(self): return self._name def services(self): return list(self._services) def manufacturer(self, filter=None): return [(m, d) for m, d in self._manufacturer if filter is None or m == filter]
[docs] def service_data(self, uuid=None): """``[(UUID, data), ...]``, optionally only for ``uuid``.""" if uuid is not None: uuid = UUID(uuid) return [(u, d) for u, d in self._service_data if uuid is None or u == uuid]
def __repr__(self): return "ScanResult({!r}, rssi={})".format(self.device, self.rssi)
[docs] class Scanner: """What ``ble.scan()`` returns: an async context manager and async iterator. A backend either subclasses this and overrides the three hooks, or pushes results into it with ``_push()`` and ``_finish()`` from the event loop. """ def __init__(self, ble, duration_ms, active=False, interval_us=None, window_us=None): self._ble = ble self.duration_ms = duration_ms self.active = active self.interval_us = interval_us self.window_us = window_us self._queue = [] self._event = asyncio.Event() self._done = False async def _start(self): pass async def _stop(self): pass def _push(self, result): self._queue.append(result) self._event.set() def _finish(self): self._done = True self._event.set() async def __aenter__(self): await self._start() return self async def __aexit__(self, exc_type, exc, tb): await self.cancel() async def cancel(self): # A second cancel while the first is still stopping the scan (the # duration timer's, then the ``async with``'s) waits for it, so the # caller can't close the loop on a radio that is still scanning. stopping = getattr(self, "_stopping", None) if stopping is not None: await stopping.wait() return if self._done: return self._stopping = asyncio.Event() self._finish() try: await self._stop() finally: self._stopping.set() def __aiter__(self): return self async def __anext__(self): while True: if self._queue: return self._queue.pop(0) if self._done: raise StopAsyncIteration self._event.clear() await self._event.wait()
class _Discovery: """An async iterator over a list a coroutine produces on first use.""" def __init__(self, fetch): # A callable returning the coroutine, so an iterator nobody walks # never creates one. self._fetch = fetch self._items = None def __aiter__(self): return self async def __anext__(self): if self._items is None: self._items = list(await self._fetch()) if not self._items: raise StopAsyncIteration return self._items.pop(0)
[docs] class Connection: """A live link to one peer, from either side. ``role`` is the role *this* side plays: ``"central"`` if it connected, ``"peripheral"`` if it advertised. ``mtu`` is the current ATT MTU; one notification or write carries ``mtu - 3`` bytes. Use ``async with`` to disconnect on exit. Service discovery works from either role, but in practice only the central uses it. """ def __init__(self, ble, device, role): self._ble = ble self.device = device self.role = role self._mtu = DEFAULT_MTU @property def mtu(self): """The current ATT MTU. One packet carries ``mtu - 3`` bytes of value.""" return self._mtu def __repr__(self): return "Connection({!r}, role={!r}, mtu={})".format(self.device, self.role, self.mtu) def is_connected(self): raise NotImplementedError
[docs] async def disconnect(self, timeout_ms=2000): """Drop the link and wait for it to be gone.""" raise NotImplementedError
[docs] async def disconnected(self, timeout_ms=None): """Wait until the link drops, from either side.""" raise NotImplementedError
@property def encrypted(self): """True once the link is encrypted (after `pair`, or a bonded reconnect).""" return False
[docs] async def pair(self, bond=True, timeout_ms=30000, passkey=None): """Pair with the peer and encrypt the link; with ``bond``, keep the keys. Either side may call it; in practice the central does, when a read fails with ``INSUFFICIENT_ENCRYPTION``. Without ``passkey`` the pairing is "just works", which is what a keyboard without a screen does. When the peer shows a passkey (a board with a display), ``passkey`` is what to type in: an int, a string of six digits, or a callable (plain or async) that returns one when asked, such as one that prompts a person. A bonded peer reconnects without pairing again, for as long as both sides keep their keys; pairing a bonded peer just encrypts the link with the stored keys. Raises `PairingError` when pairing fails (a wrong passkey, or a peer that lost its half of the bond), and `UnsupportedError` on a backend without pairing. """ raise UnsupportedError("{} cannot pair".format(self._ble.backend))
@property def authenticated(self): """True when the link's keys came from a passkey or numeric comparison.""" return False
[docs] async def unpair(self): """Forget this peer's keys on this side (and, on a laptop, the OS's pairing).""" raise UnsupportedError("{} cannot unpair".format(self._ble.backend))
[docs] async def exchange_mtu(self, mtu=None, timeout_ms=1000): """Negotiate a larger ATT MTU and return the result. Hosts that negotiate on their own (bleak, browsers) just return the current value. """ return self.mtu
[docs] def services(self, uuid=None, timeout_ms=2000): """Async-iterate the peer's services, optionally only ``uuid``.""" uuid = None if uuid is None else UUID(uuid) return _Discovery(lambda: self._discover_services(uuid, timeout_ms))
[docs] async def service(self, uuid, timeout_ms=2000): """The peer's service ``uuid``, or ``None`` if it has none.""" uuid = UUID(uuid) found = None async for service in self.services(uuid, timeout_ms): if found is None and service.uuid == uuid: found = service return found
async def _discover_services(self, uuid, timeout_ms): raise NotImplementedError async def __aenter__(self): return self async def __aexit__(self, exc_type, exc, tb): await self.disconnect()
[docs] class ClientService: """A service on the peer, found by discovery.""" def __init__(self, connection, uuid): self.connection = connection self.uuid = UUID(uuid) def __repr__(self): return "ClientService({!r})".format(self.uuid) def characteristics(self, uuid=None, timeout_ms=2000): uuid = None if uuid is None else UUID(uuid) return _Discovery(lambda: self._discover_characteristics(uuid, timeout_ms))
[docs] async def characteristic(self, uuid, timeout_ms=2000): """The characteristic ``uuid`` in this service, or ``None``.""" uuid = UUID(uuid) found = None async for characteristic in self.characteristics(uuid, timeout_ms): if found is None and characteristic.uuid == uuid: found = characteristic return found
async def _discover_characteristics(self, uuid, timeout_ms): raise NotImplementedError
[docs] class ClientCharacteristic: """A characteristic on the peer. ``properties`` holds its ``FLAG_*`` bits. Notifications and indications are queued in arrival order and never silently dropped: a backend whose queue overflows raises `BLEError` from the next ``notified()``. Call ``subscribe()`` before you expect any to arrive. ``arrival`` says in what order the last notification came in, relative to the other characteristics' (it is ``None`` on a backend that doesn't number them). Each queue is in order on its own, but waiting on two characteristics at once wakes them in no particular order; the number is taken when the radio receives the notification, so you can put them back. """ #: After ``notified()`` returns, an integer that grows with every #: notification the radio receives, whichever characteristic it is on, or #: ``None`` if the backend doesn't number them. arrival = None def __init__(self, service, uuid, properties): self.service = service self.connection = service.connection self.uuid = UUID(uuid) self.properties = properties def __repr__(self): return "ClientCharacteristic({!r}, properties=0x{:02x})".format(self.uuid, self.properties) def _check(self, flag, what): if not self.properties & flag: raise UnsupportedError("{!r} does not support {}".format(self, what))
[docs] async def read(self, timeout_ms=1000): """The value. A backend without long reads (``capabilities()["long_read"]`` is False: MicroPython) returns at most ``connection.mtu - 1`` bytes.""" raise NotImplementedError
[docs] def descriptors(self, uuid=None, timeout_ms=2000): """Async-iterate this characteristic's descriptors, optionally only ``uuid``.""" uuid = None if uuid is None else UUID(uuid) return _Discovery(lambda: self._discover_descriptors(uuid, timeout_ms))
[docs] async def descriptor(self, uuid, timeout_ms=2000): """The descriptor ``uuid`` on this characteristic, or ``None``.""" uuid = UUID(uuid) found = None async for d in self.descriptors(uuid, timeout_ms): if found is None and d.uuid == uuid: found = d return found
async def _discover_descriptors(self, uuid, timeout_ms): raise UnsupportedError("{} cannot discover descriptors".format(self.connection._ble.backend))
[docs] async def write(self, data, response=None, timeout_ms=1000): """Write ``data`` (at most ``connection.mtu - 3`` bytes). ``response=None`` asks for a response only when the characteristic doesn't allow writing without one. A write without response waits for buffer room rather than failing. """ raise NotImplementedError
async def subscribe(self, notify=True, indicate=False): raise NotImplementedError
[docs] async def notified(self, timeout_ms=None): """The next notification's data. Raises `DisconnectedError` if the link drops.""" raise NotImplementedError
async def indicated(self, timeout_ms=None): raise NotImplementedError def _want_response(self, response): if response is None: return bool(self.properties & FLAG_WRITE) and not self.properties & FLAG_WRITE_NO_RESPONSE if response: self._check(FLAG_WRITE, "write with response") else: self._check(FLAG_WRITE_NO_RESPONSE, "write without response") return bool(response)
[docs] class ClientDescriptor: """A descriptor on the peer, found by `ClientCharacteristic.descriptors`.""" def __init__(self, characteristic, uuid): self.characteristic = characteristic self.connection = characteristic.connection self.uuid = UUID(uuid) def __repr__(self): return "ClientDescriptor({!r})".format(self.uuid) async def read(self, timeout_ms=1000): raise NotImplementedError
[docs] def is_adapter(obj): """True for a bledev `BLE`; False for a raw ``bluetooth.BLE`` or anything else.""" return isinstance(obj, BLE)
[docs] async def passkey_value(passkey): """``passkey`` as an int: it may be an int, a string of digits, or a callable (plain or async) returning either. ``None`` stays ``None``.""" if callable(passkey): passkey = passkey() if hasattr(passkey, "send"): # a coroutine passkey = await passkey if passkey is None: return None return int(passkey)
[docs] async def connect_and_set_up( ble, setup, *, name=None, service=None, device=None, timeout_ms=10000, attempts=3, setup_timeout_ms=4000, **options ): """Find a device, connect, and run ``await setup(connection)``; returns ``(connection, what setup returned)``. If the link drops or stalls before ``setup`` finishes, this disconnects and tries again, up to ``attempts`` times. Profiles use it (``nus``, ``midi``), because a link can come up dead: about one reconnect in fifty from Windows, the OS reports a connection the peripheral never saw, and the first GATT operation on it hangs until Windows gives up nine seconds later. ``setup_timeout_ms`` bounds that wait. ``options`` go to ``device.connect()``, except ``pair`` (pair before ``setup``) and ``passkey`` (for `Connection.pair`). """ pair = options.pop("pair", False) passkey = options.pop("passkey", None) # A backend whose GATT calls are slow by nature says how long setup may # take at least (cpble: CircuitPython waits 2 s on every write with a # response, subscribing included). setup_timeout_ms = max(setup_timeout_ms, getattr(ble, "min_setup_ms", 0)) error = None stale = False for _ in range(attempts): target = device if target is None: target = await ble.find(name=name, service=service, timeout_ms=timeout_ms) if pair and getattr(ble, "pairs_on_connect", False): # The backend pairs before the link is up (bleak on Windows, # which can't pair a board that asked for security as it # connected). connection = await target.connect(timeout_ms=timeout_ms, pair=True, passkey=passkey, **options) reused = getattr(connection, "reused_bond", False) elif pair: connection = await target.connect(timeout_ms=timeout_ms, **options) # Before discovery: a board that wants pairing refuses the # subscriptions setup makes. Pairing waits on a person typing a # passkey, so setup_timeout_ms doesn't bound it. try: await connection.pair(passkey=passkey) except BaseException: if connection.is_connected(): await connection.disconnect() raise reused = getattr(connection, "reused_bond", False) else: connection = await target.connect(timeout_ms=timeout_ms, **options) reused = False try: return connection, await wait_ms(setup(connection), setup_timeout_ms, "setting up the connection") except (DisconnectedError, BLETimeoutError) as e: error = e stale = reused and isinstance(e, DisconnectedError) except BaseException: if connection.is_connected(): await connection.disconnect() raise try: await connection.disconnect() except BLEError: pass # Give a dead link time to be noticed before the next try. await sleep_ms(500 * (_ + 1)) if stale: # Every attempt encrypted with keys this host already had, and every # link fell. Windows hangs up when the board refuses those keys, but # it also hands out links the board never saw, for a while after the # board resets; from here the two look the same. raise PairingError( "every link dropped right after connecting with this host's stored keys. Try again in " "a few seconds (after a board reset Windows can hold a dead link); if it keeps " "happening, " + STALE_BOND ) raise error