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: BLEError

The board answered with an error status (.status).

exception bledev.filetransfer.AuthError[source]

Bases: BLEError

The board refused the password, or wants one and none was given.

class bledev.filetransfer.FileServer(root='', window=4096)[source]

Bases: object

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.

reset()[source]

Forget the transfer in progress and everything queued (the connection closed). authed is the caller’s to clear.

packet(size)[source]

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.

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 is bledev.repl.start(..., files=True). Returns at once; stop or bledev.repl.stop() ends it.

class bledev.filetransfer.Client(connection, transfer, version, *, chunk=4096)[source]

Bases: object

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.

timeout_ms

How long to wait for each part of an answer.

async read(path, offset=0)[source]

The file’s contents from offset on.

async write(path, data, offset=0, modification_time=None)[source]

Write data at offset (the file ends after it). Returns the stored time in ns.

async delete(path)[source]

Delete a file, or a directory and everything in it.

async mkdir(path, modification_time=None)[source]

Make a directory and any missing parents. Returns the stored time in ns.

async listdir(path)[source]

[(name, size, is_directory, modification_time_ns), ...].

async move(old, new)[source]

Rename or move a file or directory (protocol version 4).

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 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.