Bound the BLE connect and file-read waits so they report instead of hanging

[dhalbert]

🤖 Generated with Claude Code

Draft: two of the four commits are not yet verified against hardware. See Testing.

The BLE connect flow had several waits with no upper bound, so a failure that should have been reported instead left the editor sitting there indefinitely. This does not make any of the underlying failures go away — most of them are host-side and not ours to fix — it makes them report instead of hang.

What was unbounded

Waiting for an advertisement before connecting. connectToBluetoothDevice() armed watchAdvertisements() and only called gatt.connect() from the advertisementreceived handler. That event is never delivered on Linux: measured 0 events in 45 s while BlueZ concurrently received 38 advertising reports from the same board. It is unimplemented rather than broken — Chromium's BlueZ backend gates advertisement delivery on an EIR D-Bus property that exists only in the ChromeOS fork, Web Bluetooth on Linux is officially "partially implemented and not supported", and watchAdvertisements() is marked "No longer pursuing". So on Linux the connect was never attempted at all, which is the "device chooser works, nothing happens afterwards" symptom.

gatt.connect() itself. Chrome bounds this at roughly 41 s on Linux normally, but not while a watchAdvertisements() watch is armed — in that state the promise simply never settles, observed over two minutes with no connection attempt in progress at the BlueZ level. It is now raced against a timer and cancelled with gatt.disconnect(), which Chrome has honoured as a cancel since M140.

The same call in _attemptSilentReconnect(). Easy to miss and arguably the worse of the two, since CircuitPython autoreloads after every mutating file operation and that reconnect ladder therefore runs after every save. An unbounded connect there stalls the ladder, and the mutating op waits on it through awaitPostOpReconnect(), so a save spins with no way out.

A file read on a dead link. readFile() and listDir() could return a promise that nobody can settle, because upstream installs the reject handler after writing the request — see adafruit/ble-file-transfer-js#13. Guarded here on link liveness rather than a stopwatch, since a large file read over BLE can legitimately take tens of seconds while a dropped link is unambiguous. The device-info dialogs also now catch the rejection and say something, instead of leaving a blank dialog that reads as "the device answered with nothing".

Deliberate choice worth reviewing

The advertisement watch is now left armed across the connect and aborted only afterwards, rather than aborted first. On Linux the kernel only takes its working connect path while a discovery session is active — hci_update_passive_scan_sync() returns early when discovery.state != DISCOVERY_STOPPED, and otherwise installs an accept-list-filtered passive scan that never matches — and Chrome holds a discovery session for the lifetime of the watch. Other devices' watches are still aborted immediately so Chrome's per-device watch quota is not consumed.

This leans on Chrome-on-Linux implementation detail, not specified behaviour. It is commented as such.

Testing

Feather nRF52840 Express, CircuitPython 10.3.0-alpha.4, Chrome 151.

Verified: the bounded connect on Linux, where a failed attempt now reports an actionable error and re-enables the button instead of hanging; and the file-read guard, which stops the "Current Device Info" spinner. Both reproduced before and after.

Not verified against hardware: the shorter advertisement wait with its status message, and the bounded silent reconnect. Linux connects succeed on roughly a third of attempts for unrelated host reasons, which makes a latency change hard to observe deliberately, and the silent-reconnect path needs a specific failure to exercise. Hence draft.

Context

The Linux connect unreliability underneath all of this is a host defect, not something the editor can fix: the kernel frequently issues no create-connection at all for an unbonded peripheral, succeeding on about a third of attempts. Reported upstream without a fix in bluez#2309, bluez#2356, bleak#1244 and kernel bugzilla 199111, open since 2018. Chrome also registers no BlueZ pairing agent, so pairing cannot complete on Linux without one supplied externally; there is more detail in adafruit/circuitpython#11178.

Separate from this PR: #545 fixes Save As silently corrupting files, found during the same testing.

[dhalbert]

Claude wrote this:

Noting a related gap found during the same testing, not addressed in this PR.

FileTransferClient.readOnly() in js/common/ble-file-transfer.js never detects anything — it returns before its own check:

async readOnly() {
    let readonly = false;
    return false;
    // Check if the device is read only
    console.log("Checking if device is read only");
    // Attempt to write a 0-byte temp file and remove it
    const testPath = '/._ble_readonly_check';
    ...
}

Everything after the return false is unreachable. The other transports implement this for real — fsapi-file-transfer.js and repl-file-transfer.js both have working versions — so BLE is the exception rather than this being a convention.

The consequence is that when the board's filesystem is read-only to CircuitPython, which is the default whenever USB MSC is active, the editor reports it as writable and goes ahead with saves that cannot succeed. The device answers STATUS_ERROR_READONLY, the save retry loop runs its attempts, and the user eventually gets "Saving file ... failed after multiple attempts. Check your connection and try again." — which points at the connection, when the actual cause is that the drive is mounted over USB.

This is worth mentioning here because it made the failure hard to attribute during testing: repeated save failures over BLE looked like a bug in the write path, and it took a hex dump of the result to establish that nothing had been written at all and why.

The real check is not free — it writes and deletes a temp file on every connect — so short-circuiting it may well be deliberate. If so, the reporting is still worth improving: STATUS_ERROR_READONLY already comes back from the device on the first write attempt, so the message could name the real cause without any probing.