docs: Document BLE connection event fix.

Update CLAUDE.local.md with Issue #3 resolution and current status.
BLE connections now working on STM32WB55 with both peripheral and
central roles successfully delivering IRQ events.

Signed-off-by: Andrew Leech <[email protected]>

Author: pi-anl

CLAUDE.local.md

@@ -6,14 +6,15 @@ Add Zephyr BLE stack as an alternative to NimBLE/BTstack for all MicroPython por
 ## Current Status
 - OS abstraction layer implemented (k_work, k_sem, k_mutex, atomic ops)
 - Build system integration complete
-- **STM32WB55: BLE initialization works, scanning partially working**
-  - bt_enable() completes successfully
-  - BLE scan START succeeds (no EPERM error)
-  - **ISSUE**: No advertising reports received during scan
-  - **ISSUE**: Scan STOP command times out (10s), causes fatal error
+- **STM32WB55: BLE connections now working!**
+  - bt_enable() completes successfully ✓
+  - BLE advertising works (legacy mode) ✓
+  - BLE connections work (peripheral and central roles) ✓
+  - Connection IRQ events delivered correctly ✓
 - All HCI initialization commands complete (HCI_RESET, READ_LOCAL_FEATURES, READ_SUPPORTED_COMMANDS, LE commands)
 - Fix #1: Disabled CONFIG_BT_HCI_ACL_FLOW_CONTROL (STM32WB controller doesn't support HOST_BUFFER_SIZE command)
 - Fix #2: Enabled CONFIG_BT_SCAN_WITH_IDENTITY to fix scanning EPERM error
+- Fix #3: Disabled CONFIG_BT_SMP (STM32WB controller sends legacy connection events, not enhanced)
 - RP2 Pico 2 W: Not yet tested with these fixes
 
 ## Test Hardware
@@ -302,25 +303,43 @@ arm-none-eabi-objdump -d build-*/firmware.elf > firmware.dis
 **Files Modified**:
 - `extmod/zephyr_ble/zephyr_ble_config.h` - Added CONFIG_BT_SCAN_WITH_IDENTITY
 
-**Remaining Issues**:
-- No advertising reports received during scan (no devices detected)
-- Scan STOP command (LE_SET_SCAN_ENABLE disable) times out waiting for HCI response
-  - Command sent: `>HCI_CMD(01:0c:20:02:00:00)`
-  - No response received from controller
-  - Causes 10s timeout in `bt_hci_cmd_send_sync()` → fatal error
-- Likely issue: HCI event routing or STM32WB RF core not delivering events properly
+### Issue #3: BLE Connection IRQ Events Not Delivered (FIXED)
+**Problem**: Multi-test `ble_gap_connect.py` failed - STM32WB55 peripheral never received `_IRQ_CENTRAL_CONNECT` or `_IRQ_CENTRAL_DISCONNECT` events, though Pyboard-D central successfully connected.
+
+**Root Cause**:
+- Zephyr's `le_set_event_mask()` function (`lib/zephyr/subsys/bluetooth/host/hci_core.c:3529-3542`) conditionally enables different LE connection event types based on `CONFIG_BT_SMP`:
+  - When `CONFIG_BT_SMP=1`: Enables **LE Enhanced Connection Complete** events (HCI event mask bit 9)
+  - When `CONFIG_BT_SMP=0`: Enables **LE Connection Complete** events (HCI event mask bit 0 - legacy BLE 4.x)
+- STM32WB55 RF core sends legacy LE Connection Complete events (0x3E subcode 0x01)
+- With `CONFIG_BT_SMP=1`, Zephyr requested enhanced events that the controller never sends
+- No events delivered → Zephyr callbacks never triggered → Python IRQ handler never called
+
+**Investigation Method**:
+1. Added debug logging to connection callbacks in `modbluetooth_zephyr.c` and `modbluetooth.c`
+2. Ran multi-test and confirmed: ZERO callback invocations, ZERO HCI LE Meta Events in trace
+3. Examined NimBLE initialization code (`lib/mynewt-nimble/nimble/host/src/ble_hs_startup.c:177-251`) which explicitly sets LE event masks
+4. Compared to Zephyr's event mask logic - found conditional behavior based on CONFIG_BT_SMP
+
+**Solution**: Disabled `CONFIG_BT_SMP` in `extmod/zephyr_ble/zephyr_ble_config.h:403`
+```c
+#define CONFIG_BT_SMP 0  // Disabled: STM32WB55 controller doesn't send Enhanced Connection Complete events
+```
+
+**Result**: Connection events now delivered correctly!
+- `_IRQ_CENTRAL_CONNECT` fires when central connects to peripheral ✓
+- `_IRQ_CENTRAL_DISCONNECT` fires when connection terminates ✓
+- Both peripheral and central roles working ✓
+
+**Files Modified**:
+- `extmod/zephyr_ble/zephyr_ble_config.h:403` - Disabled CONFIG_BT_SMP
+
+**Note**: Disabling CONFIG_BT_SMP also disables Security Manager Protocol features (pairing, bonding, encryption). This is acceptable for initial bring-up and basic connection testing. Future work may need to support enhanced connection events or implement SMP differently.
 
 ## Next Steps
 
-1. **URGENT**: Investigate why scan STOP command times out
-   - Check HCI event processing in work queue
-   - Verify STM32WB RF core event delivery
-   - May need to check IPCC interrupt handling
-2. Debug why no advertising reports are received
-   - Verify HCI event routing for LE_ADVERTISING_REPORT events
-   - Check if events are making it from RF core to host stack
-3. Once scanning works, test advertising functionality
-4. Test BLE connections (central and peripheral roles)
-5. Test on RP2 Pico 2 W with both fixes applied
+1. Disable debug logging and verify multi-tests pass cleanly
+2. Test additional BLE functionality (GATT, notifications, etc.)
+3. Test on RP2 Pico 2 W with all three fixes applied
+4. Consider long-term solution for SMP support with enhanced connection events
 
 Use arm-none-eabi-gdb proactively to diagnose issues. The probe-rs agent or `~/.claude/agents/probe-rs-flash.md` has specific usage details.