Docs: entering BLE discovery mode erases all bonding; users should know host pairing is stale

[dhalbert]

Claude wrote this, edited and corrected by @dhalbert:

Entering discovery mode erases every bond the board holds — supervisor/shared/bluetooth/bluetooth.c:271-272 calls common_hal_bleio_adapter_erase_bonding() whenever boot_in_discovery_mode is set. That is deliberate, and it is the right behaviour: discovery mode exists to let a new host pair.

The problem is that only one side forgets. Every host that had previously bonded still holds its LTK and still lists the board as a paired device. On the next connection 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 can present differently depending on the platform. We've seen this, but it may work sometimes or manifest as something else:

• macOS — a sub-second connection failure.
• Windows — the device still shows as "Paired", and the connection attempt spins.
• Linux — the browser reports a connect that goes nowhere.

Recovery is a manual step the user is unlikely to guess: forget the device in the operating system's Bluetooth settings. That is normally sufficient — the browser's own Bluetooth permission for the site does not have to be cleared, and pairing again works with it left in place. Clearing it (chrome://settings/content/bluetoothDevices in Chrome) is occasionally still worth doing, because a permission for a board that is no longer around also makes the web editor's Reconnect go looking for it.

Since the discovery-mode button press is the documented way to make a board pairable again, users will hit this routinely.

Suggested addition

docs/workflows.md describes entering discovery mode in the BLE section — "press the reset button when the status led blinks blue quickly after reset" — and describes bonding, but says nothing about existing bonds being erased or about what the user must then do on the host.

Can add short paragraph in the BLE section of docs/workflows.md, after the bonding instructions, saying roughly:

Entering discovery mode erases all of the board's existing bonds. Hosts that were previously bonded still have their own copy of the pairing, which no longer works, and they will fail to connect until it is removed. On each such host, forget the board in the operating system's Bluetooth settings, then pair again.

Worth saying somewhere more visible than the workflow reference too, since the people most likely to hit it are following a Learn guide rather than reading docs/.

Also need to document in appropriate Learn Guides.

[tannewt]

I think this is better done as a PR instead of an issue.

Generally, I'm wary of multiple paragraphs of Claude output as issues because they may not be real. I'd rather have a one concise single paragraph that I know the author read.

[dhalbert]

I am working on getting Claude more concise. But I agree this is still too long. In this case, I pruned it down from an even longer description, as noted:

Claude wrote this, edited and corrected by @dhalbert:

These issues were discovered in the course of other stuff, and I'm filing them so they will get attention later, so they won't get lost. But I'm not ready for a PR yet. I could keep them as private notes, but issues is better for record-keeping.