Fix a number of BLE workflow and bonding issues

[dhalbert]

🤖 Generated with Claude Code

Draft: I want to test espressif and make further commits before this is ready for review.

The original bug

Typing at the "Press any key to enter the REPL" prompt over the BLE workflow serial ended the session after exactly one character. The first byte breaks main.c's wait loop, which then calls bleio_reset(), and on nordic that restarts the SoftDevice. The bonding survives that restart; the link does not.

bleio_reset() now returns early when user code never imported _bleio. The stack restart is only there to drop leftover user-created GATT services, which the SoftDevice offers no way to remove individually, so it is unnecessary when the VM cannot have created any.

Reconnecting when the restart does have to happen

The peripheral now chooses its reconnect advertising strategy from what the bonded central distributed at pairing time:

Central	Distributes IRK + identity address	Strategy
iOS, macOS, Android	yes	undirected, private address (unchanged)
BlueZ (default Privacy=off), Windows	no	ADV_DIRECT_IND aimed at the address it connected from

A central that distributed no IRK is not using privacy. It cannot resolve our private address, so it will never recognise an undirected advertisement as us — but it does connect from a stable address, which we now store with the bond and can target. Centrals that do use privacy keep undirected advertising, which is what works for them and what Apple's accessory guidelines require.

Bugs found along the way

The commit message has the full list with details. In brief:

• the disconnect wait in bleio_adapter_reset() waited zero milliseconds, so the stack was torn down before the disconnect went out and the central saw a supervision timeout
• the resolvable private address rotated every second instead of the SoftDevice default of 15 minutes
• directed advertising selected the high duty cycle type, capped by the spec at 1.28 seconds, for unlimited timeouts
• ble_drv_remove_heap_handlers() stopped after the first handler it removed, leaving the rest pointing into a heap about to be freed
• common_hal_bleio_packet_buffer_deinited() could never return true, so the guards in supervisor/shared/bluetooth/serial.c never took effect
• the BLE serial RX ringbuf was given a size four times the buffer it actually had
• connection slots retained the previous peer's keys, so a recycled slot could store one peer's IRK with another's LTK

Several of these had been copied into other ports and are fixed there too.

Testing

On a Feather nRF52840 Express:

• Linux with tools/workflow/ble_terminal.py, added in this PR: reconnects in about 140 ms by directed advertising.
• macOS Chrome with https://code.circuitpython.org: serial works, and reconnects by undirected private advertising. Before this PR it accepted no serial input at all on a first connection.

Not tested: espressif, silabs, ble_hci. Those changes are the copied bug fixes plus a mechanical signature change.

Still broken, and verified as pre-existing against a stock 10.3.0-alpha.4 build, so not regressions from this PR: Chrome on Windows spins while reading boot_out.txt for board information, and Chrome on Linux stops with the initial BLE workflow popup still visible.

Where to look hardest

_common_hal_bleio_adapter_start_advertising() now takes directed_to as a raw bleio_raw_address_t instead of a bleio_address_obj_t, moving mp_get_buffer_raise() up into the user-facing wrapper. That touches all four implementations. The reason is that supervisor/shared calls the internal function and must not raise.

peer_id.id_addr_info now carries two meanings, distinguished by whether peer_id.id_info holds an IRK: either an identity address the peer distributed, or merely the address the peer connected from. bonding_load_identities() skips entries with no IRK so the two cannot be confused.

Related issues

• BLE Workflow using Chrome pairs but doesn't respond #10785 looks like the same root cause on espressif, whose bleio_reset() has the identical structure. Not fixed here. It appears to have a second cause as well: bleio_user_reset() there disconnects the workflow connection on every VM exit, which is what its own // TODO: Don't stop BLE workflow connection. is about.
• OS pairing and then unpairing caused hard fault + stuck bonding info in NVM causing no name advertised. (Claude Code Buddy) #10955's "no name advertised" symptom is explained in a comment on that issue — it is the designed bonded advertisement rather than corrupted NVM. Its hard fault may be related to the ble_drv_remove_heap_handlers() class of bug fixed here, which would be worth a retest.

[dhalbert]

Claude wrote this:

Follow-up on the three-platform testing, since the description above is now out of date about where the remaining failures actually live. Short version: macOS Chrome works, Linux Chrome does not and cannot be made to from our side, and Windows still needs investigation.

Struck-through text below was wrong and is superseded by the measurements that follow it.

macOS Chrome works

Verified through https://code.circuitpython.org on a Feather nRF52840 Express: the chooser finds the board, pairing completes, both services enumerate, serial works, and typing at the "Press any key to enter the REPL" prompt no longer drops the link — the REPL banner arrives over the same connection. After a page reload it reconnects on its own by undirected private advertising.

Linux Chrome does not, because of two host defects

Neither is fixable in CircuitPython, and both are worth studying because they affect anyone trying to use the BLE workflow from a browser on Linux.

1. Chrome registers no BlueZ pairing agent, so pairing cannot complete. BlueZ has no pairing UI of its own; it delegates every pairing interaction over D-Bus to an org.bluez.Agent1 that some application must register. Chromium registers none, so with nothing else providing one bluetoothd refuses outright:

src/device.c:new_auth() No agent available for request type 2
device_confirm_passkey: Operation not permitted

The link then drops, and since both the file transfer and serial services are SECURITY_MODE_ENC_NO_MITM, nothing works past the connect. macOS and Windows are unaffected because the operating system owns pairing there and shows its own dialog. This is consistent with Chromium's own support matrix, which lists on-demand device pairing as implemented only on Android and Mac: https://github.com/WebBluetoothCG/web-bluetooth/blob/main/implementation-status.md

