Source code for bledev.cpble

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

"""CircuitPython backend, over ``_bleio``. Both roles.

    import bledev.cpble
    ble = bledev.cpble.get()       # the board's one radio, shared

Needs CircuitPython with ``_bleio`` (every nRF52, and every ESP32 with BLE
except the S2), and the ``asyncio`` library from the Adafruit bundle
(``circup install asyncio``, which brings ``adafruit_ticks``).

``_bleio`` is the model furthest from aioble's. aioble hands you events;
``_bleio`` hands you objects you poll: a connection's ``connected`` flag,
a buffer a characteristic's writes land in, a scan's iterator. So this backend
turns each wait into a short poll of those objects (every
`POLL_MS`), and a few things work differently from the other backends:

* **Some calls block the event loop.** ``_bleio`` has no async API. Connecting,
  service discovery, a read, a write with response and a subscription each
  wait inside ``_bleio`` until the radio answers, usually one or two
  connection intervals, and nothing else in asyncio runs meanwhile. A scan
  runs in slices of `SCAN_SLICE_MS` for the same reason.
* **Writes land in ring buffers** that CircuitPython fills from the radio's
  task. A characteristic you can notify on gets a ``PacketBuffer``, which
  keeps each write whole but only takes writes from the central that
  subscribed, after it subscribed. Any other writable characteristic gets a
  ``CharacteristicBuffer``, a byte stream: with ``capture=True`` each
  ``written()`` returns whatever bytes arrived since the last, not one write.
  Both drop the oldest data when full and don't say so, so read them promptly;
  the stream buffer's fill is checked and a full one raises.
* **One notification in flight per characteristic.** ``notify()`` raises
  `BusyError` while the previous one is still waiting for the radio;
  every async sender (nus, midi) waits and tries again. That's how this backend
  steps around a stall in CircuitPython 10.3's ``PacketBuffer`` (see
  `_CPServerCharacteristic._send`), and it also keeps each notification
  whole, where ``PacketBuffer`` would otherwise merge two into one.
* **Setting a value notifies.** ``Characteristic.write(data)`` on a
  characteristic with notify or indicate sends it to every subscribed central,
  whatever ``send_update`` says, because that's what ``_bleio`` does.
* **Indications** go out, but ``indicate()`` returns once they're queued:
  ``_bleio`` doesn't report the acknowledgement. A central here can't receive
  indications at all (CircuitPython's ESP32 port ignores them), so
  ``capabilities()["indicate"]`` is False.
* **Pairing is "just works" only.** CircuitPython's ESP32 port has no passkey
  or numeric comparison (``authenticated=True`` raises
  `UnsupportedError`), and it always bonds. Its MTU is fixed at build
  time (256 on the ESP32 port), so ``config(mtu=...)`` is unsupported; both
  sides exchange at connect.
* **A peripheral doesn't learn the central's address.** ``_bleio`` doesn't
  expose it, so ``connection.device.address`` is ``"central"``.
* **The GATT server allows ten characteristics per service and two
  descriptors per characteristic**, on the ESP32 port.
* **A service stays served until the board reloads.** Run a peripheral again
  from the REPL and its new objects take over the copy already served, as
  long as the characteristics match. Change them and ``register_services()``
  raises: press Ctrl-D first.

The ``_bleio`` objects are there when you need them: ``ble.raw`` is
``_bleio.adapter`` and ``connection.native`` a ``_bleio.Connection``.
"""

import asyncio

import _bleio

from . import (
    BLE,
    BLEError,
    BLETimeoutError,
    BusyError,
    ClientCharacteristic,
    ClientDescriptor,
    ClientService,
    Connection,
    DEFAULT_MTU,
    Device,
    DisconnectedError,
    FLAG_INDICATE,
    FLAG_NOTIFY,
    FLAG_READ,
    FLAG_WRITE,
    FLAG_WRITE_NO_RESPONSE,
    GattError,
    INSUFFICIENT_AUTHENTICATION,
    INSUFFICIENT_ENCRYPTION,
    PairingError,
    ScanResult,
    Scanner,
    UnsupportedError,
    UUID,
    decode_advertisement,
    decode_service_data,
    pack_advertisement,
    sleep_ms,
)

#: How often a wait looks at ``_bleio``'s objects, in milliseconds.
POLL_MS = 5

