extmod/zephyr_ble: Add Zephyr BLE host stack with RP2 port integration.

[andrewleech]

Summary

This adds the Zephyr BLE host as a third backend for modbluetooth, integrated as a port-agnostic extmod. The Zephyr host code is compiled against a HAL shim layer (extmod/zephyr_ble/hal/) that replaces Zephyr's kernel primitives (semaphores, work queues, timers, FIFOs, memory slabs) with MicroPython-compatible implementations. This means the Zephyr BLE host runs cooperatively on the main MicroPython task without requiring Zephyr RTOS itself.

This was motivated by limitations in the existing stacks — NimBLE doesn't have an active BLE pre-qualification and is missing some newer BLE features, while BTstack's MicroPython integration lacks pairing/bonding and L2CAP channel support. The Zephyr BLE host stack has active qualification, full feature coverage, and is under active development by multiple silicon vendors.

The RP2 port is the first integration, providing two build variants for Pico W and Pico 2 W:

• zephyr_ble — cooperative polling from the main task (preferred)
• zephyr_ble_freertos — HCI processing on a dedicated FreeRTOS task

Also included: a gap_unpair() API addition across all BLE backends, micropython-lib updates for aioble robustness, and bond key persistence via Python secret store callbacks.

flowchart TD
    subgraph "extmod/zephyr_ble (port-agnostic)"
        MOD[modbluetooth_zephyr.c] --> HAL[HAL shim layer]
        HAL --> WORK[work queues]
        HAL --> SEM[semaphores]
        HAL --> TIMER[timers]
        HAL --> FIFO[FIFOs]
        HAL --> H4[HCI H4 transport]
    end

    subgraph "Port integration (e.g. RP2)"
        HCI_DRV[mpzephyrport_rp2.c<br/>CYW43 HCI driver] --> H4
        POLL[main loop polling] --> WORK
    end

    subgraph "Zephyr BLE host (lib/zephyr)"
        HOST[hci_core / gatt / att / smp / l2cap]
    end

    HOST --> MOD
    HCI_DRV --> HOST

Loading

Testing

All 12 BLE multitests passing on Pico W and Pico 2 W (both zephyr_ble variant) with PYBD (NimBLE) as central:
ble_gap_advertise, ble_gap_connect, ble_characteristic, ble_gap_pair, ble_gap_pair_bond, ble_subscribe, ble_irq_calls, ble_gattc_discover_services, ble_l2cap, perf_gatt_notify, perf_l2cap, ble_gap_unpair.

Performance: ~24ms/notification (GATT), ~2184 B/s (L2CAP) on Pico W; ~25ms/notification, ~7956 B/s on Pico 2 W.

Not tested: zephyr_ble_freertos variant on Pico 2 W.

Trade-offs and Alternatives

The HAL shim layer is substantial (~3K lines) because it reimplements Zephyr kernel primitives. The alternative would be running actual Zephyr RTOS, but that would limit this to the Zephyr port only. The shim approach allows any MicroPython port with an HCI transport to use the Zephyr BLE host.

The lib/zephyr submodule adds the full Zephyr BLE host source. Only the host stack files are compiled — no kernel, no drivers, no board support. The submodule is pinned to a specific commit with two small patches (wrapper files for gatt.c and conn.c to expose static internals needed for clean teardown).

MTU is compile-time only (CONFIG_BT_L2CAP_TX_MTU=512); runtime ble.config(mtu=X) is not supported. ble_mtu.py test is skipped.

Generative AI

I used generative AI tools when creating this PR, but a human has checked the code and is responsible for the description above.

[github-actions]

Code size report:

Reference:  docs/esp32: Replace 'esptool.py' by 'esptool' in command line example. [e4920d6]
Comparison: extmod/zephyr_ble: Remove dead code from HAL shim files. [merge of c197acc]
  mpy-cross:    +0 +0.000% 
   bare-arm:    +0 +0.000% 
minimal x86:    +0 +0.000% 
   unix x64:    +0 +0.000% standard
      stm32:    +0 +0.000% PYBV10
      esp32:   +84 +0.005% ESP32_GENERIC[incl +32(data)]
     mimxrt:    +0 +0.000% TEENSY40
        rp2:  +232 +0.025% RPI_PICO_W
       samd:    +0 +0.000% ADAFRUIT_ITSYBITSY_M4_EXPRESS
  qemu rv32:    +0 +0.000% VIRT_RV32

[andrewleech]

/review

[mpy-reviewer]

Review failed. Retry with /review.

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.45%. Comparing base (e4920d6) to head (c197acc).
❗ Your organization needs to install the Codecov GitHub app to enable full functionality.

Additional details and impacted files

@@                   Coverage Diff                   @@
##           review/zephyr-ble-core      #19   +/-   ##
=======================================================
  Coverage                   98.45%   98.45%           
=======================================================
  Files                         175      175           
  Lines                       22635    22635           
=======================================================
  Hits                        22286    22286           
  Misses                        349      349           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.