tools/workflow/ble_agent.py in this PR is the workaround — run it and leave it running while pairing. Once the board is bonded, reconnects need nothing.

2. The kernel frequently never issues a connection request at all. 2. Connecting while a discovery session is active usually fails. ~~Measured against an unbonded board across seven 8-attempt runs: 1, 2, 2, 3, 4, 5 and 2 successes out of 8, about 34%. Every failure consumed the client's full connect timeout (20 s in bleak, ~41 s in Chrome).~~ This is not browser-specific — Python bleak fails identically, so it is below Web Bluetooth entirely.

btmon on a failing attempt shows the kernel enabling a passive scan filtered to an accept list it never populates, and issuing no create-connection whatsoever:

HCI Command: LE Set Extended Scan Parameters
        Type: Passive
        Filter policy: Ignore not in accept list (0x01)
... 20 seconds of silence ...
MGMT Event: Connect Failed (0x000d)

On a succeeding attempt an accept-all discovery scan happens to be running, an advertising report arrives, and the kernel then issues LE Extended Create Connection with Filter policy: Accept list is not used and connects in 250 ms. The determinant is one line in hci_update_passive_scan_sync() — if (hdev->discovery.state != DISCOVERY_STOPPED) return 0; — so whether a connect works depends on whether some client happens to hold a discovery session at that moment. Putting the address in the accept list by hand with btmgmt add-device -a 2 makes connection immediate and reliable; removing it restores the failure rate.

Later measurement inverted that conclusion. Driving org.bluez.Device1.Connect() directly over D-Bus with no browser involved, arm A being discovery active at connect time and arm B discovery stopped:

	arm A	arm B
controller in the state a boot leaves it in	18/52	18/18
after a host suspend/resume	44/44	12/12

Holding a discovery session open is what breaks the connect, not what makes it work. Arm B has never failed: 36/36 across two controllers, both kernel connect paths, every signal level tried and both orderings.

The failure also looks different from the trace above. LE Extended Create Connection is issued, with correct parameters and Filter policy: Accept list is not used (0x00); the controller answers Command Status: Success and then transmits nothing on air for 20 s until the attempt is cancelled. An air capture with an nRF sniffer following the board shows no CONNECT_IND in any of four failure windows, while the board advertises ~550 times per window and answers other centrals' scan requests throughout — so the peripheral is not involved, it is never asked to connect. Positive control: 7 of the 8 CONNECT_INDs known to have occurred were captured, so missing four by chance is about 2 × 10⁻⁴.

Two things anyone trying to reproduce this needs to know. The failing state is established by booting and cleared by a host suspend/resume — a 19-second suspend was sufficient, confirmed in both directions across three boots — so on a machine that has been suspended since boot it will not reproduce at all. And it did not reproduce on a CSR dongle in the same host on the same boot, bracketed either side by failing runs on the built-in MediaTek controller (0489:e134); whether that makes it controller-specific is unresolved, because the CSR is Bluetooth 4.0 and takes the legacy LE Create Connection path rather than the extended one. Settling that needs a Bluetooth 5.0+ controller from another vendor.

The practical consequence for the web editor is the opposite of what the struck text implied: abort any watchAdvertisements() watch before calling gatt.connect(), since Chrome holds a BlueZ discovery session for as long as a watch is armed. That change is circuitpython/web-editor#546.

This symptom family is reported upstream but not fixed anywhere: bluez/bluez#2309, bluez/bluez#2356, hbldh/bleak#1244, and https://bugzilla.kernel.org/show_bug.cgi?id=199111 which has been open since 2018. None of them identifies the discovery-state dependency or the boot/suspend toggle. Tested on kernel 7.0.0-29-generic with BlueZ 5.85.

Separately, watchAdvertisements() delivers no events at all on Linux — 0 in 45 s while BlueZ concurrently received 38 advertising reports from that same board. That is by omission rather than by bug: Chromium's BlueZ backend gates advertisement delivery on an EIR D-Bus property that exists only in the ChromeOS fork, and Web Bluetooth on Linux is officially "partially implemented and not supported". watchAdvertisements() is marked "No longer pursuing" on chromestatus: https://chromestatus.com/feature/5180688812736512

Windows needs further research

Windows Chrome did connect and run serial successfully once a stale host pairing was cleared, but the original failure — spinning while reading boot_out.txt for the board-information dialog — is not fully explained, and one unexplained observation remains: every serial notification arrived twice, consistently, which does not happen on macOS. Treating Windows as unresolved until that is understood.

An orphaned-pairing trap worth fixing separately

Not platform-specific, and arguably the most user-visible problem found. Entering discovery mode calls common_hal_bleio_adapter_erase_bonding(), so the board forgets every bond while every host keeps its own LTK. On the next connect the host encrypts with a key the board no longer has, the board correctly answers PIN or Key Missing (SMP 0x06), and the link drops. It presents differently per platform — a sub-second failure on macOS, a "Paired" device that then spins on Windows — and recovery is manual and undiscoverable: forget the device in the OS Bluetooth settings and clear the site's Bluetooth permission, which are independent.

Since the discovery-mode button press is the documented way to make a board discoverable again, users will hit this routinely, and nothing anywhere tells them what happened.

There are bugs in the web editor

The debugging sessions today exposed several bugs in web-editor and ble-file-transfer-js as well, and I'll submit issues and PR's for those later. --@dhalbert