#: How long, in milliseconds, a characteristic keeps retrying its last
#: notification after sending it. See :meth:`_CPServerCharacteristic._send`.
RETRY_MS = 5000

#: How long one slice of a scan blocks the event loop, in milliseconds.
SCAN_SLICE_MS = 100

#: The largest attribute value ``_bleio`` holds (``BLE_ATT_ATTR_MAX_LEN``).
_MAX_VALUE = 512

#: The largest ATT payload a peer can send here: CircuitPython's ESP32 port
#: asks for an MTU of 256.
_MAX_PAYLOAD = 253

#: The MTU this backend reports, and sends by: 247, one link-layer packet,
#: even when the link agreed 256. A 253-byte notification is split into two
#: packets below NimBLE's ATT layer, which needs buffers the pool may not
#: have, and when NimBLE refuses a notification, CircuitPython 10.3's
#: PacketBuffer switches to a second outgoing buffer it never allocated for
#: notifications, and the next write faults the board (seen: a hard fault in
#: the nus gate, the board restarting in safe mode).
_MAX_MTU = 247

# How long a write without response keeps retrying a full buffer by default.
_WRITE_RETRY_MS = 2000

try:
    from supervisor import ticks_ms as _ticks_ms
except ImportError:  # pragma: no cover - CPython tests with a stub _bleio
    import time as _time

    def _ticks_ms():
        return int(_time.monotonic() * 1000) & _TICKS_MASK


# supervisor.ticks_ms() wraps at 2**29.
_TICKS_MASK = (1 << 29) - 1


def _elapsed(since):
    return (_ticks_ms() - since) & _TICKS_MASK


def _cuuid(uuid):
    """bledev UUID -> _bleio.UUID."""
    uuid = UUID(uuid)
    short = uuid.short
    if short is not None and short <= 0xFFFF:
        return _bleio.UUID(short)
    return _bleio.UUID(str(uuid))


def _uuid(cuuid):
    """_bleio.UUID -> bledev UUID."""
    if cuuid.size == 16:
        return UUID(cuuid.uuid16)
    return UUID(bytes(cuuid.uuid128))


# _bleio's property bits are the Bluetooth spec's, as bledev's are; map them
# by name anyway, so a port that numbers them differently still works.
_PROPS = (
    (FLAG_READ, "READ"),
    (FLAG_WRITE, "WRITE"),
    (FLAG_WRITE_NO_RESPONSE, "WRITE_NO_RESPONSE"),
    (FLAG_NOTIFY, "NOTIFY"),
    (FLAG_INDICATE, "INDICATE"),
)


def _to_cprops(flags):
    props = 0
    for flag, name in _PROPS:
        if flags & flag:
            props |= getattr(_bleio.Characteristic, name)
    return props


def _from_cprops(props):
    flags = 0
    for flag, name in _PROPS:
        if props & getattr(_bleio.Characteristic, name):
            flags |= flag
    return flags


def _translate(e, what):
    """A bledev error for an exception ``_bleio`` raised, or ``None``."""
    if isinstance(e, BLEError):
        return e
    if isinstance(e, ConnectionError):
        return DisconnectedError("{}: not connected".format(what))
    if isinstance(e, TimeoutError):
        return BLETimeoutError("{} timed out".format(what))
    if isinstance(e, MemoryError):
        return BusyError("{}: the radio's buffers are full".format(what))
    security = getattr(_bleio, "SecurityError", None)
    if security is not None and isinstance(e, security):
        text = str(e).lower()
        status = INSUFFICIENT_AUTHENTICATION if "authentication" in text else INSUFFICIENT_ENCRYPTION
        return GattError(status, "{}: {}".format(what, e))
    if isinstance(e, _bleio.BluetoothError):
        # A read or write that the peer refused comes back as NimBLE's
        # "Unknown system firmware error: 261", 0x100 plus the ATT code,
        # because _bleio checks that status as a NimBLE error.
        text = str(e)
        tail = text.rsplit(" ", 1)[-1]
        try:
            code = int(tail)
        except ValueError:
            code = None
        if code is not None and 0x100 <= code < 0x200:
            return GattError(code - 0x100, "{}: ATT error 0x{:02x}".format(what, code - 0x100))
        return BLEError("{}: {}".format(what, text))
    return None


