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=False drops 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.

exception bledev.repl.AuthError[source]

Bases: BLEError

The board refused the password.

class bledev.repl.Login(password)[source]

Bases: object

The 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: None while waiting, True with any bytes that followed the password (they go to the REPL), or False for a refusal.

feed(data)[source]

(reply, verdict, rest) for a chunk the client wrote.

bledev.repl.take_slot(dupterm, stream, want=None)[source]

Put stream on a free os.dupterm slot and return its index.

want asks for that slot; otherwise the highest free one is taken, so slot 0 stays WebREPL’s on a port with more than one. Returns None, 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.give_slot(dupterm, stream, index)[source]

Free slot index if stream still holds it.

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 stop or a reset. MicroPython only.

password defaults to webrepl_cfg.PASS when that file exists; it must be at least 4 characters. The board advertises as name, by default its own, boarddev.name(). Returns at once.

files=True also serves bledev.filetransfer (CircuitPython’s file-transfer service) behind the same password, with window bytes of free space per round trip; console=False leaves the REPL out.

pairing is None (the default: the password alone), "passkey", "justworks", "numeric" or "auto" (see the module notes). With a pairing that authenticates (passkey, numeric), password=False serves without one. dupterm_index picks the os.dupterm slot 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 on board_config.display_drv; confirm(number) answers numeric comparison. bond_store is where the keys go (bledev.security.use_store; default NVS on an ESP32).

bledev.repl.stop()[source]

Stop serving: drop the client, give the REPL back, stop advertising.

bledev.repl.refused(pair, passkey)[source]

The bledev.PairingError for 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 >>>.

name picks the board by the name it advertises; without one, the first board serving the REPL’s service is used.

pair=True pairs first (bonding, so the next connect skips it), for a board started with pairing=; passkey is what its display shows, or a callable that asks for it. A board that pairing unlocks alone needs no password.

Raises AuthError if the board refuses the password, and bledev.PairingError if pairing fails or the board refuses the keys this host kept.

async bledev.repl.run(link, code, timeout_ms=10000)[source]

Type code at the prompt and return what it printed, up to the next >>>.