Skip to content

Add LL control PDU emulation and improve device.py test coverage - #975

Open
zxzxwu wants to merge 4 commits into
google:mainfrom
zxzxwu:cov
Open

Add LL control PDU emulation and improve device.py test coverage#975
zxzxwu wants to merge 4 commits into
google:mainfrom
zxzxwu:cov

Conversation

@zxzxwu

@zxzxwu zxzxwu commented Sep 7, 2026

Copy link
Copy Markdown
Collaborator

Summary

This PR significantly improves test coverage and Bluetooth Core Specification v6.3 compliance for bumble/device.py and bumble/controller.py by implementing
Link Layer (LL) control PDUs and over-the-air physical emulation procedures instead of relying on direct cross-controller dictionary lookups or HCI mocks.

bumble/device.py test coverage is increased from 67.65% (1,976/2,921 lines) to ~77% (+260 lines covered).


Key Changes

1. Link Layer Control PDUs (bumble/ll.py)

Added spec-accurate Link Layer Control PDUs and over-the-air Extended Advertising extensions:

  • Extended Advertising: Extended AdvExtInd with sid (Set ID from ADI) and periodic_advertising_data payload.
  • Connection Parameters & Subrating: Added ConnectionUpdateInd, ConnectionRateInd, and SubrateInd.
  • Channel Sounding (CS): Added CsConfigReq, CsConfigRsp, CsSecReq, CsSecRsp, CsReq, CsRsp, and CsInd.

2. Spec-Compliant Controller & Link Layer Emulation (bumble/controller.py)

Implemented full Bluetooth Core Spec v6.3 Message Sequence Chart (MSC) flows in Controller:

  • Over-the-Air Periodic Advertising Synchronization:
    • Replaced cross-controller LocalLink.find_advertising_set lookups with realistic over-the-air ll.AdvExtInd PDU matching by (AdvA, SID).
    • Added support for HCI_LE_Periodic_Advertising_Create_Sync_Command (sync_timeout expiration handling),
      HCI_LE_Periodic_Advertising_Create_Sync_Cancel_Command, and HCI_LE_Periodic_Advertising_Terminate_Sync_Command.
    • Automatically emits HCI_LE_Periodic_Advertising_Sync_Established_Event and HCI_LE_Periodic_Advertising_Report_Event when matching AdvExtInd PDUs are
      received over the air.
  • Broadcast Isochronous Group (BIG / BIS):
    • Implemented on_hci_le_create_big_command, on_hci_le_terminate_big_command, on_hci_le_big_create_sync_command, and on_hci_le_big_terminate_sync_command.
  • Connection Parameter Update & Subrating:
    • Implemented on_hci_le_connection_update_command, on_hci_le_connection_rate_request_command, and on_hci_le_subrate_request_command using
      ConnectionUpdateInd, ConnectionRateInd, and SubrateInd LL Control PDUs to update both initiator and peer connection states.
  • Channel Sounding (CS):
    • Implemented on_hci_le_cs_create_config_command, on_hci_le_cs_security_enable_command, on_hci_le_cs_set_procedure_parameters_command, and
      on_hci_le_cs_procedure_enable_command with bidirectional LL PDU exchanges (CsConfigReq/Rsp, CsSecReq/Rsp, CsReq/Rsp/Ind).

3. Bug Fixes (bumble/device.py)

  • Fixed PeriodicAdvertisingSync.on_establishment state handling so that host-initiated cancellation responses (status == HCI_OPERATION_CANCELLED_BY_HOST_ERROR) are properly processed as cancellations (State.CANCELLED) rather than being misinterpreted as late establishment events.

4. Comprehensive End-to-End Emulation Tests (tests/device_test.py)

Added 8 end-to-end two-device emulation tests verifying both local and remote peer states:

  • test_connection_parameters_and_subrate: Validates connection parameter updates, connection rate requests, and subrate updates across both peer controllers.
  • test_periodic_advertising_sync: Validates single Periodic Advertising train synchronization and report reception over the air.
  • test_big_and_big_sync: Validates BIG creation and BIG sync establishment over a Periodic Advertising train.
  • test_multiple_periodic_advertising_and_big_syncs: Validates concurrent synchronization to multiple Periodic Advertising trains (SID=0 and SID=1) with
    distinct payloads and multiple BIG syncs.
  • test_periodic_advertising_and_big_failure_exceptions: Validates failure and exception patterns including duplicate PA sync (ValueError), BIG sync on
    unestablished PA sync (InvalidStateError), PA sync cancellation before establishment (State.CANCELLED), over-the-air sync timeout
    (CONNECTION_FAILED_TO_BE_ESTABLISHED_ERROR), and BIG handle exhaustion (OutOfResourcesError).
  • test_channel_sounding: Validates full Channel Sounding config, security enable, procedure parameters, and procedure enable across both initiator and responder
    devices.
  • test_find_peer_by_name_and_identity_address: Validates LE extended scanning and peer discovery by name and identity address.
  • test_device_configuration_load_from_dict: Validates DeviceConfiguration dictionary parsing.

Test Plan

  • Executed full test suite via pytest (988 passed, 2 skipped).

- Add LL Control PDUs and controller handlers for connection parameter/rate updates, subrate updates, periodic advertising sync, BIG/BIS sync, and Channel Sounding (CS) following Bluetooth Core v6.3 MSC flows.
- Add end-to-end emulation unit tests in device_test.py validating both initiator and remote peer state.

TAG=agy
CONV=18de8363-863b-410a-8b35-4ad69d150a49
Replace cross-controller LocalLink.find_advertising_set lookups with
physical over-the-air Periodic Advertising Sync establishment via
ll.AdvExtInd PDUs:
- Extend ll.AdvExtInd to carry advertising set ID (sid) and periodic
  advertising data.
- Transmit AdvExtInd packets periodically when periodic advertising is
  enabled on an AdvertisingSet.
- Register pending periodic advertising sync requests by (AdvA, SID) and
  emit HCI_LE_Periodic_Advertising_Sync_Established_Event and
  HCI_LE_Periodic_Advertising_Report_Event upon receiving matching
  AdvExtInd PDUs over the air.

TAG=agy
CONV=18de8363-863b-410a-8b35-4ad69d150a49
- Add test_multiple_periodic_advertising_and_big_syncs to validate
  concurrent synchronization to multiple over-the-air Periodic Advertising
  trains (by SID) and corresponding BIG syncs.
- Add test_periodic_advertising_and_big_failure_exceptions to cover
  duplicate PA sync ValueError, InvalidStateError on unestablished PA
  sync, pending PA sync cancellation, sync timeout error handling, and
  BIG handle exhaustion (OutOfResourcesError).
- Implement on_hci_le_periodic_advertising_create_sync_cancel_command
  and sync_timeout expiration in Controller.
- Fix PeriodicAdvertisingSync.on_establishment to distinguish host
  cancellation (OPERATION_CANCELLED_BY_HOST_ERROR) from late
  establishment events.

TAG=agy
CONV=18de8363-863b-410a-8b35-4ad69d150a49
@zxzxwu zxzxwu changed the title Cov Add LL control PDU emulation and improve device.py test coverage Sep 7, 2026
Use walrus operator (:=) with dict.pop(key, None) to simplify pending
periodic advertising sync lookups and remove redundant list() cast.

TAG=agy
CONV=18de8363-863b-410a-8b35-4ad69d150a49
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.

1 participant