# SPDX-FileCopyrightText: 2026 Brad Barnett
#
# SPDX-License-Identifier: MIT
"""MicroPython backend, over aioble. Both roles.
from bledev.mpble import MPBLE
ble = MPBLE() # or MPBLE(bluetooth.BLE()) from a board config
Needs aioble, which isn't frozen into our firmware: install it once with
``mip.install("aioble")`` (MicroPython's index), then ``bledev`` from the
OmniPython index.
aioble owns the one ``bluetooth.BLE()`` object and its IRQ handler. An
`MPBLE` also answers every ``bluetooth.BLE`` method (``active()``,
``gap_advertise()``, ``gatts_notify()`` and the rest go straight to the radio),
so code written for the raw object keeps working when a board config hands
out an `MPBLE` instead. ``irq(handler)`` is the one it changes: the
handler runs beside aioble's rather than replacing it.
Where aioble would lose data, this backend doesn't:
* aioble keeps one notification per client characteristic and replaces it
when the next arrives. Here each gets a queue of ``queue_limit`` entries,
and an overflow raises from ``notified()``.
* aioble's ``capture=True`` shares a ten-entry queue across every
characteristic and drops the oldest. Here captured writes are read straight
from the IRQ into a per-characteristic queue of ``queue_limit``.
* ``notify()`` and ``write()`` refuse a payload over ``mtu - 3`` instead of
letting NimBLE truncate it.
"""
import asyncio
import time
import bluetooth
import aioble
from aioble import core as _aioble_core
from aioble.device import DeviceConnection as _AioConnection
from . import (
ADDR_MODE_NRPA,
ADDR_MODE_PUBLIC,
ADDR_MODE_RANDOM,
ADDR_MODE_RPA,
BLE,
BLEError,
BLETimeoutError,
BusyError,
ClientCharacteristic,
ClientDescriptor,
ClientService,
Connection,
DEFAULT_MTU,
Device,
DisconnectedError,
FLAG_INDICATE,
FLAG_NOTIFY,
FLAG_READ,
GattError,
PairingError,
ScanResult,
Scanner,
UnsupportedError,
UUID,
decode_service_data,
pack_advertisement,
sleep_ms,
)
_IRQ_CENTRAL_CONNECT = 1
_IRQ_CENTRAL_DISCONNECT = 2
_IRQ_GATTS_WRITE = 3
_IRQ_PERIPHERAL_DISCONNECT = 8
_IRQ_MTU_EXCHANGED = 21
_PASSKEY_INPUT = 2 # gap_passkey's action for typing in the peer's passkey
_EINVAL = 22
# As central with a passkey to type: how long to wait for the stack to ask
# before asking anyway (see _MPConnection._type_passkey).
_ASK_WITHIN_MS = 1500
_FLAG_READ_ENCRYPTED = 0x0200
_FLAG_WRITE_ENCRYPTED = 0x1000
_FLAG_READ_AUTHENTICATED = 0x0400
_FLAG_WRITE_AUTHENTICATED = 0x2000
# errno values NimBLE uses when its buffers are full (ENOMEM, EAGAIN, EBUSY,
# ENOBUFS). A send that sees one of these waits and tries again.
_BUSY_ERRNOS = (12, 11, 16, 105)
_EALREADY = 120
# The largest ATT MTU MicroPython's NimBLE will negotiate.
_MAX_MTU = 512
# Default scan interval and window: listen all the time.
_SCAN_US = 30000
# How long a write without response keeps retrying a full buffer by default.
_WRITE_RETRY_MS = 2000
def _buuid(uuid):
"""bledev UUID -> bluetooth.UUID."""
uuid = UUID(uuid)
short = uuid.short
if short is not None and short <= 0xFFFF:
return bluetooth.UUID(short)
return bluetooth.UUID(str(uuid))
def _uuid(buuid):
"""bluetooth.UUID -> bledev UUID."""
return UUID(bytes(buuid))
def _errno(e):
return e.args[0] if e.args else None
_arrivals = 0 # notifications received by this radio so far, across every characteristic
class _Queue:
"""Stands in for aioble's one-slot deque: same three operations, but it
keeps ``limit`` entries and turns an overflow into an error.
It ignores everything until ``subscribe()`` opens it. NimBLE's server
notifies whether or not the central subscribed, and the contract (like
bleak and browsers) delivers nothing before a subscription.
``append()`` runs in the radio's IRQ, so it numbers each entry as it
arrives; ``popleft()`` leaves that number in `arrival`."""
def __init__(self, limit, what):
self._items = []
self._limit = limit
self._what = what
self.overrun = 0
self.accepting = False
self.arrival = None
def __len__(self):
return len(self._items)
def append(self, item):
global _arrivals
if not self.accepting:
return
if len(self._items) >= self._limit:
self.overrun += 1
else:
_arrivals += 1
self._items.append((_arrivals, item))
def popleft(self):
if self.overrun:
raise BLEError(
"{} queue overran: {} dropped because the reader fell {} behind".format(
self._what, self.overrun, self._limit
)
)
self.arrival, item = self._items.pop(0)
return item
class _Translate:
"""Maps aioble's exceptions onto 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
if exc_type is asyncio.TimeoutError or issubclass(exc_type, asyncio.TimeoutError):
raise BLETimeoutError("{} timed out".format(self._what))
if issubclass(exc_type, aioble.DeviceDisconnectedError):
raise DisconnectedError("{}: disconnected".format(self._what))
if issubclass(exc_type, aioble.GattError):
status = getattr(exc, "_status", 0) or 0
# NimBLE reports an ATT error as 0x100 + the ATT code.
if 0x100 <= status < 0x200:
status -= 0x100
raise GattError(status)
if exc_type is ValueError and exc.args and exc.args[0] == "Not connected":
raise DisconnectedError("{}: not connected".format(self._what))
return False
# Captured characteristics by value handle, for the IRQ handler. Module-level
# because there is one radio however many MPBLE objects wrap it.
_captures = {}
# MTUs exchanged before their connection existed, by connection handle.
_early_mtu = {}
_irq_registered = False
_shared = None
_user_irq = None
def _irq(event, data):
if _user_irq is not None:
result = _user_irq(event, data)
if result is not None:
return result
# Runs beside aioble's own handlers. A captured write is copied here, in
# the IRQ, before the next write can overwrite the value buffer, and tied
# to its connection while that connection still exists.
if event == _IRQ_GATTS_WRITE:
conn_handle, value_handle = data
impl = _captures.get(value_handle)
if impl is not None:
impl._captured(
_AioConnection._connected.get(conn_handle),
bytes(_aioble_core.ble.gatts_read(value_handle)),
)
elif event == _IRQ_MTU_EXCHANGED:
# When a central (Windows, for one) exchanges the MTU at once,
# MicroPython delivers the exchange *before* the connect event, and
# aioble, with no connection to give it to, drops it. The link then
# runs at the negotiated MTU while this side believes 23, so every
# notification carries 20 bytes. Keep it for the connect below.
conn_handle, mtu = data
if conn_handle not in _AioConnection._connected:
_early_mtu[conn_handle] = mtu
elif event == _IRQ_CENTRAL_CONNECT:
conn_handle = data[0]
mtu = _early_mtu.pop(conn_handle, None)
aconn = _AioConnection._connected.get(conn_handle)
if mtu and aconn is not None and not aconn.mtu:
aconn.mtu = mtu
elif event == _IRQ_PERIPHERAL_DISCONNECT:
_early_mtu.pop(data[0], None)
elif event == _IRQ_CENTRAL_DISCONNECT:
conn_handle = data[0]
if data[1] == 0xFF and conn_handle != 0xFFFF and conn_handle not in _AioConnection._connected:
# "Connection failed" for a handle that is in fact live. ESP-IDF's
# NimBLE holds back a peripheral's connect event until it has read
# the central's version and features, then posts it with the
# status of that read. Some centrals (an nRF52840 running
# CircuitPython, for one) answer the read with an error while
# the link carries on, and MicroPython reports any non-zero status
# as a failed connection, so aioble's advertise() never returned.
# A real failure follows a live link with a real disconnect.
_connected_late(conn_handle)
return None
_early_mtu.pop(conn_handle, None)
aconn = _AioConnection._connected.get(conn_handle)
if aconn is not None and aconn._task is None:
_forget(conn_handle, aconn)
return None
def _connected_late(conn_handle):
"""Announce a central's connection that MicroPython reported as failed."""
from aioble import peripheral
# The central's address isn't in the event; peripherals here don't need it.
peripheral._peripheral_irq(_IRQ_CENTRAL_CONNECT, (conn_handle, 0, bytes(6)))
_irq(_IRQ_CENTRAL_CONNECT, (conn_handle, 0, bytes(6)))
def _forget(conn_handle, aconn):
# A central connected to something advertised with the raw API
# (ble.gap_advertise), not aioble.advertise(). aioble recorded it anyway
# and left its advertise() signal set, and nothing of aioble's will clean
# up, so do it here.
from aioble import peripheral
_AioConnection._connected.pop(conn_handle, None)
aconn._conn_handle = None
aconn.device._connection = None
if peripheral._incoming_connection is aconn:
peripheral._incoming_connection = None
try:
peripheral._connect_event.clear()
except AttributeError:
pass
[docs]
def get(ble=None):
"""The shared `MPBLE` for this board's radio, made on first use."""
global _shared
if _shared is None:
_shared = MPBLE(ble)
return _shared
[docs]
class MPBLE(BLE):
"""The board's radio. ``ble`` may be a ``bluetooth.BLE()``; there is only one.
``queue_limit`` bounds each notification and capture queue. Prefer
`get`, which returns one shared adapter.
"""
backend = "mpble"
def __init__(self, ble=None, *, queue_limit=128, mtu=None):
global _irq_registered
if ble is not None and ble is not _aioble_core.ble:
raise BLEError("MicroPython has one bluetooth.BLE(); pass that one or nothing")
self.raw = _aioble_core.ble
self.queue_limit = queue_limit
self._connections = {}
self._services = ()
self._addr_mode = ADDR_MODE_PUBLIC
if not _irq_registered:
_aioble_core.register_irq_handler(_irq, None)
_irq_registered = True
# aioble's peripheral IRQ signals its advertise() on every incoming
# connection and raises when advertise() never ran, which happens
# when code uses the raw API (ble.gap_advertise). Give it a flag.
from aioble import peripheral
if peripheral._connect_event is None:
peripheral._connect_event = asyncio.ThreadSafeFlag()
if mtu:
self.config(mtu=mtu)
[docs]
def capabilities(self):
caps = BLE.capabilities(self)
caps.update(
central=True,
peripheral=True,
mtu=self._config_mtu(),
max_mtu=_MAX_MTU,
indicate=True,
pairing=True,
long_read=False,
)
return caps
[docs]
def enable_bonding(self, store=None):
"""Bond from now on, keeping the keys in ``store`` (see
`bledev.security.use_store`): NVS on an ESP32 by default, which
survives a filesystem erase, or a path for aioble's
``ble_secrets.json``.
Call it before any connection that may pair, on both sides: the side
that doesn't start pairing still has to store the keys. A peer that
still holds its half of a bond this board has lost will refuse to
reconnect encrypted until it's paired again.
"""
from . import security
security.use_store(store)
aioble.config(bond=True, le_secure=True, mitm=False, io=security.IO_NO_INPUT_OUTPUT)
def _config_mtu(self):
try:
return aioble.config("mtu")
except Exception:
return DEFAULT_MTU
[docs]
def config(self, *names, **settings):
if "addr_mode" in settings:
self._set_addr_mode(settings.pop("addr_mode"))
if settings:
aioble.config(**settings)
if names:
if len(names) != 1:
raise ValueError("read one setting at a time")
if names[0] == "addr_mode":
return self._addr_mode
return aioble.config(names[0])
return None
def _set_addr_mode(self, mode):
if mode not in (ADDR_MODE_PUBLIC, ADDR_MODE_RANDOM, ADDR_MODE_RPA, ADDR_MODE_NRPA):
raise ValueError("addr_mode is ADDR_MODE_PUBLIC, _RANDOM, _RPA or _NRPA")
try:
aioble.config(addr_mode=mode)
except OSError as e:
# NimBLE refuses PUBLIC on a chip with no public address; BTstack
# (the Pico W) has no RPA or NRPA.
if _errno(e) == 22: # EINVAL
raise UnsupportedError("this radio can't use address mode {}".format(mode))
raise
self._addr_mode = mode
[docs]
def close(self):
"""Turn the radio off. Its services go with it: register them again
after it's back on."""
aioble.stop()
self._connections = {}
self._services = ()
self._addr_mode = ADDR_MODE_PUBLIC # the stack starts over with its own default
try:
del self._midi_server # bledev.midi registers its service again on the next serve()
except AttributeError:
pass
# -- the raw bluetooth.BLE, for code written against it
def __getattr__(self, name):
# Only reached for names MPBLE doesn't define.
return getattr(_aioble_core.ble, name)
[docs]
def irq(self, handler):
"""Like ``bluetooth.BLE.irq``, but beside aioble's handler rather than instead of it.
A later call replaces the earlier handler; ``irq(None)`` removes it.
"""
global _user_irq
_user_irq = handler
# -- connections, one wrapper per aioble connection
def _wrap(self, aconn, role, device=None):
# Keep recent wrappers after a disconnect: captured writes that raced
# it still name their connection by this object.
if len(self._connections) > 8:
for key in list(self._connections):
if not key.is_connected():
del self._connections[key]
conn = self._connections.get(aconn)
if conn is None:
if device is None:
device = Device(self, aconn.device.addr, aconn.device.addr_type, native=aconn.device)
conn = _MPConnection(self, device, role, aconn)
self._connections[aconn] = conn
return conn
def _lookup(self, aconn):
if aconn is None:
return None
return self._connections.get(aconn) or self._wrap(aconn, "peripheral")
# -- peripheral
[docs]
def register_services(self, *services):
aservices = []
for service in self._services:
for characteristic in service.characteristics:
characteristic._impl = None
for service in services:
aservice = aioble.Service(_buuid(service.uuid))
for c in service.characteristics:
f = c.flags
achar = aioble.BufferedCharacteristic(
aservice,
_buuid(c.uuid),
read=bool(f & FLAG_READ),
write=bool(f & 0x0008),
write_no_response=bool(f & 0x0004),
notify=bool(f & FLAG_NOTIFY),
indicate=bool(f & FLAG_INDICATE),
initial=c._initial,
max_len=c.max_len,
)
if c.encrypted:
achar.flags |= _FLAG_READ_ENCRYPTED | _FLAG_WRITE_ENCRYPTED
if c.authenticated:
achar.flags |= _FLAG_READ_AUTHENTICATED | _FLAG_WRITE_AUTHENTICATED
for d in c.descriptors:
aioble.Descriptor(achar, _buuid(d.uuid), read=True, initial=d.value)
c._impl = _MPServerCharacteristic(self, c, achar)
aservices.append(aservice)
aioble.register_services(*aservices)
# aioble writes the initial value and then sizes the buffer, which
# empties it again; write it once more now the buffer is final.
for service in services:
for c in service.characteristics:
if c._initial is not None:
c._impl._achar.write(c._initial)
self._services = tuple(services)
_captures.clear()
for service in services:
for c in service.characteristics:
if c.capture:
_captures[c._impl._achar._value_handle] = c._impl
[docs]
async def advertise(
self,
interval_us=100000,
*,
name=None,
services=None,
appearance=0,
manufacturer=None,
connectable=True,
timeout_ms=None,
service_data=None,
):
# Packed here rather than by aioble, so the fake and the board send
# the same bytes, and so service data (which aioble can't pack) fits.
adv_data, resp_data = pack_advertisement(name, services, appearance, manufacturer, service_data)
with _Translate("advertise"):
aconn = await aioble.advertise(
interval_us,
adv_data=adv_data,
resp_data=resp_data or None,
connectable=connectable,
timeout_ms=timeout_ms,
)
if aconn is None:
# aioble swallows the cancellation; pass it on.
raise asyncio.CancelledError()
return self._wrap(aconn, "peripheral")
# -- central
[docs]
def scan(self, duration_ms, *, active=False, interval_us=None, window_us=None):
# aioble's defaults (1.28 s interval, 11.25 ms window) listen less
# than 1 % of the time, and on the bench found one advertiser in six
# seconds where a full-duty scan found the board 40 times. Scans here
# are short and foreground, so listen continuously unless told not to.
if interval_us is None:
interval_us = _SCAN_US
if window_us is None:
window_us = interval_us
return _MPScanner(self, duration_ms, active, interval_us, window_us)
async def _connect(self, device, timeout_ms, **options):
adevice = device.native
if adevice is None:
adevice = aioble.Device(device.addr_type, device.addr or device.address)
with _Translate("connect"):
aconn = await adevice.connect(
timeout_ms=timeout_ms,
min_conn_interval_us=options.get("min_conn_interval_us"),
max_conn_interval_us=options.get("max_conn_interval_us"),
)
return self._wrap(aconn, "central", device)
class _MPScanner(Scanner):
async def __aenter__(self):
self._scan = aioble.scan(
self.duration_ms,
interval_us=self.interval_us,
window_us=self.window_us,
active=self.active,
)
await self._scan.__aenter__()
return self
async def __aexit__(self, exc_type, exc, tb):
await self._scan.__aexit__(exc_type, exc, tb)
async def cancel(self):
await self._scan.cancel()
def __aiter__(self):
return self
async def __anext__(self):
r = await self._scan.__anext__()
name = r.name()
adevice = r.device
device = Device(self._ble, adevice.addr, adevice.addr_type, name=name, native=adevice)
return ScanResult(
device,
rssi=r.rssi,
name=name,
services=[_uuid(u) for u in r.services()],
manufacturer=list(r.manufacturer()),
connectable=r.connectable,
service_data=decode_service_data(r.adv_data, r.resp_data),
)
class _MPConnection(Connection):
def __init__(self, ble, device, role, aconn):
Connection.__init__(self, ble, device, role)
self._aconn = aconn
@property
def mtu(self):
a = self._aconn
if not a.mtu and a._conn_handle is not None:
# The same race as a central's early exchange, with this board as
# the central: a peripheral that exchanges at once (Windows,
# through bless) is heard before aioble records the connection.
early = _early_mtu.pop(a._conn_handle, None)
if early:
a.mtu = early
return a.mtu or DEFAULT_MTU
def is_connected(self):
return self._aconn.is_connected()
async def disconnect(self, timeout_ms=2000):
with _Translate("disconnect"):
await self._aconn.disconnect(timeout_ms)
async def disconnected(self, timeout_ms=None):
with _Translate("disconnected"):
await self._aconn.disconnected(timeout_ms)
async def exchange_mtu(self, mtu=None, timeout_ms=1000):
try:
with _Translate("exchange_mtu"):
return await self._aconn.exchange_mtu(mtu, timeout_ms)
except OSError as e:
# NimBLE exchanges the MTU once per link. When the peer already
# did (Windows as a peripheral through bless does, at once), a
# second exchange is EALREADY: the MTU is settled, so return it.
if _errno(e) != _EALREADY:
raise
return self.mtu
@property
def encrypted(self):
return bool(self._aconn.encrypted)
@property
def authenticated(self):
from . import security
return security.state(self._aconn._conn_handle)[1] if self.is_connected() else False
async def pair(self, bond=True, timeout_ms=30000, passkey=None):
from . import security
if not self.is_connected():
raise DisconnectedError("pair: not connected")
if bond and security.store() is None:
security.use_store()
security._install()
handle = self._aconn._conn_handle
if passkey is not None:
# Type in what the peer shows: a keyboard, with MITM protection.
security.expect_passkey(handle, passkey if not callable(passkey) else _SyncPasskey(passkey))
io, mitm = security.IO_KEYBOARD_ONLY, True
else:
io, mitm = security.IO_NO_INPUT_OUTPUT, False
aioble.config(bond=bond, le_secure=True, mitm=mitm, io=io)
updates = []
def on_change(conn, encrypted, authenticated, bonded, key_size):
if conn == handle:
updates.append(encrypted)
security.on_change(on_change)
try:
with _Translate("pair"):
_aioble_core.ble.gap_pair(handle)
started = time.ticks_ms()
deadline = time.ticks_add(started, timeout_ms)
typed = passkey is None
# The stack reports the outcome as an encryption update, success
# or not, so a wrong passkey fails here at once, not at a timeout.
while not updates:
if not self.is_connected():
raise PairingError("pair: the peer hung up")
if time.ticks_diff(deadline, time.ticks_ms()) <= 0:
raise BLETimeoutError("pair: timed out")
if not typed and handle not in security._asked and time.ticks_diff(time.ticks_ms(), started) > _ASK_WITHIN_MS:
typed = True
await self._type_passkey(handle, deadline, updates)
await sleep_ms(20)
finally:
security.remove_listener(on_change)
security.expect_passkey(handle, None)
security._asked.discard(handle)
if not security.state(handle)[0]:
raise PairingError("pair: refused (wrong passkey, or the peer lost its keys)")
async def _type_passkey(self, handle, deadline, updates):
# MicroPython's NimBLE bindings raise _IRQ_PASSKEY_ACTION only on
# connections the board accepted, never on one it made
# (peripheral_gap_event_cb in extmod/nimble/modbluetooth_nimble.c
# doesn't handle it; micropython/micropython#19470 moves it), so a
# board as central is never asked for the passkey and pairing stalls
# until the stack's 30 s timeout. When the stack hasn't asked by now,
# ask for the passkey here and hand it to the stack ourselves: NimBLE
# takes it once its pairing reaches the confirm step and answers
# EINVAL before that, so keep offering it until it's taken.
from . import security
given = security._inputs.get(handle)
if callable(given):
given = given()
given = int(given)
# If the stack does ask after all, it answers from this, not by asking twice.
security._inputs[handle] = given
while not updates and handle not in security._asked and self.is_connected():
try:
_aioble_core.ble.gap_passkey(handle, _PASSKEY_INPUT, given)
return
except OSError as e:
if e.errno != _EINVAL or time.ticks_diff(deadline, time.ticks_ms()) <= 0:
return # taken already (EALREADY), or the pairing is over
await sleep_ms(50)
async def unpair(self):
from . import security
addr = self.device.address
security.forget(addr)
async def _discover_services(self, uuid, timeout_ms):
found = []
with _Translate("service discovery"):
async for aservice in self._aconn.services(None if uuid is None else _buuid(uuid), timeout_ms):
found.append(_MPClientService(self, aservice))
# aioble yields results in whatever order its IRQs and its task
# interleave; the contract promises the server's order.
found.sort(key=lambda s: s._aservice._start_handle)
return found
class _MPClientService(ClientService):
def __init__(self, connection, aservice):
ClientService.__init__(self, connection, _uuid(aservice.uuid))
self._aservice = aservice
async def _discover_characteristics(self, uuid, timeout_ms):
found = []
with _Translate("characteristic discovery"):
async for achar in self._aservice.characteristics(None if uuid is None else _buuid(uuid), timeout_ms):
found.append(_MPClientCharacteristic(self, achar))
found.sort(key=lambda c: c._achar._value_handle)
return found
class _MPClientCharacteristic(ClientCharacteristic):
def __init__(self, service, achar):
ClientCharacteristic.__init__(self, service, _uuid(achar.uuid), achar.properties)
self._achar = achar
limit = service.connection._ble.queue_limit
if achar.properties & FLAG_NOTIFY:
achar._notify_queue = _Queue(limit, "notify {}".format(self.uuid))
if achar.properties & FLAG_INDICATE:
achar._indicate_queue = _Queue(limit, "indicate {}".format(self.uuid))
# Register now, so notifications that arrive before the first
# notified() are queued rather than ignored.
achar._register_with_connection()
def _live(self, what):
# aioble hands a dead connection's None handle to the radio, which
# raises TypeError; say what actually happened.
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")
with _Translate("read"):
return bytes(await self._achar.read(timeout_ms))
async def _discover_descriptors(self, uuid, timeout_ms):
self._live("descriptor discovery")
found = []
with _Translate("descriptor discovery"):
async for adesc in self._achar.descriptors(timeout_ms):
d = _MPClientDescriptor(self, adesc)
if uuid is None or d.uuid == uuid:
found.append(d)
found.sort(key=lambda d: d._adesc._value_handle)
return found
async def write(self, data, response=None, timeout_ms=1000):
data = bytes(data)
response = self._want_response(response)
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
)
)
waited = 0
limit = timeout_ms if timeout_ms is not None else _WRITE_RETRY_MS
while True:
try:
with _Translate("write"):
await self._achar.write(data, response, timeout_ms)
return
except OSError as e:
if _errno(e) not in _BUSY_ERRNOS:
if not self.connection.is_connected():
raise DisconnectedError("write: disconnected")
raise
if not self.connection.is_connected():
raise DisconnectedError("write: disconnected")
if waited >= limit:
raise BLETimeoutError("write: buffers stayed full for {} ms".format(waited))
await sleep_ms(2)
waited += 2
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")
a = self._achar
for queue, on in ((getattr(a, "_notify_queue", None), notify), (getattr(a, "_indicate_queue", None), indicate)):
if isinstance(queue, _Queue):
queue.accepting = bool(on)
with _Translate("subscribe"):
try:
await self._achar.subscribe(notify, indicate)
except ValueError as e:
raise UnsupportedError(str(e))
async def _next(self, queue, event, timeout_ms, what):
# Not aioble's notified(): it waits only when the queue holds <= 1
# item and assumes the flag is then set, which holds for its one-slot
# queue but strands the last item of a longer one. Wait only when the
# queue is empty; the IRQ sets the flag on every empty -> non-empty.
aconn = self._achar._connection()
while True:
if len(queue):
data = bytes(queue.popleft())
self.arrival = queue.arrival
return data
if not aconn.is_connected():
raise DisconnectedError("{}: disconnected".format(what))
with _Translate(what):
with aconn.timeout(timeout_ms):
await event.wait()
async def notified(self, timeout_ms=None):
self._check(FLAG_NOTIFY, "notify")
a = self._achar
return await self._next(a._notify_queue, a._notify_event, timeout_ms, "notified")
async def indicated(self, timeout_ms=None):
self._check(FLAG_INDICATE, "indicate")
a = self._achar
return await self._next(a._indicate_queue, a._indicate_event, timeout_ms, "indicated")
class _SyncPasskey:
# The passkey is asked for from a scheduled callback, which can't await:
# an async provider isn't supported on a board, a plain callable is.
def __init__(self, fn):
self._fn = fn
def __call__(self):
value = self._fn()
if hasattr(value, "send"):
raise BLEError("a board's passkey provider must be a plain function")
return value
class _MPClientDescriptor(ClientDescriptor):
def __init__(self, characteristic, adesc):
ClientDescriptor.__init__(self, characteristic, _uuid(adesc.uuid))
self._adesc = adesc
async def read(self, timeout_ms=1000):
if not self.connection.is_connected():
raise DisconnectedError("read: not connected")
with _Translate("descriptor read"):
return bytes(await self._adesc.read(timeout_ms))
class _MPServerCharacteristic:
"""mpble's half of a `bledev.Characteristic`."""
def __init__(self, ble, characteristic, achar):
self._ble = ble
self._char = characteristic
self._achar = achar
if characteristic.capture:
self._queue = []
self._overrun = 0
self._flag = asyncio.ThreadSafeFlag()
def read(self):
return bytes(self._achar.read())
def write(self, data, send_update):
try:
self._achar.write(data, send_update)
except OSError:
if not send_update:
raise
# A central that disconnects while an update is on its way can
# leave NimBLE refusing to notify it (EINVAL). The value is
# still this characteristic's value, and the subscriber is gone,
# so set it without sending.
self._achar.write(data, False)
def _aconn(self, connection):
aconn = getattr(connection, "_aconn", None)
if aconn is None:
raise BLEError("{!r} is not an mpble connection".format(connection))
if not aconn.is_connected():
raise DisconnectedError("the connection is closed")
return aconn
def _check_size(self, connection, data):
if data is not None and 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 notify(self, connection, data):
aconn = self._aconn(connection)
self._check_size(connection, data)
try:
self._achar.notify(aconn, data)
except OSError as e:
if _errno(e) in _BUSY_ERRNOS:
raise BusyError("notify: transmit buffers full")
if not aconn.is_connected():
raise DisconnectedError("notify: disconnected")
raise
async def indicate(self, connection, data, timeout_ms):
aconn = self._aconn(connection)
self._check_size(connection, data)
with _Translate("indicate"):
await self._achar.indicate(aconn, data, timeout_ms)
def _captured(self, aconn, data):
if len(self._queue) >= self._ble.queue_limit:
self._overrun += 1
else:
self._queue.append((aconn, data))
self._flag.set()
async def written(self, timeout_ms):
if not self._char.capture:
with _Translate("written"):
aconn = await self._achar.written(timeout_ms)
return self._ble._lookup(aconn)
while True:
if self._overrun:
raise BLEError(
"writes to {} overran: {} dropped because the reader fell {} behind".format(
self._char.uuid, self._overrun, self._ble.queue_limit
)
)
if self._queue:
aconn, data = self._queue.pop(0)
return self._ble._lookup(aconn), data
if timeout_ms is not None and timeout_ms <= 0:
raise BLETimeoutError("written timed out")
try:
if timeout_ms is None:
await self._flag.wait()
else:
await asyncio.wait_for_ms(self._flag.wait(), timeout_ms)
except asyncio.TimeoutError:
if not self._queue:
raise BLETimeoutError("written timed out after {} ms".format(timeout_ms))