bledev.mpble
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_limitentries, and an overflow raises fromnotified().aioble’s
capture=Trueshares 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 ofqueue_limit.notify()andwrite()refuse a payload overmtu - 3instead of letting NimBLE truncate it.
- class bledev.mpble.MPBLE(ble=None, *, queue_limit=128, mtu=None)[source]
Bases:
BLEThe board’s radio.
blemay be abluetooth.BLE(); there is only one.queue_limitbounds each notification and capture queue. Preferget, which returns one shared adapter.- 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).
- enable_bonding(store=None)[source]
Bond from now on, keeping the keys in
store(seebledev.security.use_store): NVS on an ESP32 by default, which survives a filesystem erase, or a path for aioble’sble_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.
- 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.
- close()[source]
Turn the radio off. Its services go with it: register them again after it’s back on.
- irq(handler)[source]
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.
- 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.