Skip to content

devices/ble_hci: fix bugs found on hardware and 64-bit hosts - #11750

Merged
dhalbert merged 23 commits into
adafruit:mainfrom
MakerClassCZ:ble-hci-fixes
Nov 14, 2026
Merged

dhalbert merged 23 commits into
adafruit:mainfrom
MakerClassCZ:ble-hci-fixes

Conversation

@lynt-smitka

Copy link
Copy Markdown

Fixes in devices/ble_hci that I found while running it with new controllers: a desktop build (64-bit), a Pico 2 W with its CYW43439, and a Fruit Jam with its ESP32-C6 (nina-fw, like an AirLift). They are a step towards native BLE on the Pico W and Pico 2 W, and they also applyto AirLift boards. Each commit describes one fix.

The main ones: ACL packets were dropped on 64-bit hosts, the controller was set up only once (so the first ATT reply hung after a disable/enable), disabling took 1 s and on a CYW43 every second enable failed, and setting the name before enabling crashed. There is also support for a persistent adapter owned by the port, for boards with a built-in controller.

Testing

  • Desktop build with a virtual controller.
  • Pico 2 W: 30 enable/disable cycles, Nordic UART echo with adafruit_ble, 10 minutes of BLE together with Wi-Fi.
  • Fruit Jam (ESP32-C6, UART like an AirLift): enable/disable and the UART echo.

I don't have an ESP32 AirLift, so a test on one would be welcome.

@dhalbert

dhalbert commented Nov 4, 2026

Copy link
Copy Markdown
Collaborator

It's OK to turn off _bleio HCI on the two boards that overflowed.

@tannewt
tannewt requested a review from dhalbert November 5, 2026 17:49
@dhalbert

dhalbert commented Nov 12, 2026 •

Copy link
Copy Markdown
Collaborator

In principle I am fine with this. However, I just had to make room for some other changes on 512 kB SAMD boards, and this will use up about 600 bytes of the 1800 bytes I just recovered. I have a feeling there are more issues in the HCI that we haven't encountered yet, which would again balloon this up. We need to think about whether to continue to make this widely available or maybe restrict it to certain boards, eventually maybe having to turn off some other modules. I'll discuss this with the team.

- sizeof(acl) was a pointer's size, so on 64-bit hosts every ACL packet looked incomplete.
- The ACL header mixed bitfield types: 6 bytes under the MS layout (MinGW) instead of 5.
- Find By Type Value errors named the response opcode, so the central kept waiting.
- A new connection's connection_obj was NULL.
- The receive loop could return without clearing hci_poll_in_progress.
- The unknown-event debug print lacked its argument.
….connections

Enabling sends HCI Reset, which cleared the event mask and buffer sizes set only in the
constructor, so a re-enabled adapter hung on its first ATT answer. The init now runs on every
enable. adapter.connections is rebuilt when a connection is made or lost.
- The wait for an ACL credit is bounded and a failed write returns its credit; a controller
  that was gone hung the VM.
- A failed enable leaves the adapter off.
- An L2CAP frame longer than the reassembly buffer is dropped with its continuation fragments,
  instead of overflowing the buffer.
- Credits pending when the last link ends are cleared; the controller does not report them.
- A Number of Completed Packets count of 0 no longer clears every credit.
…ng after a connection

Disabling cleared enabled before sending HCI Reset, so its reply was left unread and the next
enable took it for its own: every second enable failed. stop_advertising() after a
connection no longer asks the controller, which may refuse or not answer.
remote_service_list was never created, so discover_remote_services() dereferenced NULL. Until
discovery is implemented it returns ().
Unhandled opcodes got an Error Response even when they were commands, responses or
notifications. Only requests are answered now (Request Not Supported); the rest are dropped.
A peer's MTU was stored as the link's, even below 23, where a response has no room for its
header. The link now keeps 23, our own MTU, and the answer says so.
…dle's room

The entry length left out the handle, and a long value could write two bytes past the response
buffer. An entry is now the handle plus the value, cut to fit the MTU.
A characteristic's UUID matched its declaration handle first, so a client got the wrong handle.
Only the value handle matches now.
common_hal_bleio_init() runs on every import of _bleio and reset the HCI state, dropping live
connections. It now resets only while the adapter is off.
common_hal_busio_uart_read() can fail with EAGAIN while a character is waiting (on SAMD, when
a zero timeout read straddles a millisecond). The poll kept that errcode for the next read,
which then succeeded and was dropped as failed: one byte of a packet lost, the command's
answer never complete.
…rom the background too

A command sent from a background task (the advertising timeout) never got its answer read,
because background tasks don't nest. send_command() and the ACL credit wait now read the
answers themselves, and the background task does nothing while a command or an ACL packet
is in flight.
…last one

Legacy advertising set the scan response only when there was one, so the controller kept the
previous one.
A CCCD write of the wrong length raised ValueError inside the HCI poll, which stopped all later
background tasks. It is now answered with Invalid Attribute Value Length. bleio_hci_reset()
also clears hci_waits.
…upported

Long writes were never implemented: Prepare Write got no answer, so the central timed out after
30 s, and Execute Write reported success. Both now get Request Not Supported.
bleio_reset() freed the adapter only if it was enabled and used. Otherwise it stayed allocated
with its UART on the freed heap, and every later Adapter() raised "Too many Adapters". On the
HCI stack the adapter always belongs to the program, so it is now always freed. A constructor
whose controller does not answer no longer leaves it allocated either. vm_used_ble, no longer
read, is gone.
HCI Reset ends all links without Disconnection Complete events, but the host kept them. The
host's HCI state is now reset with the controller, so bleio_adapter_reset() only disables.
A disconnect only freed the connection's slot, so an old Connection object took the next link
in that slot for its own. It is now detached, as on nordic.
…ds it

If a link ends without a Disconnection Complete (for example, the controller restarted),
disconnect() got Unknown Connection Identifier for ever. That answer now ends the link on the
host too, and frees its ACL credits.
The ATT client is not implemented: nothing sends a request, so the handlers for responses and
notifications only stored answers no one waits for. They are no longer dispatched; such PDUs
fall to the default and are dropped. An indication is still confirmed.
…s range

An empty PDU is ignored; it was read as the previous opcode. A Find Information Request
from handle 0, or with its start after its end, answers Invalid Handle instead of raising
an exception inside the poll.
An offset equal to the length gives an empty value, not Invalid Offset; a Read Blob of a
service answers Attribute Not Long for the request's opcode.
They came out in the middle of the program's output. HCI_DEBUG still prints the read error.
@lynt-smitka lynt-smitka changed the title devices/ble_hci: fixes for new controllers and 64-bit hosts devices/ble_hci: fix bugs found on hardware and 64-bit hosts Nov 14, 2026
@lynt-smitka

Copy link
Copy Markdown
Author

@dhalbert I've decided to change the focus of this PR. It now just fixes the ble_hci bugs I ran into while building a Desktop Lab, plus the ones I found when testing on hardware afterwards. I tested it heavily on a Fruit Jam (ESP32-C6) and on AirLift-like hardware (a PyBadge with a classic ESP32 board), including the adafruit_ble examples, long flood/soak runs and Bluefruit Connect on iOS. The result is also smaller than main: -340 bytes on metro_m4_airlift_lite.

@dhalbert dhalbert left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the fixes, and for the scope narrowing. The code was never tested that thoroughly in the past, and it looks like you've covered a lot of lifetime issues and the like. Your testing is extensive and I will not repeat.

@dhalbert
dhalbert merged commit b3712b3 into adafruit:main Nov 14, 2026
711 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants