Source code for bledev.fake

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

"""In-process loopback backend: two adapters, one pretend radio, no hardware.

Every `FakeBLE` built on the same `Air` can see and connect to
the others, so a test runs a peripheral and a central in one event loop::

    from bledev.fake import Air, FakeBLE

    air = Air()
    board = FakeBLE(air=air)                    # either role, like a board
    laptop = FakeBLE(air=air, peripheral=False)  # central only, like bleak

It runs on CPython and MicroPython, and it is stricter than a real radio on
purpose. Where real hardware would quietly truncate or drop data, the fake
raises, so a bug shows up in a test rather than as corruption on a board:

* A notification or write longer than ``mtu - 3`` raises `BLEError`
  (NimBLE truncates it).
* A write longer than the characteristic's ``max_len`` raises (MicroPython
  truncates to the buffer, 20 bytes by default).
* Notifications reach a client only after it calls ``subscribe()``.
* Only ``notify_buffers`` notifications can be in flight per connection;
  one more raises `BusyError` until the event loop runs, the way a real
  controller runs out of buffers. Send loops must await between bursts.
* A receive queue that fills up (``queue_limit``) makes the next
  ``notified()`` or ``written()`` raise instead of dropping data silently.
* The name only reaches a *passive* scan when it fits in the 31-byte
  advertisement; otherwise it is in the scan response, as on real hardware.
* An ``encrypted`` characteristic refuses an unpaired central with
  ``GattError(INSUFFICIENT_ENCRYPTION)``. ``pair()`` encrypts the link, and
  with ``bond`` both adapters remember each other (``bonds``) until
  ``forget()``.
* ``long_reads=False`` makes a central read at most ``mtu - 1`` bytes, as
  MicroPython does (it has no long read).
"""

import asyncio

from . import (
    ADDR_MODE_NRPA,
    ADDR_MODE_PUBLIC,
    ADDR_MODE_RANDOM,
    ADDR_MODE_RPA,
    ADDR_PUBLIC,
    ADDR_RANDOM,
    BLE,
    BLEError,
    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,
    MAX_MTU,
    UUID,
    ScanResult,
    Scanner,
    UnsupportedError,
    decode_advertisement,
    decode_service_data,
    pack_advertisement,
    sleep_ms,
    passkey_value,
    wait_ms,
)

#: How often a fake scan looks at the air, in milliseconds.
SCAN_TICK_MS = 5


