rust/bt-broadcast-assistant: Add crate documentation and TODO roadmap Add README.md and TODO.md for the bt-broadcast-assistant crate to document architecture, usage examples, and tracking roadmap. - Add README.md with overview, architecture diagram, and usage example. - Add TODO.md outlining implementation phases. - Remove stale TODO comment in types.rs regarding PA train endpoint. Test: cargo check -p bt-broadcast-assistant Change-Id: I12f1d9550a7679967ed592000ed239a6649620e7 Reviewed-on: https://bluetooth-review.googlesource.com/c/bluetooth/+/3620
diff --git a/rust/bt-broadcast-assistant/README.md b/rust/bt-broadcast-assistant/README.md new file mode 100644 index 0000000..a6b9175 --- /dev/null +++ b/rust/bt-broadcast-assistant/README.md
@@ -0,0 +1,75 @@ +# bt-broadcast-assistant + +This crate implements the **Broadcast Assistant** role defined in the Bluetooth SIG [Basic Audio Profile (BAP) v1.0.2][bap] specification. + +A Broadcast Assistant is a Bluetooth Low Energy (LE) device (typically a smartphone or tablet) that discovers Broadcast Sources and assists Broadcast Sinks (Scan Delegators) in synchronizing to LE Audio broadcast streams. + +## Overview + +The `bt-broadcast-assistant` crate handles: + +1. **Broadcast Source Discovery & Synchronization:** + - **Extended Advertising (EA) Scanning:** Scans for advertisements containing the Broadcast Audio Announcement Service UUID (`0x1852`) to extract the `Broadcast_ID` and `Broadcast_Name`. + - **Periodic Advertising (PA) Synchronization:** Automatically establishes Periodic Advertising sync using the platform's `bt_gatt::periodic_advertising::PeriodicAdvertising` trait when the Basic Audio Announcement Endpoint (BASE) structure (`0x1851`) is needed. + - **BASE Extraction:** Parses subgroups, Codec IDs, Codec Specific Configurations, Metadata, and BIS indices from the PA train data. + - **Resource Management:** Automatically cancels the PA sync once complete broadcast source information is gathered. + +2. **Scan Delegator Management:** + - Scans for peers advertising the Broadcast Audio Scan Service (BASS, `0x184F`). + - Establishes GATT connections to Scan Delegators and provides high-level control operations via `bt_bass::BroadcastAudioScanServiceClient`: + - Add Broadcast Source + - Modify Broadcast Source + - Remove Broadcast Source + - Set Broadcast Code + +3. **Platform Independence:** + - Uses the [`bt-gatt`][bt-gatt] crate interface to remain Bluetooth stack- and async executor-agnostic. + - On Fuchsia, integrated via `bt-gatt-fuchsia` (`FuchsiaTypes`). + +## Architecture + +```text + +--------------------------------+ + | BroadcastAssistant<T> | + +--------------------------------+ + / \ + +-----------------------+ +-----------------------+ + | EventStream<T> | | Peer<T> | + | (Source Discovery & | | (BASS Client for | + | PA Sync via BASE) | | Scan Delegator) | + +-----------------------+ +-----------------------+ + \ / + +--------------------------------+ + | T: bt_gatt::GattTypes | + +--------------------------------+ +``` + +## Usage Example + +```rust,no_run +# use futures::StreamExt; +# use bt_broadcast_assistant::assistant::Error; +use bt_broadcast_assistant::{event::Event, BroadcastAssistant}; +use bt_gatt::central::Central; + +async fn run_assistant<T: bt_gatt::GattTypes + 'static>(central: T::Central) -> Result<(), Error> { + let mut assistant = BroadcastAssistant::<T>::new(central); + // Start scanning for broadcast sources (EA + PA sync) + let mut event_stream = assistant.start()?; + while let Some(event_res) = event_stream.next().await { + match event_res? { + Event::FoundBroadcastSource { peer, advertising_sid, source } => { + println!("Discovered complete broadcast source: {:?}", source); + // Can now add this source to a connected scan delegator peer! + } + Event::CouldNotParseAdvertisingData { peer, error } => { + eprintln!("Failed to parse advertisement from peer {:?}: {:?}", peer, error); + } + } + } + Ok(()) +} +``` + +[bap]: https://www.bluetooth.com/specifications/specs/basic-audio-profile-1-0-2/ +[bt-gatt]: ../bt-gatt/README.md
diff --git a/rust/bt-broadcast-assistant/TODO.md b/rust/bt-broadcast-assistant/TODO.md new file mode 100644 index 0000000..857e2d6 --- /dev/null +++ b/rust/bt-broadcast-assistant/TODO.md
@@ -0,0 +1,28 @@ +# TODO: BAP Broadcast Assistant Implementation + +## Phase 1: Broadcast Source Discovery & PA Synchronization + - [x] Define scan filters for Broadcast Audio Announcement Service (`0x1852`). + - [x] Parse `Broadcast_ID` and `Broadcast_Name` from Extended Advertising (EA) payloads. + - [x] Integrate `bt_gatt::periodic_advertising::PeriodicAdvertising` trait for establishing PA sync when BASE data is missing. + - [x] Parse Basic Audio Announcement Service (`0x1851`) BASE structure (subgroups, Codec IDs, Codec Configurations, Metadata, BIS indices). + - [x] Merge discovered BASE endpoint into internal `BroadcastSource` state. + - [x] Automatically abort/cancel PA sync once complete source information is gathered to conserve system resources. + +## Phase 2: Scan Delegator Discovery & BASS Client Integration + - [x] Define scan filters for Broadcast Audio Scan Service (BASS, `0x184F`). + - [x] Implement connection procedure to Scan Delegator peers. + - [x] Instantiate `BroadcastAudioScanServiceClient` over discovered GATT service. + - [x] Stream BASS events (Receive State characteristic updates) to upper layers. + +## Phase 3: Control Point Operations & Delegation + - [x] Implement `Add Source` control point operation (`add_broadcast_source`). + - [x] Implement `Modify Source` control point operation (`modify_broadcast_source`). + - [x] Implement `Remove Source` control point operation (`remove_broadcast_source`). + - [x] Implement `Set Broadcast Code` control point operation (`set_broadcast_code`). + - [ ] Implement Periodic Advertising Sync Transfer (PAST) offloading procedure for platforms supporting PAST. + +## Phase 4: Refinement, Advanced Features & Testing + - [x] Provide force discovery/debug mock helpers for testing without hardware radio. + - [ ] Support high-level multi-subgroup / multi-BIS synchronization selection helpers. + - [ ] Enhanced error handling for PA sync loss / establishment failures during scanning. + - [ ] End-to-end integration tests with real/mocked platform BLE controller.
diff --git a/rust/bt-broadcast-assistant/src/lib.rs b/rust/bt-broadcast-assistant/src/lib.rs index bf0aeb4..5a814ed 100644 --- a/rust/bt-broadcast-assistant/src/lib.rs +++ b/rust/bt-broadcast-assistant/src/lib.rs
@@ -2,7 +2,40 @@ // Use of this source code is governed by a BSD-style license that can be // found in the LICENSE file. +//! This crate implements the **Broadcast Assistant** role defined in the +//! Bluetooth SIG Basic Audio Profile (BAP) v1.0.2 specification. +//! +//! A Broadcast Assistant is a Bluetooth Low Energy (LE) device that discovers +//! Broadcast Sources and assists Broadcast Sinks (Scan Delegators) in +//! synchronizing to LE Audio broadcast streams. +//! +//! # Usage Example +//! +//! ```rust,no_run +//! use futures::StreamExt; +//! use bt_broadcast_assistant::assistant::Error; +//! use bt_broadcast_assistant::{event::Event, BroadcastAssistant}; +//! use bt_gatt::central::Central; +//! +//! async fn run_assistant<T: bt_gatt::GattTypes + 'static>(central: T::Central) -> Result<(), Error> { +//! let mut assistant = BroadcastAssistant::<T>::new(central); +//! let mut event_stream = assistant.start()?; +//! while let Some(event_res) = event_stream.next().await { +//! match event_res? { +//! Event::FoundBroadcastSource { peer, advertising_sid, source } => { +//! println!("Discovered complete broadcast source: {:?}", source); +//! } +//! Event::CouldNotParseAdvertisingData { peer, error } => { +//! eprintln!("Failed to parse advertisement from peer {:?}: {:?}", peer, error); +//! } +//! } +//! } +//! Ok(()) +//! } +//! ``` + pub mod assistant; +pub use assistant::event; pub use assistant::BroadcastAssistant; pub mod debug; pub mod types;
diff --git a/rust/bt-broadcast-assistant/src/types.rs b/rust/bt-broadcast-assistant/src/types.rs index 021d86b..c953f75 100644 --- a/rust/bt-broadcast-assistant/src/types.rs +++ b/rust/bt-broadcast-assistant/src/types.rs
@@ -12,7 +12,6 @@ /// Broadcast source data as advertised through Basic Audio Announcement /// PA and Broadcast Audio Announcement. /// See BAP spec v1.0.1 Section 3.7.2.1 and Section 3.7.2.2 for details. -// TODO(b/308481381): fill out endpoint from basic audio announcement from PA trains. #[derive(Clone, Default, Debug, PartialEq)] pub struct BroadcastSource { pub(crate) address: Option<Address>,