bledev.fake
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 - 3raisesBLEError(NimBLE truncates it).A write longer than the characteristic’s
max_lenraises (MicroPython truncates to the buffer, 20 bytes by default).Notifications reach a client only after it calls
subscribe().Only
notify_buffersnotifications can be in flight per connection; one more raisesBusyErroruntil 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 nextnotified()orwritten()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
encryptedcharacteristic refuses an unpaired central withGattError(INSUFFICIENT_ENCRYPTION).pair()encrypts the link, and withbondboth adapters remember each other (bonds) untilforget().long_reads=Falsemakes a central read at mostmtu - 1bytes, as MicroPython does (it has no long read).
- bledev.fake.SCAN_TICK_MS = 5
How often a fake scan looks at the air, in milliseconds.
- class bledev.fake.FakeBLE(*, air=None, central=True, peripheral=True, mtu=23, address=None, rssi=-50, notify_buffers=8, queue_limit=128, gap_name='fake', long_reads=True)[source]
Bases:
BLEA pretend radio.
centralandperipheralpick the roles it may take.mtuis the ATT MTU it asks for inexchange_mtu().notify_buffersandqueue_limitsize the flow control described in the module docstring.- bonds
Addresses of the peers this adapter has bonded with.
- pairing
“justworks”, or “passkey” to show one (
set_pairing).- Type:
As a peripheral
- capabilities()[source]
A dict describing this backend. Keys every backend provides:
backend(its module name),centralandperipheral(which roles it can take),mtu(the ATT MTU it asks for),max_mtu,indicate,pairingandl2cap(bools),long_read: whether a read returns values longer than one packet (mtu - 1), andwrite_notifies: whether setting a served characteristic’s value already notifies its subscribers (CircuitPython’s_bleio).
- forget(address=None)[source]
Drop the bond with
address, or every bond (a board’s filesystem erased).
- set_pairing(mode='justworks', show=None)[source]
As a peripheral, pair “just works”, or show a passkey:
show(passkey)gets the six digits a central must givepair(passkey=...).
- config(*names, **settings)[source]
Read or set adapter settings, like
bluetooth.BLE.config.config(mtu=247)sets the ATT MTU this side asks for;config("mtu")reads it.gap_nameis the device name in the GAP service.addr_modeis the address the radio uses on the air:ADDR_MODE_PUBLIC,ADDR_MODE_RANDOM,ADDR_MODE_RPA(a resolvable private address that rotates, so a phone can’t follow the board except through a bond) orADDR_MODE_NRPA. Set it before you advertise or scan. A setting the backend doesn’t have raisesUnsupportedError.
- register_services(*services)[source]
Install the GATT server. Replaces whatever was registered before.
Call it before
advertise(). EachCharacteristicis bound to this adapter from here on.
- async advertise(interval_us=100000, *, name=None, services=None, appearance=0, manufacturer=None, connectable=True, timeout_ms=None, service_data=None)[source]
Advertise until a central connects, and return that
Connection.service_datais a list of(uuid, data)(Improv uses it). RaisesBLETimeoutErrorif nobody connects withintimeout_ms. Cancelling the task stops advertising. Advertising stops when a central connects; call again to accept another.
- scan(duration_ms, *, active=False, interval_us=None, window_us=None)[source]
Scan for
duration_ms. Use as:async with ble.scan(5000, active=True) as scanner: async for result in scanner: ...
A device can be yielded more than once as its data arrives. An active scan also asks for scan responses, which is where a long name ends up.