[docs] class Air: """The medium the fake adapters share. Make one per test.""" def __init__(self): self.adverts = [] self._next = 1 def _allocate(self): n = self._next self._next += 1 return "fa:ce:00:00:{:02x}:{:02x}".format((n >> 8) & 0xFF, n & 0xFF)
_default_air = Air()
[docs] def default_air(): """The `Air` used when an adapter isn't given one.""" return _default_air
class _Advert: def __init__(self, ble, adv_data, resp_data, connectable, address, addr_type): self.ble = ble # What a scanner sees: the adapter's own address, or a fresh private # one for each advertise() while the adapter is in RPA or NRPA mode. self.address = address self.addr_type = addr_type self.adv_data = adv_data self.resp_data = resp_data self.connectable = connectable self.event = asyncio.Event() self.connection = None self.closed = False class _Inbox: """An ordered queue that refuses to lose data quietly.""" def __init__(self, limit, what): self.items = [] self.stamps = [] self.arrival = None self.event = asyncio.Event() self.limit = limit self.what = what self.overrun = 0 self.closed = False def put(self, item, stamp=None): if len(self.items) >= self.limit: self.overrun += 1 else: self.items.append(item) self.stamps.append(stamp) self.event.set() def close(self): self.closed = True self.event.set() async def get(self, timeout_ms): while True: if self.overrun: raise BLEError( "{} queue overran: {} item(s) dropped because the reader fell " "{} behind".format(self.what, self.overrun, self.limit) ) if self.items: self.arrival = self.stamps.pop(0) return self.items.pop(0) if self.closed: raise DisconnectedError("{}: disconnected".format(self.what)) self.event.clear() await wait_ms(self.event.wait(), timeout_ms, self.what)
[docs] class FakeBLE(BLE): """A pretend radio. ``central`` and ``peripheral`` pick the roles it may take. ``mtu`` is the ATT MTU it asks for in ``exchange_mtu()``. ``notify_buffers`` and ``queue_limit`` size the flow control described in the module docstring. """ backend = "fake" def __init__( self, *, air=None, central=True, peripheral=True, mtu=DEFAULT_MTU, address=None, rssi=-50, notify_buffers=8, queue_limit=128, gap_name="fake", long_reads=True, ): self._air = air if air is not None else _default_air self._central = central self._peripheral = peripheral self._mtu = mtu self.address = address or self._air._allocate() self.rssi = rssi self.notify_buffers = notify_buffers self.queue_limit = queue_limit self._gap_name = gap_name self._addr_mode = ADDR_MODE_PUBLIC self._long_reads = long_reads #: Addresses of the peers this adapter has bonded with. self.bonds = set() # address -> whether that bond came from a passkey self._bond_authenticated = {} #: As a peripheral: "justworks", or "passkey" to show one (``set_pairing``). self.pairing = "justworks" self.show_passkey = None self._services = () self._adverts = [] self._links = []
[docs] def capabilities(self): caps = BLE.capabilities(self) caps.update( central=self._central, peripheral=self._peripheral, mtu=self._mtu, max_mtu=MAX_MTU, indicate=True, pairing=True, long_read=self._long_reads, ) return caps
[docs] def forget(self, address=None): """Drop the bond with ``address``, or every bond (a board's filesystem erased).""" if address is None: self.bonds.clear() else: self.bonds.discard(address)
[docs] def set_pairing(self, mode="justworks", show=None): """As a peripheral, pair "just works", or show a passkey: ``show(passkey)`` gets the six digits a central must give ``pair(passkey=...)``.""" if mode not in ("justworks", "passkey"): raise ValueError("the fake pairs 'justworks' or 'passkey'") self.pairing = mode self.show_passkey = show
[docs] def config(self, *names, **settings): for key, value in settings.items(): if key == "mtu": if not 23 <= value <= MAX_MTU: raise ValueError("mtu must be 23..{}".format(MAX_MTU)) self._mtu = value elif key == "gap_name": self._gap_name = value elif key == "addr_mode": if value 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") self._addr_mode = value else: raise UnsupportedError("fake has no setting {!r}".format(key)) if names: if len(names) != 1: raise ValueError("read one setting at a time") if names[0] == "mtu": return self._mtu if names[0] == "gap_name": return self._gap_name if names[0] == "addr_mode": return self._addr_mode raise UnsupportedError("fake has no setting {!r}".format(names[0])) return None
[docs] def close(self): for advert in list(self._adverts): advert.closed = True advert.event.set() for link in list(self._links): link.drop()
# -- peripheral
[docs] def register_services(self, *services): if not self._peripheral: raise UnsupportedError("this fake adapter is central only") for service in self._services: for characteristic in service.characteristics: characteristic._impl = None self._services = tuple(services) for service in services: for characteristic in service.characteristics: characteristic._impl = _ServerCharacteristic(self, characteristic)
[docs] async def advertise( self, interval_us=100000, *, name=None, services=None, appearance=0, manufacturer=None, connectable=True, timeout_ms=None, service_data=None, ): if not self._peripheral: raise UnsupportedError("this fake adapter is central only; it cannot advertise") adv_data, resp_data = pack_advertisement(name, services, appearance, manufacturer, service_data) if self._addr_mode in (ADDR_MODE_RPA, ADDR_MODE_NRPA): advert = _Advert(self, adv_data, resp_data, connectable, self._air._allocate(), ADDR_RANDOM) else: advert = _Advert(self, adv_data, resp_data, connectable, self.address, ADDR_PUBLIC) self._air.adverts.append(advert) self._adverts.append(advert) try: await wait_ms(advert.event.wait(), timeout_ms, "advertise") finally: if advert in self._air.adverts: self._air.adverts.remove(advert) self._adverts.remove(advert) if advert.closed: raise BLEError("adapter closed while advertising") return advert.connection
# -- central
[docs] def scan(self, duration_ms, *, active=False, interval_us=None, window_us=None): if not self._central: raise UnsupportedError("this fake adapter is peripheral only; it cannot scan") return _FakeScanner(self, duration_ms, active, interval_us, window_us)
async def _connect(self, device, timeout_ms, **options): if not self._central: raise UnsupportedError("this fake adapter is peripheral only; it cannot connect") async def attempt(): while True: for advert in self._air.adverts: if advert.address == device.address and advert.connectable: return advert await sleep_ms(SCAN_TICK_MS) advert = await wait_ms(attempt(), timeout_ms, "connect to {}".format(device.address)) link = _Link(self, advert.ble, device) advert.connection = link.peripheral self._air.adverts.remove(advert) advert.event.set() return link.central
class _FakeScanner(Scanner): async def _start(self): self._task = asyncio.create_task(self._run()) async def _stop(self): task = getattr(self, "_task", None) if task is not None: task.cancel() self._task = None async def _run(self): seen = {} elapsed = 0 try: while elapsed < self.duration_ms: for advert in list(self._ble._air.adverts): if advert.ble is self._ble: continue payloads = (advert.adv_data, advert.resp_data) if self.active else (advert.adv_data,) key = advert.address if seen.get(key) == payloads: continue seen[key] = payloads name, services, appearance, manufacturer = decode_advertisement(*payloads) device = Device(self._ble, advert.address, addr_type=advert.addr_type, name=name) self._push( ScanResult( device, rssi=advert.ble.rssi, name=name, services=services, appearance=appearance, manufacturer=manufacturer, connectable=advert.connectable, service_data=decode_service_data(*payloads), ) ) await sleep_ms(SCAN_TICK_MS) elapsed += SCAN_TICK_MS finally: self._task = None self._finish() class _Link: """Both ends of one fake connection, and what travels between them.""" def __init__(self, central_ble, peripheral_ble, device): self.connected = True self.central_ble = central_ble self.peripheral_ble = peripheral_ble self.dropped = asyncio.Event() self.central = _FakeConnection(central_ble, device, "central", self) self.peripheral = _FakeConnection( peripheral_ble, Device(peripheral_ble, central_ble.address), "peripheral", self ) # Keyed by (server characteristic, "notify" | "indicate"). self.inboxes = {} self.subscribed = {} self.in_flight = [] self._drain_task = None self._arrivals = 0 #: A test knob: land each characteristic's notifications in the #: reverse of the order the characteristics first sent, so a host that #: waits on several wakes them out of order, as a real radio's can. self.wake_reversed = False self.encrypted = False self.authenticated = False central_ble._links.append(self) peripheral_ble._links.append(self) def set_mtu(self, mtu): self.central._mtu = mtu self.peripheral._mtu = mtu def check(self): if not self.connected: raise DisconnectedError("the connection is closed") def inbox(self, server_char, kind, limit): key = (id(server_char), kind) box = self.inboxes.get(key) if box is None: box = _Inbox(limit, "{} {}".format(kind, server_char.uuid)) if not self.connected: box.close() self.inboxes[key] = box return box def deliver(self, server_char, kind, data, busy_check): self.check() if busy_check and len(self.in_flight) >= self.peripheral_ble.notify_buffers: raise BusyError("{} notifications already in flight".format(len(self.in_flight))) self._arrivals += 1 self.in_flight.append((server_char, kind, data, self._arrivals)) if self._drain_task is None: # Held so CPython can't collect the task mid-flight. self._drain_task = asyncio.create_task(self._drain()) async def _drain(self): # One event-loop turn of "air time", then everything buffered arrives. await asyncio.sleep(0) self._drain_task = None pending, self.in_flight = self.in_flight, [] if not self.connected: return if self.wake_reversed: groups = [] for entry in pending: for group in groups: if group[0][0] is entry[0] and group[0][1] == entry[1]: group.append(entry) break else: groups.append([entry]) pending = [entry for group in reversed(groups) for entry in group] for server_char, kind, data, stamp in pending: notify, indicate = self.subscribed.get(id(server_char), (False, False)) if (kind == "notify" and notify) or (kind == "indicate" and indicate): self.inbox(server_char, kind, self.central_ble.queue_limit).put(data, stamp) def drop(self): if not self.connected: return self.connected = False for box in self.inboxes.values(): box.close() for ble in (self.central_ble, self.peripheral_ble): if self in ble._links: ble._links.remove(self) self.dropped.set() class _FakeConnection(Connection): def __init__(self, ble, device, role, link): Connection.__init__(self, ble, device, role) self._link = link def is_connected(self): return self._link.connected async def disconnect(self, timeout_ms=2000): self._link.drop() await asyncio.sleep(0) async def disconnected(self, timeout_ms=None): if self._link.connected: await wait_ms(self._link.dropped.wait(), timeout_ms, "disconnected") @property def encrypted(self): return self._link.encrypted @property def authenticated(self): return self._link.authenticated async def pair(self, bond=True, timeout_ms=30000, passkey=None): link = self._link link.check() await asyncio.sleep(0) link.check() central, peripheral = link.central_ble, link.peripheral_ble if peripheral.address in central.bonds: # Encrypt with the stored keys. If the peripheral has lost its # half, that fails without a word, as it does on real hosts: the # link stays unencrypted and protected reads are refused. if central.address in peripheral.bonds: link.encrypted = True link.authenticated = central._bond_authenticated.get(peripheral.address, False) return authenticated = False if peripheral.pairing == "passkey" and passkey is not None: import os b = os.urandom(3) shown = ((b[0] << 16) | (b[1] << 8) | b[2]) % 1000000 if peripheral.show_passkey is not None: peripheral.show_passkey(shown) given = await passkey_value(passkey) link.check() if given != shown: raise PairingError("pair: wrong passkey") authenticated = True link.encrypted = True link.authenticated = authenticated if bond: central.bonds.add(peripheral.address) peripheral.bonds.add(central.address) central._bond_authenticated[peripheral.address] = authenticated peripheral._bond_authenticated[central.address] = authenticated async def unpair(self): link = self._link own = link.central_ble if self.role == "central" else link.peripheral_ble own.forget(self.device.address) async def exchange_mtu(self, mtu=None, timeout_ms=1000): self._link.check() if mtu: self._ble.config(mtu=mtu) link = self._link agreed = max(DEFAULT_MTU, min(link.central_ble._mtu, link.peripheral_ble._mtu)) await asyncio.sleep(0) link.set_mtu(agreed) return agreed def _peer(self): link = self._link return link.peripheral_ble if self.role == "central" else link.central_ble async def _discover_services(self, uuid, timeout_ms): self._link.check() await asyncio.sleep(0) return [ _FakeClientService(self, service) for service in self._peer()._services if uuid is None or service.uuid == uuid ] class _FakeClientService(ClientService): def __init__(self, connection, server_service): ClientService.__init__(self, connection, server_service.uuid) self._server = server_service async def _discover_characteristics(self, uuid, timeout_ms): self.connection._link.check() await asyncio.sleep(0) return [ _FakeClientCharacteristic(self, characteristic) for characteristic in self._server.characteristics if uuid is None or characteristic.uuid == uuid ] class _FakeClientCharacteristic(ClientCharacteristic): def __init__(self, service, server_char): ClientCharacteristic.__init__(self, service, server_char.uuid, server_char.flags) self._server = server_char def _link(self): link = self.connection._link link.check() if self._server.encrypted and not link.encrypted: raise GattError(INSUFFICIENT_ENCRYPTION, "{} needs an encrypted link; pair() first".format(self.uuid)) if self._server.authenticated and not link.authenticated: raise GattError(INSUFFICIENT_AUTHENTICATION, "{} needs a link paired with a passkey".format(self.uuid)) return link async def read(self, timeout_ms=1000): self._check(FLAG_READ, "read") self._link() await asyncio.sleep(0) link = self._link() value = self._server.read() if not link.central_ble._long_reads: value = value[: self.connection.mtu - 1] return value async def _discover_descriptors(self, uuid, timeout_ms): self.connection._link.check() await asyncio.sleep(0) found = [] if self._server.flags & (FLAG_NOTIFY | FLAG_INDICATE): found.append(_FakeClientDescriptor(self, UUID(0x2902), None)) for d in self._server.descriptors: found.append(_FakeClientDescriptor(self, d.uuid, d)) 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) link = self._link() 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 ) ) server = self._server if len(data) > server.max_len: raise BLEError( "write of {} bytes exceeds {!r} max_len={}; real firmware would " "truncate it".format(len(data), server, server.max_len) ) server._impl._remote_write(link.peripheral, data) await asyncio.sleep(0) async def subscribe(self, notify=True, indicate=False): if notify: self._check(FLAG_NOTIFY, "notify") if indicate: self._check(FLAG_INDICATE, "indicate") link = self._link() link.subscribed[id(self._server)] = (bool(notify), bool(indicate)) await asyncio.sleep(0) async def notified(self, timeout_ms=None): self._check(FLAG_NOTIFY, "notify") link = self.connection._link box = link.inbox(self._server, "notify", link.central_ble.queue_limit) data = await box.get(timeout_ms) self.arrival = box.arrival return data async def indicated(self, timeout_ms=None): self._check(FLAG_INDICATE, "indicate") link = self.connection._link return await link.inbox(self._server, "indicate", link.central_ble.queue_limit).get(timeout_ms) class _FakeClientDescriptor(ClientDescriptor): def __init__(self, characteristic, uuid, server): ClientDescriptor.__init__(self, characteristic, uuid) self._server = server async def read(self, timeout_ms=1000): link = self.connection._link link.check() await asyncio.sleep(0) link.check() if self._server is None: # the CCCD notify, indicate = link.subscribed.get(id(self.characteristic._server), (False, False)) return bytes((notify | (indicate << 1), 0)) return self._server.value class _ServerCharacteristic: """The fake's half of a `bledev.Characteristic`.""" def __init__(self, ble, characteristic): self._ble = ble self._char = characteristic self._value = characteristic._initial or b"" self._writes = _Inbox(ble.queue_limit, "writes to {}".format(characteristic.uuid)) self._last_writer = None self._written = asyncio.Event() def read(self): return self._value def write(self, data, send_update): self._value = data if send_update: for link in list(self._ble._links): if link.peripheral_ble is not self._ble or not link.connected: continue if self._char.flags & FLAG_NOTIFY: link.deliver(self._char, "notify", data, False) if self._char.flags & FLAG_INDICATE: link.deliver(self._char, "indicate", data, False) def _link_for(self, connection): link = getattr(connection, "_link", None) if link is None or link.peripheral is not connection: raise BLEError("{!r} is not a peripheral-side connection of this adapter".format(connection)) return link 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 notify(self, connection, data): link = self._link_for(connection) data = self._value if data is None else data self._check_size(connection, data) link.deliver(self._char, "notify", data, True) async def indicate(self, connection, data, timeout_ms): link = self._link_for(connection) data = self._value if data is None else data self._check_size(connection, data) link.deliver(self._char, "indicate", data, False) await asyncio.sleep(0) await asyncio.sleep(0) link.check() def _remote_write(self, connection, data): self._value = data if self._char.capture: self._writes.put((connection, data)) else: self._last_writer = connection self._written.set() async def written(self, timeout_ms): if self._char.capture: return await self._writes.get(timeout_ms) if not self._written.is_set(): await wait_ms(self._written.wait(), timeout_ms, "written") self._written.clear() return self._last_writer