bledev.repl
The MicroPython REPL over Bluetooth, behind a password.
On the board, opt in from main.py (nothing starts it for you):
import bledev.repl
bledev.repl.start(password="correct horse") # or webrepl_cfg.PASS
The board then advertises the Nordic UART service under its name
(boarddev.name(), or name=) while the normal REPL carries on. A
client connects, sends an empty line to get a Password: prompt, sends the
password and a newline, and gets the prompt. From a laptop or another board:
import bledev.repl
link = await bledev.repl.connect(ble, "correct horse", name="omnipython-a1b2c3")
await link.write(b"1 + 1\r")
It behaves like WebREPL: one attempt per connection, a wrong password gets
Access denied and a disconnect, and nothing the client sends reaches the
REPL before the password is right. Like WebREPL, the link isn’t encrypted, so
someone sniffing nearby can capture the password.
Pairing encrypts the link, and bonds so the next connection skips it.
The board asks a host to pair as soon as it connects, and shows the prompt
once the pairing settles. It’s off unless you ask (pairing=None, the
password alone):
pairing="passkey": the board shows a six-digit passkey on its display (or the console) and the host types it in. That authenticates the host, so the password becomes optional:password=Falsedrops it.pairing="justworks": encrypted and bonded, with no passkey. It proves nothing about who paired, so the password stays required; what it buys is that nobody sniffing can read the password or the session.pairing="numeric": both sides show a number;confirm(number)on the board says whether they match (a button, say).pairing="auto":"passkey"on a board with a display, else"justworks".
The keys live in NVS on an ESP32, so a filesystem erase keeps them and a full
chip erase loses them (bledev.security). A client pairs with
connect(..., pair=True, passkey=...).
The REPL owns the radio while it runs. It registers its own GATT service
(replacing any other) and advertises whenever nobody is connected. It works
from interrupts rather than asyncio, so it keeps serving at the >>>
prompt and while your program runs, and Ctrl-C interrupts a running program
as it does over USB. stop() gives the radio back. It’s MicroPython only;
connect() runs anywhere bledev does.
- bledev.repl.BUSY = b'\r\nThe REPL is busy: another console (WebREPL?) holds it\r\n'
Sent instead of the banner when every dupterm slot is taken (WebREPL has a client).
- bledev.repl.MAX_PASSWORD = 64
Longest password line the board will buffer before refusing.
- class bledev.repl.Login(password)[source]
Bases:
objectThe password exchange, without a radio, so it can be tested anywhere.
Feed it what the client writes. It answers with bytes to send back and a verdict:
Nonewhile waiting,Truewith any bytes that followed the password (they go to the REPL), orFalsefor a refusal.
- bledev.repl.take_slot(dupterm, stream, want=None)[source]
Put
streamon a freeos.duptermslot and return its index.wantasks for that slot; otherwise the highest free one is taken, so slot 0 stays WebREPL’s on a port with more than one. ReturnsNone, and leaves every slot as it was, when the slot (or all of them) is held: a port like the ESP32 has one, and WebREPL holds it while it has a client.
- bledev.repl.start(password=None, name=None, *, interval_us=100000, dupterm_index=None, files=False, console=True, window=None, pairing=None, show=None, hide=None, confirm=None, bond_store=None)[source]
Serve the REPL over BLE until
stopor a reset. MicroPython only.passworddefaults towebrepl_cfg.PASSwhen that file exists; it must be at least 4 characters. The board advertises asname, by default its own,boarddev.name(). Returns at once.files=Truealso servesbledev.filetransfer(CircuitPython’s file-transfer service) behind the same password, withwindowbytes of free space per round trip;console=Falseleaves the REPL out.pairingisNone(the default: the password alone),"passkey","justworks","numeric"or"auto"(see the module notes). With a pairing that authenticates (passkey, numeric),password=Falseserves without one.dupterm_indexpicks theos.duptermslot the REPL takes at login; by default it takes a free one, and a client that logs in while every slot is held (WebREPL in use, on a one-slot port like the ESP32) is told so and disconnected, as WebREPL does.show(passkey)/hide()replace drawing the passkey onboard_config.display_drv;confirm(number)answers numeric comparison.bond_storeis where the keys go (bledev.security.use_store; default NVS on an ESP32).
- bledev.repl.refused(pair, passkey)[source]
The
bledev.PairingErrorfor a board that refused a link.
- async bledev.repl.connect(ble, password=None, name=None, *, device=None, timeout_ms=10000, pair=False, passkey=None, **connect_options)[source]
Log in to a board’s BLE REPL and return the
bledev.nus.Link, at>>>.namepicks the board by the name it advertises; without one, the first board serving the REPL’s service is used.pair=Truepairs first (bonding, so the next connect skips it), for a board started withpairing=;passkeyis what its display shows, or a callable that asks for it. A board that pairing unlocks alone needs nopassword.Raises
AuthErrorif the board refuses the password, andbledev.PairingErrorif pairing fails or the board refuses the keys this host kept.