# SPDX-FileCopyrightText: 2026 Brad Barnett
#
# SPDX-License-Identifier: MIT
"""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.
"""
import struct
import sys
import boarddev
from . import BLEError, GattError, NEEDS_PAIRING, PairingError, STALE_BOND, pack_advertisement, wait_ms
from . import nus
# bluetooth.BLE characteristic flags for the protected characteristics.
_F_READ_ENC = 0x0200
_F_READ_AUTHN = 0x0400
_F_WRITE_ENC = 0x1000
_F_WRITE_AUTHN = 0x2000
PROMPT = b"Password: "
# How often the server retries output the controller couldn't take yet.
_TICK_MS = 5
# With pairing on, how long a link may stay unpaired before the board hangs
# up, so a host that never pairs can't hold the one connection. SMP's own
# timeout is 30 s. The clock starts again when the passkey goes up: a phone
# asks "Pair?" first, and that question alone can take most of the 30 s.
PAIR_WITHIN_MS = 30000
BANNER = b"\r\nbledev REPL connected\r\n>>> "
DENIED = b"\r\nAccess denied\r\n"
#: Sent instead of the banner when every dupterm slot is taken (WebREPL has a client).
BUSY = b"\r\nThe REPL is busy: another console (WebREPL?) holds it\r\n"
#: Longest password line the board will buffer before refusing.
MAX_PASSWORD = 64
[docs]
class AuthError(BLEError):
"""The board refused the password."""
def _check_password(given, want):
"""Constant-time comparison of two byte strings."""
diff = len(given) ^ len(want)
for i in range(len(given)):
diff |= given[i] ^ want[i % len(want)] if want else 1
return diff == 0
[docs]
class Login:
"""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.
"""
def __init__(self, password):
self._password = password.encode() if isinstance(password, str) else bytes(password)
self._line = bytearray()
self.verdict = None
[docs]
def feed(self, data):
"""``(reply, verdict, rest)`` for a chunk the client wrote."""
if self.verdict is not None:
return b"", self.verdict, b""
reply = b""
for i in range(len(data)):
b = data[i]
if b in (10, 13):
if not self._line:
reply = PROMPT # an empty line asks for the prompt; no attempt used
continue
self.verdict = _check_password(bytes(self._line), self._password)
self._line = bytearray()
rest = bytes(data[i + 1 :])
if self.verdict:
# Drop the other half of a CRLF so the REPL doesn't see a blank line.
if b == 13 and rest[:1] == b"\n":
rest = rest[1:]
return BANNER, True, rest
return DENIED, False, b""
if len(self._line) >= MAX_PASSWORD:
self.verdict = False
return DENIED, False, b""
self._line.append(b)
return reply, None, b""
# ---------------------------------------------------------------- the board side
[docs]
def take_slot(dupterm, stream, want=None):
"""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.
"""
if want is None:
count = 0
while True:
try:
held = dupterm(None, count)
except (ValueError, OSError):
break
dupterm(held, count)
count += 1
order = range(count - 1, -1, -1)
else:
order = (want,)
for index in order:
held = dupterm(None, index)
if held is None:
dupterm(stream, index)
return index
dupterm(held, index)
return None
[docs]
def give_slot(dupterm, stream, index):
"""Free slot ``index`` if ``stream`` still holds it."""
held = dupterm(None, index)
if held is not stream:
dupterm(held, index)
_server = None
[docs]
def 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,
):
"""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).
"""
global _server
if sys.implementation.name != "micropython":
raise BLEError("bledev.repl serves only on MicroPython; use connect() on this host")
mode = None
if pairing is not None:
from . import security
# Before the radio starts where possible, so its keys load first.
security.use_store(bond_store)
mode = security.configure(pairing, show=show, hide=hide, confirm=confirm)
authenticates = mode in ("passkey", "numeric")
if password is None:
try:
import webrepl_cfg
password = webrepl_cfg.PASS
except (ImportError, AttributeError):
if not authenticates:
raise ValueError("bledev.repl needs a password (or webrepl_cfg.PASS)")
password = False
if password is False or password == "":
if not authenticates:
raise ValueError(
"only a pairing that authenticates the host (passkey, numeric) can replace the password"
)
password = None
elif len(password) < 4:
raise ValueError("the password must be at least 4 characters")
if not (files or console):
raise ValueError("nothing to serve: files=False and console=False")
stop()
if name is None:
name = boarddev.name()
_server = _Server(password, name, interval_us, dupterm_index, files, console, window, mode)
_server.start()
return _server
[docs]
def stop():
"""Stop serving: drop the client, give the REPL back, stop advertising."""
global _server
if _server is not None:
_server.stop()
_server = None
def is_running():
return _server is not None
try:
import io
_IOBase = io.IOBase
except (ImportError, AttributeError): # CPython without the MicroPython stream protocol
_IOBase = object
class _Stream(_IOBase):
"""What ``os.dupterm`` reads from and writes to."""
def __init__(self, server):
self._s = server
def readinto(self, buf):
s = self._s
n = len(s.rx) - s.rx_pos
if n <= 0:
return None # nothing yet; 0 would mean end of stream and detach us
n = min(n, len(buf))
buf[:n] = s.rx[s.rx_pos : s.rx_pos + n]
s.rx_pos += n
if s.rx_pos >= len(s.rx):
s.rx = bytearray()
s.rx_pos = 0
return n
def write(self, buf):
self._s.send(buf)
return len(buf)
def ioctl(self, op, arg):
if op == 3: # MP_STREAM_POLL
return 1 if (arg & 1) and len(self._s.rx) > self._s.rx_pos else 0
return 0
class _Server:
# Output buffered beyond this waits for the link before print() returns.
TX_CAP = 4096
# Input buffered beyond this, while nothing reads stdin, is dropped.
RX_CAP = 4096
def __init__(self, password, name, interval_us, dupterm_index, files=False, console=True, window=None, pairing=None):
self.password = password
#: None (password only), or the pairing mode in force.
self.pairing = pairing
self._security = None
self.console = console
self.files = None
self.ft_flushing = False
self.ft_in = bytearray()
self.ft_scheduled = False
self.ft_reset = False
self.rx_handle = self.tx_handle = None
self.ft_handle = self.auth_handle = None
if files:
from . import filetransfer
self.files = filetransfer.FileServer(window=window or filetransfer.WINDOW)
self.name = name
self.interval_us = interval_us
self.dupterm_index = dupterm_index
self.running = False
self.conn = None
self.login = None
self.authed = False
self.greeted = False
self.mtu = 23
self.rx = bytearray()
self.rx_pos = 0
self.tx = bytearray()
self.flushing = False
self.dropped_out = 0
self.slot = None
#: ``os.dupterm``, resolved at first login (tests put a stand-in here).
self.dupterm = None
self.stream = _Stream(self)
self.timer = None
self.hang_up_at = None
self.early_mtu = None
# -- setup
def start(self):
import bluetooth
import machine
try:
from aioble import core
self.ble = core.ble
core.ensure_active()
_arm_aioble()
if not getattr(core, "_bledev_repl_irq", False):
core.register_irq_handler(_irq, None)
core._bledev_repl_irq = True
self._aioble = True
except ImportError:
self.ble = bluetooth.BLE()
self.ble.active(True)
self.ble.irq(_irq)
self._aioble = False
ble = self.ble
try:
ble.config(mtu=nus.MTU)
except Exception:
pass
try:
# The name hosts show for a paired board (Windows' Settings list)
# is the GAP name, not the advertised one: make them the same.
ble.config(gap_name=self.name)
except Exception:
pass
# With pairing, the stack itself refuses the protected characteristics
# to a link that isn't encrypted (or, for a passkey, authenticated),
# before anything here sees the request.
if self.pairing is None:
rd = wr = 0
elif self.pairing == "justworks":
rd, wr = _F_READ_ENC, _F_WRITE_ENC
else:
rd, wr = _F_READ_ENC | _F_READ_AUTHN, _F_WRITE_ENC | _F_WRITE_AUTHN
services = []
uuids = []
if self.console:
services.append(
(
bluetooth.UUID(str(nus.SERVICE)),
(
(bluetooth.UUID(str(nus.TX)), 0x0010), # notify
(bluetooth.UUID(str(nus.RX)), 0x0008 | 0x0004 | wr), # write, write without response
),
)
)
uuids.append(nus.SERVICE)
if self.files is not None:
from . import filetransfer as ft
services.append(
(
bluetooth.UUID(ft.SERVICE.short),
(
(bluetooth.UUID(str(ft.VERSION)), 0x0002), # read
# read, write without response, write, notify
(bluetooth.UUID(str(ft.TRANSFER)), 0x0002 | 0x0004 | 0x0008 | 0x0010 | rd | wr),
# read, write. Served even without a password, so the
# table is the same for every lock: hosts cache it.
(bluetooth.UUID(str(ft.AUTH)), 0x0002 | 0x0008 | rd | wr),
),
)
)
uuids.append(ft.SERVICE)
handles = ble.gatts_register_services(tuple(services))
if self.console:
(self.tx_handle, self.rx_handle) = handles[0]
# Appending: several writes between two IRQs arrive together.
ble.gatts_set_buffer(self.rx_handle, 1024, True)
if self.files is not None:
(version, self.ft_handle, self.auth_handle) = handles[-1]
ble.gatts_write(version, struct.pack("<I", ft.PROTOCOL_VERSION))
# Room for a whole window of data, its header and the next
# command: the board never offers more than this.
ble.gatts_set_buffer(self.ft_handle, 2 * self.files.window + 64, True)
ble.gatts_set_buffer(self.auth_handle, MAX_PASSWORD + 1)
ble.gatts_write(self.auth_handle, b"\x00")
self._forget_other_services()
if self.pairing is not None:
from . import security
self._security = security.on_change(self.on_security)
# One periodic timer for the life of the server, never re-armed: on
# the esp32, re-initialising a virtual Timer while its alarm is being
# dispatched calls a NULL handler and panics the board (seen as a
# Guru Meditation in esp_timer's task during long prints).
self.timer = machine.Timer(-1)
self.timer.init(mode=machine.Timer.PERIODIC, period=_TICK_MS, callback=self._tick)
self.adv = pack_advertisement(self.name, uuids)
self.running = True
self.advertise()
def _forget_other_services(self):
# The registration above replaced every service aioble and mpble knew,
# so their handle tables now point at our handles. Clear them.
mods = sys.modules
server = mods.get("aioble.server")
if server is not None:
server._registered_characteristics.clear()
mpble = mods.get("bledev.mpble")
if mpble is not None:
mpble._captures.clear()
shared = getattr(mpble, "_shared", None)
if shared is not None and hasattr(shared, "_nus_server"):
del shared._nus_server
def advertise(self):
if self.running and self.conn is None:
adv, resp = self.adv
try:
self.ble.gap_advertise(self.interval_us, adv_data=adv, resp_data=resp or None)
except OSError:
pass
def stop(self):
self.running = False
if self._security is not None:
from . import security
security.remove_listener(self._security)
self._security = None
try:
self.ble.gap_advertise(None)
except Exception:
pass
if self.conn is not None:
try:
self.ble.gap_disconnect(self.conn)
except Exception:
pass
self._detach()
if self.timer is not None:
self.timer.deinit()
# -- connection events (from the BLE IRQ)
def on_connect(self, conn):
if self.conn is not None:
self.ble.gap_disconnect(conn) # one client at a time
return
self.conn = conn
self.mtu = 23
# MicroPython can report the MTU exchange before the connection.
if self.early_mtu and self.early_mtu[0] == conn:
self.mtu = self.early_mtu[1]
self.early_mtu = None
self.login = _Gate(self.password) if self.password is not None else _Open()
self.hang_up_at = None
self.authed = False
self.greeted = False
self.rx = bytearray()
self.rx_pos = 0
self.tx = bytearray()
if self.files is not None:
self._ft_forget()
if self.pairing is not None:
# A bonded host may already be encrypting; on_security() takes over.
import time
from . import security
self.hang_up_at = time.ticks_add(time.ticks_ms(), PAIR_WITHIN_MS)
if self.secure(conn):
self.on_security(conn, *security.state(conn))
else:
self.request_security(conn)
return
if self.console:
# Sent now in case the client is already listening; clients that
# subscribe later ask for it again with an empty line.
self.notify_now(PROMPT)
# -- pairing
def request_security(self, conn):
"""Ask the host to pair (or, if it's bonded, to encrypt).
Without this, a host only pairs when the stack refuses it something,
and a write without response is refused silently: Android (and so
Chrome's Web Bluetooth) writes the NUS RX that way, so it never learned
it had to pair and every line it sent was dropped.
"""
try:
self.ble.gap_pair(conn)
except (OSError, AttributeError):
pass # a stack without it: the host pairs when a write is refused
def secure(self, conn):
"""Whether ``conn``'s link is as secure as this server asks."""
if self.pairing is None:
return True
from . import security
encrypted, authenticated, _bonded, _size = security.state(conn)
if self.pairing == "justworks":
return encrypted
return encrypted and authenticated
def on_security(self, conn, encrypted, authenticated, bonded, key_size):
# From the BLE IRQ, when pairing or a bonded reconnect settles.
if conn != self.conn:
return
if not self.secure(conn):
# Failed pairing, a weaker one than asked for, or a host whose
# keys this board no longer has. Stay connected so the host sees
# its reads refused (and can say why); the pairing deadline set at
# connect still hangs up on a host that never gets there.
return
self.hang_up_at = None # the pairing deadline is met
if self.password is None:
# The pairing was the lock: the files open now, and the REPL on
# the client's first line (_Open).
if self.files is not None and not self.files.authed:
self.files.authed = True
self.ble.gatts_write(self.auth_handle, b"\x01")
if self.console and not self.authed and not self.greeted:
self.greeted = True
if not self._slot_free():
self._refuse_busy()
return
# A host that wrote its first line while pairing was under
# way had it refused, so show the prompt now. A host that
# pairs before it subscribes misses this and asks with an
# empty line, as before.
self.notify_now(BANNER)
elif self.console and not self.authed:
self.notify_now(PROMPT)
def on_disconnect(self, conn):
if conn != self.conn:
return
self._detach()
self.conn = None
if self.files is not None:
self._ft_forget()
self.hang_up_at = None
self.login = None
self.authed = False
self.rx = bytearray()
self.rx_pos = 0
self.tx = bytearray()
self.advertise()
def on_write(self, conn, data):
if conn != self.conn or not self.secure(conn):
return
if not self.authed:
reply, verdict, rest = self.login.feed(data)
if verdict is False:
self.notify_now(reply)
self.login.refused = True
# Let "Access denied" reach the client, then hang up.
import time
self.hang_up_at = time.ticks_add(time.ticks_ms(), 300)
return
if verdict is None:
if reply:
self.notify_now(reply)
return
if not self._attach():
self._refuse_busy()
return
if self.files is not None:
self.files.authed = True # one password unlocks both
self.send(reply)
data = rest
if not data:
return
self.feed_repl(data)
def on_files(self, conn, data):
# This runs in the BLE stack's task, whose stack is a few KB: too
# small for filesystem work (a recursive delete crashed the board).
# So the IRQ only queues the bytes, and the main thread does the rest.
if conn != self.conn or not self.secure(conn):
return
self.ft_in.extend(data)
if not self.ft_scheduled:
self.ft_scheduled = True
try:
import micropython
micropython.schedule(self._ft_work, None)
except (ImportError, RuntimeError):
self.ft_scheduled = False # the queue is full; the tick picks it up
def _ft_forget(self):
# From the IRQ: lock the files and drop what's queued. Closing files
# waits for the main thread, which may be in the middle of one.
self.files.authed = False
self.ft_in = bytearray()
self.ft_reset = True
self.ble.gatts_write(self.auth_handle, b"\x00")
def _ft_work(self, _arg=None):
self.ft_scheduled = False
if self.ft_reset:
self.ft_reset = False
self.files.reset()
if self.conn is None:
return
if self.ft_in:
# Swap before feeding: bytes the IRQ adds meanwhile go to the new buffer.
data = self.ft_in
self.ft_in = bytearray()
self.files.feed(data)
self.ft_flush()
def on_auth(self, conn, data):
if conn != self.conn or self.files.authed or self.hang_up_at is not None or not self.secure(conn):
return
if self.password is None:
return # unlocked by pairing, not by a password
given = bytes(data).rstrip(b"\r\n")
want = self.password.encode() if isinstance(self.password, str) else bytes(self.password)
if _check_password(given, want):
self.files.authed = True
self.ble.gatts_write(self.auth_handle, b"\x01")
return
# One attempt per connection, as for the REPL: refuse and hang up.
if self.login is not None:
self.login.refused = True
import time
self.hang_up_at = time.ticks_add(time.ticks_ms(), 300)
def on_mtu(self, conn, mtu):
if conn == self.conn:
self.mtu = mtu
else:
self.early_mtu = (conn, mtu)
# -- the REPL
def _resolve_dupterm(self):
if self.dupterm is None:
import os
self.dupterm = os.dupterm
def _slot_free(self):
self._resolve_dupterm()
index = take_slot(self.dupterm, self.stream, self.dupterm_index)
if index is None:
return False
give_slot(self.dupterm, self.stream, index)
return True
def _refuse_busy(self):
# Another console holds the REPL: say so and hang up, the way
# WebREPL turns away a second client.
import time
self.notify_now(BUSY)
self.login.refused = True
self.hang_up_at = time.ticks_add(time.ticks_ms(), 300)
def _attach(self):
"""Take a dupterm slot for the REPL; False when none is free."""
self._resolve_dupterm()
self.slot = take_slot(self.dupterm, self.stream, self.dupterm_index)
if self.slot is None:
return False
self.authed = True
return True
def _detach(self):
if not self.authed:
return
self.authed = False
try:
give_slot(self.dupterm, self.stream, self.slot)
except Exception:
pass
self.slot = None
def feed_repl(self, data):
if len(self.rx) - self.rx_pos + len(data) > self.RX_CAP:
return
self.rx.extend(data)
if 3 in data:
# Ctrl-C: have dupterm read it now, so a running program is
# interrupted even though nothing is reading stdin.
import os
os.dupterm_notify(None)
# -- sending
def _tick(self, _timer=None):
# Every _TICK_MS while the server runs, as a scheduled callback.
if self.pairing is not None:
from . import security
security.poll()
if self.hang_up_at is not None:
import time
if time.ticks_diff(time.ticks_ms(), self.hang_up_at) >= 0:
self.hang_up_at = None
self._hang_up()
if self.tx and self.conn is not None:
self.flush()
if self.files is not None and (self.ft_reset or self.conn is not None and (self.ft_in or self.files.has_output())):
self._ft_work()
def _hang_up(self):
if self.conn is None:
return
if self.pairing is not None and not self.secure(self.conn):
import time
from . import security
asked = security.passkey_asked(self.conn)
if asked is not None and time.ticks_diff(time.ticks_ms(), asked) < PAIR_WITHIN_MS:
# Someone is reading or typing the passkey: give them their 30 s.
self.hang_up_at = time.ticks_add(asked, PAIR_WITHIN_MS)
return
try:
self.ble.gap_disconnect(self.conn)
except OSError:
pass
return
if not self.authed and not (self.files is not None and self.files.authed):
try:
self.ble.gap_disconnect(self.conn)
except OSError:
pass
def notify_now(self, data):
"""Send while unauthenticated (small replies); failures are ignored."""
if self.conn is None:
return
size = self.mtu - 3
for i in range(0, len(data), size):
try:
self.ble.gatts_notify(self.conn, self.tx_handle, data[i : i + size])
except OSError:
return
def send(self, data):
if self.conn is None or not self.authed:
return
self.tx.extend(data)
self.flush()
if len(self.tx) > self.TX_CAP:
import time
# A program printing faster than the link carries: wait for it,
# but never forever, because print() can't fail.
deadline = time.ticks_add(time.ticks_ms(), 2000)
while len(self.tx) > self.TX_CAP and self.conn is not None:
if time.ticks_diff(deadline, time.ticks_ms()) <= 0:
self.dropped_out += len(self.tx) - self.TX_CAP
self.tx = self.tx[: self.TX_CAP]
break
time.sleep_ms(2)
self.flush()
def flush(self):
# The timer's callback runs between the main program's
# bytecodes, so it can land inside a flush() that print() started.
# Two flushes interleaved sent one chunk twice and dropped the next,
# so the second one leaves the work to the first.
if self.flushing:
return
self.flushing = True
try:
size = self.mtu - 3
while self.tx and self.conn is not None:
chunk = self.tx[:size]
try:
self.ble.gatts_notify(self.conn, self.tx_handle, chunk)
except OSError:
return # the controller's buffers are full; _tick retries
self.tx = self.tx[len(chunk) :]
finally:
self.flushing = False
def ft_flush(self):
# File-transfer answers, one notification at a time; what the
# controller can't take yet waits for the next tick. Main thread only,
# but guarded like flush() against a tick landing inside it.
if self.ft_flushing:
return
self.ft_flushing = True
try:
size = self.mtu - 3
files = self.files
while self.conn is not None:
packet = files.packet(size)
if packet is None:
return
try:
self.ble.gatts_notify(self.conn, self.ft_handle, packet)
except OSError:
return
files.sent()
finally:
self.ft_flushing = False
class _Open:
"""The gate when pairing is the lock: the client's first line (the empty
one every client sends to ask for a prompt) gets the banner and ``>>>``,
and isn't passed to the REPL, so the client sees exactly one prompt."""
refused = False
verdict = None
def feed(self, data):
if self.refused:
return b"", False, b""
for i in range(len(data)):
if data[i] in (10, 13):
rest = bytes(data[i + 1 :])
if data[i] == 13 and rest[:1] == b"\n":
rest = rest[1:]
self.verdict = True
return BANNER, True, rest
return b"", None, b""
class _Gate(Login):
refused = False
def feed(self, data):
if self.refused:
return b"", False, b""
return Login.feed(self, data)
def _irq(event, data):
s = _server
if s is None or not s.running:
return None
if event == 1: # _IRQ_CENTRAL_CONNECT
s.on_connect(data[0])
elif event == 2: # _IRQ_CENTRAL_DISCONNECT
s.on_disconnect(data[0])
_tidy_aioble(data[0])
elif event == 3: # _IRQ_GATTS_WRITE
conn, handle = data
if handle == s.rx_handle:
s.on_write(conn, bytes(s.ble.gatts_read(handle)))
elif handle == s.ft_handle:
s.on_files(conn, bytes(s.ble.gatts_read(handle)))
elif handle == s.auth_handle:
s.on_auth(conn, bytes(s.ble.gatts_read(handle)))
elif event == 21: # _IRQ_MTU_EXCHANGED
s.on_mtu(data[0], data[1])
return None
def _arm_aioble():
# aioble's peripheral IRQ signals its advertise() on every incoming
# connection and raises if advertise() never ran, which would stop the
# IRQ reaching us. Give it something to signal.
try:
import asyncio
from aioble import peripheral
except ImportError:
return
if peripheral._connect_event is None:
peripheral._connect_event = asyncio.ThreadSafeFlag()
def _tidy_aioble(conn):
# aioble's peripheral IRQ records every incoming connection, expecting its
# own advertise() to start a task that forgets it on disconnect. Ours
# never went through advertise(), so forget it here.
try:
from aioble import peripheral
from aioble.device import DeviceConnection
except ImportError:
return
connection = DeviceConnection._connected.pop(conn, None)
if connection is not None:
connection._conn_handle = None
connection.device._connection = None
if peripheral._incoming_connection is connection:
peripheral._incoming_connection = None
if peripheral._connect_event is not None:
try:
peripheral._connect_event.clear()
except AttributeError:
pass
# ---------------------------------------------------------------- the client side
async def _expect(link, markers, buffer, timeout_ms):
"""Read until one of ``markers`` appears; return (marker, everything read)."""
while True:
for marker in markers:
if marker in buffer:
return marker, buffer
chunk = await wait_ms(link.read(), timeout_ms, "waiting for {!r}".format(markers[0]))
if not chunk:
return None, buffer
buffer.extend(chunk)
[docs]
def refused(pair, passkey):
"""The `bledev.PairingError` for a board that refused a link."""
if not pair:
return PairingError("the board wants pairing: connect with pair=True")
if passkey is None:
return PairingError("the board wants a link paired with a passkey (pass passkey=), or " + STALE_BOND)
return PairingError(STALE_BOND)
[docs]
async def connect(ble, password=None, name=None, *, device=None, timeout_ms=10000, pair=False, passkey=None, **connect_options):
"""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.
"""
try:
link = await nus.connect(ble, name=name, device=device, timeout_ms=timeout_ms, pair=pair, passkey=passkey, **connect_options)
except GattError as e:
if e.status in NEEDS_PAIRING:
raise refused(pair, passkey)
raise
try:
buffer = bytearray()
try:
await link.write(b"\r")
except GattError as e:
if e.status not in NEEDS_PAIRING:
raise
raise refused(pair, passkey)
marker, buffer = await _expect(link, (PROMPT, b">>> ", BUSY.strip()), buffer, timeout_ms)
if marker == BUSY.strip():
raise BLEError("the board's REPL is busy: another console (WebREPL?) holds it")
if marker is None:
raise BLEError("the board closed the link before asking for a password")
if marker == PROMPT:
if password is None:
raise AuthError("the board wants a password")
# Rebind rather than delete a slice: MicroPython's bytearray can't.
buffer = buffer[buffer.find(PROMPT) + len(PROMPT) :]
secret = password.encode() if isinstance(password, str) else bytes(password)
await link.write(secret + b"\r")
marker, buffer = await _expect(link, (b">>> ", DENIED.strip(), BUSY.strip()), buffer, timeout_ms)
if marker == BUSY.strip():
raise BLEError("the board's REPL is busy: another console (WebREPL?) holds it")
if marker != b">>> ":
raise AuthError("the board refused the password")
except BaseException:
await link.close()
raise
return link
[docs]
async def run(link, code, timeout_ms=10000):
"""Type ``code`` at the prompt and return what it printed, up to the next ``>>>``."""
line = code.encode() if isinstance(code, str) else bytes(code)
await link.write(line + b"\r")
marker, buffer = await _expect(link, (b">>> ",), bytearray(), timeout_ms)
if marker is None:
raise BLEError("the link closed while running {!r}".format(code))
text = bytes(buffer[: buffer.rfind(b">>> ")]).decode("utf-8", "replace")
# Drop the echoed command.
first = text.find("\n")
return text[first + 1 :] if first >= 0 else ""