class _Call:
    """``with _Call("read"):`` turns ``_bleio``'s exceptions into bledev's."""

    def __init__(self, what):
        self._what = what

    def __enter__(self):
        return self

    def __exit__(self, exc_type, exc, tb):
        if exc_type is None:
            return False
        error = _translate(exc, self._what)
        if error is not None and error is not exc:
            raise error
        return False


_shared = None

# The services in _bleio's GATT table, which keeps them until the board
# reloads: service UUID -> _Served. They outlive any one CPBLE, because a
# script run again from the REPL makes a new one over the same adapter.
_served = {}
_served_adapter = None


class _Served:
    """A service in the GATT table, and the characteristics bound to it now."""

    def __init__(self, layout, native, nchars):
        self.layout = layout
        self.native = native
        self.nchars = nchars
        self.bound = ()


def _layout(service):
    """What has to match for a new Service to reuse a served copy."""
    return tuple(
        (c.uuid, c.flags, c.encrypted, tuple((d.uuid, bytes(d.value)) for d in c.descriptors))
        for c in service.characteristics
    )


[docs] def get(adapter=None): """The shared `CPBLE` for this board's radio, made on first use.""" global _shared if _shared is None: _shared = CPBLE(adapter) return _shared
[docs] class CPBLE(BLE): """The board's radio, ``_bleio.adapter`` unless you pass another. ``queue_limit`` bounds each notification and capture queue, and sizes the packet buffers ``_bleio`` fills. ``stream_buffer`` is the byte size of the buffer behind a write-only characteristic with ``capture=True`` (nus's RX): what arrives while your code doesn't read. Prefer `get`. """ backend = "cpble" #: How long a profile's setup after connecting may take here (see #: ``bledev.connect_and_set_up``). CircuitPython's ESP32 port waits out #: its whole 2 s timeout on every read and every write with response, #: because it waits for a status to leave 0 and success is 0; making a #: subscription is such a write. min_setup_ms = 12000 def __init__(self, adapter=None, *, queue_limit=64, stream_buffer=32768): self.raw = adapter if adapter is not None else _bleio.adapter if self.raw is None: raise UnsupportedError("this board has no BLE adapter (_bleio.adapter is None)") if not self.raw.enabled: self.raw.enabled = True self.queue_limit = queue_limit self.stream_buffer = stream_buffer self._services = () # _bleio.Connection -> _CPConnection. _bleio hands out one object per # link, so identity is enough. self._connections = {}
[docs] def capabilities(self): caps = BLE.capabilities(self) caps.update( central=True, peripheral=True, mtu=_MAX_MTU, max_mtu=_MAX_MTU, indicate=False, pairing=True, long_read=False, write_notifies=True, ) return caps
[docs] def config(self, *names, **settings): for key, value in settings.items(): if key == "gap_name": self.raw.name = value elif key == "mtu": if value != _MAX_MTU: raise UnsupportedError( "CircuitPython's MTU is fixed when it's built ({} here)".format(_MAX_MTU) ) else: raise UnsupportedError("cpble has no setting {!r}".format(key)) if names: if len(names) != 1: raise ValueError("read one setting at a time") name = names[0] if name == "mtu": return _MAX_MTU if name == "gap_name": return self.raw.name raise UnsupportedError("cpble has no setting {!r}".format(name)) return None
[docs] def close(self): try: self.raw.stop_advertising() except Exception: pass try: self.raw.stop_scan() except Exception: pass for native in tuple(self.raw.connections): try: native.disconnect() except Exception: pass self._connections = {}
[docs] def enable_bonding(self, store=None): """CircuitPython always bonds and keeps the keys itself (in NVS on an ESP32), so this only accepts the call. ``forget_bonds()`` erases them."""
[docs] def forget_bonds(self): """Erase every bond this board holds (``_bleio.adapter.erase_bonding()``).""" self.raw.erase_bonding()
# -- connections def _wrap(self, native, role, device=None): conn = self._connections.get(native) if conn is None: if len(self._connections) > 8: for key in list(self._connections): if not self._connections[key].is_connected(): del self._connections[key] if device is None: device = Device(self, "central") conn = _CPConnection(self, device, role, native) self._connections[native] = conn return conn def _current(self): """The live peripheral-side connection a write most likely came from. ``_bleio`` doesn't say which central wrote, so with more than one this is the most recent one still connected.""" found = None for native in self.raw.connections: conn = self._connections.get(native) if conn is not None and conn.role == "peripheral" and conn.is_connected(): found = conn if found is None: for native in self.raw.connections: found = self._connections.get(native) or found return found # -- peripheral
[docs] def register_services(self, *services): """Serve ``services``. ``_bleio`` can't take a service out of the GATT table until the board reloads, so each service is added once and kept. Register a service whose UUID is already served (a script run again from the REPL) and its characteristics take over the served copy: reads, writes and notifications go to them, and the earlier objects get nothing. That needs the same characteristics, in the same order, with the same flags and descriptors. If they differ, this raises `BLEError`: reload the board (Ctrl-D) to serve the new layout. A service served before and left out here stays in the table, unbound, until then. """ global _served, _served_adapter if _served_adapter is not self.raw: _served, _served_adapter = {}, self.raw # Check everything before changing anything. seen = [] for service in services: if service.uuid in seen: raise ValueError("service {} is listed twice".format(service.uuid)) seen.append(service.uuid) if len(service.characteristics) > 10: raise UnsupportedError("CircuitPython serves at most 10 characteristics per service") for c in service.characteristics: if c.authenticated: raise UnsupportedError("CircuitPython can't require a passkey (authenticated=True)") if len(c.descriptors) > 2: raise UnsupportedError("CircuitPython allows two descriptors per characteristic") served = _served.get(service.uuid) if served is not None and served.layout != _layout(service): raise BLEError( "service {} is already served with other characteristics, and CircuitPython " "can't remove it until the board reloads: press Ctrl-D and run again".format(service.uuid) ) # Unbind whatever is bound to a served copy, from this CPBLE or an # earlier one, so no old object keeps a buffer or gets the traffic. for served in _served.values(): for c in served.bound: if c._impl is not None: c._impl._release() c._impl = None served.bound = () for service in services: served = _served.get(service.uuid) if served is None: served = self._add_service(service) _served[service.uuid] = served else: for c, nchar in zip(service.characteristics, served.nchars): nchar.value = c._initial or b"" for c, nchar in zip(service.characteristics, served.nchars): c._impl = _CPServerCharacteristic(self, c, nchar) served.bound = tuple(service.characteristics) self._services = tuple(services)
def _add_service(self, service): """Add ``service`` to _bleio's GATT table.""" open_ = _bleio.Attribute.OPEN nservice = _bleio.Service(_cuuid(service.uuid)) nchars = [] for c in service.characteristics: perm = _bleio.Attribute.ENCRYPT_NO_MITM if c.encrypted else open_ # Every value gets the largest buffer: max_len is kept here, # in Python, as the other backends keep it (a longer write # keeps its first max_len bytes). _bleio would refuse the # write instead, and a notification can't exceed the value's # buffer. nchar = _bleio.Characteristic.add_to_service( nservice, _cuuid(c.uuid), properties=_to_cprops(c.flags), read_perm=perm if c.flags & FLAG_READ or c.flags & (FLAG_NOTIFY | FLAG_INDICATE) else open_, write_perm=perm if c.flags & (FLAG_WRITE | FLAG_WRITE_NO_RESPONSE) else _bleio.Attribute.NO_ACCESS, max_length=_MAX_VALUE, fixed_length=False, initial_value=c._initial or b"", ) for d in c.descriptors: _bleio.Descriptor.add_to_characteristic( nchar, _cuuid(d.uuid), read_perm=perm, write_perm=_bleio.Attribute.NO_ACCESS, max_length=max(1, len(d.value)), fixed_length=True, initial_value=d.value or b"\x00", ) nchars.append(nchar) return _Served(_layout(service), nservice, nchars)
[docs] async def advertise( self, interval_us=100000, *, name=None, services=None, appearance=0, manufacturer=None, connectable=True, timeout_ms=None, service_data=None, ): adv_data, resp_data = pack_advertisement(name, services, appearance, manufacturer, service_data) if name: # The GAP name, which a paired computer lists, is the advertised one. self.raw.name = name interval = min(10.24, max(0.02, interval_us / 1000000)) known = set(self.raw.connections) if not known: # Fresh packet buffers for the next link (see _renew), made # before a central can connect and subscribe. for service in self._services: for c in service.characteristics: if c._impl is not None and c._impl._packets is not None: c._impl._renew() try: self.raw.stop_advertising() except Exception: pass with _Call("advertise"): self.raw.start_advertising( adv_data, scan_response=resp_data or None, connectable=connectable, interval=interval, ) start = _ticks_ms() try: while True: for native in self.raw.connections: if native not in known and native.connected: # A connect stops advertising. return self._wrap(native, "peripheral") if timeout_ms is not None and _elapsed(start) >= timeout_ms: raise BLETimeoutError("advertise: nobody connected in {} ms".format(timeout_ms)) await sleep_ms(POLL_MS * 4) finally: if self.raw.advertising: try: self.raw.stop_advertising() except Exception: pass
# -- central
[docs] def scan(self, duration_ms, *, active=False, interval_us=None, window_us=None): return _CPScanner(self, duration_ms, active, interval_us, window_us)
async def _connect(self, device, timeout_ms, **options): address = device.native if not isinstance(address, _bleio.Address): if device.addr is None: raise BLEError("cpble connects by address; {!r} has none".format(device)) address = _bleio.Address(bytes(reversed(device.addr)), device.addr_type) try: self.raw.stop_scan() except Exception: pass await sleep_ms(0) with _Call("connect"): native = self.raw.connect(address, timeout=(timeout_ms or 10000) / 1000) if native is None or not native.connected: raise BLETimeoutError("connect timed out") conn = self._wrap(native, "central", device) # _bleio asks for 15 to 300 ms and may get the slow end; ask for what # MicroPython's NimBLE asks by default (30 ms) unless told otherwise. interval_us = options.get("max_conn_interval_us") or options.get("min_conn_interval_us") or 30000 try: native.connection_interval = interval_us / 1000 except Exception: pass # the peripheral may refuse; the link keeps its interval return conn
class _CPScanner(Scanner): """Runs ``_bleio``'s scan in slices, so the event loop gets a turn between them.""" def __init__(self, ble, duration_ms, active, interval_us, window_us): Scanner.__init__(self, ble, duration_ms, active, interval_us, window_us) self._seen = {} self._started = None async def _start(self): self._started = _ticks_ms() async def _stop(self): try: self._ble.raw.stop_scan() except Exception: pass def _slice(self): interval = (self.interval_us or 30000) / 1000000 window = (self.window_us or self.interval_us or 30000) / 1000000 left = self.duration_ms - _elapsed(self._started) if left <= 0: self._finish() return length = min(SCAN_SLICE_MS, left) / 1000 with _Call("scan"): results = self._ble.raw.start_scan( timeout=length, interval=interval, window=min(window, interval), active=self.active, minimum_rssi=-127, buffer_size=2048, ) try: for entry in results: self._entry(entry) finally: try: self._ble.raw.stop_scan() except Exception: pass def _entry(self, entry): raw = bytes(entry.advertisement_bytes) key = bytes(entry.address.address_bytes) seen = self._seen.get(key) if seen is None: seen = self._seen[key] = [b"", b"", True, None] if entry.scan_response: seen[1] = raw else: seen[0] = raw seen[2] = entry.connectable name, services, appearance, manufacturer = decode_advertisement(seen[0], seen[1]) # A name seen once stays (a host may put it in only one of the two # packets), and a UUID in both packets is listed once. name = seen[3] = name or seen[3] unique = [] for uuid in services: if uuid not in unique: unique.append(uuid) services = unique device = Device( self._ble, bytes(reversed(key)), entry.address.type, name=name, native=entry.address ) self._push( ScanResult( device, rssi=entry.rssi, name=name, services=services, appearance=appearance, manufacturer=manufacturer, connectable=seen[2], service_data=decode_service_data(seen[0], seen[1]), ) ) async def __anext__(self): while True: if self._queue: return self._queue.pop(0) if self._done: raise StopAsyncIteration self._slice() await sleep_ms(0) class _CPConnection(Connection): def __init__(self, ble, device, role, native): Connection.__init__(self, ble, device, role) #: The ``_bleio.Connection``. self.native = native self._remote = None self._by_uuid = {} self._last_mtu = DEFAULT_MTU @property def mtu(self): try: self._last_mtu = min(self.native.max_packet_length + 3, _MAX_MTU) except Exception: pass # disconnected: keep the last value return self._last_mtu def is_connected(self): try: return bool(self.native.connected) except Exception: return False async def disconnect(self, timeout_ms=2000): if self.is_connected(): try: self.native.disconnect() except Exception: pass await self.disconnected(timeout_ms) async def disconnected(self, timeout_ms=None): start = _ticks_ms() while self.is_connected(): if timeout_ms is not None and _elapsed(start) >= timeout_ms: raise BLETimeoutError("disconnected timed out after {} ms".format(timeout_ms)) await sleep_ms(POLL_MS * 4) async def exchange_mtu(self, mtu=None, timeout_ms=1000): # CircuitPython exchanges at every connect, from either side; wait for # the result rather than asking again. start = _ticks_ms() while self.is_connected() and self.mtu <= DEFAULT_MTU and _elapsed(start) < (timeout_ms or 0): await sleep_ms(POLL_MS * 4) if not self.is_connected(): raise DisconnectedError("exchange_mtu: disconnected") return self.mtu @property def encrypted(self): try: return bool(self.native.paired) except Exception: return False async def pair(self, bond=True, timeout_ms=30000, passkey=None): if passkey is not None: raise UnsupportedError("CircuitPython pairs only 'just works': no passkey") if not bond: raise UnsupportedError("CircuitPython always bonds") if not self.is_connected(): raise DisconnectedError("pair: not connected") # _bleio's pair() blocks until the link is encrypted; a refusal leaves # it waiting, which only a disconnect or Ctrl-C ends. with _Call("pair"): self.native.pair(bond=True) if not self.encrypted: if not self.is_connected(): raise PairingError("pair: the peer hung up") raise PairingError("pair: refused") async def unpair(self): raise UnsupportedError("CircuitPython forgets one peer only by erasing every bond: ble.forget_bonds()") def _discover(self, uuid=None): # _bleio discovers characteristics and descriptors too, one round trip # each, so asking for one service is far quicker than asking for all # (7 s against a MicroPython nus server at CircuitPython's default # interval). Services found either way are kept. if self._remote is not None: return self._remote if not self.is_connected(): raise DisconnectedError("service discovery: not connected") if uuid is not None: found = self._by_uuid.get(uuid) if found is None: with _Call("service discovery"): found = [_CPClientService(self, s) for s in self.native.discover_remote_services((_cuuid(uuid),))] self._by_uuid[uuid] = found return found with _Call("service discovery"): self._remote = [_CPClientService(self, s) for s in self.native.discover_remote_services()] return self._remote async def _discover_services(self, uuid, timeout_ms): await sleep_ms(0) return [s for s in self._discover(uuid) if uuid is None or s.uuid == uuid] class _CPClientService(ClientService): def __init__(self, connection, native): ClientService.__init__(self, connection, _uuid(native.uuid)) self.native = native self._characteristics = None async def _discover_characteristics(self, uuid, timeout_ms): if self._characteristics is None: self._characteristics = [_CPClientCharacteristic(self, c) for c in self.native.characteristics] return [c for c in self._characteristics if uuid is None or c.uuid == uuid] class _CPClientCharacteristic(ClientCharacteristic): def __init__(self, service, native): ClientCharacteristic.__init__(self, service, _uuid(native.uuid), _from_cprops(native.properties)) self.native = native self._buffer = None self._packet = bytearray(_MAX_VALUE) self._queue = [] self._overrun = 0 def _live(self, what): if not self.connection.is_connected(): raise DisconnectedError("{}: not connected".format(what)) async def read(self, timeout_ms=1000): self._check(FLAG_READ, "read") self._live("read") await sleep_ms(0) with _Call("read"): value = self.native.value self._live("read") return bytes(value) async def _discover_descriptors(self, uuid, timeout_ms): self._live("descriptor discovery") found = [_CPClientDescriptor(self, d) for d in self.native.descriptors] return [d for d in found if uuid is None or d.uuid == uuid] async def write(self, data, response=None, timeout_ms=1000): data = bytes(data) response = self._want_response(response) if response and self.properties & FLAG_WRITE_NO_RESPONSE: # _bleio picks the write type from the properties, and a # characteristic that allows both always gets one without. raise UnsupportedError( "CircuitPython writes {!r} without response; it can't ask for one".format(self) ) self._live("write") if len(data) > self.connection.mtu - 3: raise BLEError( "write of {} bytes exceeds the ATT payload of {} (mtu {} - 3)".format( len(data), self.connection.mtu - 3, self.connection.mtu ) ) start = _ticks_ms() limit = timeout_ms if timeout_ms is not None else _WRITE_RETRY_MS while True: try: with _Call("write"): self.native.value = data return except BusyError: self._live("write") if _elapsed(start) >= limit: raise BLETimeoutError("write: buffers stayed full for {} ms".format(limit)) await sleep_ms(2) except BLEError: self._live("write") raise async def subscribe(self, notify=True, indicate=False): if indicate: raise UnsupportedError("CircuitPython can't receive indications") if notify: self._check(FLAG_NOTIFY, "notify") self._live("subscribe") await sleep_ms(0) if notify and self._buffer is None: # Making the buffer writes the CCCD. with _Call("subscribe"): self._buffer = _bleio.PacketBuffer( self.native, buffer_size=self.connection._ble.queue_limit, max_packet_size=_MAX_PAYLOAD ) elif not notify and self._buffer is not None: self._buffer.deinit() self._buffer = None with _Call("unsubscribe"): self.native.set_cccd(notify=False, indicate=False) def _drain(self): buffer = self._buffer if buffer is None: return limit = self.connection._ble.queue_limit while True: try: n = buffer.readinto(self._packet) except Exception: return if n <= 0: return if len(self._queue) >= limit: self._overrun += 1 else: self._queue.append(bytes(self._packet[:n])) async def notified(self, timeout_ms=None): self._check(FLAG_NOTIFY, "notify") start = _ticks_ms() while True: self._drain() if self._overrun: raise BLEError( "notify {} queue overran: {} dropped because the reader fell behind".format( self.uuid, self._overrun ) ) if self._queue: return self._queue.pop(0) if not self.connection.is_connected(): raise DisconnectedError("notified: disconnected") if timeout_ms is not None and _elapsed(start) >= timeout_ms: raise BLETimeoutError("notified timed out after {} ms".format(timeout_ms)) await sleep_ms(POLL_MS) async def indicated(self, timeout_ms=None): raise UnsupportedError("CircuitPython can't receive indications") class _CPClientDescriptor(ClientDescriptor): def __init__(self, characteristic, native): ClientDescriptor.__init__(self, characteristic, _uuid(native.uuid)) self.native = native async def read(self, timeout_ms=1000): if not self.connection.is_connected(): raise DisconnectedError("read: not connected") await sleep_ms(0) with _Call("descriptor read"): return bytes(self.native.value) _retrying = [] _retry_task = None def _retry(impl): """Retry ``impl``'s last notification every `POLL_MS` for `RETRY_MS`, in case the radio couldn't take it yet.""" global _retry_task impl._sent_at = _ticks_ms() if impl not in _retrying: _retrying.append(impl) if _retry_task is None: _retry_task = asyncio.create_task(_retry_loop()) async def _retry_loop(): global _retry_task try: while _retrying: await sleep_ms(POLL_MS) for impl in list(_retrying): packets = impl._packets if packets is None or _elapsed(impl._sent_at) >= RETRY_MS: _retrying.remove(impl) continue try: packets.write(b"") except Exception: _retrying.remove(impl) finally: _retry_task = None class _CPServerCharacteristic: """cpble's half of a `bledev.Characteristic`.""" def __init__(self, ble, characteristic, native): self._ble = ble self._char = characteristic self.native = native self._packets = None # a PacketBuffer: notifications out, writes in self._stream = None # a CharacteristicBuffer: writes in, as bytes self._stream_size = 0 self._queue = [] self._overrun = 0 self._scratch = None self._value_sent = False # write() notified the subscribers already self._sent_at = 0 flags = characteristic.flags writable = flags & (FLAG_WRITE | FLAG_WRITE_NO_RESPONSE) if flags & (FLAG_NOTIFY | FLAG_INDICATE): self._renew() self._scratch = bytearray(_MAX_PAYLOAD) elif writable: self._stream_size = ble.stream_buffer if characteristic.capture else 1024 self._stream = _bleio.CharacteristicBuffer(native, timeout=0, buffer_size=self._stream_size) def _renew(self): """A fresh PacketBuffer, for each new connection. One that saw NimBLE refuse a notification is left pointing at a buffer it never allocated (see _MAX_MTU), so none is kept past its link.""" if self._packets is not None: try: self._packets.deinit() except Exception: pass writable = self._char.flags & (FLAG_WRITE | FLAG_WRITE_NO_RESPONSE) self._packets = _bleio.PacketBuffer( self.native, buffer_size=self._ble.queue_limit if writable else 1, max_packet_size=_MAX_PAYLOAD ) self._queue = [] self._overrun = 0 def _release(self): for buffer in (self._packets, self._stream): if buffer is not None: try: buffer.deinit() except Exception: pass self._packets = self._stream = None def read(self): value = bytes(self.native.value) if self._char.flags & (FLAG_WRITE | FLAG_WRITE_NO_RESPONSE): return value[: self._char.max_len] return value def write(self, data, send_update): # Setting the value notifies subscribers whatever send_update says, # so a notify() of this value that follows has nothing left to send. self.native.value = data self._value_sent = self._subscribed() def _subscribed(self): if self._packets is None: return False try: self._packets.outgoing_packet_length except ValueError: # _bleio raises this until the central subscribes ("No connection: # length cannot be determined"). return False return True def _check_size(self, connection, data): if len(data) > connection.mtu - 3: raise BLEError( "notification of {} bytes exceeds the ATT payload of {} (mtu {} - 3)".format( len(data), connection.mtu - 3, connection.mtu ) ) def _send(self, connection, data, what): if not connection.is_connected(): raise DisconnectedError("{}: disconnected".format(what)) if data is None: if self._value_sent: self._value_sent = False return # write() already sent it data = bytes(self.native.value) self._check_size(connection, data) # CircuitPython 10.3's PacketBuffer.write() keeps a packet it couldn't # hand to NimBLE (the buffer pool was dry) and retries it only on the # next "sent" event, which then never comes; the write after that # waits for it forever inside _bleio. Ten notifications back to back # were enough. So the packet goes in as the header of an empty write: # _bleio copies a header only into an empty packet, and an empty # write never waits, but it does retry what's left. 0 back means the # previous packet is still there: busy, and it was just retried. if not self._subscribed(): return # the central hasn't subscribed: as on every backend, it gets nothing with _Call(what): n = self._packets.write(b"", header=data) if n == 0 and data: if not connection.is_connected(): raise DisconnectedError("{}: disconnected".format(what)) raise BusyError("{}: the previous packet is still waiting for the radio".format(what)) if n > 0: # It may be the one left waiting; keep retrying it for a while. _retry(self) if n < 0 and not connection.is_connected(): raise DisconnectedError("{}: disconnected".format(what)) # n < 0 on a live link: the central hasn't subscribed, so, as on # every backend, it gets nothing. def notify(self, connection, data): self._send(connection, data, "notify") async def indicate(self, connection, data, timeout_ms): if not self._char.flags & FLAG_INDICATE: raise UnsupportedError("{!r} was not created with indicate=True".format(self._char)) self._send(connection, data, "indicate") await sleep_ms(0) def _drain(self): """Move what ``_bleio`` buffered into the queue. True if anything came.""" got = False limit = self._ble.queue_limit max_len = self._char.max_len if self._packets is not None: while True: try: n = self._packets.readinto(self._scratch) except Exception: break if n <= 0: break got = True if len(self._queue) >= limit: self._overrun += 1 else: self._queue.append(bytes(self._scratch[: min(n, max_len)])) elif self._stream is not None: waiting = self._stream.in_waiting if waiting: if waiting >= self._stream_size - 1: # A full ring drops what doesn't fit, silently. Say so. self._overrun += 1 data = self._stream.read(waiting) if data: got = True if len(self._queue) >= limit: self._overrun += 1 else: self._queue.append(bytes(data)) return got async def written(self, timeout_ms): start = _ticks_ms() while True: self._drain() if self._overrun: raise BLEError( "writes to {} overran: {} lost because the reader fell behind".format( self._char.uuid, self._overrun ) ) if self._queue: data = self._queue.pop(0) connection = self._ble._current() if self._char.capture: return connection, data self._queue = [] # Every buffer is polled on its own, so a task reading # another characteristic may not have seen writes that came # before this one. Move them into their queues now, and give # those tasks a poll to take them first, which keeps the # central's order across characteristics (the contract check # that counts 100 captured writes and then asks: 96 of 100, # once in three, before this). for service in self._ble._services: for c in service.characteristics: if c._impl is not None and c._impl is not self: c._impl._drain() await sleep_ms(POLL_MS * 2) return connection if timeout_ms is not None and _elapsed(start) >= timeout_ms: raise BLETimeoutError("written timed out after {} ms".format(timeout_ms)) await sleep_ms(POLL_MS)