# 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