bledev.filetransfer
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:
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).
- bledev.filetransfer.AUTH = UUID('adaf0300-4669-6c65-5472-616e73666572')
write the password here. CircuitPython has no such characteristic (it uses pairing), which is how a client tells them apart.
- Type:
bledev’s addition
- bledev.filetransfer.PROTOCOL_VERSION = 4
The protocol version this server speaks (CircuitPython 9 and 10 serve 4).
- bledev.filetransfer.STATUS_LOCKED = 128
nothing is served until the password is right.
- Type:
bledev only
- bledev.filetransfer.WINDOW = 4096
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).
- Type:
How much a writing client may send before the board says “more”
- bledev.filetransfer.MAX_PATH = 256
The longest path the board accepts, in bytes (CircuitPython’s is about 1 KB).
- exception bledev.filetransfer.FileTransferError(status, message)[source]
Bases:
BLEErrorThe board answered with an error status (
.status).
- exception bledev.filetransfer.AuthError[source]
Bases:
BLEErrorThe board refused the password, or wants one and none was given.
- class bledev.filetransfer.FileServer(root='', window=4096)[source]
Bases:
objectThe 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 mostnbytes, never spanning two answers, as CircuitPython’s clients expect) andsent()says it went out.rootis prepended to every path (tests serve a scratch directory);windowis the free space offered per round trip.
- bledev.filetransfer.start(password=None, name=None, *, console=True, window=4096, **options)[source]
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 isbledev.repl.start(..., files=True). Returns at once;stoporbledev.repl.stop()ends it.
- class bledev.filetransfer.Client(connection, transfer, version, *, chunk=4096)[source]
Bases:
objectA connection to a board’s file service. Made by
connect.Paths are absolute (
/lib/x.py). Every method raisesFileTransferErrorwhen the board answers with an error, andDisconnectedErrorif the link drops.- timeout_ms
How long to wait for each part of an answer.
- async write(path, data, offset=0, modification_time=None)[source]
Write
dataatoffset(the file ends after it). Returns the stored time in ns.
- async bledev.filetransfer.connect(ble, password=None, name=None, *, device=None, timeout_ms=10000, mtu=247, pair=None, passkey=None, **connect_options)[source]
Find a board serving files (by
name, or the first advertising the service), connect, log in, and return aClient.passwordis needed for a bledev board locked by one, and ignored by a CircuitPython board, which uses pairing instead.pair:Truepairs first;None(the default) pairs when the board asks for it, which a CircuitPython board always does and a bledev board started withpairing=does;Falsenever pairs.passkeyis what the board’s display shows, or a callable that asks for it.