Skip to content

bledev.cpble: the CircuitPython backend over _bleio - #90

Merged
bdbarnett merged 5 commits into
mainfrom
bledev-cpble
Sep 25, 2026
Merged

bdbarnett merged 5 commits into
mainfrom
bledev-cpble

Conversation

@bdbarnett

@bdbarnett bdbarnett commented Sep 25, 2026 •

Copy link
Copy Markdown
Contributor

bledev.cpble, the CircuitPython backend over _bleio, both roles. Stacked on #88 (bledev-pairing).

It works on _bleio directly rather than adafruit_ble: bledev already has the parts adafruit_ble adds (advertisement packing, a service model, a UART stream), so leaning on it would mean translating between two service models and installing a library for no gain. Every _bleio call it makes is one adafruit_ble would make anyway.

What passed on hardware (LilyGO T-Embed, CircuitPython 10.3.0, laptop through bleak; details in docs/bledev-internals.md, "CircuitPython (cpble)"). Every planted fault failed its gate.

  • nus, 16 KB up, down and echoed from the laptop: 12 of 12 on a patched build, 50-91 KB/s up, 25-49 down, 16-28 echoed.
  • The GATT contract from the laptop (gatt_central.py --mtu 256), BLE-MIDI's 1,000-message gate (latency the same as against a MicroPython S3: 52.1 ms median, 13.3 ms with throughput parameters).
  • MicroPython LCD-7 as central, CircuitPython serving nus: pass.
  • CircuitPython's own file service (the supervisor's) with bledev.filetransfer.connect(): it pairs by itself, 20 KB up and down byte for byte, and reconnects from the bond. tests/bledev_board/cpfiles_discovery.py puts the board in discovery mode without a hand on the reset button.
  • The contract and codec checks also run under CircuitPython's own interpreter (unix port), in tests/test_bledev_cpble.py, beside stub-_bleio checks of what cpble adds.

A CircuitPython bug, and the build it needed. On the official 10.3.0 build, PacketBuffer on the ESP32 stalls a notification stream for good when NimBLE's buffers run dry, and can hard-fault the board after a refused notification (2 of 11 nus runs restarted in safe mode; the file service's 20 KB download stalled 2 of 2 times). cpble steps around the stall by writing each notification as the header= of an empty write, but only a firmware fix removes the fault. The fix and an upstream draft are in docs/upstream-reports/cp-packetbuffer-notify-stall.{md,patch}, for Brad to post (not posted, not pushed anywhere). The gates above ran on 10.3.0 with that patch.

Not finished: CircuitPython as central running the full nus gate against the LCD-7. In a probe it found, connected, discovered, subscribed and wrote, but nus_client.py itself hung, likely mpftp garbling the long paste (seen elsewhere in the run), and the LCD-7 went back to another session before it was settled.

Also in here: bledev.connect_and_set_up honours a backend's min_setup_ms (CircuitPython waits 2 s on every write with response, subscribing included); auto picks cpble; nus and midi take a raw _bleio.adapter.

Packaging question left open: CircuitPython has no mip, so cpble ships in the bledev mip package (one unused file on a MicroPython board) and in pydevices-desktop.

Both roles. Waits are short polls of _bleio's objects; writes land in
PacketBuffer (notify characteristics) or CharacteristicBuffer (the rest).
Notifications go in as the header of an empty PacketBuffer.write(), which
steps around CircuitPython 10.3's stall when NimBLE's buffer pool runs dry
and keeps each notification whole. The reported MTU is capped at 247.

auto picks cpble where _bleio exists; nus and midi accept a raw
_bleio.adapter; midi's clock uses supervisor.ticks_ms on CircuitPython.
The board scripts for nus, the GATT contract and midi run on CircuitPython,
and cpfiles_client/cpfiles_discovery reach CircuitPython's own file service.
…ow-setup hint, sticky scan names, order across characteristics; board scripts and docs
Base automatically changed from bledev-pairing to main September 25, 2026 05:38
@bdbarnett
bdbarnett merged commit 2768bb2 into main Sep 25, 2026
3 checks passed
@bdbarnett
bdbarnett deleted the bledev-cpble branch September 25, 2026 05:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Development

Successfully merging this pull request may close these issues.

1 participant