Bluetooth LE support
What bledev can do on each host, and what it can’t. The
Bluetooth LE guide shows how to use each part.
Roles and features by host
MicroPython |
CircuitPython |
Laptop ( |
Browser ( |
|
|---|---|---|---|---|
Peripheral: advertise, serve a GATT table |
Yes |
Yes |
No |
No |
Central: scan, connect |
Yes |
Yes |
Yes |
The browser’s chooser stands in for a scan |
Indications sent by a peripheral |
Yes, waits for the acknowledgement |
Sent, but the acknowledgement isn’t reported |
No |
No |
Indications received by a central |
Yes |
No |
Yes |
Yes |
Long reads, past one packet |
No |
No |
Yes |
Yes |
Resolvable private addresses |
Yes on NimBLE (the ESP32 family), with |
No |
No |
No |
Pairing |
Just Works, passkey, numeric comparison |
Just Works only |
The operating system’s |
The browser’s |
Bonding |
Yes, kept in NVS or a file |
Always |
The operating system’s |
The browser’s |
ATT MTU |
Set with |
Fixed at build time |
Set with |
Recorded, not used: the browser never reports it |
What the parts give you
Part |
What it is |
Roles |
|---|---|---|
|
Nordic UART: a two-way byte stream |
|
|
BLE-MIDI 1.0 as a MIDI port |
|
|
Wi-Fi setup with Improv |
|
|
The REPL over Bluetooth, behind a password, with optional pairing |
|
|
CircuitPython’s file transfer service ( |
|
|
Battery Service (0x180F) |
A peripheral: |
|
Device Information Service (0x180A) |
A peripheral: |
|
Heart Rate Service (0x180D), with the energy-expended control point |
A peripheral: |
|
Cycling Speed and Cadence Service (0x1816), with its control point |
A peripheral: |
|
Cycling Power Service (0x1818), with its control point |
A peripheral: |
|
Running Speed and Cadence Service (0x1814), with its control point |
A peripheral: |
|
Environmental Sensing Service (0x181A): temperature, humidity, pressure and UV index |
A peripheral: |
|
Keyboards, remotes and gamepads, as OmniPython events |
|
|
A keyboard, mouse, media remote and gamepad, with |
|
|
Your own GATT table, served or discovered |
Each host, in the roles above |
Not supported, and why
What |
Where |
Because |
|---|---|---|
Peripheral role |
Laptop, browser |
|
Scanning |
Browser |
A page can’t scan; |
Passkey and numeric comparison |
CircuitPython |
|
Receiving indications |
CircuitPython |
Its ESP32 port ignores them |
Reading a value longer than one packet |
MicroPython, CircuitPython |
Neither |
HID over GATT as a host |
Laptop, browser |
Windows keeps the HID service from apps, and Web Bluetooth’s blocklist covers it. A board’s HID characteristics are also served under a vendor UUID, so a laptop can inspect them |
Bluetooth 5 features: extended and periodic advertising, the 2M and Coded PHYs, LE Audio |
MicroPython |
The |
Resolvable and non-resolvable private addresses |
Pico W on MicroPython; CircuitPython; laptop; browser |
BTstack has no RPA or NRPA, |
A BLE radio |
ESP32-P4 on CircuitPython |
CircuitPython builds no Bluetooth for the P4 |
On CircuitPython
On CircuitPython, adafruit_midi and adafruit_hid are already the way to do MIDI and HID over usb_midi and usb_hid; over BLE, use bledev.midi and bledev.hid. The CircuitPython-compatible build for the ESP32-P4 has no Bluetooth at all, so there is no BLE MIDI or HID there, and no USB device either until CircuitPython gives the P4 one.
Installing bledev
On a laptop, bledev is inside the omnipython wheel. pip install "omnipython[ble]"
adds bleak, which the laptop backend needs.
With Wi-Fi, omip.install("bledev") runs on the board once
boot.py has made the drive writable, and omip tells you how if it isn’t. It
leaves aioble out, because CircuitPython’s Bluetooth is its own, and brings
Adafruit’s asyncio library and adafruit_ticks in its place. At around -70 dBm
it usually loses the connection partway and raises OSError. Run it again: it
keeps the files it already has. Or copy the files
yourself: bledev isn’t in a circup bundle. With the board’s CIRCUITPY drive mounted, make a
lib/bledev/ folder on it and copy these into it from
lib/bledev/, as .py source (MicroPython’s .mpy files
won’t load on CircuitPython):
__init__.pyandcpble.py, always;auto.py, if you’d rather not name the backend;the parts you use, with what they import:
nus.py;midi.pywithmidi_codec.py;filetransfer.pywithnus.py,repl.pyandsecurity.py. Those are the parts measured on CircuitPython (see What differs).
Leave out mpble.py, bleak.py, webble.py and fake.py; they’re for other
hosts. bledev also needs CircuitPython’s asyncio library: circup install asyncio, which brings adafruit_ticks, or omip.install("asyncio") on the board.
What differs
The same code runs with bledev.cpble, in either role: nus, MIDI, the contract’s checks and the file client all pass over the radio. _bleio works differently from aioble underneath, so:
Connecting, discovery, a read, a write with response and subscribing each hold up your other tasks until the radio answers, usually a connection interval or two.
_bleiohas no async calls.It pairs “just works” only.
authenticated=Trueand passkeys raiseUnsupportedError, and it always bonds.A central there can’t receive indications, and the MTU is 247 at most.
Characteristic.write()on a characteristic that notifies sends the value to subscribed centrals even withoutsend_update.CircuitPython 10.3’s
PacketBuffercan stall or fault the board when a notification stream outruns the radio. bledev steps around the stall; the fault needs a CircuitPython fix. On the official build, 2 of 11 fast 16 KB streams restarted the board in safe mode; on a patched build, none did.A central there waits 2 s on every read and every write with a response (subscribing is one), so connecting and setting up takes several seconds.
CircuitPython’s own BLE file service, the one its supervisor serves, is
reached with the same bledev.filetransfer.connect() a MicroPython board
uses; it pairs by itself. The service is only public in CircuitPython’s
discovery mode, it won’t write while a computer has the CIRCUITPY drive
mounted, and on the official 10.3.0 build a 20 KB download stalls (the same
PacketBuffer fault). What cpble does about each of these, and why, is in
bledev-internals.md.