# SPDX-FileCopyrightText: 2026 Brad Barnett
#
# SPDX-License-Identifier: MIT
"""Files over Bluetooth: CircuitPython's BLE file-transfer protocol, both sides.
CircuitPython boards serve this protocol from their supervisor
(``supervisor/shared/bluetooth/file_transfer.c``). This module lets a
MicroPython board serve it too, so one client reaches files on either
interpreter. The protocol is Adafruit's, documented with their client in
`Adafruit_CircuitPython_BLE_File_Transfer
<https://github.com/adafruit/Adafruit_CircuitPython_BLE_File_Transfer>`_:
service ``0xFEBB``, a version characteristic, and one transfer
characteristic that the client writes commands to and the board answers on
with notifications. It reads, writes (at an offset), deletes, makes
directories, lists them and moves, and the board paces every write with a
"free space" count so it never receives more than it can hold.
On the board, opt in from ``main.py`` (nothing starts it for you)::
import bledev.filetransfer
bledev.filetransfer.start(password="correct horse", name="rack")
It's served beside the REPL of `bledev.repl` by default (``console=False``
serves files alone), from interrupts, so it keeps working at the ``>>>``
prompt and while your program runs. From a laptop or another board::
import bledev.filetransfer as ft
files = await ft.connect(ble, "correct horse", name="rack")
await files.write("/hello.txt", b"hi")
print(await files.read("/hello.txt"), await files.listdir("/"))
**The lock.** CircuitPython protects the transfer characteristic with
pairing. bledev uses the REPL's password by default, the same way WebREPL
does: the service carries one more characteristic (``AUTH``), the client
writes the password to it, and until it's right every command is answered
with `STATUS_LOCKED`. One attempt per connection; a wrong password is
hung up on. Logging in to the REPL over the same connection unlocks files
too. Without pairing the link isn't encrypted, so a sniffer nearby can capture
the password.
``start(pairing=...)`` adds pairing, as for `bledev.repl`: the transfer
and ``AUTH`` characteristics then refuse a host that hasn't paired, and with
a passkey the password can go (``password=False``). ``AUTH`` then reads 1
once the link is paired. A client connecting to a CircuitPython board finds
no ``AUTH`` characteristic, pairs ("just works", as CircuitPython asks) and
skips the password.
The protocol carries no checksum of its own beyond the link layer's CRC, so a
client that must be sure checks what landed (mcuctl compares SHA-256).
"""
import asyncio
import struct
from . import (
BLEError,
BLETimeoutError,
DisconnectedError,
GattError,
NEEDS_PAIRING,
UnsupportedError,
UUID,
connect_and_set_up,
wait_ms,
)
SERVICE = UUID(0xFEBB)
VERSION = UUID("adaf0100-4669-6c65-5472-616e73666572")
TRANSFER = UUID("adaf0200-4669-6c65-5472-616e73666572")
#: bledev's addition: write the password here. CircuitPython has no such
#: characteristic (it uses pairing), which is how a client tells them apart.
AUTH = UUID("adaf0300-4669-6c65-5472-616e73666572")
#: The protocol version this server speaks (CircuitPython 9 and 10 serve 4).
PROTOCOL_VERSION = 4
READ = 0x10
READ_DATA = 0x11
READ_PACING = 0x12
WRITE = 0x20
WRITE_PACING = 0x21
WRITE_DATA = 0x22
DELETE = 0x30
DELETE_STATUS = 0x31
MKDIR = 0x40
MKDIR_STATUS = 0x41
LISTDIR = 0x50
LISTDIR_ENTRY = 0x51
MOVE = 0x60
MOVE_STATUS = 0x61
STATUS_OK = 0x01
STATUS_ERROR = 0x02
STATUS_ERROR_NO_FILE = 0x03
STATUS_ERROR_PROTOCOL = 0x04
STATUS_ERROR_READONLY = 0x05
#: bledev only: nothing is served until the password is right.
STATUS_LOCKED = 0x80
FLAG_DIRECTORY = 0x01
# Every header, little-endian and packed. Reserved fields are sent as zero.
_READ = "<BBHII" # command, 0, path length, offset, chunk size; path follows
_READ_DATA = "<BBHIII" # command, status, 0, offset, total length, data size; data follows
_READ_PACING = "<BBHII" # command, status, 0, offset, chunk size
_WRITE = "<BBHIQI" # command, 0, path length, offset, time (ns), total length; path follows
_WRITE_PACING = "<BBHIQI" # command, status, 0, offset, time (ns), free space
_WRITE_DATA = "<BBHII" # command, status, 0, offset, data size; data follows
_PATH = "<BBH" # DELETE and LISTDIR: command, 0, path length; path follows
_MKDIR = "<BBHIQ" # command, 0, path length, 0, time (ns); path follows
_MKDIR_STATUS = "<BBHIQ" # command, status, 0, 0, time (ns)
_ENTRY = "<BBHIIIQI" # command, status, path length, number, count, flags, time, size; name follows
_MOVE = "<BBHH" # command, 0, old length, new length; old, one spare byte, new follow
_STATUS = "<BB" # DELETE_STATUS and MOVE_STATUS
#: The shape of each command's answer, so even a refusal is one a client can parse.
_ANSWER = {
READ: (READ_DATA, _READ_DATA),
READ_PACING: (READ_DATA, _READ_DATA),
WRITE: (WRITE_PACING, _WRITE_PACING),
WRITE_DATA: (WRITE_PACING, _WRITE_PACING),
DELETE: (DELETE_STATUS, _STATUS),
MKDIR: (MKDIR_STATUS, _MKDIR_STATUS),
LISTDIR: (LISTDIR_ENTRY, _ENTRY),
MOVE: (MOVE_STATUS, _STATUS),
}
#: How much a writing client may send before the board says "more": the free
#: space in each WRITE_PACING. CircuitPython offers one 512-byte sector at a
#: time; a bigger window means fewer round trips (see docs/how-it-works/bledev-internals.md).
WINDOW = 4096
#: The longest path the board accepts, in bytes (CircuitPython's is about 1 KB).
MAX_PATH = 256
[docs]
class FileTransferError(BLEError):
"""The board answered with an error status (``.status``)."""
def __init__(self, status, message):
super().__init__(message)
self.status = status
[docs]
class AuthError(BLEError):
"""The board refused the password, or wants one and none was given."""
def _answer(command, status, *values):
code, fmt = _ANSWER[command]
fields = [code, status] + [0] * (len(struct.unpack(fmt, bytes(struct.calcsize(fmt)))) - 2)
for i, value in enumerate(values):
fields[2 + i] = value
return struct.pack(fmt, *fields)
def _errno(e):
return e.args[0] if e.args and isinstance(e.args[0], int) else getattr(e, "errno", None)
def _status_for(e):
return STATUS_ERROR_READONLY if _errno(e) == 30 else STATUS_ERROR # EROFS
def _epoch_offset():
# os.stat() times count from the port's epoch, which is 2000 on some
# MicroPython ports; the protocol counts from 1970.
try:
import time
return -time.mktime((1970, 1, 1, 0, 0, 0, 0, 0))
except Exception:
return 0
_EPOCH = None
def _ns(seconds):
global _EPOCH
if _EPOCH is None:
import sys
_EPOCH = _epoch_offset() if sys.implementation.name == "micropython" else 0
return (int(seconds) + _EPOCH) * 1000000000
class _Out:
"""One answer waiting to go out: a header, then maybe part of a file."""
def __init__(self, head, f=None, pos=0, size=0, close=False):
self.head = head
self.f = f
self.pos = pos
self.size = size
self.close = close
[docs]
class FileServer:
"""The protocol, without a radio, so it runs and is tested anywhere.
``feed()`` takes what the client wrote to the transfer characteristic, in
any split; ``packet(n)`` gives the next notification (at most ``n`` bytes,
never spanning two answers, as CircuitPython's clients expect) and
``sent()`` says it went out. ``root`` is prepended to every path (tests
serve a scratch directory); ``window`` is the free space offered per
round trip.
"""
def __init__(self, root="", window=WINDOW):
self.root = root.rstrip("/")
self.window = window
self.authed = False
self.changed = 0
self._buf = bytearray()
self._out = []
self._pending = None
self._expect = None
self._file = None
self._total = 0
self._offset = 0
self._time = 0
self._path = None
# -- the radio side
[docs]
def reset(self):
"""Forget the transfer in progress and everything queued (the connection
closed). ``authed`` is the caller's to clear."""
self._abort()
for item in self._out:
if item.close and item.f is not None:
item.f.close()
self._out = []
self._pending = None
self._buf = bytearray()
def feed(self, data):
self._buf.extend(data)
while self._buf:
used = self._step(self._buf)
if not used:
break
self._buf = self._buf[used:]
def has_output(self):
return self._pending is not None or bool(self._out)
[docs]
def packet(self, size):
"""The next notification's payload (``None`` when nothing is waiting).
The same bytes come back until `sent` is called, so a send that
failed for want of buffers is simply retried.
"""
if self._pending is not None:
return self._pending
while self._out:
item = self._out[0]
data = bytes(item.head[:size])
item.head = item.head[len(data) :]
room = size - len(data)
if room and item.size:
n = min(room, item.size)
item.f.seek(item.pos)
chunk = item.f.read(n)
if not chunk:
item.size = 0 # the file got shorter; the client will notice
else:
data += chunk
item.pos += len(chunk)
item.size -= len(chunk)
if not item.head and not item.size:
self._out.pop(0)
if item.close and item.f is not None:
item.f.close()
if data:
self._pending = data
return data
return None
def sent(self):
self._pending = None
# -- the protocol
def _path_at(self, buf, start, length):
path = bytes(buf[start : start + length]).decode()
return self.root + path
def _send(self, head, f=None, pos=0, size=0, close=False):
self._out.append(_Out(head, f, pos, size, close))
def _abort(self):
f = self._file
if f is not None:
# A read's chunk may still be going out; let it close the file.
for item in self._out:
if item.f is f:
item.close = True
break
else:
try:
f.close()
except OSError:
pass
self._file = None
self._expect = None
def _step(self, buf):
"""Handle the command at the head of ``buf``; return the bytes used, 0 if incomplete."""
command = buf[0]
if command not in _ANSWER:
self._abort()
return len(buf) # nothing to resynchronise on; drop what's buffered
need = self._needed(command, buf)
if need is None:
return 0
if need < 0:
# A length no answer could fit (over MAX_PATH, or more data than
# the window offered): refuse it and drop the stream.
self._send(_answer(command, STATUS_ERROR_PROTOCOL))
self._abort()
return len(buf)
if len(buf) < need:
return 0
if not self.authed:
self._send(_answer(command, STATUS_LOCKED))
return need
if command & 0x0F:
if command != self._expect:
# A continuation of a transfer that isn't running.
self._send(_answer(command, STATUS_ERROR_PROTOCOL))
self._abort()
return need
else:
self._abort() # a new command abandons a transfer in progress
getattr(self, "_do_{:02x}".format(command))(buf)
return need
def _needed(self, command, buf):
fixed = {
READ: 12,
READ_PACING: 12,
WRITE: 20,
WRITE_DATA: 12,
DELETE: 4,
MKDIR: 16,
LISTDIR: 4,
MOVE: 6,
}[command]
if len(buf) < fixed:
return None
if command in (READ, WRITE, DELETE, LISTDIR, MKDIR):
extra = struct.unpack_from("<H", buf, 2)[0]
limit = MAX_PATH
elif command == WRITE_DATA:
extra = struct.unpack_from("<I", buf, 8)[0]
limit = self.window
elif command == MOVE:
old, new = struct.unpack_from("<HH", buf, 2)
extra = old + 1 + new
limit = 2 * MAX_PATH + 1
else:
return fixed
return fixed + extra if extra <= limit else -1
# READ
def _do_10(self, buf):
_, _, length, offset, chunk = struct.unpack_from(_READ, buf)
path = self._path_at(buf, 12, length)
try:
import os
if os.stat(path)[0] & 0x4000:
raise OSError(21)
f = open(path, "rb")
total = os.stat(path)[6]
except OSError:
self._send(_answer(READ, STATUS_ERROR))
return
self._file = f
self._total = total
self._read_chunk(offset, chunk)
# READ_PACING
def _do_12(self, buf):
_, _, _, offset, chunk = struct.unpack_from(_READ_PACING, buf)
self._read_chunk(offset, chunk)
def _read_chunk(self, offset, chunk):
total = self._total
offset = min(offset, total)
size = min(chunk, total - offset)
last = offset + size >= total
head = struct.pack(_READ_DATA, READ_DATA, STATUS_OK, 0, offset, total, size)
self._send(head, self._file, offset, size, close=last)
if last:
self._file = None
self._expect = None
else:
self._expect = READ_PACING
# WRITE
def _do_20(self, buf):
_, _, length, offset, when, total = struct.unpack_from(_WRITE, buf)
path = self._path_at(buf, 20, length)
import os
try:
try:
size = os.stat(path)[6]
except OSError:
size = -1
if offset == 0 or size < 0:
f = open(path, "wb")
size = 0
else:
f = open(path, "r+b")
if offset > size:
f.seek(size)
gap = offset - size
while gap:
n = min(gap, 512)
f.write(bytes(n))
gap -= n
except OSError as e:
self._send(_answer(WRITE, _status_for(e)))
return
self._file = f
self._path = path
self._total = total
self._time = when
self._offset = offset
self._expect = WRITE_DATA
self._pace(offset)
# WRITE_DATA
def _do_22(self, buf):
_, status, _, offset, size = struct.unpack_from(_WRITE_DATA, buf)
f = self._file
if status != STATUS_OK or offset != self._offset or size > self.window or offset + size > self._total:
self._send(_answer(WRITE_DATA, STATUS_ERROR_PROTOCOL if status == STATUS_OK else STATUS_ERROR))
self._abort()
return
try:
f.seek(offset)
f.write(memoryview(buf)[12 : 12 + size])
except OSError as e:
self._send(_answer(WRITE_DATA, _status_for(e)))
self._abort()
return
self._offset = offset + size
self._pace(self._offset)
def _pace(self, offset):
free = min(self._total - offset, self.window)
when = self._time
if not free:
try:
self._finish_write()
when = self._stored_time()
except OSError as e:
self._send(_answer(WRITE_DATA, _status_for(e)))
self._abort()
return
self._send(struct.pack(_WRITE_PACING, WRITE_PACING, STATUS_OK, 0, offset, when, free))
def _finish_write(self):
import os
f, self._file, self._expect = self._file, None, None
f.close()
self.changed += 1
if os.stat(self._path)[6] > self._total:
_truncate(self._path, self._total)
def _stored_time(self):
import os
try:
return _ns(os.stat(self._path)[8])
except OSError:
return self._time
# DELETE
def _do_30(self, buf):
length = struct.unpack_from(_PATH, buf)[2]
path = self._path_at(buf, 4, length).rstrip("/") or "/"
try:
_remove(path)
status = STATUS_OK
self.changed += 1
except OSError as e:
status = _status_for(e)
self._send(struct.pack(_STATUS, DELETE_STATUS, status))
# MKDIR
def _do_40(self, buf):
_, _, length, _, when = struct.unpack_from(_MKDIR, buf)
path = self._path_at(buf, 16, length).rstrip("/")
import os
status = STATUS_OK
try:
_makedirs(path)
when = _ns(os.stat(path)[8])
self.changed += 1
except OSError as e:
status = _status_for(e)
self._send(struct.pack(_MKDIR_STATUS, MKDIR_STATUS, status, 0, 0, when))
# LISTDIR
def _do_50(self, buf):
import os
length = struct.unpack_from(_PATH, buf)[2]
path = self._path_at(buf, 4, length).rstrip("/") or "/"
try:
if not os.stat(path)[0] & 0x4000:
raise OSError(20)
names = sorted(os.listdir(path))
except OSError:
self._send(_answer(LISTDIR, STATUS_ERROR_NO_FILE))
return
count = len(names)
prefix = path if path.endswith("/") else path + "/"
for i, name in enumerate(names):
try:
st = os.stat(prefix + name)
except OSError:
st = (0, 0, 0, 0, 0, 0, 0, 0, 0, 0)
directory = bool(st[0] & 0x4000)
raw = name.encode()
head = struct.pack(
_ENTRY,
LISTDIR_ENTRY,
STATUS_OK,
len(raw),
i,
count,
FLAG_DIRECTORY if directory else 0,
_ns(st[8]),
0 if directory else st[6],
)
# One answer per entry: CircuitPython's own client expects an
# entry's header to start a notification.
self._send(head + raw)
self._send(struct.pack(_ENTRY, LISTDIR_ENTRY, STATUS_OK, 0, count, count, 0, 0, 0))
# MOVE
def _do_60(self, buf):
import os
_, _, old, new = struct.unpack_from(_MOVE, buf)
src = self._path_at(buf, 6, old)
dst = self._path_at(buf, 6 + old + 1, new)
try:
os.rename(src, dst)
status = STATUS_OK
self.changed += 1
except OSError as e:
status = _status_for(e)
self._send(struct.pack(_STATUS, MOVE_STATUS, status))
def _remove(path):
import os
if os.stat(path)[0] & 0x4000:
prefix = path if path.endswith("/") else path + "/"
for name in os.listdir(path):
_remove(prefix + name)
os.rmdir(path)
else:
os.remove(path)
def _makedirs(path):
import os
try:
mode = os.stat(path)[0]
except OSError:
parent = path[: path.rfind("/")]
if parent:
_makedirs(parent)
os.mkdir(path)
return
if not mode & 0x4000:
raise OSError(17) # a file is in the way
def _truncate(path, size):
# MicroPython's files can't truncate, so copy the part that stays.
import os
tmp = path + ".bledev-tmp"
with open(path, "rb") as src, open(tmp, "wb") as dst:
left = size
while left:
chunk = src.read(min(left, 1024))
if not chunk:
break
dst.write(chunk)
left -= len(chunk)
os.remove(path)
os.rename(tmp, path)
# ---------------------------------------------------------------- the board side
[docs]
def start(password=None, name=None, *, console=True, window=WINDOW, **options):
"""Serve files (and, unless ``console=False``, the REPL) over BLE. MicroPython only.
The board advertises as ``name``, by default its own, ``boarddev.name()``.
The radio, the password and the advertising are `bledev.repl`'s;
this is ``bledev.repl.start(..., files=True)``. Returns at once;
`stop` or ``bledev.repl.stop()`` ends it.
"""
from . import repl
return repl.start(password, name, files=True, console=console, window=window, **options)
def stop():
from . import repl
repl.stop()
# ---------------------------------------------------------------- the client side
[docs]
class Client:
"""A connection to a board's file service. Made by `connect`.
Paths are absolute (``/lib/x.py``). Every method raises
`FileTransferError` when the board answers with an error, and
`DisconnectedError` if the link drops.
"""
def __init__(self, connection, transfer, version, *, chunk=WINDOW):
self.connection = connection
self.version = version
self.chunk = chunk
#: How long to wait for each part of an answer.
self.timeout_ms = 10000
self._transfer = transfer
self._buf = bytearray()
self._event = asyncio.Event()
self._closed = False
self._no_response = bool(transfer.properties & 0x0004) if transfer is not None else True
self._pump = asyncio.create_task(self._receive()) if transfer is not None else None
self.bytes_in = 0
self.bytes_out = 0
async def _receive(self):
try:
while True:
self._feed(await self._transfer.notified())
except DisconnectedError:
pass
finally:
self._closed = True
self._event.set()
def _feed(self, data):
self._buf.extend(data)
self.bytes_in += len(data)
self._event.set()
async def _send(self, data):
size = max(1, self.connection.mtu - 3)
for i in range(0, len(data), size):
if not self.connection.is_connected():
raise DisconnectedError("the board hung up")
await self._transfer.write(data[i : i + size], response=not self._no_response)
self.bytes_out += len(data)
async def _recv(self, n):
while len(self._buf) < n:
if self._closed:
raise DisconnectedError("the board hung up mid-answer")
self._event.clear()
await wait_ms(self._event.wait(), self.timeout_ms, "the board's answer")
data = bytes(self._buf[:n])
self._buf = self._buf[n:]
return data
async def _header(self, fmt, code):
data = await self._recv(struct.calcsize(fmt))
fields = struct.unpack(fmt, data)
if fields[0] != code:
raise FileTransferError(STATUS_ERROR_PROTOCOL, "expected answer 0x{:02x}, got 0x{:02x}".format(code, fields[0]))
return fields
@staticmethod
def _check(status, what):
if status == STATUS_OK:
return
if status == STATUS_LOCKED:
raise AuthError("{}: the board wants the password first".format(what))
text = {
STATUS_ERROR_NO_FILE: "no such file or directory",
STATUS_ERROR_PROTOCOL: "protocol error",
STATUS_ERROR_READONLY: "the filesystem is read-only",
}.get(status, "failed")
raise FileTransferError(status, "{}: {} (status 0x{:02x})".format(what, text, status))
[docs]
async def read(self, path, offset=0):
"""The file's contents from ``offset`` on."""
raw = path.encode()
chunk = self.chunk
await self._send(struct.pack(_READ, READ, 0, len(raw), offset, chunk) + raw)
out = bytearray()
while True:
_, status, _, at, total, size = await self._header(_READ_DATA, READ_DATA)
self._check(status, "read " + path)
out.extend(await self._recv(size))
at += size
if at >= total or not size:
return bytes(out)
await self._send(struct.pack(_READ_PACING, READ_PACING, STATUS_OK, 0, at, min(chunk, total - at)))
[docs]
async def write(self, path, data, offset=0, modification_time=None):
"""Write ``data`` at ``offset`` (the file ends after it). Returns the stored time in ns."""
raw = path.encode()
data = memoryview(bytes(data))
total = offset + len(data)
if modification_time is None:
modification_time = _now_ns()
await self._send(struct.pack(_WRITE, WRITE, 0, len(raw), offset, modification_time, total) + raw)
while True:
_, status, _, at, when, free = await self._header(_WRITE_PACING, WRITE_PACING)
self._check(status, "write " + path)
if at < offset or at > total:
raise FileTransferError(STATUS_ERROR_PROTOCOL, "write {}: the board asked for offset {}".format(path, at))
if not free:
if at != total:
raise FileTransferError(STATUS_ERROR_PROTOCOL, "write {}: stopped at {} of {}".format(path, at, total))
return when
n = min(free, total - at)
start = at - offset
await self._send(struct.pack(_WRITE_DATA, WRITE_DATA, STATUS_OK, 0, at, n) + bytes(data[start : start + n]))
[docs]
async def delete(self, path):
"""Delete a file, or a directory and everything in it."""
raw = path.encode()
await self._send(struct.pack(_PATH, DELETE, 0, len(raw)) + raw)
_, status = await self._header(_STATUS, DELETE_STATUS)
self._check(status, "delete " + path)
[docs]
async def mkdir(self, path, modification_time=None):
"""Make a directory and any missing parents. Returns the stored time in ns."""
raw = path.encode()
if modification_time is None:
modification_time = _now_ns()
await self._send(struct.pack(_MKDIR, MKDIR, 0, len(raw), 0, modification_time) + raw)
_, status, _, _, when = await self._header(_MKDIR_STATUS, MKDIR_STATUS)
self._check(status, "mkdir " + path)
return when
[docs]
async def listdir(self, path):
"""``[(name, size, is_directory, modification_time_ns), ...]``."""
raw = path.encode()
await self._send(struct.pack(_PATH, LISTDIR, 0, len(raw)) + raw)
entries = []
while True:
_, status, length, number, count, flags, when, size = await self._header(_ENTRY, LISTDIR_ENTRY)
self._check(status, "listdir " + path)
if number >= count:
return entries
name = (await self._recv(length)).decode()
entries.append((name, size, bool(flags & FLAG_DIRECTORY), when))
[docs]
async def move(self, old, new):
"""Rename or move a file or directory (protocol version 4)."""
if self.version is not None and self.version < 4:
raise UnsupportedError("move needs protocol version 4; the board has {}".format(self.version))
a = old.encode()
b = new.encode()
await self._send(struct.pack(_MOVE, MOVE, 0, len(a), len(b)) + a + b" " + b)
_, status = await self._header(_STATUS, MOVE_STATUS)
self._check(status, "move {} to {}".format(old, new))
async def close(self):
if self.connection is not None and self.connection.is_connected():
await self.connection.disconnect()
self._closed = True
self._event.set()
def _now_ns():
import time
try:
return time.time_ns()
except AttributeError:
return _ns(time.time())
[docs]
async def connect(ble, password=None, name=None, *, device=None, timeout_ms=10000, mtu=247, pair=None, passkey=None, **connect_options):
"""Find a board serving files (by ``name``, or the first advertising the
service), connect, log in, and return a `Client`.
``password`` is needed for a bledev board locked by one, and ignored by
a CircuitPython board, which uses pairing instead.
``pair``: ``True`` pairs first; ``None`` (the default) pairs when the
board asks for it, which a CircuitPython board always does and a bledev
board started with ``pairing=`` does; ``False`` never pairs. ``passkey``
is what the board's display shows, or a callable that asks for it.
"""
from . import nus
ble = nus._adapter(ble)
nus._set_mtu(ble, mtu)
async def setup(connection):
try:
await connection.exchange_mtu(mtu)
except (UnsupportedError, BLETimeoutError):
pass
service = await connection.service(SERVICE)
if service is None:
raise BLEError("{!r} has no file transfer service".format(connection.device))
transfer = await service.characteristic(TRANSFER)
if transfer is None:
raise BLEError("{!r}: the file transfer service has no transfer characteristic".format(connection.device))
version = None
char = await service.characteristic(VERSION)
if char is not None:
try:
version = struct.unpack("<I", (await char.read())[:4])[0]
except (BLEError, ValueError):
pass
auth = await service.characteristic(AUTH)
# Does the board want pairing? CircuitPython (no AUTH) always does. A
# bledev board with pairing on refuses to let AUTH be read.
locked = None
wants = auth is None
if auth is not None:
try:
locked = (await auth.read())[:1] != b"\x01"
except GattError as e:
if e.status not in NEEDS_PAIRING:
raise
wants = True
return transfer, version, auth, wants, locked
connection, (transfer, version, auth, wants, locked) = await connect_and_set_up(
ble, setup, name=name, service=SERVICE, device=device, timeout_ms=timeout_ms, pair=pair is True, passkey=passkey, **connect_options
)
try:
if wants and pair is None and not connection.encrypted:
await connection.pair(passkey=passkey)
try:
await transfer.subscribe(notify=True)
if auth is not None and (locked is None or wants):
locked = (await auth.read())[:1] != b"\x01"
if locked and password is None and connection.encrypted:
# The board unlocks on its own encryption event, which
# can land a moment after this side's pair() returned.
for _ in range(10):
await asyncio.sleep(0.05)
locked = (await auth.read())[:1] != b"\x01"
if not locked:
break
except GattError as e:
if e.status not in NEEDS_PAIRING:
raise
from .repl import refused
raise refused(pair is not False, passkey)
except BaseException:
if connection.is_connected():
await connection.disconnect()
raise
client = Client(connection, transfer, version)
if auth is not None and locked:
try:
if password is None:
raise AuthError("the board wants a password")
secret = password.encode() if isinstance(password, str) else bytes(password)
await auth.write(secret, response=True)
if (await auth.read())[:1] != b"\x01":
raise AuthError("the board refused the password")
except BaseException:
await client.close()
raise
return client