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 - 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).

bledev.fake.SCAN_TICK_MS = 5

How often a fake scan looks at the air, in milliseconds.

class bledev.fake.Air[source]

Bases: object

The medium the fake adapters share. Make one per test.

bledev.fake.default_air()[source]

The Air used when an adapter isn’t given one.

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: 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.

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), central and peripheral (which roles it can take), mtu (the ATT MTU it asks for), max_mtu, indicate, pairing and l2cap (bools), long_read: whether a read returns values longer than one packet (mtu - 1), and write_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 give pair(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_name is the device name in the GAP service. addr_mode is 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) or ADDR_MODE_NRPA. Set it before you advertise or scan. A setting the backend doesn’t have raises UnsupportedError.

close()[source]

Stop advertising and scanning, drop connections, and turn the radio off.

register_services(*services)[source]

Install the GATT server. Replaces whatever was registered before.

Call it before advertise(). Each Characteristic is 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_data is a list of (uuid, data) (Improv uses it). Raises BLETimeoutError if nobody connects within timeout_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.