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_limit entries, and an overflow raises from notified().

  • aioble’s capture=True shares 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 of queue_limit.

  • notify() and write() refuse a payload over mtu - 3 instead of letting NimBLE truncate it.

bledev.mpble.get(ble=None)[source]

The shared MPBLE for this board’s radio, made on first use.

class bledev.mpble.MPBLE(ble=None, *, queue_limit=128, mtu=None)[source]

Bases: BLE

The board’s radio. ble may be a bluetooth.BLE(); there is only one.

queue_limit bounds each notification and capture queue. Prefer get, which returns one shared adapter.

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

enable_bonding(store=None)[source]

Bond from now on, keeping the keys in store (see bledev.security.use_store): NVS on an ESP32 by default, which survives a filesystem erase, or a path for aioble’s ble_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_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]

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