Skip to content

Reach a board over Bluetooth: ble:// devices through bledev - #47

Merged
bdbarnett merged 1 commit into
mainfrom
ble-transport
Sep 25, 2026
Merged

bdbarnett merged 1 commit into
mainfrom
ble-transport

Conversation

@bdbarnett

Copy link
Copy Markdown
Collaborator

Every board command now takes -d ble://NAME, which reaches a board running pydevices' bledev.repl or bledev.filetransfer over Bluetooth with no serial port involved. It's modelled on the ws:// transport: a pyserial-shaped link handed to mpremote's SerialTransport, here over bleak in the sidecar's Python. The board side is PyDevices/pydevices#86 (unmerged).

export MPFTP_BLE_PASSWORD=...
mpftp exec -d ble://rack "print(1+1)"
mpftp put -d ble://rack main.py /main.py
  • Files go over the board's BLE file-transfer service when it serves one (CircuitPython's protocol), and over the raw REPL when it doesn't. For 20 KB, file transfer took 0.83 s up and 0.30 s down; the raw REPL took 15.6 s and 10.6 s. put/get keep their SHA-256 check.
  • The password is looked up the way the WebREPL one is (A WebREPL password set in VS Code can't be used by the CLI, the PWA or agents #43): first ~/.mpftp/webrepl-passwords.json under ble:NAME (mpftp wifi password ble://NAME), then MPFTP_BLE_PASSWORD / blePassword, then the WebREPL password, because bledev.repl defaults to webrepl_cfg.PASS.
  • Resets. soft-reset refuses over BLE and says why: a soft reset turns Bluetooth off. soft-reboot works if main.py starts bledev. mount stays serial-only.

Gate, run on the T-Embed over BLE with USB serial used only for setup:

  • CLI: ls, put (verified), get (cmp byte for byte), exec, and interrupt of a while True loop started by run (61 ms) all passed. The REPL answered afterwards.
  • tools/ble_gate.py ran the same checks inside one sidecar session and passed.
  • Planted faults: MPFTP_BLE_PLANT=put made put exit 1 with a hash mismatch, and MPFTP_BLE_PLANT=get made get report one.
  • A wrong password, an absent board and soft-reset each gave a clear message.
  • The unit tests pass (436 of 436, including 13 new ones in test_ble.py), and ruff is clean.

The measurements and design are in docs/plans/ble.md, and the numbers come from tools/ble_bench.py.

Not done

  • The VS Code extension and the PWA don't list BLE boards.
  • There's no ble find and no remembered BLE boards.
  • Only Windows' radio has been tried.

A bledev.repl link dressed as a pyserial port for mpremote's SerialTransport,
over bleak in the sidecar's Python. Files go through the board's BLE
file-transfer service (bledev.filetransfer, CircuitPython's protocol) when it
serves one: 20 KB up in 0.8 s and down in 0.3 s, against 16 s and 11 s over
the raw REPL. put/get keep their SHA-256 check, and MPFTP_BLE_PLANT proves it
fails on a flipped bit. The password comes the way the WebREPL one does.
Soft reset refuses over BLE (it turns Bluetooth off); mount stays serial-only.
@bdbarnett
bdbarnett merged commit 3bcf7a8 into main Sep 25, 2026
3 checks passed
@bdbarnett
bdbarnett deleted the ble-transport branch September 25, 2026 05:42
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