* [PATCH BlueZ v2 1/9] doc/btmon: Split Advertising and Scanning into btmon-advertising.rst
@ 2026-03-24 19:49 Luiz Augusto von Dentz
2026-03-24 19:49 ` [PATCH BlueZ v2 2/9] doc/btmon: Split LE Audio Protocol Flow into btmon-le-audio.rst Luiz Augusto von Dentz
` (8 more replies)
0 siblings, 9 replies; 11+ messages in thread
From: Luiz Augusto von Dentz @ 2026-03-24 19:49 UTC (permalink / raw)
To: linux-bluetooth
From: Luiz Augusto von Dentz <luiz.von.dentz@intel.com>
Move the ADVERTISING AND SCANNING section into a standalone file and
replace it with an RST include directive. This allows the
btsnoop-analyzer to load only the relevant documentation for
advertising/scanning focus-area analysis instead of the full btmon.rst.
---
doc/btmon-advertising.rst | 155 ++++++++++++++++++++++++++++++++++++++
doc/btmon.rst | 155 +-------------------------------------
2 files changed, 158 insertions(+), 152 deletions(-)
create mode 100644 doc/btmon-advertising.rst
diff --git a/doc/btmon-advertising.rst b/doc/btmon-advertising.rst
new file mode 100644
index 000000000000..dfa5dbb1da66
--- /dev/null
+++ b/doc/btmon-advertising.rst
@@ -0,0 +1,155 @@
+.. This file is included by btmon.rst.
+
+ADVERTISING AND SCANNING
+==========================
+
+btmon decodes advertising data structures automatically. Advertising
+and scan response data appears in HCI LE advertising report events
+and in advertising command parameters.
+
+Advertising Reports
+--------------------
+
+When the controller reports received advertisements::
+
+ > HCI Event: LE Meta Event (0x3e) plen 43 #120 [hci0] 0.500003
+ LE Extended Advertising Report (0x0d)
+ Event type: 0x0013
+ Props: 0x0013
+ Connectable
+ Scannable
+ Complete
+ Address type: Random (0x01)
+ Address: 00:11:22:33:44:55
+ Primary PHY: LE 1M
+ Secondary PHY: LE 2M
+ SID: 0x01
+ TX power: 0 dBm
+ RSSI: -55 dBm (0xc9)
+ Data length: 18
+
+The advertising data (AD) structures within the report are decoded
+as typed fields:
+
+**Common AD types btmon decodes**:
+
+.. list-table::
+ :header-rows: 1
+ :widths: 10 30 60
+
+ * - AD Type
+ - Name
+ - Example in btmon output
+ * - 0x01
+ - Flags
+ - ``Flags: 0x06`` with decoded bits (LE General Discoverable,
+ BR/EDR Not Supported)
+ * - 0x02/0x03
+ - Incomplete/Complete 16-bit UUIDs
+ - ``16-bit Service UUIDs (complete): 2 entries``
+ followed by UUID list
+ * - 0x06/0x07
+ - Incomplete/Complete 128-bit UUIDs
+ - ``128-bit Service UUIDs (complete): 1 entry``
+ * - 0x08/0x09
+ - Shortened/Complete Local Name
+ - ``Name (complete): MyDevice``
+ * - 0x0a
+ - TX Power Level
+ - ``TX power: 4 dBm``
+ * - 0x16
+ - Service Data (16-bit UUID)
+ - ``Service Data (UUID 0x184e): ...`` with protocol-specific
+ decoding
+ * - 0xff
+ - Manufacturer Specific Data
+ - ``Company: Apple, Inc. (76)`` followed by hex data
+
+**Typical advertising report**::
+
+ > HCI Event: LE Meta Event (0x3e) plen 38 #120 [hci0] 0.500003
+ LE Extended Advertising Report (0x0d)
+ Address: 00:11:22:33:44:55
+ RSSI: -62 dBm (0xc2)
+ Flags: 0x06
+ LE General Discoverable Mode
+ BR/EDR Not Supported
+ Name (complete): LE-Audio-Left
+ 16-bit Service UUIDs (complete): 3 entries
+ Published Audio Capabilities (0x1850)
+ Audio Stream Control (0x184e)
+ Common Audio (0x1853)
+ Service Data (UUID 0x1852): 01a2b3
+ Appearance: Earbud (0x0941)
+
+Extended Advertising
+---------------------
+
+Modern controllers use extended advertising commands and events.
+The setup sequence in btmon::
+
+ < HCI Command: LE Set Extended Adv Parameters (0x08|0x0036) plen 25 #50 [hci0] 0.100003
+ Handle: 0x01
+ Properties: 0x0000
+ Min advertising interval: 160.000 msec (0x0100)
+ Max advertising interval: 160.000 msec (0x0100)
+ Channel map: 37, 38, 39 (0x07)
+ Own address type: Random (0x01)
+ Peer address type: Public (0x00)
+ PHY: LE 1M, LE 2M
+ SID: 0x01
+ TX power: 7 dBm
+
+ < HCI Command: LE Set Extended Adv Data (0x08|0x0037) plen 35 #52 [hci0] 0.101003
+ Handle: 0x01
+ Operation: Complete extended advertising data (0x01)
+ Fragment preference: No fragmentation (0x01)
+
+Periodic Advertising (LE Audio)
+--------------------------------
+
+LE Audio broadcast sources use periodic advertising to transmit
+BASE announcements containing codec configuration::
+
+ > HCI Event: LE Meta Event (0x3e) plen 80 #200 [hci0] 0.500003
+ LE Periodic Advertising Report (0x0f)
+ Sync handle: 0x0001
+ TX power: 0 dBm
+ RSSI: -45 dBm
+ CTE Type: No CTE (0xff)
+ Data status: Complete (0x00)
+ Data length: 60
+ Service Data: Basic Audio Announcement (0x1851)
+ Presentation Delay: 40000 us
+ Number of Subgroups: 1
+ Codec: LC3 (0x06)
+ Sampling Frequency: 48000 Hz
+ Frame Duration: 10 ms
+ Frame Length: 120
+
+Automating Advertising Analysis
+---------------------------------
+
+**Find all advertising reports** (devices seen)::
+
+ grep -n "Advertising Report\|Address:.*RSSI:" output.txt
+
+**Extract device names**::
+
+ grep -n "Name (complete):\|Name (short):" output.txt
+
+**Find LE Audio devices** (by service UUIDs in advertising)::
+
+ grep -n "Audio Stream Control\|Published Audio Capabilities\|Common Audio\|Basic Audio Announcement\|Broadcast Audio" output.txt
+
+**Track advertising setup** (local device configuring advertising)::
+
+ grep -n "Set Extended Adv\|Set Advertising\|Set Scan Response\|Adv Enable" output.txt
+
+**Find periodic advertising** (broadcast audio)::
+
+ grep -n "Periodic Advertising\|PA Sync\|PA Report\|Basic Audio Announcement\|Broadcast.*Announcement" output.txt
+
+**Identify devices by appearance**::
+
+ grep -n "Appearance:" output.txt
diff --git a/doc/btmon.rst b/doc/btmon.rst
index 2299c13ca16c..657f33ff19f1 100644
--- a/doc/btmon.rst
+++ b/doc/btmon.rst
@@ -2402,159 +2402,10 @@ Errors often cascade across layers. Common patterns:
4. L2CAP ``Connection refused - security block`` → triggers SMP
pairing
-ADVERTISING AND SCANNING
-==========================
+PROTOCOL FLOWS
+===============
-btmon decodes advertising data structures automatically. Advertising
-and scan response data appears in HCI LE advertising report events
-and in advertising command parameters.
-
-Advertising Reports
---------------------
-
-When the controller reports received advertisements::
-
- > HCI Event: LE Meta Event (0x3e) plen 43 #120 [hci0] 0.500003
- LE Extended Advertising Report (0x0d)
- Event type: 0x0013
- Props: 0x0013
- Connectable
- Scannable
- Complete
- Address type: Random (0x01)
- Address: 00:11:22:33:44:55
- Primary PHY: LE 1M
- Secondary PHY: LE 2M
- SID: 0x01
- TX power: 0 dBm
- RSSI: -55 dBm (0xc9)
- Data length: 18
-
-The advertising data (AD) structures within the report are decoded
-as typed fields:
-
-**Common AD types btmon decodes**:
-
-.. list-table::
- :header-rows: 1
- :widths: 10 30 60
-
- * - AD Type
- - Name
- - Example in btmon output
- * - 0x01
- - Flags
- - ``Flags: 0x06`` with decoded bits (LE General Discoverable,
- BR/EDR Not Supported)
- * - 0x02/0x03
- - Incomplete/Complete 16-bit UUIDs
- - ``16-bit Service UUIDs (complete): 2 entries``
- followed by UUID list
- * - 0x06/0x07
- - Incomplete/Complete 128-bit UUIDs
- - ``128-bit Service UUIDs (complete): 1 entry``
- * - 0x08/0x09
- - Shortened/Complete Local Name
- - ``Name (complete): MyDevice``
- * - 0x0a
- - TX Power Level
- - ``TX power: 4 dBm``
- * - 0x16
- - Service Data (16-bit UUID)
- - ``Service Data (UUID 0x184e): ...`` with protocol-specific
- decoding
- * - 0xff
- - Manufacturer Specific Data
- - ``Company: Apple, Inc. (76)`` followed by hex data
-
-**Typical advertising report**::
-
- > HCI Event: LE Meta Event (0x3e) plen 38 #120 [hci0] 0.500003
- LE Extended Advertising Report (0x0d)
- Address: 00:11:22:33:44:55
- RSSI: -62 dBm (0xc2)
- Flags: 0x06
- LE General Discoverable Mode
- BR/EDR Not Supported
- Name (complete): LE-Audio-Left
- 16-bit Service UUIDs (complete): 3 entries
- Published Audio Capabilities (0x1850)
- Audio Stream Control (0x184e)
- Common Audio (0x1853)
- Service Data (UUID 0x1852): 01a2b3
- Appearance: Earbud (0x0941)
-
-Extended Advertising
----------------------
-
-Modern controllers use extended advertising commands and events.
-The setup sequence in btmon::
-
- < HCI Command: LE Set Extended Adv Parameters (0x08|0x0036) plen 25 #50 [hci0] 0.100003
- Handle: 0x01
- Properties: 0x0000
- Min advertising interval: 160.000 msec (0x0100)
- Max advertising interval: 160.000 msec (0x0100)
- Channel map: 37, 38, 39 (0x07)
- Own address type: Random (0x01)
- Peer address type: Public (0x00)
- PHY: LE 1M, LE 2M
- SID: 0x01
- TX power: 7 dBm
-
- < HCI Command: LE Set Extended Adv Data (0x08|0x0037) plen 35 #52 [hci0] 0.101003
- Handle: 0x01
- Operation: Complete extended advertising data (0x01)
- Fragment preference: No fragmentation (0x01)
-
-Periodic Advertising (LE Audio)
---------------------------------
-
-LE Audio broadcast sources use periodic advertising to transmit
-BASE announcements containing codec configuration::
-
- > HCI Event: LE Meta Event (0x3e) plen 80 #200 [hci0] 0.500003
- LE Periodic Advertising Report (0x0f)
- Sync handle: 0x0001
- TX power: 0 dBm
- RSSI: -45 dBm
- CTE Type: No CTE (0xff)
- Data status: Complete (0x00)
- Data length: 60
- Service Data: Basic Audio Announcement (0x1851)
- Presentation Delay: 40000 us
- Number of Subgroups: 1
- Codec: LC3 (0x06)
- Sampling Frequency: 48000 Hz
- Frame Duration: 10 ms
- Frame Length: 120
-
-Automating Advertising Analysis
----------------------------------
-
-**Find all advertising reports** (devices seen)::
-
- grep -n "Advertising Report\|Address:.*RSSI:" output.txt
-
-**Extract device names**::
-
- grep -n "Name (complete):\|Name (short):" output.txt
-
-**Find LE Audio devices** (by service UUIDs in advertising)::
-
- grep -n "Audio Stream Control\|Published Audio Capabilities\|Common Audio\|Basic Audio Announcement\|Broadcast Audio" output.txt
-
-**Track advertising setup** (local device configuring advertising)::
-
- grep -n "Set Extended Adv\|Set Advertising\|Set Scan Response\|Adv Enable" output.txt
-
-**Find periodic advertising** (broadcast audio)::
-
- grep -n "Periodic Advertising\|PA Sync\|PA Report\|Basic Audio Announcement\|Broadcast.*Announcement" output.txt
-
-**Identify devices by appearance**::
-
- grep -n "Appearance:" output.txt
+.. include:: btmon-advertising.rst
EXAMPLES
========
--
2.53.0
^ permalink raw reply related [flat|nested] 11+ messages in thread
* [PATCH BlueZ v2 2/9] doc/btmon: Split LE Audio Protocol Flow into btmon-le-audio.rst
2026-03-24 19:49 [PATCH BlueZ v2 1/9] doc/btmon: Split Advertising and Scanning into btmon-advertising.rst Luiz Augusto von Dentz
@ 2026-03-24 19:49 ` Luiz Augusto von Dentz
2026-03-24 19:49 ` [PATCH BlueZ v2 3/9] doc/btmon: Split L2CAP Channel Tracking into btmon-l2cap.rst Luiz Augusto von Dentz
` (7 subsequent siblings)
8 siblings, 0 replies; 11+ messages in thread
From: Luiz Augusto von Dentz @ 2026-03-24 19:49 UTC (permalink / raw)
To: linux-bluetooth
From: Luiz Augusto von Dentz <luiz.von.dentz@intel.com>
Move the LE AUDIO PROTOCOL FLOW section (including CIS unicast,
BIS broadcast, and BIG sync flows) into a standalone file and
replace it with an RST include directive. This is the largest
split section (660 lines) and was being truncated away in
context-limited analysis.
---
doc/btmon-le-audio.rst | 655 ++++++++++++++++++++++++++++++++++++++++
doc/btmon.rst | 656 +----------------------------------------
2 files changed, 657 insertions(+), 654 deletions(-)
create mode 100644 doc/btmon-le-audio.rst
diff --git a/doc/btmon-le-audio.rst b/doc/btmon-le-audio.rst
new file mode 100644
index 000000000000..db909ac38e47
--- /dev/null
+++ b/doc/btmon-le-audio.rst
@@ -0,0 +1,655 @@
+.. This file is included by btmon.rst.
+
+LE AUDIO PROTOCOL FLOW
+=======================
+
+LE Audio uses a multi-layer protocol stack visible in btmon traces.
+The setup sequence involves ATT operations on specific GATT
+characteristics (PACS, ASCS) followed by HCI-level CIS/BIG
+management. btmon fully decodes all layers.
+
+PACS: Published Audio Capabilities
+------------------------------------
+
+Before audio streaming begins, devices exchange codec capabilities
+via the Published Audio Capabilities Service (PACS). The client reads
+PACS characteristics to learn what the remote device supports.
+
+**Sink PAC read** (remote device's receive capabilities)::
+
+ < ACL Data TX: Handle 2048 flags 0x00 dlen 7 #550 [hci0] 0.824003
+ ATT: Read Request (0x0a) len 2
+ Handle: 0x0075
+
+ > ACL Data RX: Handle 2048 flags 0x02 dlen 30 #552 [hci0] 0.886556
+ ATT: Read Response (0x0b) len 25
+ Handle: 0x0075
+ Number of PAC(s): 1
+ Codec: LC3 (0x06)
+ Codec Specific Capabilities: #0
+ Sampling Frequency: 8000 Hz 16000 Hz 24000 Hz 32000 Hz 48000 Hz
+ Frame Duration: 7.5 ms 10 ms
+ Audio Channel Counts: 1
+ Frame Length: 26 - 240
+
+The PAC record shows codec capabilities using LTV (Length-Type-Value)
+encoding. Key fields:
+
+- **Codec** -- ``LC3 (0x06)`` is the mandatory LE Audio codec
+- **Sampling Frequency** -- Supported sample rates (bitmask)
+- **Frame Duration** -- Supported frame durations (7.5 ms and/or 10 ms)
+- **Audio Channel Counts** -- Supported channel counts
+- **Frame Length** -- Min and max octets per codec frame
+
+**Audio Locations** (channel assignment)::
+
+ > ACL Data RX: Handle 2048 flags 0x02 dlen 9 #554 [hci0] 0.948003
+ ATT: Read Response (0x0b) len 4
+ Handle: 0x0077
+ Location: Front Left
+
+**Available Audio Contexts** (current use cases)::
+
+ > ACL Data RX: Handle 2048 flags 0x02 dlen 9 #558 [hci0] 1.012556
+ ATT: Read Response (0x0b) len 4
+ Handle: 0x007b
+ Sink Context: Media Conversational
+ Source Context: Unspecified
+
+ASCS: Audio Stream Control
+----------------------------
+
+The Audio Stream Control Service (ASCS) manages the ASE (Audio Stream
+Endpoint) state machine. Each ASE transitions through a defined set
+of states as streaming is set up and torn down.
+
+**ASE State Machine**::
+
+ Idle ──► Codec Configured ──► QoS Configured ──► Enabling ──► Streaming
+ │
+ Idle ◄── Releasing ◄──────── Disabling ◄─────────────────────────┘
+
+**ASE Status notification** (state change)::
+
+ > ACL Data RX: Handle 2048 flags 0x02 dlen 20 #580 [hci0] 1.456003
+ ATT: Handle Value Notification (0x1b) len 15
+ Handle: 0x0088
+ ASE ID: 0x01
+ State: Codec Configured (0x01)
+ Framing: Unframed PDUs supported (0x00)
+ PHY: 0x02
+ LE 2M PHY (0x02)
+ RTN: 2
+ Max Transport Latency: 10
+ Presentation Delay Min: 20000 us
+ Presentation Delay Max: 40000 us
+ Preferred Presentation Delay Min: 20000 us
+ Preferred Presentation Delay Max: 40000 us
+ Codec: LC3 (0x06)
+ Sampling Frequency: 48000 Hz
+ Frame Duration: 10 ms
+ Audio Channel Allocation: Front Left
+ Frame Length: 120
+
+**ASE Control Point operations** drive state transitions. The client
+writes to the ASE Control Point characteristic to issue commands::
+
+ < ACL Data TX: Handle 2048 flags 0x00 dlen 25 #582 [hci0] 1.518003
+ ATT: Write Request (0x12) len 20
+ Handle: 0x008b
+ ASE Control Point: Config Codec (0x01)
+ ASE ID: 0x01
+ Target Latency: Low Latency (0x01)
+ PHY: LE 2M PHY
+ Codec: LC3 (0x06)
+ Sampling Frequency: 48000 Hz
+ Frame Duration: 10 ms
+ Audio Channel Allocation: Front Left
+ Frame Length: 120
+
+ASE Control Point commands:
+
+.. list-table::
+ :header-rows: 1
+ :widths: 10 25 65
+
+ * - Opcode
+ - Command
+ - Purpose
+ * - 0x01
+ - Config Codec
+ - Select codec and parameters (Idle → Codec Configured)
+ * - 0x02
+ - Config QoS
+ - Set CIG/CIS IDs and QoS params (Codec Configured → QoS Configured)
+ * - 0x03
+ - Enable
+ - Start ASE with metadata (QoS Configured → Enabling)
+ * - 0x04
+ - Receiver Start Ready
+ - Signal receiver readiness (Enabling → Streaming, server-side)
+ * - 0x05
+ - Disable
+ - Stop streaming (Streaming → Disabling)
+ * - 0x06
+ - Receiver Stop Ready
+ - Signal receiver stopped
+ * - 0x07
+ - Update Metadata
+ - Change metadata during streaming
+ * - 0x08
+ - Release
+ - Tear down ASE (any → Releasing → Idle)
+
+CIS Setup and Teardown
+------------------------
+
+After ASE QoS Configuration, the host creates Connected Isochronous
+Streams (CIS) at the HCI level.
+
+**CIG Parameters** (configure the CIS group)::
+
+ < HCI Command: LE Set CIG Parameters (0x08|0x0062) plen 26 #590 [hci0] 1.624003
+ CIG ID: 0x00
+ Central to Peripheral SDU Interval: 10000 us
+ Peripheral to Central SDU Interval: 10000 us
+ SCA: 0x00
+ Packing: Sequential (0x00)
+ Framing: Unframed (0x00)
+ Central to Peripheral Max Latency: 10 ms
+ Peripheral to Central Max Latency: 10 ms
+ Number of CIS: 1
+ CIS ID: 0x00
+ Central to Peripheral Max SDU: 120
+ Peripheral to Central Max SDU: 0
+ Central to Peripheral PHY: LE 2M PHY
+ Peripheral to Central PHY: LE 2M PHY
+ Central to Peripheral RTN: 2
+ Peripheral to Central RTN: 2
+
+ > HCI Event: Command Complete (0x0e) plen 8 #592 [hci0] 1.624556
+ LE Set CIG Parameters (0x08|0x0062) ncmd 1
+ Status: Success (0x00)
+ CIG ID: 0x00
+ Number of Handles: 1
+ Connection Handle: 2064
+
+**CIS Creation**::
+
+ < HCI Command: LE Create CIS (0x08|0x0064) plen 9 #594 [hci0] 1.688003
+ Number of CIS: 1
+ CIS Handle: 2064
+ ACL Handle: 2048
+
+ > HCI Event: LE Meta Event (0x3e) plen 29 #596 [hci0] 1.756556
+ LE CIS Established (0x19)
+ Status: Success (0x00)
+ Connection Handle: 2064
+ CIG Sync Delay: 5000 us
+ CIS Sync Delay: 5000 us
+ Central to Peripheral Latency: 10000 us
+ Peripheral to Central Latency: 10000 us
+ Central to Peripheral PHY: LE 2M PHY
+ Peripheral to Central PHY: LE 2M PHY
+ NSE: 3
+ Central to Peripheral BN: 1
+ Peripheral to Central BN: 0
+ Central to Peripheral FT: 2
+ Peripheral to Central FT: 2
+ Max PDU C to P: 120
+ Max PDU P to C: 0
+ ISO Interval: 10.00 msec (0x0008)
+
+Note that the CIS Handle (2064) is different from the ACL Handle
+(2048). CIS data packets use the CIS handle.
+
+**ISO Data Path Setup**::
+
+ < HCI Command: LE Setup ISO Data Path (0x08|0x006e) plen 13 #598 [hci0] 1.820003
+ Handle: 2064
+ Data Path Direction: Input (Host to Controller) (0x00)
+ Data Path ID: HCI (0x00)
+ Coding Format: LC3 (0x06)
+ Company ID: 0x0000
+ Vendor Codec ID: 0x0000
+ Controller Delay: 0 us
+
+After this, ISO data packets flow on the CIS handle::
+
+ < ISO Data TS: Handle 2064 flags 0x02 dlen 124 #600 [hci0] 1.884003
+
+Broadcast Audio (BIG)
+----------------------
+
+Broadcast Isochronous Streams use BIG (Broadcast Isochronous Group)
+instead of CIS. The setup involves periodic advertising with BASE
+(Broadcast Audio Source Endpoint) announcements.
+
+**BASE announcement** (in periodic advertising data)::
+
+ > HCI Event: LE Meta Event (0x3e) plen 80 #200 [hci0] 0.500003
+ LE Periodic Advertising Report (0x0f)
+ ...
+ Service Data: Basic Audio Announcement (0x1851)
+ Presentation Delay: 40000 us
+ Number of Subgroups: 1
+ Number of BIS: 2
+ Codec: LC3 (0x06)
+ Sampling Frequency: 48000 Hz
+ Frame Duration: 10 ms
+ Frame Length: 120
+ BIS #1
+ Audio Channel Allocation: Front Left
+ BIS #2
+ Audio Channel Allocation: Front Right
+
+**BIG creation** (source side)::
+
+ < HCI Command: LE Create BIG (0x08|0x0068) plen 31 #210 [hci0] 0.600003
+ BIG Handle: 0x00
+ Advertising Handle: 0x01
+ Number of BIS: 2
+ SDU Interval: 10000 us
+ Max SDU: 120
+ Max Latency: 10 ms
+ RTN: 2
+ PHY: LE 2M PHY
+ Packing: Sequential (0x00)
+ Framing: Unframed (0x00)
+ Encryption: Unencrypted (0x00)
+
+**BIG sync** (receiver side)::
+
+ < HCI Command: LE BIG Create Sync (0x08|0x006b) plen 15 #220 [hci0] 0.700003
+ BIG Handle: 0x00
+ Sync Handle: 0x0001
+ Encryption: Unencrypted (0x00)
+ Number of BIS: 2
+ BIS: 0x01
+ BIS: 0x02
+
+BIG Sync Receiver Flow
+~~~~~~~~~~~~~~~~~~~~~~
+
+A receiver must complete a specific sequence of steps before it can
+receive broadcast audio. The critical prerequisite chain is:
+
+1. **Synchronize to periodic advertising** -- the receiver must first
+ discover and sync to the broadcaster's periodic advertising train.
+2. **Receive PA Reports with BASE** -- the periodic advertising data
+ contains the BASE (Broadcast Audio Source Endpoint) structure
+ describing the broadcast's codec configuration.
+3. **Receive BIG Info Advertising Report** -- this event tells the
+ receiver that a BIG exists on the periodic advertising train and
+ provides its parameters (number of BIS, encryption, SDU interval,
+ etc.). **This is the critical gate**: without receiving BIG Info,
+ the receiver cannot issue ``LE BIG Create Sync``.
+4. **Issue LE BIG Create Sync** -- using the sync handle from step 1
+ and parameters from step 3.
+5. **Receive BIG Sync Established** -- the controller confirms sync
+ with BIS connection handles.
+6. **Setup ISO Data Path** -- configure the data path for each BIS.
+7. **ISO Data flows** -- broadcast audio packets arrive.
+
+If any step fails or is missing, the subsequent steps cannot proceed.
+The most common failure pattern is that **BIG Info is never received**
+(e.g., the periodic advertising data does not contain a BIG, or PA
+sync was lost before BIG Info arrived), which means ``LE BIG Create
+Sync`` is never sent.
+
+Without PAST (Direct PA Sync)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When the receiver scans for and syncs to periodic advertising
+directly (without assistance from a Broadcast Assistant):
+
+**Step 1 -- Create PA sync**::
+
+ < HCI Command: LE Periodic Advertising Create Sync (0x08|0x0044) plen 14 #100 [hci0] 0.100003
+ Options: 0x0000
+ SID: 0x01
+ Adv Address Type: Public (0x00)
+ Adv Address: XX:XX:XX:XX:XX:XX
+ Skip: 0x0000
+ Sync Timeout: 2000 msec (0x00c8)
+ Sync CTE Type: 0x0000
+
+**Step 2 -- PA Sync Established** (sync handle assigned)::
+
+ > HCI Event: LE Meta Event (0x3e) plen 16 #105 [hci0] 0.150003
+ LE Periodic Advertising Sync Established (0x0e)
+ Status: Success (0x00)
+ Sync Handle: 0x0001
+ Advertising SID: 0x01
+ Advertiser Address Type: Public (0x00)
+ Advertiser Address: XX:XX:XX:XX:XX:XX
+ Advertiser PHY: LE 2M PHY (0x02)
+ Periodic Advertising Interval: 10.000 msec (0x0008)
+ Advertiser Clock Accuracy: 0x05
+
+**Step 3 -- PA Reports** (contain BASE data)::
+
+ > HCI Event: LE Meta Event (0x3e) plen 80 #110 [hci0] 0.200003
+ LE Periodic Advertising Report (0x0f)
+ Sync Handle: 0x0001
+ ...
+ Service Data: Basic Audio Announcement (0x1851)
+
+**Step 4 -- BIG Info Advertising Report** (critical gate)::
+
+ > HCI Event: LE Meta Event (0x3e) plen 24 #120 [hci0] 0.300003
+ LE BIG Info Advertising Report (0x22)
+ Sync Handle: 0x0001
+ Number BIS: 2
+ NSE: 4
+ ISO Interval: 10.000 msec (0x0008)
+ BN: 2
+ PTO: 1
+ IRC: 2
+ Maximum PDU: 120
+ SDU Interval: 10000 us
+ Maximum SDU: 120
+ PHY: LE 2M PHY (0x02)
+ Framing: Unframed (0x00)
+ Encryption: 0x00
+
+This event is generated by the controller each time it receives a
+periodic advertising packet that contains BIG Info. It provides all
+parameters the receiver needs to decide whether to sync to the BIG.
+Key fields:
+
+- ``Number BIS`` -- how many BIS streams are available.
+- ``SDU Interval`` and ``Maximum SDU`` -- audio frame timing and size.
+- ``Encryption`` -- whether a Broadcast Code is required (0x01) or
+ not (0x00). If encrypted, the receiver must supply the correct
+ Broadcast Code in ``LE BIG Create Sync``.
+- ``Sync Handle`` -- must match a currently active PA sync.
+
+**Step 5 -- BIG Create Sync** (using sync handle + BIG Info)::
+
+ < HCI Command: LE BIG Create Sync (0x08|0x006b) plen 15 #130 [hci0] 0.400003
+ BIG Handle: 0x00
+ BIG Sync Handle: 0x0001
+ Encryption: Unencrypted (0x00)
+ Broadcast Code: 00000000000000000000000000000000
+ Maximum Number Subevents: 0x00
+ Timeout: 2000 ms (0x00c8)
+ Number of BIS: 2
+ BIS: 0x01
+ BIS: 0x02
+
+**Step 6 -- BIG Sync Established**::
+
+ > HCI Event: LE Meta Event (0x3e) plen 20 #135 [hci0] 0.450003
+ LE BIG Sync Established (0x1d)
+ Status: Success (0x00)
+ BIG Handle: 0x00
+ Transport Latency: 10000 us
+ NSE: 4
+ BN: 2
+ PTO: 1
+ IRC: 2
+ Maximum PDU: 120
+ ISO Interval: 10.000 msec (0x0008)
+ Connection Handle: 0x0010
+ Connection Handle: 0x0011
+
+On success, the controller assigns BIS connection handles (0x0010,
+0x0011 above). A non-zero Status indicates failure -- common errors:
+
+- ``0x3e`` (Connection Failed to be Established) -- BIG parameters
+ do not match or the BIG is no longer present.
+- ``0x3f`` (Limit Reached) -- controller resources exhausted.
+
+**Step 7 -- Setup ISO Data Path** (for each BIS)::
+
+ < HCI Command: LE Setup ISO Data Path (0x08|0x006e) plen 13 #140 [hci0] 0.500003
+ Connection Handle: 0x0010
+ Data Path Direction: Output (Host to Controller) (0x01)
+ Data Path ID: HCI (0x00)
+
+ < HCI Command: LE Setup ISO Data Path (0x08|0x006e) plen 13 #145 [hci0] 0.550003
+ Connection Handle: 0x0011
+ Data Path Direction: Output (Host to Controller) (0x01)
+ Data Path ID: HCI (0x00)
+
+**Step 8 -- ISO Data flows** on BIS handles::
+
+ > ISO Data: Handle 0x0010 flags 0x02 dlen 124 #150 [hci0] 0.600003
+ > ISO Data: Handle 0x0011 flags 0x02 dlen 124 #151 [hci0] 0.600003
+
+With PAST (Periodic Advertising Sync Transfer)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When a Broadcast Assistant (e.g., a phone) helps a Scan Delegator
+(e.g., a hearing aid) sync to a broadcast, it can transfer the PA
+sync via PAST over an existing ACL connection. This avoids the
+delegator having to scan for and sync to the PA train itself.
+
+The BASS (Broadcast Audio Scan Service) protocol coordinates this:
+
+1. The assistant writes an **Add Source** operation to the delegator's
+ BASS control point with ``PA Sync`` set to ``0x01``
+ (Synchronize via PAST).
+2. The delegator prepares to receive the transfer by setting PAST
+ parameters.
+3. The assistant transfers its PA sync to the delegator.
+4. The delegator receives the PAST event with a sync handle.
+5. From here, the flow continues as in the non-PAST case (PA Reports
+ → BIG Info → BIG Create Sync → etc.).
+
+**BASS Add Source** (assistant writes to delegator, seen in ATT)::
+
+ < ACL Data TX: Handle 64 flags 0x00 dlen 27 #300 [hci0] 1.000003
+ ATT: Write Command (0x52) len 22
+ Handle: 0x0025
+ Data: 04...
+ Opcode: Add Source (0x04)
+ Advertiser Address Type: Public (0x00)
+ Advertiser Address: XX:XX:XX:XX:XX:XX
+ Advertising SID: 0x01
+ PA Sync: Synchronize to PA - PAST (0x01)
+ PA Interval: 0x0008
+ Number of Subgroups: 1
+ BIS Sync: 0x00000003
+ Metadata Length: 0
+
+PA Sync values in the Add Source operation:
+
+- ``0x00`` -- Do not synchronize to PA
+- ``0x01`` -- Synchronize to PA, PAST available
+- ``0x02`` -- Synchronize to PA, PAST not available (delegator
+ must scan and sync directly)
+
+**PAST Parameters** (delegator prepares to receive transfer)::
+
+ < HCI Command: LE Periodic Advertising Sync Transfer Parameters (0x08|0x005c) plen 8 #310 [hci0] 1.100003
+ Connection handle: 64
+ Mode: Enabled with report events enabled (0x02)
+ Skip: 0x00
+ Sync timeout: 2000 msec (0x00c8)
+ Sync CTE Type: 0x0000
+
+**PAST Transfer** (assistant sends its PA sync)::
+
+ < HCI Command: LE Periodic Advertising Sync Transfer (0x08|0x005a) plen 6 #320 [hci0] 1.200003
+ Connection handle: 64
+ Service data: 0x0001
+ Sync handle: 1
+
+**PAST Received** (delegator gets the sync handle)::
+
+ > HCI Event: LE Meta Event (0x3e) plen 19 #325 [hci0] 1.250003
+ LE Periodic Advertising Sync Transfer Received (0x18)
+ Status: Success (0x00)
+ Handle: 64
+ Connection handle: 64
+ Service data: 0x0001
+ Sync handle: 1
+ SID: 0x01
+ Address type: Public (0x00)
+ Address: XX:XX:XX:XX:XX:XX
+ PHY: LE 2M PHY (0x02)
+ Periodic advertising Interval: 10.000
+ Clock Accuracy: 0x05
+
+On success, the delegator now has a PA sync (``Sync handle: 1``) and
+will begin receiving PA Reports and BIG Info events, continuing from
+step 3 of the non-PAST flow above.
+
+.. note::
+
+ **Race condition**: The PAST Parameters command must be sent
+ **before** the assistant sends the PAST Transfer. In BlueZ, the
+ PA sync state in BASS is set after probing completes to avoid
+ the remote sending PAST before the kernel has enabled PAST
+ Parameters on the HCI level.
+
+BIG Sync Teardown
+^^^^^^^^^^^^^^^^^
+
+**Receiver-initiated teardown** -- the receiver terminates its BIG
+sync::
+
+ < HCI Command: LE BIG Terminate Sync (0x08|0x006c) plen 1 #500 [hci0] 5.000003
+ BIG Handle: 0x00
+
+ > HCI Event: Command Complete (0x0e) plen 5 #501 [hci0] 5.001003
+ LE BIG Terminate Sync (0x08|0x006c) ncmd 1
+ Status: Success (0x00)
+ BIG Handle: 0x00
+
+**Broadcaster-initiated teardown** -- the broadcaster terminates its
+BIG, and the receiver gets a BIG Sync Lost event::
+
+ > HCI Event: LE Meta Event (0x3e) plen 2 #510 [hci0] 6.000003
+ LE BIG Sync Lost (0x1e)
+ BIG Handle: 0x00
+ Reason: Connection Terminated By Local Host (0x16)
+
+The ``Reason`` field indicates why sync was lost:
+
+- ``0x08`` (Connection Timeout) -- BIG packets not received within
+ the sync timeout.
+- ``0x13`` (Remote User Terminated Connection) -- broadcaster stopped
+ the BIG intentionally.
+- ``0x16`` (Connection Terminated By Local Host) -- local controller
+ terminated.
+- ``0x3e`` (Connection Failed to be Established) -- could not
+ establish sync initially.
+
+**Source-side BIG termination** (broadcaster tears down)::
+
+ < HCI Command: LE Terminate BIG (0x08|0x006a) plen 2 #520 [hci0] 7.000003
+ BIG Handle: 0x00
+ Reason: Connection Terminated By Local Host (0x16)
+
+ > HCI Event: LE Meta Event (0x3e) plen 2 #521 [hci0] 7.001003
+ LE BIG Terminate (0x1c)
+ BIG Handle: 0x00
+ Reason: Connection Terminated By Local Host (0x16)
+
+BIG Sync Failure Diagnosis
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When analyzing a trace where BIG sync fails, check the following in
+order:
+
+1. **Is PA sync established?** -- Look for ``LE Periodic Advertising
+ Sync Established`` with ``Status: Success``. If missing, the
+ receiver never synced to the PA train.
+2. **Are PA Reports arriving?** -- Look for ``LE Periodic Advertising
+ Report`` events. If absent after PA sync, the PA train may have
+ been lost.
+3. **Is BIG Info received?** -- Look for ``LE BIG Info Advertising
+ Report``. **If this event never appears, the BIG does not exist
+ on this PA train**, or the broadcaster has not yet started it.
+ Without BIG Info, ``LE BIG Create Sync`` cannot be sent.
+4. **Is BIG Create Sync sent?** -- If BIG Info was received but
+ ``LE BIG Create Sync`` was never sent, the host-side logic failed
+ to act on the BIG Info (e.g., mismatched codec, encryption
+ mismatch, application-level issue).
+5. **Does BIG Sync Established succeed?** -- Check the ``Status``
+ field. A non-zero status means the controller could not sync to
+ the BIG.
+6. **Is ISO Data Path set up?** -- Look for ``LE Setup ISO Data Path``
+ for each BIS handle from BIG Sync Established.
+7. **Is ISO Data flowing?** -- Look for ``ISO Data`` packets on the
+ BIS handles.
+
+Automating LE Audio Analysis
+------------------------------
+
+**Identify LE Audio activity**::
+
+ grep -n "ASE Control Point\|ASE ID\|State:.*Codec Configured\|State:.*QoS Configured\|State:.*Enabling\|State:.*Streaming\|State:.*Releasing" output.txt
+
+**Track ASE state transitions** for a specific ASE::
+
+ grep -n "ASE ID:" output.txt
+
+Then examine the ``State:`` line following each ASE ID match.
+
+**Check codec configuration**::
+
+ grep -n "Codec: LC3\|Sampling Frequency:\|Frame Duration:\|Frame Length:\|Audio Channel" output.txt
+
+**Verify CIS establishment**::
+
+ grep -n "Set CIG Parameters\|Create CIS\|CIS Established\|Setup ISO Data Path" output.txt
+
+**Detect CIS failures** -- check the Status field after
+``CIS Established``::
+
+ grep -n "CIS Established" output.txt
+
+Then examine the following line for ``Status:``.
+
+**Detect broadcast audio**::
+
+ grep -n "Basic Audio Announcement\|Create BIG\|BIG Complete\|BIG Create Sync\|BIG Sync\|BIG Info\|BIG Terminate\|BIG Sync Lost" output.txt
+
+**Trace BIG Sync receiver flow** -- verify each prerequisite step::
+
+ grep -n "Periodic Advertising Create Sync\|Periodic Advertising Sync Established\|BIG Info Advertising Report\|BIG Create Sync\|BIG Sync Established\|BIG Sync Lost\|BIG Terminate" output.txt
+
+**Detect PAST-based sync** -- check for Periodic Advertising Sync
+Transfer::
+
+ grep -n "Sync Transfer Parameters\|Sync Transfer (0x08\|PAST Received\|PA Sync:.*PAST\|Add Source" output.txt
+
+**Check BIG Info arrival** -- the critical gate for BIG sync. If this
+is absent, the receiver has no BIG to sync to::
+
+ grep -n "BIG Info Advertising Report" output.txt
+
+**Full LE Audio diagnosis pattern**:
+
+*Unicast (CIS) flow:*
+
+1. Find PACS reads -- verify codec compatibility between devices
+2. Find ASE Control Point writes -- trace the Config Codec → Config
+ QoS → Enable sequence
+3. Find ASE state notifications -- verify each transition succeeds
+4. Find CIG Parameters and CIS creation -- verify HCI-level setup
+5. Find ``CIS Established`` -- check Status for success
+6. Find ``Setup ISO Data Path`` -- verify data path configuration
+7. Find ISO Data packets -- confirm audio is flowing
+8. On failure, check ASE Control Point notification responses for
+ error codes (Response Code and Response Reason fields)
+
+*Broadcast (BIG) receiver flow:*
+
+1. Find ``Periodic Advertising Create Sync`` or ``PAST Received`` --
+ how did PA sync start?
+2. Find ``Periodic Advertising Sync Established`` or
+ ``PAST Received`` with ``Status: Success`` -- is PA synced?
+3. Find ``Periodic Advertising Report`` with
+ ``Basic Audio Announcement`` -- is BASE data arriving?
+4. Find ``BIG Info Advertising Report`` -- **critical**: does the BIG
+ exist? If missing, the BIG cannot be synced.
+5. Find ``BIG Create Sync`` -- did the host request BIG sync?
+6. Find ``BIG Sync Established`` -- check ``Status`` for success.
+7. Find ``Setup ISO Data Path`` for each BIS handle.
+8. Find ``ISO Data`` on BIS handles -- confirm audio is flowing.
+9. On failure, check for ``BIG Sync Lost`` and examine ``Reason``.
diff --git a/doc/btmon.rst b/doc/btmon.rst
index 657f33ff19f1..66650752c490 100644
--- a/doc/btmon.rst
+++ b/doc/btmon.rst
@@ -1567,660 +1567,6 @@ channel, note the Source CID and Destination CID from the Connection
Request/Response pair. Then search for those CIDs in subsequent data
frames.
-LE AUDIO PROTOCOL FLOW
-=======================
-
-LE Audio uses a multi-layer protocol stack visible in btmon traces.
-The setup sequence involves ATT operations on specific GATT
-characteristics (PACS, ASCS) followed by HCI-level CIS/BIG
-management. btmon fully decodes all layers.
-
-PACS: Published Audio Capabilities
-------------------------------------
-
-Before audio streaming begins, devices exchange codec capabilities
-via the Published Audio Capabilities Service (PACS). The client reads
-PACS characteristics to learn what the remote device supports.
-
-**Sink PAC read** (remote device's receive capabilities)::
-
- < ACL Data TX: Handle 2048 flags 0x00 dlen 7 #550 [hci0] 0.824003
- ATT: Read Request (0x0a) len 2
- Handle: 0x0075
-
- > ACL Data RX: Handle 2048 flags 0x02 dlen 30 #552 [hci0] 0.886556
- ATT: Read Response (0x0b) len 25
- Handle: 0x0075
- Number of PAC(s): 1
- Codec: LC3 (0x06)
- Codec Specific Capabilities: #0
- Sampling Frequency: 8000 Hz 16000 Hz 24000 Hz 32000 Hz 48000 Hz
- Frame Duration: 7.5 ms 10 ms
- Audio Channel Counts: 1
- Frame Length: 26 - 240
-
-The PAC record shows codec capabilities using LTV (Length-Type-Value)
-encoding. Key fields:
-
-- **Codec** -- ``LC3 (0x06)`` is the mandatory LE Audio codec
-- **Sampling Frequency** -- Supported sample rates (bitmask)
-- **Frame Duration** -- Supported frame durations (7.5 ms and/or 10 ms)
-- **Audio Channel Counts** -- Supported channel counts
-- **Frame Length** -- Min and max octets per codec frame
-
-**Audio Locations** (channel assignment)::
-
- > ACL Data RX: Handle 2048 flags 0x02 dlen 9 #554 [hci0] 0.948003
- ATT: Read Response (0x0b) len 4
- Handle: 0x0077
- Location: Front Left
-
-**Available Audio Contexts** (current use cases)::
-
- > ACL Data RX: Handle 2048 flags 0x02 dlen 9 #558 [hci0] 1.012556
- ATT: Read Response (0x0b) len 4
- Handle: 0x007b
- Sink Context: Media Conversational
- Source Context: Unspecified
-
-ASCS: Audio Stream Control
-----------------------------
-
-The Audio Stream Control Service (ASCS) manages the ASE (Audio Stream
-Endpoint) state machine. Each ASE transitions through a defined set
-of states as streaming is set up and torn down.
-
-**ASE State Machine**::
-
- Idle ──► Codec Configured ──► QoS Configured ──► Enabling ──► Streaming
- │
- Idle ◄── Releasing ◄──────── Disabling ◄─────────────────────────┘
-
-**ASE Status notification** (state change)::
-
- > ACL Data RX: Handle 2048 flags 0x02 dlen 20 #580 [hci0] 1.456003
- ATT: Handle Value Notification (0x1b) len 15
- Handle: 0x0088
- ASE ID: 0x01
- State: Codec Configured (0x01)
- Framing: Unframed PDUs supported (0x00)
- PHY: 0x02
- LE 2M PHY (0x02)
- RTN: 2
- Max Transport Latency: 10
- Presentation Delay Min: 20000 us
- Presentation Delay Max: 40000 us
- Preferred Presentation Delay Min: 20000 us
- Preferred Presentation Delay Max: 40000 us
- Codec: LC3 (0x06)
- Sampling Frequency: 48000 Hz
- Frame Duration: 10 ms
- Audio Channel Allocation: Front Left
- Frame Length: 120
-
-**ASE Control Point operations** drive state transitions. The client
-writes to the ASE Control Point characteristic to issue commands::
-
- < ACL Data TX: Handle 2048 flags 0x00 dlen 25 #582 [hci0] 1.518003
- ATT: Write Request (0x12) len 20
- Handle: 0x008b
- ASE Control Point: Config Codec (0x01)
- ASE ID: 0x01
- Target Latency: Low Latency (0x01)
- PHY: LE 2M PHY
- Codec: LC3 (0x06)
- Sampling Frequency: 48000 Hz
- Frame Duration: 10 ms
- Audio Channel Allocation: Front Left
- Frame Length: 120
-
-ASE Control Point commands:
-
-.. list-table::
- :header-rows: 1
- :widths: 10 25 65
-
- * - Opcode
- - Command
- - Purpose
- * - 0x01
- - Config Codec
- - Select codec and parameters (Idle → Codec Configured)
- * - 0x02
- - Config QoS
- - Set CIG/CIS IDs and QoS params (Codec Configured → QoS Configured)
- * - 0x03
- - Enable
- - Start ASE with metadata (QoS Configured → Enabling)
- * - 0x04
- - Receiver Start Ready
- - Signal receiver readiness (Enabling → Streaming, server-side)
- * - 0x05
- - Disable
- - Stop streaming (Streaming → Disabling)
- * - 0x06
- - Receiver Stop Ready
- - Signal receiver stopped
- * - 0x07
- - Update Metadata
- - Change metadata during streaming
- * - 0x08
- - Release
- - Tear down ASE (any → Releasing → Idle)
-
-CIS Setup and Teardown
-------------------------
-
-After ASE QoS Configuration, the host creates Connected Isochronous
-Streams (CIS) at the HCI level.
-
-**CIG Parameters** (configure the CIS group)::
-
- < HCI Command: LE Set CIG Parameters (0x08|0x0062) plen 26 #590 [hci0] 1.624003
- CIG ID: 0x00
- Central to Peripheral SDU Interval: 10000 us
- Peripheral to Central SDU Interval: 10000 us
- SCA: 0x00
- Packing: Sequential (0x00)
- Framing: Unframed (0x00)
- Central to Peripheral Max Latency: 10 ms
- Peripheral to Central Max Latency: 10 ms
- Number of CIS: 1
- CIS ID: 0x00
- Central to Peripheral Max SDU: 120
- Peripheral to Central Max SDU: 0
- Central to Peripheral PHY: LE 2M PHY
- Peripheral to Central PHY: LE 2M PHY
- Central to Peripheral RTN: 2
- Peripheral to Central RTN: 2
-
- > HCI Event: Command Complete (0x0e) plen 8 #592 [hci0] 1.624556
- LE Set CIG Parameters (0x08|0x0062) ncmd 1
- Status: Success (0x00)
- CIG ID: 0x00
- Number of Handles: 1
- Connection Handle: 2064
-
-**CIS Creation**::
-
- < HCI Command: LE Create CIS (0x08|0x0064) plen 9 #594 [hci0] 1.688003
- Number of CIS: 1
- CIS Handle: 2064
- ACL Handle: 2048
-
- > HCI Event: LE Meta Event (0x3e) plen 29 #596 [hci0] 1.756556
- LE CIS Established (0x19)
- Status: Success (0x00)
- Connection Handle: 2064
- CIG Sync Delay: 5000 us
- CIS Sync Delay: 5000 us
- Central to Peripheral Latency: 10000 us
- Peripheral to Central Latency: 10000 us
- Central to Peripheral PHY: LE 2M PHY
- Peripheral to Central PHY: LE 2M PHY
- NSE: 3
- Central to Peripheral BN: 1
- Peripheral to Central BN: 0
- Central to Peripheral FT: 2
- Peripheral to Central FT: 2
- Max PDU C to P: 120
- Max PDU P to C: 0
- ISO Interval: 10.00 msec (0x0008)
-
-Note that the CIS Handle (2064) is different from the ACL Handle
-(2048). CIS data packets use the CIS handle.
-
-**ISO Data Path Setup**::
-
- < HCI Command: LE Setup ISO Data Path (0x08|0x006e) plen 13 #598 [hci0] 1.820003
- Handle: 2064
- Data Path Direction: Input (Host to Controller) (0x00)
- Data Path ID: HCI (0x00)
- Coding Format: LC3 (0x06)
- Company ID: 0x0000
- Vendor Codec ID: 0x0000
- Controller Delay: 0 us
-
-After this, ISO data packets flow on the CIS handle::
-
- < ISO Data TS: Handle 2064 flags 0x02 dlen 124 #600 [hci0] 1.884003
-
-Broadcast Audio (BIG)
-----------------------
-
-Broadcast Isochronous Streams use BIG (Broadcast Isochronous Group)
-instead of CIS. The setup involves periodic advertising with BASE
-(Broadcast Audio Source Endpoint) announcements.
-
-**BASE announcement** (in periodic advertising data)::
-
- > HCI Event: LE Meta Event (0x3e) plen 80 #200 [hci0] 0.500003
- LE Periodic Advertising Report (0x0f)
- ...
- Service Data: Basic Audio Announcement (0x1851)
- Presentation Delay: 40000 us
- Number of Subgroups: 1
- Number of BIS: 2
- Codec: LC3 (0x06)
- Sampling Frequency: 48000 Hz
- Frame Duration: 10 ms
- Frame Length: 120
- BIS #1
- Audio Channel Allocation: Front Left
- BIS #2
- Audio Channel Allocation: Front Right
-
-**BIG creation** (source side)::
-
- < HCI Command: LE Create BIG (0x08|0x0068) plen 31 #210 [hci0] 0.600003
- BIG Handle: 0x00
- Advertising Handle: 0x01
- Number of BIS: 2
- SDU Interval: 10000 us
- Max SDU: 120
- Max Latency: 10 ms
- RTN: 2
- PHY: LE 2M PHY
- Packing: Sequential (0x00)
- Framing: Unframed (0x00)
- Encryption: Unencrypted (0x00)
-
-**BIG sync** (receiver side)::
-
- < HCI Command: LE BIG Create Sync (0x08|0x006b) plen 15 #220 [hci0] 0.700003
- BIG Handle: 0x00
- Sync Handle: 0x0001
- Encryption: Unencrypted (0x00)
- Number of BIS: 2
- BIS: 0x01
- BIS: 0x02
-
-BIG Sync Receiver Flow
-~~~~~~~~~~~~~~~~~~~~~~
-
-A receiver must complete a specific sequence of steps before it can
-receive broadcast audio. The critical prerequisite chain is:
-
-1. **Synchronize to periodic advertising** -- the receiver must first
- discover and sync to the broadcaster's periodic advertising train.
-2. **Receive PA Reports with BASE** -- the periodic advertising data
- contains the BASE (Broadcast Audio Source Endpoint) structure
- describing the broadcast's codec configuration.
-3. **Receive BIG Info Advertising Report** -- this event tells the
- receiver that a BIG exists on the periodic advertising train and
- provides its parameters (number of BIS, encryption, SDU interval,
- etc.). **This is the critical gate**: without receiving BIG Info,
- the receiver cannot issue ``LE BIG Create Sync``.
-4. **Issue LE BIG Create Sync** -- using the sync handle from step 1
- and parameters from step 3.
-5. **Receive BIG Sync Established** -- the controller confirms sync
- with BIS connection handles.
-6. **Setup ISO Data Path** -- configure the data path for each BIS.
-7. **ISO Data flows** -- broadcast audio packets arrive.
-
-If any step fails or is missing, the subsequent steps cannot proceed.
-The most common failure pattern is that **BIG Info is never received**
-(e.g., the periodic advertising data does not contain a BIG, or PA
-sync was lost before BIG Info arrived), which means ``LE BIG Create
-Sync`` is never sent.
-
-Without PAST (Direct PA Sync)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-When the receiver scans for and syncs to periodic advertising
-directly (without assistance from a Broadcast Assistant):
-
-**Step 1 -- Create PA sync**::
-
- < HCI Command: LE Periodic Advertising Create Sync (0x08|0x0044) plen 14 #100 [hci0] 0.100003
- Options: 0x0000
- SID: 0x01
- Adv Address Type: Public (0x00)
- Adv Address: XX:XX:XX:XX:XX:XX
- Skip: 0x0000
- Sync Timeout: 2000 msec (0x00c8)
- Sync CTE Type: 0x0000
-
-**Step 2 -- PA Sync Established** (sync handle assigned)::
-
- > HCI Event: LE Meta Event (0x3e) plen 16 #105 [hci0] 0.150003
- LE Periodic Advertising Sync Established (0x0e)
- Status: Success (0x00)
- Sync Handle: 0x0001
- Advertising SID: 0x01
- Advertiser Address Type: Public (0x00)
- Advertiser Address: XX:XX:XX:XX:XX:XX
- Advertiser PHY: LE 2M PHY (0x02)
- Periodic Advertising Interval: 10.000 msec (0x0008)
- Advertiser Clock Accuracy: 0x05
-
-**Step 3 -- PA Reports** (contain BASE data)::
-
- > HCI Event: LE Meta Event (0x3e) plen 80 #110 [hci0] 0.200003
- LE Periodic Advertising Report (0x0f)
- Sync Handle: 0x0001
- ...
- Service Data: Basic Audio Announcement (0x1851)
-
-**Step 4 -- BIG Info Advertising Report** (critical gate)::
-
- > HCI Event: LE Meta Event (0x3e) plen 24 #120 [hci0] 0.300003
- LE BIG Info Advertising Report (0x22)
- Sync Handle: 0x0001
- Number BIS: 2
- NSE: 4
- ISO Interval: 10.000 msec (0x0008)
- BN: 2
- PTO: 1
- IRC: 2
- Maximum PDU: 120
- SDU Interval: 10000 us
- Maximum SDU: 120
- PHY: LE 2M PHY (0x02)
- Framing: Unframed (0x00)
- Encryption: 0x00
-
-This event is generated by the controller each time it receives a
-periodic advertising packet that contains BIG Info. It provides all
-parameters the receiver needs to decide whether to sync to the BIG.
-Key fields:
-
-- ``Number BIS`` -- how many BIS streams are available.
-- ``SDU Interval`` and ``Maximum SDU`` -- audio frame timing and size.
-- ``Encryption`` -- whether a Broadcast Code is required (0x01) or
- not (0x00). If encrypted, the receiver must supply the correct
- Broadcast Code in ``LE BIG Create Sync``.
-- ``Sync Handle`` -- must match a currently active PA sync.
-
-**Step 5 -- BIG Create Sync** (using sync handle + BIG Info)::
-
- < HCI Command: LE BIG Create Sync (0x08|0x006b) plen 15 #130 [hci0] 0.400003
- BIG Handle: 0x00
- BIG Sync Handle: 0x0001
- Encryption: Unencrypted (0x00)
- Broadcast Code: 00000000000000000000000000000000
- Maximum Number Subevents: 0x00
- Timeout: 2000 ms (0x00c8)
- Number of BIS: 2
- BIS: 0x01
- BIS: 0x02
-
-**Step 6 -- BIG Sync Established**::
-
- > HCI Event: LE Meta Event (0x3e) plen 20 #135 [hci0] 0.450003
- LE BIG Sync Established (0x1d)
- Status: Success (0x00)
- BIG Handle: 0x00
- Transport Latency: 10000 us
- NSE: 4
- BN: 2
- PTO: 1
- IRC: 2
- Maximum PDU: 120
- ISO Interval: 10.000 msec (0x0008)
- Connection Handle: 0x0010
- Connection Handle: 0x0011
-
-On success, the controller assigns BIS connection handles (0x0010,
-0x0011 above). A non-zero Status indicates failure -- common errors:
-
-- ``0x3e`` (Connection Failed to be Established) -- BIG parameters
- do not match or the BIG is no longer present.
-- ``0x3f`` (Limit Reached) -- controller resources exhausted.
-
-**Step 7 -- Setup ISO Data Path** (for each BIS)::
-
- < HCI Command: LE Setup ISO Data Path (0x08|0x006e) plen 13 #140 [hci0] 0.500003
- Connection Handle: 0x0010
- Data Path Direction: Output (Host to Controller) (0x01)
- Data Path ID: HCI (0x00)
-
- < HCI Command: LE Setup ISO Data Path (0x08|0x006e) plen 13 #145 [hci0] 0.550003
- Connection Handle: 0x0011
- Data Path Direction: Output (Host to Controller) (0x01)
- Data Path ID: HCI (0x00)
-
-**Step 8 -- ISO Data flows** on BIS handles::
-
- > ISO Data: Handle 0x0010 flags 0x02 dlen 124 #150 [hci0] 0.600003
- > ISO Data: Handle 0x0011 flags 0x02 dlen 124 #151 [hci0] 0.600003
-
-With PAST (Periodic Advertising Sync Transfer)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-When a Broadcast Assistant (e.g., a phone) helps a Scan Delegator
-(e.g., a hearing aid) sync to a broadcast, it can transfer the PA
-sync via PAST over an existing ACL connection. This avoids the
-delegator having to scan for and sync to the PA train itself.
-
-The BASS (Broadcast Audio Scan Service) protocol coordinates this:
-
-1. The assistant writes an **Add Source** operation to the delegator's
- BASS control point with ``PA Sync`` set to ``0x01``
- (Synchronize via PAST).
-2. The delegator prepares to receive the transfer by setting PAST
- parameters.
-3. The assistant transfers its PA sync to the delegator.
-4. The delegator receives the PAST event with a sync handle.
-5. From here, the flow continues as in the non-PAST case (PA Reports
- → BIG Info → BIG Create Sync → etc.).
-
-**BASS Add Source** (assistant writes to delegator, seen in ATT)::
-
- < ACL Data TX: Handle 64 flags 0x00 dlen 27 #300 [hci0] 1.000003
- ATT: Write Command (0x52) len 22
- Handle: 0x0025
- Data: 04...
- Opcode: Add Source (0x04)
- Advertiser Address Type: Public (0x00)
- Advertiser Address: XX:XX:XX:XX:XX:XX
- Advertising SID: 0x01
- PA Sync: Synchronize to PA - PAST (0x01)
- PA Interval: 0x0008
- Number of Subgroups: 1
- BIS Sync: 0x00000003
- Metadata Length: 0
-
-PA Sync values in the Add Source operation:
-
-- ``0x00`` -- Do not synchronize to PA
-- ``0x01`` -- Synchronize to PA, PAST available
-- ``0x02`` -- Synchronize to PA, PAST not available (delegator
- must scan and sync directly)
-
-**PAST Parameters** (delegator prepares to receive transfer)::
-
- < HCI Command: LE Periodic Advertising Sync Transfer Parameters (0x08|0x005c) plen 8 #310 [hci0] 1.100003
- Connection handle: 64
- Mode: Enabled with report events enabled (0x02)
- Skip: 0x00
- Sync timeout: 2000 msec (0x00c8)
- Sync CTE Type: 0x0000
-
-**PAST Transfer** (assistant sends its PA sync)::
-
- < HCI Command: LE Periodic Advertising Sync Transfer (0x08|0x005a) plen 6 #320 [hci0] 1.200003
- Connection handle: 64
- Service data: 0x0001
- Sync handle: 1
-
-**PAST Received** (delegator gets the sync handle)::
-
- > HCI Event: LE Meta Event (0x3e) plen 19 #325 [hci0] 1.250003
- LE Periodic Advertising Sync Transfer Received (0x18)
- Status: Success (0x00)
- Handle: 64
- Connection handle: 64
- Service data: 0x0001
- Sync handle: 1
- SID: 0x01
- Address type: Public (0x00)
- Address: XX:XX:XX:XX:XX:XX
- PHY: LE 2M PHY (0x02)
- Periodic advertising Interval: 10.000
- Clock Accuracy: 0x05
-
-On success, the delegator now has a PA sync (``Sync handle: 1``) and
-will begin receiving PA Reports and BIG Info events, continuing from
-step 3 of the non-PAST flow above.
-
-.. note::
-
- **Race condition**: The PAST Parameters command must be sent
- **before** the assistant sends the PAST Transfer. In BlueZ, the
- PA sync state in BASS is set after probing completes to avoid
- the remote sending PAST before the kernel has enabled PAST
- Parameters on the HCI level.
-
-BIG Sync Teardown
-^^^^^^^^^^^^^^^^^
-
-**Receiver-initiated teardown** -- the receiver terminates its BIG
-sync::
-
- < HCI Command: LE BIG Terminate Sync (0x08|0x006c) plen 1 #500 [hci0] 5.000003
- BIG Handle: 0x00
-
- > HCI Event: Command Complete (0x0e) plen 5 #501 [hci0] 5.001003
- LE BIG Terminate Sync (0x08|0x006c) ncmd 1
- Status: Success (0x00)
- BIG Handle: 0x00
-
-**Broadcaster-initiated teardown** -- the broadcaster terminates its
-BIG, and the receiver gets a BIG Sync Lost event::
-
- > HCI Event: LE Meta Event (0x3e) plen 2 #510 [hci0] 6.000003
- LE BIG Sync Lost (0x1e)
- BIG Handle: 0x00
- Reason: Connection Terminated By Local Host (0x16)
-
-The ``Reason`` field indicates why sync was lost:
-
-- ``0x08`` (Connection Timeout) -- BIG packets not received within
- the sync timeout.
-- ``0x13`` (Remote User Terminated Connection) -- broadcaster stopped
- the BIG intentionally.
-- ``0x16`` (Connection Terminated By Local Host) -- local controller
- terminated.
-- ``0x3e`` (Connection Failed to be Established) -- could not
- establish sync initially.
-
-**Source-side BIG termination** (broadcaster tears down)::
-
- < HCI Command: LE Terminate BIG (0x08|0x006a) plen 2 #520 [hci0] 7.000003
- BIG Handle: 0x00
- Reason: Connection Terminated By Local Host (0x16)
-
- > HCI Event: LE Meta Event (0x3e) plen 2 #521 [hci0] 7.001003
- LE BIG Terminate (0x1c)
- BIG Handle: 0x00
- Reason: Connection Terminated By Local Host (0x16)
-
-BIG Sync Failure Diagnosis
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-When analyzing a trace where BIG sync fails, check the following in
-order:
-
-1. **Is PA sync established?** -- Look for ``LE Periodic Advertising
- Sync Established`` with ``Status: Success``. If missing, the
- receiver never synced to the PA train.
-2. **Are PA Reports arriving?** -- Look for ``LE Periodic Advertising
- Report`` events. If absent after PA sync, the PA train may have
- been lost.
-3. **Is BIG Info received?** -- Look for ``LE BIG Info Advertising
- Report``. **If this event never appears, the BIG does not exist
- on this PA train**, or the broadcaster has not yet started it.
- Without BIG Info, ``LE BIG Create Sync`` cannot be sent.
-4. **Is BIG Create Sync sent?** -- If BIG Info was received but
- ``LE BIG Create Sync`` was never sent, the host-side logic failed
- to act on the BIG Info (e.g., mismatched codec, encryption
- mismatch, application-level issue).
-5. **Does BIG Sync Established succeed?** -- Check the ``Status``
- field. A non-zero status means the controller could not sync to
- the BIG.
-6. **Is ISO Data Path set up?** -- Look for ``LE Setup ISO Data Path``
- for each BIS handle from BIG Sync Established.
-7. **Is ISO Data flowing?** -- Look for ``ISO Data`` packets on the
- BIS handles.
-
-Automating LE Audio Analysis
-------------------------------
-
-**Identify LE Audio activity**::
-
- grep -n "ASE Control Point\|ASE ID\|State:.*Codec Configured\|State:.*QoS Configured\|State:.*Enabling\|State:.*Streaming\|State:.*Releasing" output.txt
-
-**Track ASE state transitions** for a specific ASE::
-
- grep -n "ASE ID:" output.txt
-
-Then examine the ``State:`` line following each ASE ID match.
-
-**Check codec configuration**::
-
- grep -n "Codec: LC3\|Sampling Frequency:\|Frame Duration:\|Frame Length:\|Audio Channel" output.txt
-
-**Verify CIS establishment**::
-
- grep -n "Set CIG Parameters\|Create CIS\|CIS Established\|Setup ISO Data Path" output.txt
-
-**Detect CIS failures** -- check the Status field after
-``CIS Established``::
-
- grep -n "CIS Established" output.txt
-
-Then examine the following line for ``Status:``.
-
-**Detect broadcast audio**::
-
- grep -n "Basic Audio Announcement\|Create BIG\|BIG Complete\|BIG Create Sync\|BIG Sync\|BIG Info\|BIG Terminate\|BIG Sync Lost" output.txt
-
-**Trace BIG Sync receiver flow** -- verify each prerequisite step::
-
- grep -n "Periodic Advertising Create Sync\|Periodic Advertising Sync Established\|BIG Info Advertising Report\|BIG Create Sync\|BIG Sync Established\|BIG Sync Lost\|BIG Terminate" output.txt
-
-**Detect PAST-based sync** -- check for Periodic Advertising Sync
-Transfer::
-
- grep -n "Sync Transfer Parameters\|Sync Transfer (0x08\|PAST Received\|PA Sync:.*PAST\|Add Source" output.txt
-
-**Check BIG Info arrival** -- the critical gate for BIG sync. If this
-is absent, the receiver has no BIG to sync to::
-
- grep -n "BIG Info Advertising Report" output.txt
-
-**Full LE Audio diagnosis pattern**:
-
-*Unicast (CIS) flow:*
-
-1. Find PACS reads -- verify codec compatibility between devices
-2. Find ASE Control Point writes -- trace the Config Codec → Config
- QoS → Enable sequence
-3. Find ASE state notifications -- verify each transition succeeds
-4. Find CIG Parameters and CIS creation -- verify HCI-level setup
-5. Find ``CIS Established`` -- check Status for success
-6. Find ``Setup ISO Data Path`` -- verify data path configuration
-7. Find ISO Data packets -- confirm audio is flowing
-8. On failure, check ASE Control Point notification responses for
- error codes (Response Code and Response Reason fields)
-
-*Broadcast (BIG) receiver flow:*
-
-1. Find ``Periodic Advertising Create Sync`` or ``PAST Received`` --
- how did PA sync start?
-2. Find ``Periodic Advertising Sync Established`` or
- ``PAST Received`` with ``Status: Success`` -- is PA synced?
-3. Find ``Periodic Advertising Report`` with
- ``Basic Audio Announcement`` -- is BASE data arriving?
-4. Find ``BIG Info Advertising Report`` -- **critical**: does the BIG
- exist? If missing, the BIG cannot be synced.
-5. Find ``BIG Create Sync`` -- did the host request BIG sync?
-6. Find ``BIG Sync Established`` -- check ``Status`` for success.
-7. Find ``Setup ISO Data Path`` for each BIS handle.
-8. Find ``ISO Data`` on BIS handles -- confirm audio is flowing.
-9. On failure, check for ``BIG Sync Lost`` and examine ``Reason``.
-
PROTOCOL ERROR CODES
=====================
@@ -2405,6 +1751,8 @@ Errors often cascade across layers. Common patterns:
PROTOCOL FLOWS
===============
+.. include:: btmon-le-audio.rst
+
.. include:: btmon-advertising.rst
EXAMPLES
--
2.53.0
^ permalink raw reply related [flat|nested] 11+ messages in thread
* [PATCH BlueZ v2 3/9] doc/btmon: Split L2CAP Channel Tracking into btmon-l2cap.rst
2026-03-24 19:49 [PATCH BlueZ v2 1/9] doc/btmon: Split Advertising and Scanning into btmon-advertising.rst Luiz Augusto von Dentz
2026-03-24 19:49 ` [PATCH BlueZ v2 2/9] doc/btmon: Split LE Audio Protocol Flow into btmon-le-audio.rst Luiz Augusto von Dentz
@ 2026-03-24 19:49 ` Luiz Augusto von Dentz
2026-03-24 19:49 ` [PATCH BlueZ v2 4/9] doc/btmon: Split SMP Pairing Flow into btmon-smp.rst Luiz Augusto von Dentz
` (6 subsequent siblings)
8 siblings, 0 replies; 11+ messages in thread
From: Luiz Augusto von Dentz @ 2026-03-24 19:49 UTC (permalink / raw)
To: linux-bluetooth
From: Luiz Augusto von Dentz <luiz.von.dentz@intel.com>
Move the L2CAP CHANNEL TRACKING section into a standalone file and
replace it with an RST include directive.
---
doc/btmon-l2cap.rst | 192 +++++++++++++++++++++++++++++++++++++++++++
doc/btmon.rst | 193 +-------------------------------------------
2 files changed, 194 insertions(+), 191 deletions(-)
create mode 100644 doc/btmon-l2cap.rst
diff --git a/doc/btmon-l2cap.rst b/doc/btmon-l2cap.rst
new file mode 100644
index 000000000000..e8c52c5e6c5c
--- /dev/null
+++ b/doc/btmon-l2cap.rst
@@ -0,0 +1,192 @@
+.. This file is included by btmon.rst.
+
+L2CAP CHANNEL TRACKING
+=======================
+
+L2CAP (Logical Link Control and Adaptation Protocol) multiplexes
+multiple logical channels over a single ACL connection. btmon decodes
+L2CAP signaling automatically and routes data to higher-layer protocol
+decoders based on the channel.
+
+Fixed Channels
+--------------
+
+Fixed channels have pre-assigned Channel Identifiers (CIDs) and do
+not require signaling to establish:
+
+.. list-table::
+ :header-rows: 1
+ :widths: 10 30 60
+
+ * - CID
+ - Protocol
+ - Description
+ * - 0x0001
+ - L2CAP Signaling (BR/EDR)
+ - Channel management for classic connections
+ * - 0x0002
+ - Connectionless Reception
+ - Connectionless L2CAP data
+ * - 0x0003
+ - AMP Manager
+ - AMP (Alternate MAC/PHY) control
+ * - 0x0004
+ - ATT
+ - Attribute Protocol (GATT operations)
+ * - 0x0005
+ - L2CAP Signaling (LE)
+ - Channel management for LE connections
+ * - 0x0006
+ - SMP (LE)
+ - Security Manager Protocol
+ * - 0x0007
+ - SMP (BR/EDR)
+ - Security Manager over classic transport
+
+In btmon output, fixed channel traffic is decoded directly without
+any L2CAP signaling preamble. For example, ATT on CID 0x0004 appears
+as::
+
+ < ACL Data TX: Handle 2048 flags 0x00 dlen 7 #494 [hci0] 0.004488
+ ATT: Exchange MTU Request (0x02) len 2
+ Client RX MTU: 517
+
+Dynamic Channels (BR/EDR)
+--------------------------
+
+Classic Bluetooth uses L2CAP signaling on CID 0x0001 to establish
+dynamic channels. Each channel is identified by a PSM (Protocol/Service
+Multiplexer) that determines which protocol runs on it.
+
+**Channel establishment**::
+
+ > ACL Data RX: Handle 256 flags 0x02 dlen 16 #142 [hci0] 2.034556
+ L2CAP: Connection Request (0x02) ident 3 len 4
+ PSM: 25 (0x0019)
+ Source CID: 0x0040
+
+ < ACL Data TX: Handle 256 flags 0x00 dlen 20 #144 [hci0] 2.035002
+ L2CAP: Connection Response (0x03) ident 3 len 8
+ Destination CID: 0x0041
+ Source CID: 0x0040
+ Result: Connection successful (0x0000)
+ Status: No further information available (0x0000)
+
+After connection, configuration is exchanged::
+
+ > ACL Data RX: Handle 256 flags 0x02 dlen 20 #146 [hci0] 2.035556
+ L2CAP: Configure Request (0x04) ident 4 len 8
+ Destination CID: 0x0041
+ Flags: 0x0000
+ Option: MTU (0x01) [2]
+ MTU: 1024
+
+ < ACL Data TX: Handle 256 flags 0x00 dlen 18 #148 [hci0] 2.036003
+ L2CAP: Configure Response (0x05) ident 4 len 6
+ Source CID: 0x0040
+ Flags: 0x0000
+ Result: Success (0x0000)
+
+Common PSM-to-protocol mappings:
+
+.. list-table::
+ :header-rows: 1
+ :widths: 12 25 63
+
+ * - PSM
+ - Protocol
+ - Description
+ * - 0x0001
+ - SDP
+ - Service Discovery Protocol
+ * - 0x0003
+ - RFCOMM
+ - Serial port emulation (SPP, HFP, etc.)
+ * - 0x000f
+ - BNEP
+ - Bluetooth Network Encapsulation Protocol
+ * - 0x0017
+ - AVCTP
+ - Audio/Video Control Transport (AVRCP)
+ * - 0x0019
+ - AVDTP
+ - Audio/Video Distribution Transport (A2DP)
+ * - 0x001b
+ - AVCTP Browsing
+ - AVRCP browsing channel
+ * - 0x001f
+ - ATT (BR/EDR)
+ - Attribute Protocol over classic transport
+ * - 0x0027
+ - EATT
+ - Enhanced Attribute Protocol
+
+LE Credit-Based Channels
+--------------------------
+
+LE connections use L2CAP signaling on CID 0x0005 for dynamic
+channels. The LE Credit Based Connection mechanism provides flow
+control::
+
+ < ACL Data TX: Handle 2048 flags 0x00 dlen 18 #600 [hci0] 1.824003
+ LE L2CAP: LE Connection Request (0x14) ident 1 len 10
+ PSM: 39 (0x0027)
+ Source CID: 0x0040
+ MTU: 517
+ MPS: 251
+ Credits: 10
+
+ > ACL Data RX: Handle 2048 flags 0x02 dlen 18 #602 [hci0] 1.886556
+ LE L2CAP: LE Connection Response (0x15) ident 1 len 10
+ Destination CID: 0x0041
+ MTU: 517
+ MPS: 251
+ Credits: 10
+ Result: Connection successful (0x0000)
+
+EATT (Enhanced ATT) uses PSM 0x0027 over LE Credit-Based channels to
+provide multiple parallel ATT bearers.
+
+Connection Parameter Updates
+-----------------------------
+
+LE peripherals frequently request connection parameter changes via
+L2CAP signaling::
+
+ < ACL Data TX: Handle 2048 flags 0x00 dlen 16 #493 [hci0] 0.003915
+ LE L2CAP: Connection Parameter Update Request (0x12) ident 1 len 8
+ Min interval: 24
+ Max interval: 40
+ Peripheral latency: 0
+ Timeout multiplier: 256
+
+ > ACL Data RX: Handle 2048 flags 0x02 dlen 10 #495 [hci0] 0.066003
+ LE L2CAP: Connection Parameter Update Response (0x13) ident 1 len 2
+ Result: Connection Parameters accepted (0x0000)
+
+A result of ``Connection Parameters rejected (0x0001)`` means the
+central denied the request.
+
+Automating L2CAP Analysis
+--------------------------
+
+**Find all L2CAP channel establishments**::
+
+ grep -n "Connection Request\|Connection Response\|LE Connection Request\|LE Connection Response" output.txt
+
+**Track PSM usage** (identifies which protocols are active)::
+
+ grep -n "PSM:" output.txt
+
+**Find connection parameter update issues**::
+
+ grep -n "Parameter Update Request\|Parameter Update Response\|Parameters rejected" output.txt
+
+**Find EATT channel setup**::
+
+ grep -n "PSM: 39\|Enhanced Credit" output.txt
+
+**Trace a specific L2CAP channel**: To follow traffic on a dynamic
+channel, note the Source CID and Destination CID from the Connection
+Request/Response pair. Then search for those CIDs in subsequent data
+frames.
diff --git a/doc/btmon.rst b/doc/btmon.rst
index 66650752c490..6f283c21c490 100644
--- a/doc/btmon.rst
+++ b/doc/btmon.rst
@@ -1376,197 +1376,6 @@ appears on reconnection, the bond was lost on one side.
5. Check for ``Identity Address Information`` -- reveals the device's
true address
-L2CAP CHANNEL TRACKING
-=======================
-
-L2CAP (Logical Link Control and Adaptation Protocol) multiplexes
-multiple logical channels over a single ACL connection. btmon decodes
-L2CAP signaling automatically and routes data to higher-layer protocol
-decoders based on the channel.
-
-Fixed Channels
---------------
-
-Fixed channels have pre-assigned Channel Identifiers (CIDs) and do
-not require signaling to establish:
-
-.. list-table::
- :header-rows: 1
- :widths: 10 30 60
-
- * - CID
- - Protocol
- - Description
- * - 0x0001
- - L2CAP Signaling (BR/EDR)
- - Channel management for classic connections
- * - 0x0002
- - Connectionless Reception
- - Connectionless L2CAP data
- * - 0x0003
- - AMP Manager
- - AMP (Alternate MAC/PHY) control
- * - 0x0004
- - ATT
- - Attribute Protocol (GATT operations)
- * - 0x0005
- - L2CAP Signaling (LE)
- - Channel management for LE connections
- * - 0x0006
- - SMP (LE)
- - Security Manager Protocol
- * - 0x0007
- - SMP (BR/EDR)
- - Security Manager over classic transport
-
-In btmon output, fixed channel traffic is decoded directly without
-any L2CAP signaling preamble. For example, ATT on CID 0x0004 appears
-as::
-
- < ACL Data TX: Handle 2048 flags 0x00 dlen 7 #494 [hci0] 0.004488
- ATT: Exchange MTU Request (0x02) len 2
- Client RX MTU: 517
-
-Dynamic Channels (BR/EDR)
---------------------------
-
-Classic Bluetooth uses L2CAP signaling on CID 0x0001 to establish
-dynamic channels. Each channel is identified by a PSM (Protocol/Service
-Multiplexer) that determines which protocol runs on it.
-
-**Channel establishment**::
-
- > ACL Data RX: Handle 256 flags 0x02 dlen 16 #142 [hci0] 2.034556
- L2CAP: Connection Request (0x02) ident 3 len 4
- PSM: 25 (0x0019)
- Source CID: 0x0040
-
- < ACL Data TX: Handle 256 flags 0x00 dlen 20 #144 [hci0] 2.035002
- L2CAP: Connection Response (0x03) ident 3 len 8
- Destination CID: 0x0041
- Source CID: 0x0040
- Result: Connection successful (0x0000)
- Status: No further information available (0x0000)
-
-After connection, configuration is exchanged::
-
- > ACL Data RX: Handle 256 flags 0x02 dlen 20 #146 [hci0] 2.035556
- L2CAP: Configure Request (0x04) ident 4 len 8
- Destination CID: 0x0041
- Flags: 0x0000
- Option: MTU (0x01) [2]
- MTU: 1024
-
- < ACL Data TX: Handle 256 flags 0x00 dlen 18 #148 [hci0] 2.036003
- L2CAP: Configure Response (0x05) ident 4 len 6
- Source CID: 0x0040
- Flags: 0x0000
- Result: Success (0x0000)
-
-Common PSM-to-protocol mappings:
-
-.. list-table::
- :header-rows: 1
- :widths: 12 25 63
-
- * - PSM
- - Protocol
- - Description
- * - 0x0001
- - SDP
- - Service Discovery Protocol
- * - 0x0003
- - RFCOMM
- - Serial port emulation (SPP, HFP, etc.)
- * - 0x000f
- - BNEP
- - Bluetooth Network Encapsulation Protocol
- * - 0x0017
- - AVCTP
- - Audio/Video Control Transport (AVRCP)
- * - 0x0019
- - AVDTP
- - Audio/Video Distribution Transport (A2DP)
- * - 0x001b
- - AVCTP Browsing
- - AVRCP browsing channel
- * - 0x001f
- - ATT (BR/EDR)
- - Attribute Protocol over classic transport
- * - 0x0027
- - EATT
- - Enhanced Attribute Protocol
-
-LE Credit-Based Channels
---------------------------
-
-LE connections use L2CAP signaling on CID 0x0005 for dynamic
-channels. The LE Credit Based Connection mechanism provides flow
-control::
-
- < ACL Data TX: Handle 2048 flags 0x00 dlen 18 #600 [hci0] 1.824003
- LE L2CAP: LE Connection Request (0x14) ident 1 len 10
- PSM: 39 (0x0027)
- Source CID: 0x0040
- MTU: 517
- MPS: 251
- Credits: 10
-
- > ACL Data RX: Handle 2048 flags 0x02 dlen 18 #602 [hci0] 1.886556
- LE L2CAP: LE Connection Response (0x15) ident 1 len 10
- Destination CID: 0x0041
- MTU: 517
- MPS: 251
- Credits: 10
- Result: Connection successful (0x0000)
-
-EATT (Enhanced ATT) uses PSM 0x0027 over LE Credit-Based channels to
-provide multiple parallel ATT bearers.
-
-Connection Parameter Updates
------------------------------
-
-LE peripherals frequently request connection parameter changes via
-L2CAP signaling::
-
- < ACL Data TX: Handle 2048 flags 0x00 dlen 16 #493 [hci0] 0.003915
- LE L2CAP: Connection Parameter Update Request (0x12) ident 1 len 8
- Min interval: 24
- Max interval: 40
- Peripheral latency: 0
- Timeout multiplier: 256
-
- > ACL Data RX: Handle 2048 flags 0x02 dlen 10 #495 [hci0] 0.066003
- LE L2CAP: Connection Parameter Update Response (0x13) ident 1 len 2
- Result: Connection Parameters accepted (0x0000)
-
-A result of ``Connection Parameters rejected (0x0001)`` means the
-central denied the request.
-
-Automating L2CAP Analysis
---------------------------
-
-**Find all L2CAP channel establishments**::
-
- grep -n "Connection Request\|Connection Response\|LE Connection Request\|LE Connection Response" output.txt
-
-**Track PSM usage** (identifies which protocols are active)::
-
- grep -n "PSM:" output.txt
-
-**Find connection parameter update issues**::
-
- grep -n "Parameter Update Request\|Parameter Update Response\|Parameters rejected" output.txt
-
-**Find EATT channel setup**::
-
- grep -n "PSM: 39\|Enhanced Credit" output.txt
-
-**Trace a specific L2CAP channel**: To follow traffic on a dynamic
-channel, note the Source CID and Destination CID from the Connection
-Request/Response pair. Then search for those CIDs in subsequent data
-frames.
-
PROTOCOL ERROR CODES
=====================
@@ -1751,6 +1560,8 @@ Errors often cascade across layers. Common patterns:
PROTOCOL FLOWS
===============
+.. include:: btmon-l2cap.rst
+
.. include:: btmon-le-audio.rst
.. include:: btmon-advertising.rst
--
2.53.0
^ permalink raw reply related [flat|nested] 11+ messages in thread
* [PATCH BlueZ v2 4/9] doc/btmon: Split SMP Pairing Flow into btmon-smp.rst
2026-03-24 19:49 [PATCH BlueZ v2 1/9] doc/btmon: Split Advertising and Scanning into btmon-advertising.rst Luiz Augusto von Dentz
2026-03-24 19:49 ` [PATCH BlueZ v2 2/9] doc/btmon: Split LE Audio Protocol Flow into btmon-le-audio.rst Luiz Augusto von Dentz
2026-03-24 19:49 ` [PATCH BlueZ v2 3/9] doc/btmon: Split L2CAP Channel Tracking into btmon-l2cap.rst Luiz Augusto von Dentz
@ 2026-03-24 19:49 ` Luiz Augusto von Dentz
2026-03-24 19:49 ` [PATCH BlueZ v2 5/9] doc/btmon: Split GATT Database Reconstruction into btmon-gatt.rst Luiz Augusto von Dentz
` (5 subsequent siblings)
8 siblings, 0 replies; 11+ messages in thread
From: Luiz Augusto von Dentz @ 2026-03-24 19:49 UTC (permalink / raw)
To: linux-bluetooth
From: Luiz Augusto von Dentz <luiz.von.dentz@intel.com>
Move the SMP PAIRING FLOW section into a standalone file and replace
it with an RST include directive.
---
doc/btmon-smp.rst | 248 +++++++++++++++++++++++++++++++++++++++++++++
doc/btmon.rst | 249 +---------------------------------------------
2 files changed, 250 insertions(+), 247 deletions(-)
create mode 100644 doc/btmon-smp.rst
diff --git a/doc/btmon-smp.rst b/doc/btmon-smp.rst
new file mode 100644
index 000000000000..00b0b34fe1bb
--- /dev/null
+++ b/doc/btmon-smp.rst
@@ -0,0 +1,248 @@
+.. This file is included by btmon.rst.
+
+SMP PAIRING FLOW
+================
+
+The Security Manager Protocol (SMP) handles pairing, key generation,
+and key distribution between Bluetooth devices. SMP traffic appears
+inside L2CAP on fixed CID 0x0006 (LE) or CID 0x0007 (BR/EDR). btmon
+decodes all SMP operations automatically.
+
+Pairing Phases
+--------------
+
+SMP pairing proceeds in three phases. Each phase produces a distinct
+pattern in the btmon output.
+
+**Phase 1: Feature Exchange**
+
+Pairing begins when one device sends a Security Request (peripheral)
+or the host initiates pairing directly. The initiator sends a Pairing
+Request and the responder replies with a Pairing Response::
+
+ > ACL Data RX: Handle 2048 flags 0x02 dlen 11 #497 [hci0] 0.026107
+ SMP: Pairing Request (0x01) len 6
+ IO capability: NoInputNoOutput (0x03)
+ OOB data: Authentication data not present (0x00)
+ Authentication requirement: Bonding, MITM, SC, CT2 (0x2d)
+ Max encryption key size: 16
+ Initiator key distribution: IdKey Sign (0x06)
+ Responder key distribution: IdKey Sign (0x06)
+
+ < ACL Data TX: Handle 2048 flags 0x00 dlen 11 #499 [hci0] 0.026894
+ SMP: Pairing Response (0x02) len 6
+ IO capability: KeyboardDisplay (0x04)
+ OOB data: Authentication data not present (0x00)
+ Authentication requirement: Bonding, SC, CT2 (0x29)
+ Max encryption key size: 16
+ Initiator key distribution: IdKey (0x02)
+ Responder key distribution: IdKey (0x02)
+
+Key fields to check:
+
+- **Authentication requirement** -- The ``SC`` flag indicates Secure
+ Connections. Its absence means Legacy Pairing.
+- **IO capability** -- Determines the association model (Just Works,
+ Passkey Entry, Numeric Comparison, OOB).
+- **Key distribution** -- Which keys each side will send after
+ encryption is established. ``IdKey`` = Identity Resolving Key (IRK),
+ ``EncKey`` = Long Term Key (legacy only), ``Sign`` = CSRK.
+
+**Phase 2: Authentication (Secure Connections)**
+
+For Secure Connections pairing (``SC`` flag set), both devices exchange
+public keys, then perform confirm/random value exchange::
+
+ > ACL Data RX: Handle 2048 flags 0x02 dlen 69 #501 [hci0] 0.098224
+ SMP: Pairing Public Key (0x0c) len 64
+ X: 1a2b3c4d...
+ Y: 5e6f7a8b...
+
+ < ACL Data TX: Handle 2048 flags 0x00 dlen 69 #503 [hci0] 0.148556
+ SMP: Pairing Public Key (0x0c) len 64
+ X: 9c8d7e6f...
+ Y: 0a1b2c3d...
+
+ < ACL Data TX: Handle 2048 flags 0x00 dlen 21 #505 [hci0] 0.149003
+ SMP: Pairing Confirm (0x03) len 16
+ Confirm value: a1b2c3d4e5f6...
+
+ > ACL Data RX: Handle 2048 flags 0x02 dlen 21 #507 [hci0] 0.212884
+ SMP: Pairing Random (0x04) len 16
+ Random value: 1122334455...
+
+ < ACL Data TX: Handle 2048 flags 0x00 dlen 21 #509 [hci0] 0.213100
+ SMP: Pairing Random (0x04) len 16
+ Random value: 6677889900...
+
+ > ACL Data RX: Handle 2048 flags 0x02 dlen 21 #511 [hci0] 0.278003
+ SMP: Pairing DHKey Check (0x0d) len 16
+ E: aabbccddee...
+
+ < ACL Data TX: Handle 2048 flags 0x00 dlen 21 #513 [hci0] 0.278450
+ SMP: Pairing DHKey Check (0x0d) len 16
+ E: ffeeddccbb...
+
+After DHKey Check, the initiator starts encryption at the HCI level::
+
+ < HCI Command: LE Start Encryption (0x08|0x0019) plen 28 #515 [hci0] 0.279002
+ > HCI Event: Encryption Change (0x08) plen 4 #517 [hci0] 0.342556
+ Status: Success (0x00)
+ Handle: 2048
+ Encryption: Enabled with AES-CCM (0x01)
+
+**Phase 2: Authentication (Legacy Pairing)**
+
+Legacy pairing (no ``SC`` flag) skips the Public Key and DHKey Check
+exchanges. Only Confirm and Random values are exchanged::
+
+ < ACL Data TX: Handle 2048 flags 0x00 dlen 21 #501 [hci0] 0.098224
+ SMP: Pairing Confirm (0x03) len 16
+ Confirm value: ...
+
+ > ACL Data RX: Handle 2048 flags 0x02 dlen 21 #503 [hci0] 0.162556
+ SMP: Pairing Confirm (0x03) len 16
+ Confirm value: ...
+
+ < ACL Data TX: Handle 2048 flags 0x00 dlen 21 #505 [hci0] 0.163003
+ SMP: Pairing Random (0x04) len 16
+ Random value: ...
+
+ > ACL Data RX: Handle 2048 flags 0x02 dlen 21 #507 [hci0] 0.228884
+ SMP: Pairing Random (0x04) len 16
+ Random value: ...
+
+**Phase 3: Key Distribution**
+
+After encryption is established, each device distributes keys as
+negotiated in Phase 1::
+
+ > ACL Data RX: Handle 2048 flags 0x02 dlen 21 #519 [hci0] 0.343002
+ SMP: Identity Information (0x08) len 16
+ Identity resolving key: 00112233445566778899aabbccddeeff
+
+ > ACL Data RX: Handle 2048 flags 0x02 dlen 12 #521 [hci0] 0.343556
+ SMP: Identity Address Information (0x09) len 7
+ Address type: Public (0x00)
+ Address: 00:11:22:33:44:55
+
+The Identity Address Information reveals the device's true public or
+static random address (as opposed to a Resolvable Private Address used
+during connection).
+
+For Legacy Pairing, LTK distribution also appears::
+
+ > ACL Data RX: Handle 2048 flags 0x02 dlen 21 #519 [hci0] 0.343002
+ SMP: Encryption Information (0x06) len 16
+ Long term key: 00112233...
+
+ > ACL Data RX: Handle 2048 flags 0x02 dlen 15 #521 [hci0] 0.343556
+ SMP: Central Identification (0x07) len 10
+ EDIV: 0x1234
+ Rand: 0x0123456789abcdef
+
+Pairing Failure
+---------------
+
+When pairing fails, one device sends a Pairing Failed PDU::
+
+ > ACL Data RX: Handle 2048 flags 0x02 dlen 6 #505 [hci0] 0.213002
+ SMP: Pairing Failed (0x05) len 1
+ Reason: Authentication requirements (0x03)
+
+SMP failure reasons:
+
+.. list-table::
+ :header-rows: 1
+ :widths: 8 35 57
+
+ * - Code
+ - Reason
+ - Diagnostic Meaning
+ * - 0x01
+ - Passkey Entry Failed
+ - User cancelled or entered wrong passkey
+ * - 0x02
+ - OOB Not Available
+ - OOB data expected but not provided
+ * - 0x03
+ - Authentication Requirements
+ - Devices cannot agree on security level (e.g.,
+ one requires MITM but IO caps only allow Just Works)
+ * - 0x04
+ - Confirm Value Failed
+ - Cryptographic check failed; possible MITM attack
+ * - 0x05
+ - Pairing Not Supported
+ - Remote does not support pairing
+ * - 0x06
+ - Encryption Key Size
+ - Cannot agree on key size
+ * - 0x07
+ - Command Not Supported
+ - Received unrecognized SMP command
+ * - 0x08
+ - Unspecified Reason
+ - Generic failure
+ * - 0x09
+ - Repeated Attempts
+ - Pairing rate-limited; wait before retry
+ * - 0x0a
+ - Invalid Parameters
+ - Invalid fields in SMP command
+ * - 0x0b
+ - DHKey Check Failed
+ - ECDH key agreement failed (SC only)
+ * - 0x0c
+ - Numeric Comparison Failed
+ - User rejected numeric comparison
+ * - 0x0d
+ - BR/EDR Pairing In Progress
+ - Classic pairing already active
+ * - 0x0e
+ - Cross-Transport Key Derivation Not Allowed
+ - CTKD rejected by policy
+
+Automating Pairing Analysis
+----------------------------
+
+**Identify all pairing attempts**::
+
+ grep -n "Pairing Request\|Pairing Response\|Pairing Failed\|Pairing Public Key\|DHKey Check" output.txt
+
+**Check pairing method (Secure Connections vs Legacy)**:
+
+- If ``Pairing Public Key`` appears between Request/Response and
+ Confirm: Secure Connections.
+- If only Confirm/Random follow Request/Response: Legacy Pairing.
+- Check the ``Authentication requirement`` line for the ``SC`` flag.
+
+**Detect pairing failures**::
+
+ grep -n "Pairing Failed" output.txt
+
+**Correlate pairing with encryption**:
+
+After successful pairing, expect ``Encryption Change`` with
+``Status: Success``. Search for::
+
+ grep -n "Encryption Change\|Encryption:" output.txt
+
+**Identify re-pairing on reconnect**:
+
+Reconnections to a bonded device should show ``Encryption Change``
+without SMP traffic (using stored keys). If SMP Pairing Request
+appears on reconnection, the bond was lost on one side.
+
+**Full pairing diagnosis pattern**:
+
+1. Find ``Pairing Request`` -- note the handle, IO capabilities,
+ auth requirements
+2. Find ``Pairing Response`` -- compare IO capabilities to determine
+ association model
+3. Check for ``Pairing Failed`` -- if present, the reason code
+ identifies the failure
+4. Check for ``Encryption Change`` with ``Status: Success`` -- confirms
+ pairing completed
+5. Check for ``Identity Address Information`` -- reveals the device's
+ true address
diff --git a/doc/btmon.rst b/doc/btmon.rst
index 6f283c21c490..a9b08bdfab01 100644
--- a/doc/btmon.rst
+++ b/doc/btmon.rst
@@ -1129,253 +1129,6 @@ The CCC descriptor at handle 0x000d belongs to the Service Changed
characteristic (0x000c), because it falls between that value handle
and the next characteristic declaration at 0x000e.
-SMP PAIRING FLOW
-================
-
-The Security Manager Protocol (SMP) handles pairing, key generation,
-and key distribution between Bluetooth devices. SMP traffic appears
-inside L2CAP on fixed CID 0x0006 (LE) or CID 0x0007 (BR/EDR). btmon
-decodes all SMP operations automatically.
-
-Pairing Phases
---------------
-
-SMP pairing proceeds in three phases. Each phase produces a distinct
-pattern in the btmon output.
-
-**Phase 1: Feature Exchange**
-
-Pairing begins when one device sends a Security Request (peripheral)
-or the host initiates pairing directly. The initiator sends a Pairing
-Request and the responder replies with a Pairing Response::
-
- > ACL Data RX: Handle 2048 flags 0x02 dlen 11 #497 [hci0] 0.026107
- SMP: Pairing Request (0x01) len 6
- IO capability: NoInputNoOutput (0x03)
- OOB data: Authentication data not present (0x00)
- Authentication requirement: Bonding, MITM, SC, CT2 (0x2d)
- Max encryption key size: 16
- Initiator key distribution: IdKey Sign (0x06)
- Responder key distribution: IdKey Sign (0x06)
-
- < ACL Data TX: Handle 2048 flags 0x00 dlen 11 #499 [hci0] 0.026894
- SMP: Pairing Response (0x02) len 6
- IO capability: KeyboardDisplay (0x04)
- OOB data: Authentication data not present (0x00)
- Authentication requirement: Bonding, SC, CT2 (0x29)
- Max encryption key size: 16
- Initiator key distribution: IdKey (0x02)
- Responder key distribution: IdKey (0x02)
-
-Key fields to check:
-
-- **Authentication requirement** -- The ``SC`` flag indicates Secure
- Connections. Its absence means Legacy Pairing.
-- **IO capability** -- Determines the association model (Just Works,
- Passkey Entry, Numeric Comparison, OOB).
-- **Key distribution** -- Which keys each side will send after
- encryption is established. ``IdKey`` = Identity Resolving Key (IRK),
- ``EncKey`` = Long Term Key (legacy only), ``Sign`` = CSRK.
-
-**Phase 2: Authentication (Secure Connections)**
-
-For Secure Connections pairing (``SC`` flag set), both devices exchange
-public keys, then perform confirm/random value exchange::
-
- > ACL Data RX: Handle 2048 flags 0x02 dlen 69 #501 [hci0] 0.098224
- SMP: Pairing Public Key (0x0c) len 64
- X: 1a2b3c4d...
- Y: 5e6f7a8b...
-
- < ACL Data TX: Handle 2048 flags 0x00 dlen 69 #503 [hci0] 0.148556
- SMP: Pairing Public Key (0x0c) len 64
- X: 9c8d7e6f...
- Y: 0a1b2c3d...
-
- < ACL Data TX: Handle 2048 flags 0x00 dlen 21 #505 [hci0] 0.149003
- SMP: Pairing Confirm (0x03) len 16
- Confirm value: a1b2c3d4e5f6...
-
- > ACL Data RX: Handle 2048 flags 0x02 dlen 21 #507 [hci0] 0.212884
- SMP: Pairing Random (0x04) len 16
- Random value: 1122334455...
-
- < ACL Data TX: Handle 2048 flags 0x00 dlen 21 #509 [hci0] 0.213100
- SMP: Pairing Random (0x04) len 16
- Random value: 6677889900...
-
- > ACL Data RX: Handle 2048 flags 0x02 dlen 21 #511 [hci0] 0.278003
- SMP: Pairing DHKey Check (0x0d) len 16
- E: aabbccddee...
-
- < ACL Data TX: Handle 2048 flags 0x00 dlen 21 #513 [hci0] 0.278450
- SMP: Pairing DHKey Check (0x0d) len 16
- E: ffeeddccbb...
-
-After DHKey Check, the initiator starts encryption at the HCI level::
-
- < HCI Command: LE Start Encryption (0x08|0x0019) plen 28 #515 [hci0] 0.279002
- > HCI Event: Encryption Change (0x08) plen 4 #517 [hci0] 0.342556
- Status: Success (0x00)
- Handle: 2048
- Encryption: Enabled with AES-CCM (0x01)
-
-**Phase 2: Authentication (Legacy Pairing)**
-
-Legacy pairing (no ``SC`` flag) skips the Public Key and DHKey Check
-exchanges. Only Confirm and Random values are exchanged::
-
- < ACL Data TX: Handle 2048 flags 0x00 dlen 21 #501 [hci0] 0.098224
- SMP: Pairing Confirm (0x03) len 16
- Confirm value: ...
-
- > ACL Data RX: Handle 2048 flags 0x02 dlen 21 #503 [hci0] 0.162556
- SMP: Pairing Confirm (0x03) len 16
- Confirm value: ...
-
- < ACL Data TX: Handle 2048 flags 0x00 dlen 21 #505 [hci0] 0.163003
- SMP: Pairing Random (0x04) len 16
- Random value: ...
-
- > ACL Data RX: Handle 2048 flags 0x02 dlen 21 #507 [hci0] 0.228884
- SMP: Pairing Random (0x04) len 16
- Random value: ...
-
-**Phase 3: Key Distribution**
-
-After encryption is established, each device distributes keys as
-negotiated in Phase 1::
-
- > ACL Data RX: Handle 2048 flags 0x02 dlen 21 #519 [hci0] 0.343002
- SMP: Identity Information (0x08) len 16
- Identity resolving key: 00112233445566778899aabbccddeeff
-
- > ACL Data RX: Handle 2048 flags 0x02 dlen 12 #521 [hci0] 0.343556
- SMP: Identity Address Information (0x09) len 7
- Address type: Public (0x00)
- Address: 00:11:22:33:44:55
-
-The Identity Address Information reveals the device's true public or
-static random address (as opposed to a Resolvable Private Address used
-during connection).
-
-For Legacy Pairing, LTK distribution also appears::
-
- > ACL Data RX: Handle 2048 flags 0x02 dlen 21 #519 [hci0] 0.343002
- SMP: Encryption Information (0x06) len 16
- Long term key: 00112233...
-
- > ACL Data RX: Handle 2048 flags 0x02 dlen 15 #521 [hci0] 0.343556
- SMP: Central Identification (0x07) len 10
- EDIV: 0x1234
- Rand: 0x0123456789abcdef
-
-Pairing Failure
----------------
-
-When pairing fails, one device sends a Pairing Failed PDU::
-
- > ACL Data RX: Handle 2048 flags 0x02 dlen 6 #505 [hci0] 0.213002
- SMP: Pairing Failed (0x05) len 1
- Reason: Authentication requirements (0x03)
-
-SMP failure reasons:
-
-.. list-table::
- :header-rows: 1
- :widths: 8 35 57
-
- * - Code
- - Reason
- - Diagnostic Meaning
- * - 0x01
- - Passkey Entry Failed
- - User cancelled or entered wrong passkey
- * - 0x02
- - OOB Not Available
- - OOB data expected but not provided
- * - 0x03
- - Authentication Requirements
- - Devices cannot agree on security level (e.g.,
- one requires MITM but IO caps only allow Just Works)
- * - 0x04
- - Confirm Value Failed
- - Cryptographic check failed; possible MITM attack
- * - 0x05
- - Pairing Not Supported
- - Remote does not support pairing
- * - 0x06
- - Encryption Key Size
- - Cannot agree on key size
- * - 0x07
- - Command Not Supported
- - Received unrecognized SMP command
- * - 0x08
- - Unspecified Reason
- - Generic failure
- * - 0x09
- - Repeated Attempts
- - Pairing rate-limited; wait before retry
- * - 0x0a
- - Invalid Parameters
- - Invalid fields in SMP command
- * - 0x0b
- - DHKey Check Failed
- - ECDH key agreement failed (SC only)
- * - 0x0c
- - Numeric Comparison Failed
- - User rejected numeric comparison
- * - 0x0d
- - BR/EDR Pairing In Progress
- - Classic pairing already active
- * - 0x0e
- - Cross-Transport Key Derivation Not Allowed
- - CTKD rejected by policy
-
-Automating Pairing Analysis
-----------------------------
-
-**Identify all pairing attempts**::
-
- grep -n "Pairing Request\|Pairing Response\|Pairing Failed\|Pairing Public Key\|DHKey Check" output.txt
-
-**Check pairing method (Secure Connections vs Legacy)**:
-
-- If ``Pairing Public Key`` appears between Request/Response and
- Confirm: Secure Connections.
-- If only Confirm/Random follow Request/Response: Legacy Pairing.
-- Check the ``Authentication requirement`` line for the ``SC`` flag.
-
-**Detect pairing failures**::
-
- grep -n "Pairing Failed" output.txt
-
-**Correlate pairing with encryption**:
-
-After successful pairing, expect ``Encryption Change`` with
-``Status: Success``. Search for::
-
- grep -n "Encryption Change\|Encryption:" output.txt
-
-**Identify re-pairing on reconnect**:
-
-Reconnections to a bonded device should show ``Encryption Change``
-without SMP traffic (using stored keys). If SMP Pairing Request
-appears on reconnection, the bond was lost on one side.
-
-**Full pairing diagnosis pattern**:
-
-1. Find ``Pairing Request`` -- note the handle, IO capabilities,
- auth requirements
-2. Find ``Pairing Response`` -- compare IO capabilities to determine
- association model
-3. Check for ``Pairing Failed`` -- if present, the reason code
- identifies the failure
-4. Check for ``Encryption Change`` with ``Status: Success`` -- confirms
- pairing completed
-5. Check for ``Identity Address Information`` -- reveals the device's
- true address
-
PROTOCOL ERROR CODES
=====================
@@ -1560,6 +1313,8 @@ Errors often cascade across layers. Common patterns:
PROTOCOL FLOWS
===============
+.. include:: btmon-smp.rst
+
.. include:: btmon-l2cap.rst
.. include:: btmon-le-audio.rst
--
2.53.0
^ permalink raw reply related [flat|nested] 11+ messages in thread
* [PATCH BlueZ v2 5/9] doc/btmon: Split GATT Database Reconstruction into btmon-gatt.rst
2026-03-24 19:49 [PATCH BlueZ v2 1/9] doc/btmon: Split Advertising and Scanning into btmon-advertising.rst Luiz Augusto von Dentz
` (2 preceding siblings ...)
2026-03-24 19:49 ` [PATCH BlueZ v2 4/9] doc/btmon: Split SMP Pairing Flow into btmon-smp.rst Luiz Augusto von Dentz
@ 2026-03-24 19:49 ` Luiz Augusto von Dentz
2026-03-24 19:49 ` [PATCH BlueZ v2 6/9] doc/btmon: Split Connection Tracking into btmon-connections.rst Luiz Augusto von Dentz
` (4 subsequent siblings)
8 siblings, 0 replies; 11+ messages in thread
From: Luiz Augusto von Dentz @ 2026-03-24 19:49 UTC (permalink / raw)
To: linux-bluetooth
From: Luiz Augusto von Dentz <luiz.von.dentz@intel.com>
Move the RECONSTRUCTING A GATT DATABASE FROM SNOOP TRACES section
into a standalone file and replace it with an RST include directive.
---
doc/btmon-gatt.rst | 419 ++++++++++++++++++++++++++++++++++++++++++++
doc/btmon.rst | 421 +--------------------------------------------
2 files changed, 422 insertions(+), 418 deletions(-)
create mode 100644 doc/btmon-gatt.rst
diff --git a/doc/btmon-gatt.rst b/doc/btmon-gatt.rst
new file mode 100644
index 000000000000..a4738b3bb177
--- /dev/null
+++ b/doc/btmon-gatt.rst
@@ -0,0 +1,419 @@
+.. This file is included by btmon.rst.
+
+RECONSTRUCTING A GATT DATABASE FROM SNOOP TRACES
+=================================================
+
+A btsnoop trace contains the complete ATT protocol exchange used by
+GATT clients and servers to discover each other's services. By reading
+the discovery requests and responses, it is possible to reconstruct the
+full GATT database of a remote device -- even without access to the
+device itself.
+
+This section explains the GATT discovery procedure and how each ATT
+operation appears in ``btmon`` output.
+
+Overview of GATT Discovery
+---------------------------
+
+GATT discovery is a multi-phase process where a client queries the
+server's attribute database using ATT protocol operations. The phases
+are:
+
+1. **Primary Service Discovery** -- Find all primary services and their
+ handle ranges.
+2. **Secondary Service Discovery** -- Find any secondary (included-only)
+ services.
+3. **Included Service Discovery** -- Find which services include other
+ services.
+4. **Characteristic Discovery** -- Find all characteristics within each
+ service.
+5. **Descriptor Discovery** -- Find all descriptors for each
+ characteristic.
+6. **Characteristic Value Reading** -- Read the values of readable
+ characteristics.
+
+Each phase uses a specific ATT operation and produces a
+request/response pattern in the trace. The client repeats each request
+with advancing handle ranges until the server responds with
+``Attribute Not Found``, indicating the end of that phase.
+
+Phase 1: Primary Service Discovery (Read By Group Type)
+--------------------------------------------------------
+
+The client discovers primary services using ``Read By Group Type
+Request`` with the ``Primary Service`` UUID (0x2800) as the group type.
+
+**Request**::
+
+ < ACL Data TX: Handle 2048 flags 0x00 dlen 11 #516 [hci0] 0.124726
+ ATT: Read By Group Type Request (0x10) len 6
+ Handle range: 0x0001-0xffff
+ Attribute group type: Primary Service (0x2800)
+
+The first request always starts at handle 0x0001 and searches through
+0xffff (the entire handle space).
+
+**Response**::
+
+ > ACL Data RX: Handle 2048 flags 0x02 dlen 42 #523 [hci0] 0.240151
+ ATT: Read By Group Type Response (0x11) len 37
+ Attribute data length: 6
+ Attribute group list: 6 entries
+ Handle range: 0x0001-0x0009
+ UUID: Generic Access Profile (0x1800)
+ Handle range: 0x000a-0x0011
+ UUID: Generic Attribute Profile (0x1801)
+ Handle range: 0x0012-0x0014
+ UUID: Device Information (0x180a)
+ Handle range: 0x0015-0x0039
+ UUID: Generic Telephony Bearer (0x184c)
+ Handle range: 0x003a-0x0059
+ UUID: Generic Media Control (0x1849)
+ Handle range: 0x005a-0x005c
+ UUID: Telephony and Media Audio (0x1855)
+
+Each entry provides:
+
+- **Handle range** -- The start and end handle of the service. All
+ attributes belonging to this service (characteristics, descriptors)
+ have handles within this range.
+- **UUID** -- The service UUID. Standard 16-bit UUIDs are shown with
+ their name (e.g., ``Generic Access Profile``). 128-bit vendor-specific
+ UUIDs appear as full UUID strings.
+
+The client continues by sending another request starting after the last
+handle in the response::
+
+ < ACL Data TX: Handle 2048 flags 0x00 dlen 11 #525 [hci0] 0.240641
+ ATT: Read By Group Type Request (0x10) len 6
+ Handle range: 0x005d-0xffff
+ Attribute group type: Primary Service (0x2800)
+
+This continues until the server responds with ``Attribute Not Found``::
+
+ > ACL Data RX: Handle 2048 flags 0x02 dlen 9 #532 [hci0] 0.360069
+ ATT: Error Response (0x01) len 4
+ Read By Group Type Request (0x10)
+ Handle: 0x005d
+ Error: Attribute Not Found (0x0a)
+
+This error indicates that no more primary services exist beyond handle
+0x005d. The client now has the complete list of primary services.
+
+.. note::
+
+ The ``Attribute data length`` field indicates the size of each entry
+ in the response. A value of 6 means 16-bit UUIDs (2 bytes start
+ handle + 2 bytes end handle + 2 bytes UUID). A value of 20 means
+ 128-bit UUIDs (2 + 2 + 16). If the server has both 16-bit and
+ 128-bit service UUIDs, they are returned in separate responses
+ because all entries in a single response must have the same length.
+
+Phase 2: Secondary Service Discovery
+--------------------------------------
+
+After primary services, the client may discover secondary services
+using the same ``Read By Group Type Request`` but with the ``Secondary
+Service`` UUID (0x2801)::
+
+ < ACL Data TX: Handle 2048 flags 0x00 dlen 11 #534 [hci0] 0.360752
+ ATT: Read By Group Type Request (0x10) len 6
+ Handle range: 0x0001-0xffff
+ Attribute group type: Secondary Service (0x2801)
+
+If no secondary services exist, the server responds with
+``Attribute Not Found``. Secondary services are not directly accessible
+to clients -- they are only reachable via include references from
+primary services.
+
+Phase 3: Included Service Discovery (Read By Type)
+----------------------------------------------------
+
+To discover which services include other services, the client uses
+``Read By Type Request`` with the ``Include`` UUID (0x2802)::
+
+ < ACL Data TX: Handle 2048 flags 0x00 dlen 11 #540 [hci0] 0.480731
+ ATT: Read By Type Request (0x08) len 6
+ Handle range: 0x0001-0x005c
+ Attribute type: Include (0x2802)
+
+The handle range typically spans the entire discovered database. Each
+include declaration in the response identifies a service that is
+included by the service containing that handle.
+
+Phase 4: Characteristic Discovery (Read By Type)
+--------------------------------------------------
+
+For each service, the client discovers its characteristics using
+``Read By Type Request`` with the ``Characteristic`` UUID (0x2803).
+The handle range is limited to the service's handle range.
+
+**Request**::
+
+ > ACL Data RX: Handle 2048 flags 0x02 dlen 11 #531 [hci0] 0.360063
+ ATT: Read By Type Request (0x08) len 6
+ Handle range: 0x0008-0x0011
+ Attribute type: Characteristic (0x2803)
+
+**Response**::
+
+ < ACL Data TX: Handle 2048 flags 0x00 dlen 27 #533 [hci0] 0.360714
+ ATT: Read By Type Response (0x09) len 22
+ Attribute data length: 7
+ Attribute data list: 3 entries
+ Handle: 0x0009
+ Value[5]: 200a00052a
+ Properties: 0x20
+ Indicate (0x20)
+ Value Handle: 0x000a
+ Value UUID: Service Changed (0x2a05)
+ Handle: 0x000c
+ Value[5]: 0a0d00292b
+ Properties: 0x0a
+ Read (0x02)
+ Write (0x08)
+ Value Handle: 0x000d
+ Value UUID: Client Supported Features (0x2b29)
+ Handle: 0x000e
+ Value[5]: 020f002a2b
+ Properties: 0x02
+ Read (0x02)
+ Value Handle: 0x000f
+ Value UUID: Database Hash (0x2b2a)
+
+Each characteristic entry provides:
+
+- **Handle** -- The handle of the characteristic declaration attribute.
+- **Properties** -- A bitmask indicating supported operations:
+
+ .. list-table::
+ :header-rows: 1
+ :widths: 10 30 60
+
+ * - Bit
+ - Property
+ - Description
+ * - 0x01
+ - Broadcast
+ - Can be broadcast in advertising data
+ * - 0x02
+ - Read
+ - Can be read
+ * - 0x04
+ - Write Without Response
+ - Can be written without acknowledgment
+ * - 0x08
+ - Write
+ - Can be written with acknowledgment
+ * - 0x10
+ - Notify
+ - Server can send notifications
+ * - 0x20
+ - Indicate
+ - Server can send indications
+ * - 0x40
+ - Authenticated Signed Writes
+ - Supports signed write commands
+ * - 0x80
+ - Extended Properties
+ - Has extended properties descriptor
+
+- **Value Handle** -- The handle where the characteristic's value is
+ stored (always declaration handle + 1).
+- **Value UUID** -- The UUID identifying the characteristic type.
+
+The client continues with advancing handle ranges until it receives
+``Attribute Not Found``::
+
+ > ACL Data RX: Handle 2048 flags 0x02 dlen 9 #572 [hci0] 1.200228
+ ATT: Error Response (0x01) len 4
+ Read By Type Request (0x08)
+ Handle: 0x005c
+ Error: Attribute Not Found (0x0a)
+
+Phase 5: Descriptor Discovery (Find Information)
+--------------------------------------------------
+
+Descriptors occupy the handles between a characteristic's value handle
+and the next characteristic declaration (or end of service). The client
+discovers them using ``Find Information Request``.
+
+**Request**::
+
+ > ACL Data RX: Handle 2048 flags 0x02 dlen 9 #556 [hci0] 0.959965
+ ATT: Find Information Request (0x04) len 4
+ Handle range: 0x000b-0x000b
+
+The handle range covers the gap between the characteristic value handle
+and the next characteristic declaration handle.
+
+**Response**::
+
+ < ACL Data TX: Handle 2048 flags 0x00 dlen 10 #561 [hci0] 0.961049
+ ATT: Find Information Response (0x05) len 5
+ Format: UUID-16 (0x01)
+ Handle: 0x000b
+ UUID: Client Characteristic Configuration (0x2902)
+
+Common descriptor UUIDs:
+
+.. list-table::
+ :header-rows: 1
+ :widths: 15 40 45
+
+ * - UUID
+ - Name
+ - Purpose
+ * - 0x2900
+ - Characteristic Extended Properties
+ - Additional property bits
+ * - 0x2901
+ - Characteristic User Description
+ - Human-readable description string
+ * - 0x2902
+ - Client Characteristic Configuration (CCC)
+ - Enable/disable notifications or indications
+ * - 0x2903
+ - Server Characteristic Configuration
+ - Server-side broadcast configuration
+ * - 0x2904
+ - Characteristic Presentation Format
+ - Data format, exponent, unit
+
+Phase 6: Reading Characteristic Values
+----------------------------------------
+
+After discovery, the client may read characteristic values using
+``Read Request``::
+
+ > ACL Data RX: Handle 2048 flags 0x02 dlen 7 #577 [hci0] 1.380203
+ ATT: Read Request (0x0a) len 2
+ Handle: 0x000f
+
+ < ACL Data TX: Handle 2048 flags 0x00 dlen 21 #579 [hci0] 1.380774
+ ATT: Read Response (0x0b) len 16
+ Value[16]: a470d508da8751a2a50b79da0250bfda
+
+The ``Handle`` in the request corresponds to a characteristic value
+handle from the discovery phase. btmon shows the raw value bytes; the
+interpretation depends on the characteristic UUID.
+
+Find By Type Value (Targeted Service Search)
+----------------------------------------------
+
+In addition to discovering all services, a client can search for a
+specific service UUID using ``Find By Type Value Request``::
+
+ > ACL Data RX: Handle 2048 flags 0x02 dlen 13 #513 [hci0] 0.124195
+ ATT: Find By Type Value Request (0x06) len 8
+ Handle range: 0x0001-0xffff
+ Attribute type: Primary Service (0x2800)
+ UUID: Generic Attribute Profile (0x1801)
+
+ < ACL Data TX: Handle 2048 flags 0x00 dlen 9 #515 [hci0] 0.124684
+ ATT: Find By Type Value Response (0x07) len 4
+ Handle range: 0x0008-0x0011
+
+This returns only the handle range for the matching service, without
+iterating through all services. If the service is not found::
+
+ < ACL Data TX: Handle 2048 flags 0x00 dlen 9 #524 [hci0] 0.240607
+ ATT: Error Response (0x01) len 4
+ Find By Type Value Request (0x06)
+ Handle: 0x0012
+ Error: Attribute Not Found (0x0a)
+
+Bidirectional Discovery
+------------------------
+
+Both devices in a connection can act as GATT client and server
+simultaneously. In a btsnoop trace, you may see interleaved discovery
+in both directions:
+
+- **TX (``<``) requests + RX (``>``) responses** -- The local device
+ (whose trace this is) is acting as a GATT client, discovering the
+ remote device's services.
+- **RX (``>``) requests + TX (``<``) responses** -- The remote device
+ is acting as a GATT client, discovering the local device's services.
+
+For example, the local server responding to the remote's discovery::
+
+ > ACL Data RX: Handle 2048 flags 0x02 dlen 11 #584 [hci0] 1.512006
+ ATT: Read By Group Type Request (0x10) len 6
+ Handle range: 0x0001-0xffff
+ Attribute group type: Primary Service (0x2800)
+
+ < ACL Data TX: Handle 2048 flags 0x00 dlen 66 #586 [hci0] 1.518778
+ ATT: Read By Group Type Response (0x11) len 61
+ Attribute data length: 6
+ Attribute group list: 10 entries
+ Handle range: 0x0001-0x0007
+ UUID: Generic Access Profile (0x1800)
+ Handle range: 0x0008-0x0011
+ UUID: Generic Attribute Profile (0x1801)
+ Handle range: 0x0012-0x0014
+ UUID: Device Information (0x180a)
+ Handle range: 0x0015-0x001e
+ UUID: Coordinated Set Identification (0x1846)
+ Handle range: 0x001f-0x0020
+ UUID: Common Audio (0x1853)
+ Handle range: 0x0021-0x0024
+ UUID: Microphone Control (0x184d)
+ Handle range: 0x0041-0x004b
+ UUID: Volume Control (0x1844)
+ Handle range: 0x006b-0x0073
+ UUID: Broadcast Audio Scan (0x184f)
+ Handle range: 0x0074-0x0086
+ UUID: Published Audio Capabilities (0x1850)
+ Handle range: 0x0087-0x0096
+ UUID: Audio Stream Control (0x184e)
+
+This shows the local device's own GATT database as seen by the remote.
+To reconstruct the remote device's database, focus on the TX requests
+and RX responses (the local device acting as client).
+
+Building the Attribute Table
+-----------------------------
+
+To reconstruct the GATT database, extract the discovery responses and
+organize them into a table. Using the trace above as an example, the
+remote device at address 00:11:22:33:44:55 has:
+
+**Services** (from Read By Group Type Response)::
+
+ Handle Range UUID Service Name
+ ────────────── ────────────────────────────── ────────────────────────────
+ 0x0001-0x0009 0x1800 Generic Access Profile
+ 0x000a-0x0011 0x1801 Generic Attribute Profile
+ 0x0012-0x0014 0x180a Device Information
+ 0x0015-0x0039 0x184c Generic Telephony Bearer
+ 0x003a-0x0059 0x1849 Generic Media Control
+ 0x005a-0x005c 0x1855 Telephony and Media Audio
+
+**Characteristics** (from Read By Type Response, within GAP 0x0001-0x0009)::
+
+ Handle Value Handle Properties UUID Name
+ ────── ──────────── ────────── ────── ────────────────────────────────
+ 0x0002 0x0003 Read 0x2a00 Device Name
+ 0x0004 0x0005 Read 0x2a01 Appearance
+ 0x0006 0x0007 Read 0x2a04 Peripheral Preferred Conn Params
+ 0x0008 0x0009 Read 0x2aa6 Central Address Resolution
+
+**Characteristics** (within GATT 0x000a-0x0011)::
+
+ Handle Value Handle Properties UUID Name
+ ────── ──────────── ─────────────── ────── ────────────────────────────
+ 0x000b 0x000c Indicate 0x2a05 Service Changed
+ 0x000e 0x000f Read, Write 0x2b29 Client Supported Features
+ 0x0010 0x0011 Read 0x2b2a Database Hash
+
+**Descriptors** (from Find Information Response)::
+
+ Handle UUID Name
+ ────── ────── ────────────────────────────────────
+ 0x000d 0x2902 Client Characteristic Configuration
+
+The CCC descriptor at handle 0x000d belongs to the Service Changed
+characteristic (0x000c), because it falls between that value handle
+and the next characteristic declaration at 0x000e.
+
diff --git a/doc/btmon.rst b/doc/btmon.rst
index a9b08bdfab01..c2309fc30389 100644
--- a/doc/btmon.rst
+++ b/doc/btmon.rst
@@ -710,424 +710,7 @@ Analyze mode reports, for each controller found in the trace:
connection, the same packet/latency/size statistics.
- **Latency plots**: If ``gnuplot`` is installed, ASCII-art latency
- distribution plots are rendered in the terminal.
-
-RECONSTRUCTING A GATT DATABASE FROM SNOOP TRACES
-=================================================
-
-A btsnoop trace contains the complete ATT protocol exchange used by
-GATT clients and servers to discover each other's services. By reading
-the discovery requests and responses, it is possible to reconstruct the
-full GATT database of a remote device -- even without access to the
-device itself.
-
-This section explains the GATT discovery procedure and how each ATT
-operation appears in ``btmon`` output.
-
-Overview of GATT Discovery
----------------------------
-
-GATT discovery is a multi-phase process where a client queries the
-server's attribute database using ATT protocol operations. The phases
-are:
-
-1. **Primary Service Discovery** -- Find all primary services and their
- handle ranges.
-2. **Secondary Service Discovery** -- Find any secondary (included-only)
- services.
-3. **Included Service Discovery** -- Find which services include other
- services.
-4. **Characteristic Discovery** -- Find all characteristics within each
- service.
-5. **Descriptor Discovery** -- Find all descriptors for each
- characteristic.
-6. **Characteristic Value Reading** -- Read the values of readable
- characteristics.
-
-Each phase uses a specific ATT operation and produces a
-request/response pattern in the trace. The client repeats each request
-with advancing handle ranges until the server responds with
-``Attribute Not Found``, indicating the end of that phase.
-
-Phase 1: Primary Service Discovery (Read By Group Type)
---------------------------------------------------------
-
-The client discovers primary services using ``Read By Group Type
-Request`` with the ``Primary Service`` UUID (0x2800) as the group type.
-
-**Request**::
-
- < ACL Data TX: Handle 2048 flags 0x00 dlen 11 #516 [hci0] 0.124726
- ATT: Read By Group Type Request (0x10) len 6
- Handle range: 0x0001-0xffff
- Attribute group type: Primary Service (0x2800)
-
-The first request always starts at handle 0x0001 and searches through
-0xffff (the entire handle space).
-
-**Response**::
-
- > ACL Data RX: Handle 2048 flags 0x02 dlen 42 #523 [hci0] 0.240151
- ATT: Read By Group Type Response (0x11) len 37
- Attribute data length: 6
- Attribute group list: 6 entries
- Handle range: 0x0001-0x0009
- UUID: Generic Access Profile (0x1800)
- Handle range: 0x000a-0x0011
- UUID: Generic Attribute Profile (0x1801)
- Handle range: 0x0012-0x0014
- UUID: Device Information (0x180a)
- Handle range: 0x0015-0x0039
- UUID: Generic Telephony Bearer (0x184c)
- Handle range: 0x003a-0x0059
- UUID: Generic Media Control (0x1849)
- Handle range: 0x005a-0x005c
- UUID: Telephony and Media Audio (0x1855)
-
-Each entry provides:
-
-- **Handle range** -- The start and end handle of the service. All
- attributes belonging to this service (characteristics, descriptors)
- have handles within this range.
-- **UUID** -- The service UUID. Standard 16-bit UUIDs are shown with
- their name (e.g., ``Generic Access Profile``). 128-bit vendor-specific
- UUIDs appear as full UUID strings.
-
-The client continues by sending another request starting after the last
-handle in the response::
-
- < ACL Data TX: Handle 2048 flags 0x00 dlen 11 #525 [hci0] 0.240641
- ATT: Read By Group Type Request (0x10) len 6
- Handle range: 0x005d-0xffff
- Attribute group type: Primary Service (0x2800)
-
-This continues until the server responds with ``Attribute Not Found``::
-
- > ACL Data RX: Handle 2048 flags 0x02 dlen 9 #532 [hci0] 0.360069
- ATT: Error Response (0x01) len 4
- Read By Group Type Request (0x10)
- Handle: 0x005d
- Error: Attribute Not Found (0x0a)
-
-This error indicates that no more primary services exist beyond handle
-0x005d. The client now has the complete list of primary services.
-
-.. note::
-
- The ``Attribute data length`` field indicates the size of each entry
- in the response. A value of 6 means 16-bit UUIDs (2 bytes start
- handle + 2 bytes end handle + 2 bytes UUID). A value of 20 means
- 128-bit UUIDs (2 + 2 + 16). If the server has both 16-bit and
- 128-bit service UUIDs, they are returned in separate responses
- because all entries in a single response must have the same length.
-
-Phase 2: Secondary Service Discovery
---------------------------------------
-
-After primary services, the client may discover secondary services
-using the same ``Read By Group Type Request`` but with the ``Secondary
-Service`` UUID (0x2801)::
-
- < ACL Data TX: Handle 2048 flags 0x00 dlen 11 #534 [hci0] 0.360752
- ATT: Read By Group Type Request (0x10) len 6
- Handle range: 0x0001-0xffff
- Attribute group type: Secondary Service (0x2801)
-
-If no secondary services exist, the server responds with
-``Attribute Not Found``. Secondary services are not directly accessible
-to clients -- they are only reachable via include references from
-primary services.
-
-Phase 3: Included Service Discovery (Read By Type)
-----------------------------------------------------
-
-To discover which services include other services, the client uses
-``Read By Type Request`` with the ``Include`` UUID (0x2802)::
-
- < ACL Data TX: Handle 2048 flags 0x00 dlen 11 #540 [hci0] 0.480731
- ATT: Read By Type Request (0x08) len 6
- Handle range: 0x0001-0x005c
- Attribute type: Include (0x2802)
-
-The handle range typically spans the entire discovered database. Each
-include declaration in the response identifies a service that is
-included by the service containing that handle.
-
-Phase 4: Characteristic Discovery (Read By Type)
---------------------------------------------------
-
-For each service, the client discovers its characteristics using
-``Read By Type Request`` with the ``Characteristic`` UUID (0x2803).
-The handle range is limited to the service's handle range.
-
-**Request**::
-
- > ACL Data RX: Handle 2048 flags 0x02 dlen 11 #531 [hci0] 0.360063
- ATT: Read By Type Request (0x08) len 6
- Handle range: 0x0008-0x0011
- Attribute type: Characteristic (0x2803)
-
-**Response**::
-
- < ACL Data TX: Handle 2048 flags 0x00 dlen 27 #533 [hci0] 0.360714
- ATT: Read By Type Response (0x09) len 22
- Attribute data length: 7
- Attribute data list: 3 entries
- Handle: 0x0009
- Value[5]: 200a00052a
- Properties: 0x20
- Indicate (0x20)
- Value Handle: 0x000a
- Value UUID: Service Changed (0x2a05)
- Handle: 0x000c
- Value[5]: 0a0d00292b
- Properties: 0x0a
- Read (0x02)
- Write (0x08)
- Value Handle: 0x000d
- Value UUID: Client Supported Features (0x2b29)
- Handle: 0x000e
- Value[5]: 020f002a2b
- Properties: 0x02
- Read (0x02)
- Value Handle: 0x000f
- Value UUID: Database Hash (0x2b2a)
-
-Each characteristic entry provides:
-
-- **Handle** -- The handle of the characteristic declaration attribute.
-- **Properties** -- A bitmask indicating supported operations:
-
- .. list-table::
- :header-rows: 1
- :widths: 10 30 60
-
- * - Bit
- - Property
- - Description
- * - 0x01
- - Broadcast
- - Can be broadcast in advertising data
- * - 0x02
- - Read
- - Can be read
- * - 0x04
- - Write Without Response
- - Can be written without acknowledgment
- * - 0x08
- - Write
- - Can be written with acknowledgment
- * - 0x10
- - Notify
- - Server can send notifications
- * - 0x20
- - Indicate
- - Server can send indications
- * - 0x40
- - Authenticated Signed Writes
- - Supports signed write commands
- * - 0x80
- - Extended Properties
- - Has extended properties descriptor
-
-- **Value Handle** -- The handle where the characteristic's value is
- stored (always declaration handle + 1).
-- **Value UUID** -- The UUID identifying the characteristic type.
-
-The client continues with advancing handle ranges until it receives
-``Attribute Not Found``::
-
- > ACL Data RX: Handle 2048 flags 0x02 dlen 9 #572 [hci0] 1.200228
- ATT: Error Response (0x01) len 4
- Read By Type Request (0x08)
- Handle: 0x005c
- Error: Attribute Not Found (0x0a)
-
-Phase 5: Descriptor Discovery (Find Information)
---------------------------------------------------
-
-Descriptors occupy the handles between a characteristic's value handle
-and the next characteristic declaration (or end of service). The client
-discovers them using ``Find Information Request``.
-
-**Request**::
-
- > ACL Data RX: Handle 2048 flags 0x02 dlen 9 #556 [hci0] 0.959965
- ATT: Find Information Request (0x04) len 4
- Handle range: 0x000b-0x000b
-
-The handle range covers the gap between the characteristic value handle
-and the next characteristic declaration handle.
-
-**Response**::
-
- < ACL Data TX: Handle 2048 flags 0x00 dlen 10 #561 [hci0] 0.961049
- ATT: Find Information Response (0x05) len 5
- Format: UUID-16 (0x01)
- Handle: 0x000b
- UUID: Client Characteristic Configuration (0x2902)
-
-Common descriptor UUIDs:
-
-.. list-table::
- :header-rows: 1
- :widths: 15 40 45
-
- * - UUID
- - Name
- - Purpose
- * - 0x2900
- - Characteristic Extended Properties
- - Additional property bits
- * - 0x2901
- - Characteristic User Description
- - Human-readable description string
- * - 0x2902
- - Client Characteristic Configuration (CCC)
- - Enable/disable notifications or indications
- * - 0x2903
- - Server Characteristic Configuration
- - Server-side broadcast configuration
- * - 0x2904
- - Characteristic Presentation Format
- - Data format, exponent, unit
-
-Phase 6: Reading Characteristic Values
-----------------------------------------
-
-After discovery, the client may read characteristic values using
-``Read Request``::
-
- > ACL Data RX: Handle 2048 flags 0x02 dlen 7 #577 [hci0] 1.380203
- ATT: Read Request (0x0a) len 2
- Handle: 0x000f
-
- < ACL Data TX: Handle 2048 flags 0x00 dlen 21 #579 [hci0] 1.380774
- ATT: Read Response (0x0b) len 16
- Value[16]: a470d508da8751a2a50b79da0250bfda
-
-The ``Handle`` in the request corresponds to a characteristic value
-handle from the discovery phase. btmon shows the raw value bytes; the
-interpretation depends on the characteristic UUID.
-
-Find By Type Value (Targeted Service Search)
-----------------------------------------------
-
-In addition to discovering all services, a client can search for a
-specific service UUID using ``Find By Type Value Request``::
-
- > ACL Data RX: Handle 2048 flags 0x02 dlen 13 #513 [hci0] 0.124195
- ATT: Find By Type Value Request (0x06) len 8
- Handle range: 0x0001-0xffff
- Attribute type: Primary Service (0x2800)
- UUID: Generic Attribute Profile (0x1801)
-
- < ACL Data TX: Handle 2048 flags 0x00 dlen 9 #515 [hci0] 0.124684
- ATT: Find By Type Value Response (0x07) len 4
- Handle range: 0x0008-0x0011
-
-This returns only the handle range for the matching service, without
-iterating through all services. If the service is not found::
-
- < ACL Data TX: Handle 2048 flags 0x00 dlen 9 #524 [hci0] 0.240607
- ATT: Error Response (0x01) len 4
- Find By Type Value Request (0x06)
- Handle: 0x0012
- Error: Attribute Not Found (0x0a)
-
-Bidirectional Discovery
-------------------------
-
-Both devices in a connection can act as GATT client and server
-simultaneously. In a btsnoop trace, you may see interleaved discovery
-in both directions:
-
-- **TX (``<``) requests + RX (``>``) responses** -- The local device
- (whose trace this is) is acting as a GATT client, discovering the
- remote device's services.
-- **RX (``>``) requests + TX (``<``) responses** -- The remote device
- is acting as a GATT client, discovering the local device's services.
-
-For example, the local server responding to the remote's discovery::
-
- > ACL Data RX: Handle 2048 flags 0x02 dlen 11 #584 [hci0] 1.512006
- ATT: Read By Group Type Request (0x10) len 6
- Handle range: 0x0001-0xffff
- Attribute group type: Primary Service (0x2800)
-
- < ACL Data TX: Handle 2048 flags 0x00 dlen 66 #586 [hci0] 1.518778
- ATT: Read By Group Type Response (0x11) len 61
- Attribute data length: 6
- Attribute group list: 10 entries
- Handle range: 0x0001-0x0007
- UUID: Generic Access Profile (0x1800)
- Handle range: 0x0008-0x0011
- UUID: Generic Attribute Profile (0x1801)
- Handle range: 0x0012-0x0014
- UUID: Device Information (0x180a)
- Handle range: 0x0015-0x001e
- UUID: Coordinated Set Identification (0x1846)
- Handle range: 0x001f-0x0020
- UUID: Common Audio (0x1853)
- Handle range: 0x0021-0x0024
- UUID: Microphone Control (0x184d)
- Handle range: 0x0041-0x004b
- UUID: Volume Control (0x1844)
- Handle range: 0x006b-0x0073
- UUID: Broadcast Audio Scan (0x184f)
- Handle range: 0x0074-0x0086
- UUID: Published Audio Capabilities (0x1850)
- Handle range: 0x0087-0x0096
- UUID: Audio Stream Control (0x184e)
-
-This shows the local device's own GATT database as seen by the remote.
-To reconstruct the remote device's database, focus on the TX requests
-and RX responses (the local device acting as client).
-
-Building the Attribute Table
------------------------------
-
-To reconstruct the GATT database, extract the discovery responses and
-organize them into a table. Using the trace above as an example, the
-remote device at address 00:11:22:33:44:55 has:
-
-**Services** (from Read By Group Type Response)::
-
- Handle Range UUID Service Name
- ────────────── ────────────────────────────── ────────────────────────────
- 0x0001-0x0009 0x1800 Generic Access Profile
- 0x000a-0x0011 0x1801 Generic Attribute Profile
- 0x0012-0x0014 0x180a Device Information
- 0x0015-0x0039 0x184c Generic Telephony Bearer
- 0x003a-0x0059 0x1849 Generic Media Control
- 0x005a-0x005c 0x1855 Telephony and Media Audio
-
-**Characteristics** (from Read By Type Response, within GAP 0x0001-0x0009)::
-
- Handle Value Handle Properties UUID Name
- ────── ──────────── ────────── ────── ────────────────────────────────
- 0x0002 0x0003 Read 0x2a00 Device Name
- 0x0004 0x0005 Read 0x2a01 Appearance
- 0x0006 0x0007 Read 0x2a04 Peripheral Preferred Conn Params
- 0x0008 0x0009 Read 0x2aa6 Central Address Resolution
-
-**Characteristics** (within GATT 0x000a-0x0011)::
-
- Handle Value Handle Properties UUID Name
- ────── ──────────── ─────────────── ────── ────────────────────────────
- 0x000b 0x000c Indicate 0x2a05 Service Changed
- 0x000e 0x000f Read, Write 0x2b29 Client Supported Features
- 0x0010 0x0011 Read 0x2b2a Database Hash
-
-**Descriptors** (from Find Information Response)::
-
- Handle UUID Name
- ────── ────── ────────────────────────────────────
- 0x000d 0x2902 Client Characteristic Configuration
-
-The CCC descriptor at handle 0x000d belongs to the Service Changed
-characteristic (0x000c), because it falls between that value handle
-and the next characteristic declaration at 0x000e.
+ distribution plots are rendered in the terminal.
PROTOCOL ERROR CODES
=====================
@@ -1313,6 +896,8 @@ Errors often cascade across layers. Common patterns:
PROTOCOL FLOWS
===============
+.. include:: btmon-gatt.rst
+
.. include:: btmon-smp.rst
.. include:: btmon-l2cap.rst
--
2.53.0
^ permalink raw reply related [flat|nested] 11+ messages in thread
* [PATCH BlueZ v2 6/9] doc/btmon: Split Connection Tracking into btmon-connections.rst
2026-03-24 19:49 [PATCH BlueZ v2 1/9] doc/btmon: Split Advertising and Scanning into btmon-advertising.rst Luiz Augusto von Dentz
` (3 preceding siblings ...)
2026-03-24 19:49 ` [PATCH BlueZ v2 5/9] doc/btmon: Split GATT Database Reconstruction into btmon-gatt.rst Luiz Augusto von Dentz
@ 2026-03-24 19:49 ` Luiz Augusto von Dentz
2026-03-24 19:49 ` [PATCH BlueZ v2 7/9] doc/btmon: Add HCI initialization sequence documentation Luiz Augusto von Dentz
` (3 subsequent siblings)
8 siblings, 0 replies; 11+ messages in thread
From: Luiz Augusto von Dentz @ 2026-03-24 19:49 UTC (permalink / raw)
To: linux-bluetooth
From: Luiz Augusto von Dentz <luiz.von.dentz@intel.com>
Move the CONNECTION TRACKING and HCI ERROR AND DISCONNECT REASON CODES
sections into a standalone file and replace them with an RST include
directive.
---
doc/btmon-connections.rst | 142 +++++++++++++++++++++++++++++++++++++
doc/btmon.rst | 143 +-------------------------------------
2 files changed, 144 insertions(+), 141 deletions(-)
create mode 100644 doc/btmon-connections.rst
diff --git a/doc/btmon-connections.rst b/doc/btmon-connections.rst
new file mode 100644
index 000000000000..d0d4e799d7e7
--- /dev/null
+++ b/doc/btmon-connections.rst
@@ -0,0 +1,142 @@
+.. This file is included by btmon.rst.
+
+CONNECTION TRACKING
+===================
+
+HCI uses **connection handles** (16-bit integers) to identify individual
+connections. Understanding how handles map to devices is essential for
+reading traces.
+
+Handle Types
+------------
+
+Different connection types use different handle ranges, but these ranges
+are controller-specific and not standardized. The connection type can be
+determined by looking at the event that created the handle:
+
+.. list-table::
+ :header-rows: 1
+ :widths: 15 25 60
+
+ * - Type
+ - Creation Event
+ - Description
+ * - BR/EDR ACL
+ - Connection Complete
+ - Classic Bluetooth data connection
+ * - LE ACL
+ - LE (Enhanced) Connection Complete
+ - Low Energy data connection
+ * - CIS
+ - LE CIS Established
+ - Connected Isochronous Stream (LE Audio)
+ * - BIS
+ - LE BIG Complete
+ - Broadcast Isochronous Stream (LE Audio)
+ * - SCO/eSCO
+ - Synchronous Connection Complete
+ - Voice/audio synchronous connection (classic)
+
+A single device may have multiple handles simultaneously. For example,
+an LE Audio device will have an LE ACL handle for control traffic and
+one or more CIS handles for audio streams. The ``LE CIS Established``
+event includes the ACL connection handle that the CIS is associated
+with.
+
+Controller Buffer Tracking
+--------------------------
+
+Buffer tracking may show a indicator in square brackets::
+
+ < ACL: Handle 2048 [1/6] flags 0x00 dlen 16
+
+The ``[1/6]`` means this is buffer slot 1 of 6 available controller
+ACL buffers. This reflects the host-side HCI flow control: the host
+tracks how many buffers the controller has available and shows the
+current usage. When the controller sends ``Number of Completed Packets``
+events, buffers are freed and the count decreases.
+
+HCI ERROR AND DISCONNECT REASON CODES
+======================================
+
+HCI status and disconnect reason codes use the same code space. These
+appear in ``Status:`` and ``Reason:`` fields throughout the trace.
+btmon decodes them automatically, but the hex values are useful for
+searching and filtering.
+
+Common Disconnect Reasons
+-------------------------
+
+.. list-table::
+ :header-rows: 1
+ :widths: 8 40 52
+
+ * - Code
+ - Name
+ - Diagnostic Meaning
+ * - 0x05
+ - Authentication Failure
+ - Pairing or encryption setup failed. Key may be
+ stale or devices have mismatched security databases.
+ * - 0x08
+ - Connection Timeout
+ - The supervision timer expired. The remote device
+ moved out of range or stopped responding. This is
+ an RF link loss.
+ * - 0x13
+ - Remote User Terminated Connection
+ - The remote device intentionally disconnected.
+ This is the normal graceful disconnect.
+ * - 0x14
+ - Remote Device Terminated due to Low Resources
+ - The remote device ran out of resources (memory,
+ connection slots).
+ * - 0x15
+ - Remote Device Terminated due to Power Off
+ - The remote device is powering down.
+ * - 0x16
+ - Connection Terminated By Local Host
+ - The local BlueZ stack intentionally disconnected.
+ Normal when bluetoothd initiates disconnect.
+ * - 0x1f
+ - Unspecified Error
+ - Generic error. Often indicates a firmware issue.
+ * - 0x22
+ - LMP/LL Response Timeout
+ - Link layer procedure timed out. The remote device
+ stopped responding to LL control PDUs.
+ * - 0x28
+ - Instant Passed
+ - A timing-critical operation missed its deadline.
+ Often seen with connection parameter updates.
+ * - 0x2f
+ - Insufficient Security
+ - The required security level (encryption, MITM
+ protection) was not met.
+ * - 0x3b
+ - Unacceptable Connection Parameters
+ - The remote rejected a connection parameter update.
+ * - 0x3d
+ - Connection Terminated due to MIC Failure
+ - Encryption integrity check failed. Possible key
+ mismatch or corruption.
+ * - 0x3e
+ - Connection Failed to be Established
+ - Connection attempt failed entirely (e.g., the
+ remote device did not respond to connection
+ requests).
+ * - 0x3f
+ - MAC Connection Failed
+ - MAC-level connection failure.
+ * - 0x44
+ - Operation Cancelled by Host
+ - The host cancelled the operation before it
+ completed.
+
+Full Error Code Table
+---------------------
+
+The complete set of HCI error codes (0x00-0x45) is defined in the
+Bluetooth Core Specification, Volume 1, Part F. btmon decodes all
+of them automatically in ``Status:`` and ``Reason:`` fields. The
+source mapping is in ``monitor/packet.c`` (``error2str_table``).
diff --git a/doc/btmon.rst b/doc/btmon.rst
index c2309fc30389..9cf1464eae63 100644
--- a/doc/btmon.rst
+++ b/doc/btmon.rst
@@ -534,147 +534,6 @@ The kernel forwarded this as a MGMT Device Connected event. bluetoothd
logged its ``connected_callback()``. Then data exchange began -- an L2CAP
parameter update and ATT MTU negotiation over the new ACL connection.
-CONNECTION TRACKING
-===================
-
-HCI uses **connection handles** (16-bit integers) to identify individual
-connections. Understanding how handles map to devices is essential for
-reading traces.
-
-Handle Types
-------------
-
-Different connection types use different handle ranges, but these ranges
-are controller-specific and not standardized. The connection type can be
-determined by looking at the event that created the handle:
-
-.. list-table::
- :header-rows: 1
- :widths: 15 25 60
-
- * - Type
- - Creation Event
- - Description
- * - BR/EDR ACL
- - Connection Complete
- - Classic Bluetooth data connection
- * - LE ACL
- - LE (Enhanced) Connection Complete
- - Low Energy data connection
- * - CIS
- - LE CIS Established
- - Connected Isochronous Stream (LE Audio)
- * - BIS
- - LE BIG Complete
- - Broadcast Isochronous Stream (LE Audio)
- * - SCO/eSCO
- - Synchronous Connection Complete
- - Voice/audio synchronous connection (classic)
-
-A single device may have multiple handles simultaneously. For example,
-an LE Audio device will have an LE ACL handle for control traffic and
-one or more CIS handles for audio streams. The ``LE CIS Established``
-event includes the ACL connection handle that the CIS is associated
-with.
-
-Controller Buffer Tracking
---------------------------
-
-Buffer tracking may show a indicator in square brackets::
-
- < ACL: Handle 2048 [1/6] flags 0x00 dlen 16
-
-The ``[1/6]`` means this is buffer slot 1 of 6 available controller
-ACL buffers. This reflects the host-side HCI flow control: the host
-tracks how many buffers the controller has available and shows the
-current usage. When the controller sends ``Number of Completed Packets``
-events, buffers are freed and the count decreases.
-
-HCI ERROR AND DISCONNECT REASON CODES
-======================================
-
-HCI status and disconnect reason codes use the same code space. These
-appear in ``Status:`` and ``Reason:`` fields throughout the trace.
-btmon decodes them automatically, but the hex values are useful for
-searching and filtering.
-
-Common Disconnect Reasons
--------------------------
-
-.. list-table::
- :header-rows: 1
- :widths: 8 40 52
-
- * - Code
- - Name
- - Diagnostic Meaning
- * - 0x05
- - Authentication Failure
- - Pairing or encryption setup failed. Key may be
- stale or devices have mismatched security databases.
- * - 0x08
- - Connection Timeout
- - The supervision timer expired. The remote device
- moved out of range or stopped responding. This is
- an RF link loss.
- * - 0x13
- - Remote User Terminated Connection
- - The remote device intentionally disconnected.
- This is the normal graceful disconnect.
- * - 0x14
- - Remote Device Terminated due to Low Resources
- - The remote device ran out of resources (memory,
- connection slots).
- * - 0x15
- - Remote Device Terminated due to Power Off
- - The remote device is powering down.
- * - 0x16
- - Connection Terminated By Local Host
- - The local BlueZ stack intentionally disconnected.
- Normal when bluetoothd initiates disconnect.
- * - 0x1f
- - Unspecified Error
- - Generic error. Often indicates a firmware issue.
- * - 0x22
- - LMP/LL Response Timeout
- - Link layer procedure timed out. The remote device
- stopped responding to LL control PDUs.
- * - 0x28
- - Instant Passed
- - A timing-critical operation missed its deadline.
- Often seen with connection parameter updates.
- * - 0x2f
- - Insufficient Security
- - The required security level (encryption, MITM
- protection) was not met.
- * - 0x3b
- - Unacceptable Connection Parameters
- - The remote rejected a connection parameter update.
- * - 0x3d
- - Connection Terminated due to MIC Failure
- - Encryption integrity check failed. Possible key
- mismatch or corruption.
- * - 0x3e
- - Connection Failed to be Established
- - Connection attempt failed entirely (e.g., the
- remote device did not respond to connection
- requests).
- * - 0x3f
- - MAC Connection Failed
- - MAC-level connection failure.
- * - 0x44
- - Operation Cancelled by Host
- - The host cancelled the operation before it
- completed.
-
-Full Error Code Table
----------------------
-
-The complete set of HCI error codes (0x00-0x45) is defined in the
-Bluetooth Core Specification, Volume 1, Part F. btmon decodes all
-of them automatically in ``Status:`` and ``Reason:`` fields. The
-source mapping is in ``monitor/packet.c`` (``error2str_table``).
-
ANALYZE MODE
============
@@ -896,6 +755,8 @@ Errors often cascade across layers. Common patterns:
PROTOCOL FLOWS
===============
+.. include:: btmon-connections.rst
+
.. include:: btmon-gatt.rst
.. include:: btmon-smp.rst
--
2.53.0
^ permalink raw reply related [flat|nested] 11+ messages in thread
* [PATCH BlueZ v2 7/9] doc/btmon: Add HCI initialization sequence documentation
2026-03-24 19:49 [PATCH BlueZ v2 1/9] doc/btmon: Split Advertising and Scanning into btmon-advertising.rst Luiz Augusto von Dentz
` (4 preceding siblings ...)
2026-03-24 19:49 ` [PATCH BlueZ v2 6/9] doc/btmon: Split Connection Tracking into btmon-connections.rst Luiz Augusto von Dentz
@ 2026-03-24 19:49 ` Luiz Augusto von Dentz
2026-03-24 19:49 ` [PATCH BlueZ v2 8/9] doc/btmon: Add A2DP/AVDTP protocol flow documentation Luiz Augusto von Dentz
` (2 subsequent siblings)
8 siblings, 0 replies; 11+ messages in thread
From: Luiz Augusto von Dentz @ 2026-03-24 19:49 UTC (permalink / raw)
To: linux-bluetooth
From: Luiz Augusto von Dentz <luiz.von.dentz@intel.com>
Document the multi-stage HCI controller initialization performed by
the kernel (net/bluetooth/hci_sync.c). The four stages cover reset
and identity, capability discovery, event mask configuration, and
final setup. This helps trace readers distinguish normal init traffic
from application-level issues.
---
doc/btmon-hci-init.rst | 363 +++++++++++++++++++++++++++++++++++++++++
doc/btmon.rst | 2 +
2 files changed, 365 insertions(+)
create mode 100644 doc/btmon-hci-init.rst
diff --git a/doc/btmon-hci-init.rst b/doc/btmon-hci-init.rst
new file mode 100644
index 000000000000..9890df7c38af
--- /dev/null
+++ b/doc/btmon-hci-init.rst
@@ -0,0 +1,363 @@
+.. This file is included by btmon.rst.
+
+HCI INITIALIZATION SEQUENCE
+============================
+
+Every btsnoop trace that captures controller startup begins with a
+dense block of HCI commands and events. This is the kernel's
+Bluetooth subsystem initializing the controller through a multi-stage
+sequence defined in ``net/bluetooth/hci_sync.c``. Understanding this
+sequence helps distinguish normal initialization traffic from
+application-level issues.
+
+Overview
+--------
+
+The kernel initializes a Bluetooth controller in four stages after
+opening the HCI device. Each stage sends a batch of HCI commands and
+waits for their completion before proceeding to the next. The full
+call chain is::
+
+ hci_power_on_sync
+ └─ hci_dev_open_sync
+ └─ hci_dev_init_sync
+ ├─ hci_dev_setup_sync (driver setup + quirks)
+ └─ hci_init_sync
+ ├─ Stage 1: Reset + identity
+ ├─ Stage 2: Capabilities + buffer sizes
+ ├─ Stage 3: Event masks + policy
+ └─ Stage 4: Final configuration
+
+After all four stages complete, a post-init phase
+(``hci_powered_update_sync``) configures runtime parameters like
+SSP, advertising, and scan settings.
+
+For unconfigured devices (e.g. controllers that need firmware or a
+BD address programmed), only a minimal **Stage 0** runs to identify
+the hardware.
+
+Stage 0: Reset and Basic Identity (Unconfigured Only)
+-----------------------------------------------------
+
+This stage runs only for unconfigured controllers that need setup
+before full initialization.
+
+**Commands sent:**
+
+.. list-table::
+ :header-rows: 1
+ :widths: 40 60
+
+ * - HCI Command
+ - Purpose
+ * - ``HCI_Reset``
+ - Reset the controller (skipped if ``RESET_ON_CLOSE`` quirk)
+ * - ``HCI_Read_Local_Version_Information``
+ - Read hardware/firmware version
+ * - ``HCI_Read_BD_ADDR``
+ - Read the controller's Bluetooth address
+
+Stage 1: Reset and Read Local Features
+---------------------------------------
+
+Resets the controller and reads core identity and capability
+information.
+
+**Commands sent:**
+
+.. list-table::
+ :header-rows: 1
+ :widths: 40 60
+
+ * - HCI Command
+ - Purpose
+ * - ``HCI_Reset``
+ - Reset the controller
+ * - ``HCI_Read_Local_Supported_Features``
+ - Read LMP feature bitmask (BR/EDR, LE, SSP, etc.)
+ * - ``HCI_Read_Local_Version_Information``
+ - Read HCI version, LMP version, manufacturer
+ * - ``HCI_Read_BD_ADDR``
+ - Read the public Bluetooth address
+
+Stage 2: Read Capabilities and Setup
+-------------------------------------
+
+Reads detailed capabilities, enables core features, and reads buffer
+sizes. This stage has three phases: common commands, BR/EDR-specific
+commands, and LE-specific commands.
+
+Common Commands
+~~~~~~~~~~~~~~~
+
+.. list-table::
+ :header-rows: 1
+ :widths: 40 60
+
+ * - HCI Command
+ - Purpose
+ * - ``HCI_Read_Local_Supported_Commands``
+ - Read the supported command bitmask (HCI 1.2+)
+ * - ``HCI_Write_Simple_Pairing_Mode`` (enable)
+ - Enable SSP if supported and configured
+ * - ``HCI_Write_Extended_Inquiry_Response`` (clear)
+ - Clear EIR data when SSP is disabled
+ * - ``HCI_Write_Inquiry_Mode``
+ - Set inquiry mode (RSSI or Extended, based on features)
+ * - ``HCI_Read_Inquiry_Response_Transmit_Power_Level``
+ - Read inquiry TX power if supported
+ * - ``HCI_Read_Local_Extended_Features`` (page 1)
+ - Read extended feature page 1 (SSP host, LE host, etc.)
+ * - ``HCI_Write_Authentication_Enable``
+ - Sync authentication state with ``LINK_SECURITY`` flag
+
+BR/EDR Commands (if BR/EDR capable)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. list-table::
+ :header-rows: 1
+ :widths: 40 60
+
+ * - HCI Command
+ - Purpose
+ * - ``HCI_Read_Buffer_Size``
+ - Read ACL/SCO buffer sizes and count
+ * - ``HCI_Read_Class_of_Device``
+ - Read current device class
+ * - ``HCI_Read_Local_Name``
+ - Read the stored local name
+ * - ``HCI_Read_Voice_Setting``
+ - Read SCO voice setting (if supported)
+ * - ``HCI_Read_Number_of_Supported_IAC``
+ - Read number of supported inquiry access codes
+ * - ``HCI_Read_Current_IAC_LAP``
+ - Read current IAC LAP values
+ * - ``HCI_Set_Event_Filter`` (clear all)
+ - Clear any stored event filters
+ * - ``HCI_Write_Connection_Accept_Timeout``
+ - Set connection accept timeout (~20 seconds)
+ * - ``HCI_Write_Synchronous_Flow_Control_Enable``
+ - Enable SCO flow control if supported
+
+LE Commands (if LE capable)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. list-table::
+ :header-rows: 1
+ :widths: 40 60
+
+ * - HCI Command
+ - Purpose
+ * - ``LE_Read_Local_Supported_Features``
+ - Read LE feature bitmask
+ * - ``LE_Read_All_Local_Supported_Features``
+ - Read extended LE features (if supported)
+ * - ``LE_Read_Buffer_Size`` [v2] or [v1]
+ - Read LE ACL (and ISO) buffer sizes; v2 used when ISO capable
+ * - ``LE_Read_Supported_States``
+ - Read the LE state combination table
+
+Stage 3: Event Masks, Link Policy, and Features
+------------------------------------------------
+
+Configures which events the controller should report, sets link
+policy, and reads extended feature pages. This is the longest stage.
+
+Event Masks and Link Policy
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. list-table::
+ :header-rows: 1
+ :widths: 40 60
+
+ * - HCI Command
+ - Purpose
+ * - ``HCI_Set_Event_Mask``
+ - Configure the main event mask based on controller capabilities
+ * - ``HCI_Read_Stored_Link_Key``
+ - Read all stored link keys
+ * - ``HCI_Write_Default_Link_Policy_Settings``
+ - Enable role switch, hold, sniff, park based on LMP features
+ * - ``HCI_Read_Page_Scan_Activity``
+ - Read page scan interval and window
+ * - ``HCI_Read_Default_Erroneous_Data_Reporting``
+ - Read error data reporting state (for wideband speech)
+ * - ``HCI_Read_Page_Scan_Type``
+ - Read page scan type (standard or interlaced)
+ * - ``HCI_Read_Local_Extended_Features`` (pages 2..N)
+ - Read all remaining extended feature pages
+
+**Event mask details:** For dual-mode controllers the kernel enables
+events for inquiry results (RSSI and extended), SSP (IO capability,
+user confirmation, passkey), synchronous connections, sniff
+subrating, encryption refresh, link supervision, and LE meta-events.
+For LE-only controllers a minimal mask covers only command
+completion, hardware errors, disconnection, and encryption changes.
+
+LE Event Mask and Capabilities
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. list-table::
+ :header-rows: 1
+ :widths: 40 60
+
+ * - HCI Command
+ - Purpose
+ * - ``LE_Set_Event_Mask``
+ - Configure which LE sub-events are reported
+ * - ``LE_Read_Advertising_Channel_Tx_Power``
+ - Read advertising TX power (legacy advertising only)
+ * - ``LE_Read_Transmit_Power``
+ - Read min/max transmit power range
+ * - ``LE_Read_Accept_List_Size``
+ - Read filter accept list capacity
+ * - ``LE_Clear_Accept_List``
+ - Clear the filter accept list
+ * - ``LE_Read_Resolving_List_Size``
+ - Read resolving list capacity (LL Privacy)
+ * - ``LE_Clear_Resolving_List``
+ - Clear the resolving list
+ * - ``LE_Set_Resolvable_Private_Address_Timeout``
+ - Set RPA rotation timeout
+ * - ``LE_Read_Maximum_Data_Length``
+ - Read max TX/RX octets and time (Data Length Extension)
+ * - ``LE_Read_Suggested_Default_Data_Length``
+ - Read current default data length
+ * - ``LE_Read_Number_of_Supported_Advertising_Sets``
+ - Read extended advertising set capacity
+ * - ``HCI_Write_LE_Host_Supported``
+ - Notify controller of host LE support (dual-mode only)
+ * - ``LE_Set_Host_Feature``
+ - Enable CIS Central (bit 32) and/or Channel Sounding (bit 47)
+
+**LE event mask details:** The kernel enables LE sub-events based on
+features: connection complete (enhanced if available), advertising
+reports (extended if available), long term key request, connection
+parameter request, data length change, PHY update, channel selection
+algorithm, periodic advertising events, CIS established/request (if
+CIS capable), BIG create/sync/info (if BIS capable), and channel
+sounding events (if CS capable).
+
+Stage 4: Final Configuration
+-----------------------------
+
+Performs final setup: deletes stale keys, sets event mask page 2,
+reads codec information, enables Secure Connections, and configures
+LE data length and PHY defaults.
+
+Keys, Codecs, and Secure Connections
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. list-table::
+ :header-rows: 1
+ :widths: 40 60
+
+ * - HCI Command
+ - Purpose
+ * - ``HCI_Delete_Stored_Link_Key`` (all)
+ - Delete all stored link keys from controller
+ * - ``HCI_Set_Event_Mask_Page_2``
+ - Enable page 2 events (authenticated payload timeout, etc.)
+ * - ``HCI_Read_Local_Supported_Codecs`` [v2] or [v1]
+ - Read supported codec IDs; v2 includes transport type info
+ * - ``HCI_Read_Local_Pairing_Options``
+ - Read default pairing options (max encryption key size)
+ * - ``HCI_Get_MWS_Transport_Layer_Configuration``
+ - Read MWS coexistence config if supported
+ * - ``HCI_Read_Synchronization_Train_Parameters``
+ - Read sync train params (Connectionless Peripheral Broadcast)
+ * - ``HCI_Write_Secure_Connections_Support`` (enable)
+ - Enable Secure Connections if SSP active
+ * - ``HCI_Write_Default_Erroneous_Data_Reporting``
+ - Enable/disable based on wideband speech setting
+
+LE Data Length and PHY Defaults
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. list-table::
+ :header-rows: 1
+ :widths: 40 60
+
+ * - HCI Command
+ - Purpose
+ * - ``LE_Write_Suggested_Default_Data_Length``
+ - Set default TX octets/time for new connections
+ * - ``LE_Set_Default_PHY``
+ - Set preferred PHY (1M always; 2M and Coded if supported)
+
+Post-Initialization
+-------------------
+
+After the four stages complete, ``hci_powered_update_sync`` runs to
+apply runtime configuration:
+
+.. list-table::
+ :header-rows: 1
+ :widths: 40 60
+
+ * - Action
+ - Purpose
+ * - ``HCI_Write_Simple_Pairing_Mode``
+ - Re-enable SSP + Secure Connections if configured
+ * - ``HCI_Write_LE_Host_Supported``
+ - Sync LE host support state
+ * - LE advertising setup
+ - Configure advertising parameters and data
+ * - ``HCI_Write_Authentication_Enable``
+ - Sync authentication enable state
+ * - Scan/class/name/EIR updates
+ - Configure page scan, device class, local name, EIR data
+ * - ``LE_Set_Random_Address``
+ - Set static random address if no public address
+
+Reading the Init Sequence in a Trace
+-------------------------------------
+
+When examining a btsnoop trace, the initialization block is the
+first thing after the controller is opened. A typical dual-mode
+controller trace starts with::
+
+ < HCI Command: Reset
+ > HCI Event: Command Complete (Reset)
+ < HCI Command: Read Local Supported Features
+ > HCI Event: Command Complete (Read Local Supported Features)
+ < HCI Command: Read Local Version Information
+ > HCI Event: Command Complete (Read Local Version Information)
+ < HCI Command: Read BD ADDR
+ > HCI Event: Command Complete (Read BD ADDR)
+ ... [Stage 2-4 commands follow]
+
+**Key things to look for:**
+
+- **Missing commands**: If expected commands are absent, the
+ controller may not support the corresponding feature. For example,
+ no ``LE_Read_Buffer_Size`` means the controller is BR/EDR only.
+
+- **Command failures**: A ``Status`` other than ``0x00`` in a Command
+ Complete event during init usually indicates a broken controller or
+ unsupported feature. The kernel handles most gracefully, but
+ persistent errors may prevent the adapter from functioning.
+
+- **Buffer sizes**: The values returned by ``Read_Buffer_Size`` and
+ ``LE_Read_Buffer_Size`` determine how many in-flight packets the
+ controller can hold. Small buffer counts can cause throughput
+ issues.
+
+- **Feature bits**: The ``Read_Local_Supported_Features`` response
+ reveals what the controller supports (LE, SSP, eSCO, etc.). Cross
+ reference with the commands that follow — the kernel only sends
+ commands for features the controller reports supporting.
+
+- **Event mask**: The ``Set_Event_Mask`` command shows exactly which
+ events the host wants to receive. If an expected event never
+ appears in the trace, check whether it was enabled in the mask.
+
+- **LE-only controllers**: These skip all BR/EDR commands
+ (``Read_Buffer_Size``, ``Read_Local_Name``, link policy, etc.) and
+ use a minimal event mask. The trace will be noticeably shorter.
+
+- **Vendor commands**: Some controllers (Intel, Broadcom, Qualcomm,
+ Realtek, MediaTek) insert vendor-specific HCI commands between
+ stages for firmware download, configuration, or patch application.
+ These appear as opcode groups ``0x3F`` (vendor) and are
+ driver-specific.
diff --git a/doc/btmon.rst b/doc/btmon.rst
index 9cf1464eae63..6ecadf3f260d 100644
--- a/doc/btmon.rst
+++ b/doc/btmon.rst
@@ -755,6 +755,8 @@ Errors often cascade across layers. Common patterns:
PROTOCOL FLOWS
===============
+.. include:: btmon-hci-init.rst
+
.. include:: btmon-connections.rst
.. include:: btmon-gatt.rst
--
2.53.0
^ permalink raw reply related [flat|nested] 11+ messages in thread
* [PATCH BlueZ v2 8/9] doc/btmon: Add A2DP/AVDTP protocol flow documentation
2026-03-24 19:49 [PATCH BlueZ v2 1/9] doc/btmon: Split Advertising and Scanning into btmon-advertising.rst Luiz Augusto von Dentz
` (5 preceding siblings ...)
2026-03-24 19:49 ` [PATCH BlueZ v2 7/9] doc/btmon: Add HCI initialization sequence documentation Luiz Augusto von Dentz
@ 2026-03-24 19:49 ` Luiz Augusto von Dentz
2026-03-24 19:49 ` [PATCH BlueZ v2 9/9] doc/btmon: Add HFP " Luiz Augusto von Dentz
2026-03-24 20:44 ` [BlueZ,v2,1/9] doc/btmon: Split Advertising and Scanning into btmon-advertising.rst bluez.test.bot
8 siblings, 0 replies; 11+ messages in thread
From: Luiz Augusto von Dentz @ 2026-03-24 19:49 UTC (permalink / raw)
To: linux-bluetooth
From: Luiz Augusto von Dentz <luiz.von.dentz@intel.com>
Add btmon-a2dp.rst documenting the A2DP protocol flow as seen in btmon
output, wrapped by btmon-classic-audio.rst parent file. Coverage
includes:
- AVDTP signaling: Discover, Get Capabilities, Set Configuration,
Open, Start, Suspend, Close
- Codec capability/configuration decoding for SBC, AAC, aptX, aptX HD,
aptX Low Latency, FastStream, LDAC, and Opus
- AVDTP media transport channel setup
- AVRCP control and browsing channel overview
- Delay Reporting
- Automation-friendly grep patterns
---
doc/btmon-a2dp.rst | 418 ++++++++++++++++++++++++++++++++++++
doc/btmon-classic-audio.rst | 12 ++
doc/btmon.rst | 2 +
3 files changed, 432 insertions(+)
create mode 100644 doc/btmon-a2dp.rst
create mode 100644 doc/btmon-classic-audio.rst
diff --git a/doc/btmon-a2dp.rst b/doc/btmon-a2dp.rst
new file mode 100644
index 000000000000..516410e4e283
--- /dev/null
+++ b/doc/btmon-a2dp.rst
@@ -0,0 +1,418 @@
+.. This file is included by btmon-classic-audio.rst.
+
+A2DP: Advanced Audio Distribution
+-----------------------------------
+
+A2DP uses AVDTP (Audio/Video Distribution Transport Protocol) over
+L2CAP to negotiate codec parameters and stream high-quality audio.
+btmon fully decodes AVDTP signaling, codec capabilities, and AVRCP
+remote control messages.
+
+AVDTP Signaling Channel
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+A2DP begins with an L2CAP connection on PSM 25 (0x0019). The first
+L2CAP connection on this PSM carries AVDTP signaling; a second
+connection on the same PSM carries media transport data::
+
+ < ACL Data TX: Handle 1 flags 0x00 dlen 12
+ L2CAP: Connection Request (0x02) ident 1 len 4
+ PSM: 25 (0x0019)
+ Source CID: 64
+
+ > ACL Data RX: Handle 1 flags 0x02 dlen 16
+ L2CAP: Connection Response (0x03) ident 1 len 8
+ Destination CID: 64
+ Source CID: 64
+ Result: Connection successful (0x0000)
+ Status: No further information available (0x0000)
+
+After L2CAP configuration completes, AVDTP signaling begins on this
+channel.
+
+Stream Endpoint Discovery
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The initiator discovers available Stream Endpoints (SEPs) on the
+remote device::
+
+ < ACL Data TX: Handle 1 flags 0x00 dlen 6
+ Channel: 64 len 2 [PSM 25 mode Basic (0x00)] {chan 0}
+ AVDTP: Discover (0x01) Command (0x00) type 0x00 label 0 nosp 0
+
+ > ACL Data RX: Handle 1 flags 0x02 dlen 10
+ Channel: 64 len 6 [PSM 25 mode Basic (0x00)] {chan 0}
+ AVDTP: Discover (0x01) Response Accept (0x02) type 0x00 label 0 nosp 0
+ ACP SEID: 1
+ Media Type: Audio (0x00)
+ SEP Type: SNK (0x01)
+ In use: No
+
+Each SEP has a SEID (Stream Endpoint Identifier), media type, and
+role (Source or Sink). ``In use: Yes`` means the endpoint is already
+streaming.
+
+Codec Capability Discovery
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+After discovering SEIDs, the initiator queries each endpoint's
+capabilities::
+
+ < ACL Data TX: Handle 1 flags 0x00 dlen 7
+ Channel: 64 len 3 [PSM 25 mode Basic (0x00)] {chan 0}
+ AVDTP: Get All Capabilities (0x0c) Command (0x00) type 0x00 label 1 nosp 0
+ ACP SEID: 1
+
+ > ACL Data RX: Handle 1 flags 0x02 dlen 30
+ Channel: 64 len 26 [PSM 25 mode Basic (0x00)] {chan 0}
+ AVDTP: Get All Capabilities (0x0c) Response Accept (0x02) type 0x00 label 1 nosp 0
+ Service Category: Media Transport (0x01)
+ Service Category: Media Codec (0x07)
+ Media Type: Audio (0x00)
+ Media Codec: SBC (0x00)
+ Frequency: 0xf0
+ 16000
+ 32000
+ 44100
+ 48000
+ Channel Mode: 0x0f
+ Mono
+ Dual Channel
+ Stereo
+ Joint Stereo
+ Block Length: 0xf0
+ 4
+ 8
+ 12
+ 16
+ Subbands: 0x0c
+ 4
+ 8
+ Allocation Method: 0x03
+ SNR
+ Loudness
+ Minimum Bitpool: 2
+ Maximum Bitpool: 53
+ Service Category: Content Protection (0x04)
+ Content Protection Type: SCMS-T (0x0002)
+ Service Category: Delay Reporting (0x08)
+
+Capability responses list all supported values as bitmasks. Key
+service categories:
+
+- **Media Transport** (0x01) -- Always present, indicates the endpoint
+ supports a media transport channel
+- **Media Codec** (0x07) -- Codec type and supported parameters
+- **Content Protection** (0x04) -- Copy protection (SCMS-T or DTCP)
+- **Delay Reporting** (0x08) -- Endpoint supports delay reporting
+
+Supported Codecs
+~~~~~~~~~~~~~~~~~
+
+btmon decodes several A2DP codecs. Each has a different parameter
+format.
+
+**SBC** (mandatory A2DP codec)::
+
+ Media Codec: SBC (0x00)
+ Frequency: 44100 (0x20)
+ Channel Mode: Joint Stereo (0x01)
+ Block Length: 16 (0x10)
+ Subbands: 8 (0x04)
+ Allocation Method: Loudness (0x01)
+ Minimum Bitpool: 2
+ Maximum Bitpool: 53
+
+**AAC** (MPEG-2,4)::
+
+ Media Codec: MPEG-2,4 AAC (0x02)
+ Object Type: MPEG-4 AAC LC (0x40)
+ Frequency: 44100 (0x0100)
+ Channels: 2 (0x04)
+ Bitrate: 256000bps
+ VBR: No
+
+**aptX** (Qualcomm, vendor-specific)::
+
+ Media Codec: Non-A2DP (0xff)
+ Vendor ID: Qualcomm Technologies International, Ltd. (APT) (0x0000004f)
+ Vendor Specific Codec ID: aptX (0x0001)
+ Frequency: 44100 (0x20)
+ Channel Mode: Stereo (0x02)
+
+**aptX HD** (Qualcomm, vendor-specific)::
+
+ Media Codec: Non-A2DP (0xff)
+ Vendor ID: Qualcomm Technologies, Inc. (0x000000d7)
+ Vendor Specific Codec ID: aptX HD (0x0024)
+ Frequency: 44100 (0x20)
+ Channel Mode: Stereo (0x02)
+
+**LDAC** (Sony, vendor-specific)::
+
+ Media Codec: Non-A2DP (0xff)
+ Vendor ID: Sony Corporation (0x0000012d)
+ Vendor Specific Codec ID: LDAC (0x00aa)
+
+Vendor codecs appear as ``Non-A2DP (0xff)`` with decoded Vendor ID
+and Codec ID. Capability responses list all supported values as
+bitmasks; configuration responses show the single selected value.
+
+Stream Configuration
+~~~~~~~~~~~~~~~~~~~~~
+
+After selecting a codec and parameters, the initiator sends Set
+Configuration::
+
+ < ACL Data TX: Handle 1 flags 0x00 dlen 20
+ Channel: 64 len 16 [PSM 25 mode Basic (0x00)] {chan 0}
+ AVDTP: Set Configuration (0x03) Command (0x00) type 0x00 label 2 nosp 0
+ ACP SEID: 1
+ INT SEID: 1
+ Service Category: Media Transport (0x01)
+ Service Category: Media Codec (0x07)
+ Media Type: Audio (0x00)
+ Media Codec: SBC (0x00)
+ Frequency: 44100 (0x20)
+ Channel Mode: Joint Stereo (0x01)
+ Block Length: 16 (0x10)
+ Subbands: 8 (0x04)
+ Allocation Method: Loudness (0x01)
+ Minimum Bitpool: 2
+ Maximum Bitpool: 53
+
+ > ACL Data RX: Handle 1 flags 0x02 dlen 6
+ Channel: 64 len 2 [PSM 25 mode Basic (0x00)] {chan 0}
+ AVDTP: Set Configuration (0x03) Response Accept (0x02) type 0x00 label 2 nosp 0
+
+Configuration responses show single selected values instead of
+bitmask lists. ``ACP SEID`` is the remote endpoint, ``INT SEID`` is
+the local endpoint.
+
+If configuration is rejected::
+
+ > ACL Data RX: Handle 1 flags 0x02 dlen 8
+ Channel: 64 len 4 [PSM 25 mode Basic (0x00)] {chan 0}
+ AVDTP: Set Configuration (0x03) Response Reject (0x03) type 0x00 label 2 nosp 0
+ Service Category: Media Codec (0x07)
+ Error code: Unsupported Configuration (0x29)
+
+Common AVDTP error codes:
+
+.. list-table::
+ :header-rows: 1
+ :widths: 10 30 60
+
+ * - Code
+ - Name
+ - Meaning
+ * - 0x01
+ - Bad Header Format
+ - Malformed AVDTP header
+ * - 0x11
+ - Bad ACP SEID
+ - Unknown endpoint ID
+ * - 0x12
+ - SEP In Use
+ - Endpoint already streaming
+ * - 0x13
+ - SEP Not In Use
+ - Endpoint not configured
+ * - 0x29
+ - Unsupported Configuration
+ - Requested parameters not supported
+ * - 0x31
+ - Bad State
+ - Command not valid in current state
+
+Open and Start
+~~~~~~~~~~~~~~~
+
+After configuration, the stream is opened and then started::
+
+ < ACL Data TX: Handle 1 flags 0x00 dlen 7
+ Channel: 64 len 3 [PSM 25 mode Basic (0x00)] {chan 0}
+ AVDTP: Open (0x06) Command (0x00) type 0x00 label 3 nosp 0
+ ACP SEID: 1
+
+ > ACL Data RX: Handle 1 flags 0x02 dlen 6
+ Channel: 64 len 2 [PSM 25 mode Basic (0x00)] {chan 0}
+ AVDTP: Open (0x06) Response Accept (0x02) type 0x00 label 3 nosp 0
+
+After Open succeeds, a **second L2CAP connection** on PSM 25 is
+established for the media transport channel. Then Start begins
+streaming::
+
+ < ACL Data TX: Handle 1 flags 0x00 dlen 7
+ Channel: 64 len 3 [PSM 25 mode Basic (0x00)] {chan 0}
+ AVDTP: Start (0x07) Command (0x00) type 0x00 label 4 nosp 0
+ ACP SEID: 1
+
+ > ACL Data RX: Handle 1 flags 0x02 dlen 6
+ Channel: 64 len 2 [PSM 25 mode Basic (0x00)] {chan 0}
+ AVDTP: Start (0x07) Response Accept (0x02) type 0x00 label 4 nosp 0
+
+Media Data
+~~~~~~~~~~~
+
+After Start, encoded audio flows on the media transport channel
+(second L2CAP connection on PSM 25). btmon does **not** decode media
+packet contents by default -- media data is suppressed. Only the
+L2CAP channel header is visible when the ``--show-a2dp-stream``
+filter is enabled, with the payload shown as a raw hex dump.
+
+The AVDTP state machine visible in the trace:
+
+.. list-table::
+ :header-rows: 1
+ :widths: 20 30 50
+
+ * - State
+ - Triggered By
+ - Description
+ * - Idle
+ - Initial / Abort response
+ - No stream configured
+ * - Configured
+ - Set Configuration accept
+ - Codec and parameters selected
+ * - Open
+ - Open accept / Suspend accept
+ - Transport channel ready, not streaming
+ * - Streaming
+ - Start accept
+ - Audio data flowing
+ * - Closing
+ - Close command sent
+ - Tearing down stream
+ * - Aborting
+ - Abort command sent
+ - Forced teardown
+
+Suspend, Close, and Abort
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**Suspend** pauses streaming without tearing down the transport::
+
+ AVDTP: Suspend (0x09) Command (0x00) type 0x00 label 5 nosp 0
+ ACP SEID: 1
+ AVDTP: Suspend (0x09) Response Accept (0x02) type 0x00 label 5 nosp 0
+
+**Close** tears down the stream (returns to Idle)::
+
+ AVDTP: Close (0x08) Command (0x00) type 0x00 label 6 nosp 0
+ ACP SEID: 1
+ AVDTP: Close (0x08) Response Accept (0x02) type 0x00 label 6 nosp 0
+
+**Abort** forces immediate teardown::
+
+ AVDTP: Abort (0x0a) Command (0x00) type 0x00 label 7 nosp 0
+ ACP SEID: 1
+ AVDTP: Abort (0x0a) Response Accept (0x02) type 0x00 label 7 nosp 0
+
+Delay Reporting
+~~~~~~~~~~~~~~~~
+
+When the sink supports delay reporting, it sends a Delay Report to
+inform the source of its rendering delay::
+
+ AVDTP: Delay Report (0x0d) Command (0x00) type 0x00 label 8 nosp 0
+ ACP SEID: 1
+ Delay: 15.0ms
+ AVDTP: Delay Report (0x0d) Response Accept (0x02) type 0x00 label 8 nosp 0
+
+AVRCP Remote Control
+~~~~~~~~~~~~~~~~~~~~~
+
+AVRCP (Audio/Video Remote Control Profile) uses L2CAP PSM 23
+(control) and PSM 27 (browsing). btmon decodes AVCTP framing and
+AVRCP PDUs.
+
+**Volume control**::
+
+ < ACL Data TX: Handle 1 flags 0x00 dlen 17
+ Channel: 66 len 13 [PSM 23 mode Basic (0x00)] {chan 2}
+ AVCTP Control: Response: type 0x00 label 0 PID 0x110e
+ AV/C: Accepted: address 0x48 opcode 0x00
+ Subunit: Panel
+ Opcode: Vendor Dependent
+ Company ID: 0x001958
+ AVRCP: SetAbsoluteVolume pt Single len 0x0001
+ Volume: 50.39% (64/127)
+
+**Playback status**::
+
+ AVRCP: GetPlayStatus pt Single len 0x0009
+ SongLength: 0x00038270 (230000 milliseconds)
+ SongPosition: 0x00000000 (0 milliseconds)
+ PlayStatus: 0x01 (PLAYING)
+
+**Track metadata** (GetElementAttributes response)::
+
+ AVRCP: GetElementAttributes pt Single len 0x0050
+ AttributeCount: 0x02
+ Attribute: 0x00000001 (Title)
+ CharsetID: 0x006a (UTF-8)
+ AttributeValueLength: 0x000c
+ AttributeValue: My Song Name
+ Attribute: 0x00000002 (Artist)
+ CharsetID: 0x006a (UTF-8)
+ AttributeValueLength: 0x000b
+ AttributeValue: The Artist
+
+**Passthrough commands** (play, pause, skip)::
+
+ AVCTP Control: Command: type 0x00 label 1 PID 0x110e
+ AV/C: Control: address 0x48 opcode 0x7c
+ Subunit: Panel
+ Opcode: Passthrough
+ Operation: 0x44 (PLAY Pressed)
+ Length: 0x00
+
+**Event notifications** (volume change, track change)::
+
+ AVRCP: RegisterNotification pt Single len 0x0005
+ EventID: 0x0d (EVENT_VOLUME_CHANGED)
+ Volume: 50.39% (64/127)
+
+Automating A2DP Analysis
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**Identify A2DP activity**::
+
+ grep -n "AVDTP:\|Media Codec:" output.txt
+
+**Track AVDTP state transitions**::
+
+ grep -n "AVDTP:.*Command\|AVDTP:.*Response" output.txt
+
+**Check codec negotiation** (what was selected)::
+
+ grep -n "Set Configuration\|Media Codec:" output.txt
+
+**Verify stream is flowing** -- look for Start accept followed by
+media data::
+
+ grep -n "AVDTP: Start\|PSM 25.*chan 1" output.txt
+
+**Detect codec mismatch** -- look for Set Configuration reject::
+
+ grep -n "Response Reject\|Error code:" output.txt
+
+**Track AVRCP volume and playback**::
+
+ grep -n "SetAbsoluteVolume\|Volume:\|GetPlayStatus\|PlayStatus:" output.txt
+
+**Full A2DP diagnosis pattern**:
+
+1. Find L2CAP Connection Request for PSM 25 -- confirms AVDTP channel
+ setup
+2. Find Discover response -- shows available endpoints and whether any
+ are already in use
+3. Find Get All Capabilities response -- verify codec support overlap
+4. Find Set Configuration -- verify agreed codec and parameters
+5. Find Open and Start -- confirm stream setup succeeded
+6. Find second L2CAP connection on PSM 25 -- media transport channel
+7. On failure, check for Response Reject with error code
+8. If audio cuts out, look for Suspend or Close, or check for ACL
+ disconnection
diff --git a/doc/btmon-classic-audio.rst b/doc/btmon-classic-audio.rst
new file mode 100644
index 000000000000..11943c3a54bf
--- /dev/null
+++ b/doc/btmon-classic-audio.rst
@@ -0,0 +1,12 @@
+.. This file is included by btmon.rst.
+
+CLASSIC AUDIO PROTOCOL FLOW
+=============================
+
+Classic Bluetooth audio uses two main profiles: A2DP for high-quality
+stereo streaming and HFP for voice calls. Both run over BR/EDR ACL
+connections and use different transport mechanisms for audio data --
+A2DP uses L2CAP-based AVDTP media channels while HFP uses SCO/eSCO
+synchronous connections.
+
+.. include:: btmon-a2dp.rst
diff --git a/doc/btmon.rst b/doc/btmon.rst
index 6ecadf3f260d..8a02edce8e6a 100644
--- a/doc/btmon.rst
+++ b/doc/btmon.rst
@@ -767,6 +767,8 @@ PROTOCOL FLOWS
.. include:: btmon-le-audio.rst
+.. include:: btmon-classic-audio.rst
+
.. include:: btmon-advertising.rst
EXAMPLES
--
2.53.0
^ permalink raw reply related [flat|nested] 11+ messages in thread
* [PATCH BlueZ v2 9/9] doc/btmon: Add HFP protocol flow documentation
2026-03-24 19:49 [PATCH BlueZ v2 1/9] doc/btmon: Split Advertising and Scanning into btmon-advertising.rst Luiz Augusto von Dentz
` (6 preceding siblings ...)
2026-03-24 19:49 ` [PATCH BlueZ v2 8/9] doc/btmon: Add A2DP/AVDTP protocol flow documentation Luiz Augusto von Dentz
@ 2026-03-24 19:49 ` Luiz Augusto von Dentz
2026-03-26 11:28 ` Frédéric Danis
2026-03-24 20:44 ` [BlueZ,v2,1/9] doc/btmon: Split Advertising and Scanning into btmon-advertising.rst bluez.test.bot
8 siblings, 1 reply; 11+ messages in thread
From: Luiz Augusto von Dentz @ 2026-03-24 19:49 UTC (permalink / raw)
To: linux-bluetooth
From: Luiz Augusto von Dentz <luiz.von.dentz@intel.com>
Add btmon-hfp.rst documenting the HFP protocol flow as seen in btmon
output. Coverage includes:
- SDP service discovery for Handsfree/AG UUIDs
- RFCOMM channel setup over L2CAP PSM 3 (SABM/UA, Parameter
Negotiation, Modem Status Command)
- AT command exchange for SLC setup (noted as hex dump only -- btmon
does not parse AT commands within RFCOMM UIH data frames)
- Codec negotiation via AT+BAC/AT+BCS
- SCO/eSCO synchronous connection setup (voice setting, coding format)
- Codec summary tables (AT-level vs HCI-level codec IDs)
- Automation-friendly grep patterns
---
doc/btmon-classic-audio.rst | 2 +
doc/btmon-hfp.rst | 476 ++++++++++++++++++++++++++++++++++++
2 files changed, 478 insertions(+)
create mode 100644 doc/btmon-hfp.rst
diff --git a/doc/btmon-classic-audio.rst b/doc/btmon-classic-audio.rst
index 11943c3a54bf..3e7c5384be87 100644
--- a/doc/btmon-classic-audio.rst
+++ b/doc/btmon-classic-audio.rst
@@ -10,3 +10,5 @@ A2DP uses L2CAP-based AVDTP media channels while HFP uses SCO/eSCO
synchronous connections.
.. include:: btmon-a2dp.rst
+
+.. include:: btmon-hfp.rst
diff --git a/doc/btmon-hfp.rst b/doc/btmon-hfp.rst
new file mode 100644
index 000000000000..c81c0df3feb3
--- /dev/null
+++ b/doc/btmon-hfp.rst
@@ -0,0 +1,476 @@
+.. This file is included by btmon-classic-audio.rst.
+
+HFP: Hands-Free Profile
+-------------------------
+
+HFP carries voice audio over SCO/eSCO connections with call control
+over RFCOMM. btmon decodes RFCOMM framing and SCO/eSCO connection
+setup. AT commands (the HFP control protocol) appear as raw hex dumps
+within RFCOMM data frames -- btmon does not parse AT command syntax.
+
+SDP Discovery
+~~~~~~~~~~~~~~
+
+HFP uses SDP to discover the remote device's Hands-Free or Audio
+Gateway service record and its RFCOMM channel number::
+
+ < ACL Data TX: Handle 1 flags 0x00 dlen 25
+ Channel: 64 len 21 [PSM 1 mode Basic (0x00)] {chan 0}
+ SDP: Service Search Attribute Request (0x06) tid 1 len 16
+ Search pattern: [len 5]
+ Sequence (6) with 3 byte(s) [8 extra bits] len 5
+ UUID (3) with 2 byte(s) [0 extra bits] len 3
+ Handsfree Audio Gateway (0x111f)
+ Max record count: 65535
+ Attribute list: [len 5]
+ Sequence (6) with 3 byte(s) [8 extra bits] len 5
+ Unsigned Integer (1) with 4 byte(s) [0 extra bits] len 5
+ 0x0000ffff
+ Continuation state: 0
+
+The response contains the service record with the RFCOMM channel::
+
+ > ACL Data RX: Handle 1 flags 0x02 dlen 89
+ Channel: 64 len 85 [PSM 1 mode Basic (0x00)] {chan 0}
+ SDP: Service Search Attribute Response (0x07) tid 1 len 80
+ Attribute bytes: 77
+ Attribute list: [len 75] {position 0}
+ Attribute: Service Class ID List (0x0001) [len 2]
+ Handsfree Audio Gateway (0x111f)
+ Attribute: Protocol Descriptor List (0x0004) [len 2]
+ L2CAP (0x0100)
+ RFCOMM (0x0003)
+ Channel: 1
+ Attribute: Bluetooth Profile Descriptor List (0x0009) [len 2]
+ Handsfree (0x111e)
+ Version: 0x0108
+ Continuation state: 0
+
+Key fields to extract:
+
+- **Service Class** -- ``Handsfree (0x111e)`` for HF role,
+ ``Handsfree Audio Gateway (0x111f)`` for AG role
+- **RFCOMM Channel** -- The channel number under ``RFCOMM (0x0003)``
+ in the Protocol Descriptor List (e.g., channel 1)
+- **Profile Version** -- Under the Bluetooth Profile Descriptor List
+ (e.g., ``0x0108`` = HFP 1.8, ``0x0109`` = HFP 1.9)
+
+RFCOMM Connection Setup
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+RFCOMM runs over L2CAP PSM 3. The connection proceeds in stages:
+multiplexer session on DLCI 0, parameter negotiation, then the data
+channel on the target DLCI.
+
+**L2CAP connection for RFCOMM**::
+
+ < ACL Data TX: Handle 1 flags 0x00 dlen 12
+ L2CAP: Connection Request (0x02) ident 2 len 4
+ PSM: 3 (0x0003)
+ Source CID: 65
+
+ > ACL Data RX: Handle 1 flags 0x02 dlen 16
+ L2CAP: Connection Response (0x03) ident 2 len 8
+ Destination CID: 65
+ Source CID: 65
+ Result: Connection successful (0x0000)
+ Status: No further information available (0x0000)
+
+**SABM/UA on DLCI 0** (multiplexer session)::
+
+ < ACL Data TX: Handle 1 flags 0x00 dlen 12
+ Channel: 65 len 4 [PSM 3 mode Basic (0x00)] {chan 1}
+ RFCOMM: Set Async Balance Mode (SABM) (0x2f)
+ Address: 0x03 cr 1 dlci 0x00
+ Control: 0x3f poll/final 1
+ Length: 0
+ FCS: 0x1c
+
+ > ACL Data RX: Handle 1 flags 0x02 dlen 12
+ Channel: 65 len 4 [PSM 3 mode Basic (0x00)] {chan 1}
+ RFCOMM: Unnumbered Ack (UA) (0x63)
+ Address: 0x03 cr 1 dlci 0x00
+ Control: 0x73 poll/final 1
+ Length: 0
+ FCS: 0xd7
+
+**Parameter Negotiation** (MCC on DLCI 0)::
+
+ Channel: 65 len 14 [PSM 3 mode Basic (0x00)] {chan 1}
+ RFCOMM: Unnumbered Info with Header Check (UIH) (0xef)
+ Address: 0x03 cr 1 dlci 0x00
+ Control: 0xef poll/final 0
+ Length: 10
+ FCS: 0x70
+ MCC Message type: DLC Parameter Negotiation CMD (0x20)
+ Length: 8
+ dlci 2 frame_type 0 credit_flow 15 pri 7
+ ack_timer 0 frame_size 127 max_retrans 0 credits 7
+
+The DLCI in the PN command identifies the target channel. For RFCOMM
+channel N, DLCI = N * 2 (or N * 2 + 1 depending on the initiator
+role).
+
+**SABM/UA on target DLCI** (data channel)::
+
+ Channel: 65 len 4 [PSM 3 mode Basic (0x00)] {chan 1}
+ RFCOMM: Set Async Balance Mode (SABM) (0x2f)
+ Address: 0x0b cr 1 dlci 0x02
+ Control: 0x3f poll/final 1
+ Length: 0
+ FCS: 0x59
+
+ Channel: 65 len 4 [PSM 3 mode Basic (0x00)] {chan 1}
+ RFCOMM: Unnumbered Ack (UA) (0x63)
+ Address: 0x0b cr 1 dlci 0x02
+ Control: 0x73 poll/final 1
+ Length: 0
+ FCS: 0x92
+
+**Modem Status Command** (signals readiness)::
+
+ Channel: 65 len 8 [PSM 3 mode Basic (0x00)] {chan 1}
+ RFCOMM: Unnumbered Info with Header Check (UIH) (0xef)
+ Address: 0x03 cr 1 dlci 0x00
+ Control: 0xef poll/final 0
+ Length: 4
+ FCS: 0x70
+ MCC Message type: Modem Status Command CMD (0x38)
+ Length: 2
+ dlci 2
+ fc 0 rtc 1 rtr 1 ic 0 dv 1
+
+AT Command Exchange (SLC Setup)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+HFP uses AT commands over RFCOMM for call control and feature
+negotiation. btmon shows these as RFCOMM UIH frames with the AT
+command text visible in the hex dump.
+
+**AT command in RFCOMM UIH frame**::
+
+ Channel: 65 len 21 [PSM 3 mode Basic (0x00)] {chan 1}
+ RFCOMM: Unnumbered Info with Header Check (UIH) (0xef)
+ Address: 0x09 cr 0 dlci 0x02
+ Control: 0xff poll/final 1
+ Length: 14
+ FCS: 0x86
+ Credits: 1
+ 41 54 2b 42 52 53 46 3d 32 30 35 35 0d AT+BRSF=2055.
+
+The AT command text is readable in the ASCII column of the hex dump
+(right side). The Service Level Connection (SLC) setup sequence
+exchanges device features and capabilities:
+
+1. ``AT+BRSF=<features>`` / ``+BRSF:<features>`` -- Supported
+ features bitmask exchange
+2. ``AT+BAC=1,2`` -- Available codecs (if codec negotiation supported).
+ Codec IDs: 1 = CVSD, 2 = mSBC, 3 = LC3-SWB
+3. ``AT+CIND=?`` / ``+CIND:(...)`` -- Indicator mapping query
+4. ``AT+CIND?`` / ``+CIND:values`` -- Current indicator values
+5. ``AT+CMER=3,0,0,1`` -- Enable indicator status reporting
+6. ``AT+CHLD=?`` / ``+CHLD:(0,1,2,3,4)`` -- Three-way calling support
+
+Key HFP feature bits (from ``AT+BRSF``):
+
+.. list-table::
+ :header-rows: 1
+ :widths: 10 25 25
+
+ * - Bit
+ - HF Feature
+ - AG Feature
+ * - 0
+ - EC/NR
+ - Three-way calling
+ * - 1
+ - Three-way calling
+ - EC/NR
+ * - 2
+ - CLI presentation
+ - Voice recognition
+ * - 3
+ - Voice recognition
+ - In-band ring tone
+ * - 4
+ - Remote volume
+ - Voice tag
+ * - 5
+ - Enhanced call status
+ - Reject call
+ * - 6
+ - Enhanced call control
+ - Enhanced call status
+ * - 7
+ - Codec negotiation
+ - Enhanced call control
+ * - 8
+ - HF indicators
+ - Extended error codes
+ * - 9
+ - eSCO S4 (T2)
+ - Codec negotiation
+ * - 11
+ -
+ - eSCO S4 (T2)
+
+Codec Connection Setup
+~~~~~~~~~~~~~~~~~~~~~~~
+
+When both sides support codec negotiation (feature bit 7 on HF, bit 9
+on AG), the AG selects a codec before establishing the audio link.
+This appears as AT commands in RFCOMM UIH frames::
+
+ AG -> HF: +BCS:2 (select mSBC)
+ HF -> AG: AT+BCS=2 (confirm mSBC)
+ AG -> HF: OK
+
+HFP codec IDs (used in ``AT+BAC`` and ``AT+BCS``):
+
+.. list-table::
+ :header-rows: 1
+ :widths: 10 20 30
+
+ * - ID
+ - Codec
+ - Description
+ * - 1
+ - CVSD
+ - Narrow band (8 kHz), mandatory
+ * - 2
+ - mSBC
+ - Wide band speech (16 kHz)
+ * - 3
+ - LC3-SWB
+ - Super wide band (32 kHz), HFP 1.9+
+
+These HFP-level codec IDs differ from HCI codec IDs.
+
+Voice Setting
+~~~~~~~~~~~~~~
+
+Before SCO/eSCO setup, the host configures the voice setting. For
+CVSD, the air coding format is CVSD; for mSBC or LC3-SWB, it must be
+set to Transparent Data::
+
+ < HCI Command: Write Voice Setting (0x0c|0x0026) plen 2
+ Setting: 0x0063
+ Input Coding: Linear
+ Input Data Format: 2's complement
+ Input Sample Size: 16-bit
+ # of bits padding at MSB: 0
+ Air Coding Format: Transparent Data
+
+For CVSD::
+
+ < HCI Command: Write Voice Setting (0x0c|0x0026) plen 2
+ Setting: 0x0060
+ Input Coding: Linear
+ Input Data Format: 2's complement
+ Input Sample Size: 16-bit
+ # of bits padding at MSB: 0
+ Air Coding Format: CVSD
+
+SCO/eSCO Connection Setup
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+After codec negotiation, the host establishes a synchronous connection
+for voice audio.
+
+**Setup Synchronous Connection** (basic)::
+
+ < HCI Command: Setup Synchronous Connection (0x01|0x0028) plen 17
+ Handle: 1
+ Transmit bandwidth: 8000
+ Receive bandwidth: 8000
+ Max latency: 13
+ Setting: 0x0063
+ Input Coding: Linear
+ Input Data Format: 2's complement
+ Input Sample Size: 16-bit
+ # of bits padding at MSB: 0
+ Air Coding Format: Transparent Data
+ Retransmission effort: Optimize for link quality (0x02)
+ Packet type: 0x0008
+ EV3 may be used
+
+**Enhanced Setup Synchronous Connection** (codec-aware)::
+
+ < HCI Command: Enhanced Setup Synchronous Connection (0x01|0x003d) plen 59
+ Handle: 1
+ Transmit bandwidth: 8000
+ Receive bandwidth: 8000
+ Transmit Coding Format:
+ Codec: mSBC (0x05)
+ Receive Coding Format:
+ Codec: mSBC (0x05)
+ Transmit Codec Frame Size: 60
+ Receive Codec Frame Size: 60
+ Input Coding Format:
+ Codec: mSBC (0x05)
+ Output Coding Format:
+ Codec: mSBC (0x05)
+ Input Coded Data Size: 16
+ Output Coded Data Size: 16
+ Input PCM Data Format: 2's complement
+ Output PCM Data Format: 2's complement
+ Input PCM Sample Payload MSB Position: 0
+ Output PCM Sample Payload MSB Position: 0
+ Input Data Path: HCI
+ Output Data Path: HCI
+ Input Transport Unit Size: 60
+ Output Transport Unit Size: 60
+ Max latency: 13
+ Packet type: 0x0008
+ EV3 may be used
+ Retransmission effort: Optimize for link quality (0x02)
+
+HCI codec IDs displayed by btmon:
+
+.. list-table::
+ :header-rows: 1
+ :widths: 10 20 30
+
+ * - ID
+ - btmon Name
+ - Used For
+ * - 0x02
+ - CVSD
+ - Narrow band voice
+ * - 0x03
+ - Transparent
+ - Transparent data mode
+ * - 0x04
+ - Linear PCM
+ - Uncompressed PCM input/output
+ * - 0x05
+ - mSBC
+ - Wide band speech
+ * - 0x06
+ - LC3
+ - Super wide band (LC3-SWB)
+
+**Synchronous Connection Complete** (result)::
+
+ > HCI Event: Synchronous Connection Complete (0x2c) plen 17
+ Status: Success (0x00)
+ Handle: 257
+ Address: 11:22:33:44:55:66 (OUI 11-22-33)
+ Link type: eSCO (0x02)
+ Transmission interval: 0x0c
+ Retransmission window: 0x06
+ RX packet length: 60
+ TX packet length: 60
+ Air mode: Transparent (0x03)
+
+Key fields:
+
+- **Link type** -- ``SCO (0x00)`` for legacy, ``eSCO (0x02)`` for
+ enhanced (used by mSBC and LC3-SWB)
+- **Air mode** -- ``CVSD (0x02)`` for narrow band,
+ ``Transparent (0x03)`` for mSBC or LC3-SWB
+- **RX/TX packet length** -- 60 bytes typical for mSBC T2 settings
+
+SCO Data Packets
+~~~~~~~~~~~~~~~~~
+
+After the synchronous connection is established, voice data flows as
+SCO/eSCO data packets::
+
+ > BR-ESCO: Handle 257 flags 0x00 dlen 60
+ < BR-ESCO: Handle 257 flags 0x00 dlen 60
+
+btmon labels packets based on the connection type established in
+Synchronous Connection Complete:
+
+- ``BR-SCO`` -- Legacy SCO connection
+- ``BR-ESCO`` -- Enhanced SCO connection (mSBC, LC3-SWB, or eSCO CVSD)
+
+SCO data payload is **not displayed by default**. It requires the
+``--show-sco-data`` filter to see the hex dump of voice data.
+
+Codec-Specific Connection Summary
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**CVSD (narrow band)**:
+
+- HFP codec ID: 1
+- HCI codec: CVSD (0x02)
+- Voice setting: 0x0060 (Air Coding Format: CVSD)
+- Air mode: CVSD (0x02)
+- Link type: SCO or eSCO
+- Typical packet size: 48 bytes (HV3) or 60 bytes (EV3)
+
+**mSBC (wide band speech)**:
+
+- HFP codec ID: 2
+- HCI codec: mSBC (0x05)
+- Voice setting: 0x0063 (Air Coding Format: Transparent Data)
+- Air mode: Transparent (0x03)
+- Link type: eSCO
+- Typical packet size: 60 bytes (EV3, T2 settings)
+
+**LC3-SWB (super wide band)**:
+
+- HFP codec ID: 3
+- HCI codec: LC3 (0x06)
+- Voice setting: 0x0063 (Air Coding Format: Transparent Data)
+- Air mode: Transparent (0x03)
+- Link type: eSCO
+- Note: btmon displays ``LC3``, not ``LC3-SWB``
+
+Automating HFP Analysis
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**Identify HFP activity** -- look for RFCOMM on PSM 3::
+
+ grep -n "PSM: 3\|RFCOMM:" output.txt
+
+**Read AT commands** -- search hex dump ASCII for AT command patterns::
+
+ grep -n "AT+B\|AT+C\|+BRSF\|+CIND\|+CHLD\|+BCS" output.txt
+
+**Check codec negotiation** -- look for BCS (Bluetooth Codec
+Selection)::
+
+ grep -n "+BCS\|AT+BAC\|AT+BCS" output.txt
+
+**Verify SCO/eSCO setup**::
+
+ grep -n "Setup Synchronous\|Enhanced Setup Synchronous\|Synchronous Connection Complete\|Write Voice Setting" output.txt
+
+**Check voice codec** -- confirm air mode and coding format::
+
+ grep -n "Air mode:\|Air Coding Format:\|Codec:" output.txt
+
+**Detect SCO failures** -- check Synchronous Connection Complete
+status::
+
+ grep -n "Synchronous Connection Complete" output.txt
+
+Then examine the next line for ``Status:``. Common failures:
+
+- ``Connection Rejected due to Limited Resources (0x0d)`` -- controller
+ cannot allocate bandwidth
+- ``SCO Offset Rejected (0x2b)`` -- timing parameters rejected
+- ``SCO Interval Rejected (0x2c)`` -- interval parameters rejected
+
+**Track call state** -- look for CIEV indicator updates::
+
+ grep -n "+CIEV\|AT+CHUP\|ATD\|ATA\|AT+CLCC\|RING" output.txt
+
+**Full HFP diagnosis pattern**:
+
+1. Find SDP query for UUID 0x111e/0x111f -- confirms HFP discovery
+2. Find L2CAP Connection Request for PSM 3 -- RFCOMM channel setup
+3. Find RFCOMM SABM/UA on DLCI 0 then target DLCI -- multiplexer and
+ data channel
+4. Find AT+BRSF in hex dumps -- feature exchange, check codec
+ negotiation bit
+5. Find AT+BAC in hex dumps -- available codecs reported
+6. Find +BCS/AT+BCS in hex dumps -- codec selected for audio
+7. Find Write Voice Setting -- verify air coding format matches codec
+8. Find Setup Synchronous Connection or Enhanced variant -- SCO setup
+9. Find Synchronous Connection Complete -- check Status, Link type,
+ Air mode
+10. Find BR-SCO or BR-ESCO packets -- voice data flowing
--
2.53.0
^ permalink raw reply related [flat|nested] 11+ messages in thread
* RE: [BlueZ,v2,1/9] doc/btmon: Split Advertising and Scanning into btmon-advertising.rst
2026-03-24 19:49 [PATCH BlueZ v2 1/9] doc/btmon: Split Advertising and Scanning into btmon-advertising.rst Luiz Augusto von Dentz
` (7 preceding siblings ...)
2026-03-24 19:49 ` [PATCH BlueZ v2 9/9] doc/btmon: Add HFP " Luiz Augusto von Dentz
@ 2026-03-24 20:44 ` bluez.test.bot
8 siblings, 0 replies; 11+ messages in thread
From: bluez.test.bot @ 2026-03-24 20:44 UTC (permalink / raw)
To: linux-bluetooth, luiz.dentz
[-- Attachment #1: Type: text/plain, Size: 1796 bytes --]
This is automated email and please do not reply to this email!
Dear submitter,
Thank you for submitting the patches to the linux bluetooth mailing list.
This is a CI test results with your patch series:
PW Link:https://patchwork.kernel.org/project/bluetooth/list/?series=1071883
---Test result---
Test Summary:
CheckPatch PENDING 0.38 seconds
GitLint PENDING 0.37 seconds
BuildEll PASS 17.80 seconds
BluezMake PASS 613.03 seconds
MakeCheck PASS 18.24 seconds
MakeDistcheck FAIL 49.40 seconds
CheckValgrind PASS 275.57 seconds
CheckSmatch PASS 307.47 seconds
bluezmakeextell PASS 165.34 seconds
IncrementalBuild PENDING 0.32 seconds
ScanBuild PASS 891.00 seconds
Details
##############################
Test: CheckPatch - PENDING
Desc: Run checkpatch.pl script
Output:
##############################
Test: GitLint - PENDING
Desc: Run gitlint
Output:
##############################
Test: MakeDistcheck - FAIL
Desc: Run Bluez Make Distcheck
Output:
../../doc/btmon.rst:758: (SEVERE/4) Problems with "include" directive path:
InputError: [Errno 2] No such file or directory: '../../doc/btmon-hci-init.rst'.
Exiting due to level-4 (SEVERE) system message.
make[2]: *** [Makefile:12166: doc/btmon.1] Error 1
make[2]: *** Waiting for unfinished jobs....
make[1]: *** [Makefile:4145: all] Error 2
make: *** [Makefile:10665: distcheck] Error 1
##############################
Test: IncrementalBuild - PENDING
Desc: Incremental build with the patches in the series
Output:
https://github.com/bluez/bluez/pull/1986/checks
---
Regards,
Linux Bluetooth
^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [PATCH BlueZ v2 9/9] doc/btmon: Add HFP protocol flow documentation
2026-03-24 19:49 ` [PATCH BlueZ v2 9/9] doc/btmon: Add HFP " Luiz Augusto von Dentz
@ 2026-03-26 11:28 ` Frédéric Danis
0 siblings, 0 replies; 11+ messages in thread
From: Frédéric Danis @ 2026-03-26 11:28 UTC (permalink / raw)
To: Luiz Augusto von Dentz; +Cc: linux-bluetooth
Hi Luiz,
On 24/03/2026 20:49, Luiz Augusto von Dentz wrote:
> From: Luiz Augusto von Dentz <luiz.von.dentz@intel.com>
>
> Add btmon-hfp.rst documenting the HFP protocol flow as seen in btmon
> output. Coverage includes:
>
> - SDP service discovery for Handsfree/AG UUIDs
> - RFCOMM channel setup over L2CAP PSM 3 (SABM/UA, Parameter
> Negotiation, Modem Status Command)
> - AT command exchange for SLC setup (noted as hex dump only -- btmon
> does not parse AT commands within RFCOMM UIH data frames)
> - Codec negotiation via AT+BAC/AT+BCS
> - SCO/eSCO synchronous connection setup (voice setting, coding format)
> - Codec summary tables (AT-level vs HCI-level codec IDs)
> - Automation-friendly grep patterns
> ---
> doc/btmon-classic-audio.rst | 2 +
> doc/btmon-hfp.rst | 476 ++++++++++++++++++++++++++++++++++++
> 2 files changed, 478 insertions(+)
> create mode 100644 doc/btmon-hfp.rst
>
> diff --git a/doc/btmon-classic-audio.rst b/doc/btmon-classic-audio.rst
> index 11943c3a54bf..3e7c5384be87 100644
> --- a/doc/btmon-classic-audio.rst
> +++ b/doc/btmon-classic-audio.rst
> @@ -10,3 +10,5 @@ A2DP uses L2CAP-based AVDTP media channels while HFP uses SCO/eSCO
> synchronous connections.
>
> .. include:: btmon-a2dp.rst
> +
> +.. include:: btmon-hfp.rst
> diff --git a/doc/btmon-hfp.rst b/doc/btmon-hfp.rst
> new file mode 100644
> index 000000000000..c81c0df3feb3
> --- /dev/null
> +++ b/doc/btmon-hfp.rst
> @@ -0,0 +1,476 @@
> +.. This file is included by btmon-classic-audio.rst.
> +
> +HFP: Hands-Free Profile
> +-------------------------
> +
> +HFP carries voice audio over SCO/eSCO connections with call control
> +over RFCOMM. btmon decodes RFCOMM framing and SCO/eSCO connection
> +setup. AT commands (the HFP control protocol) appear as raw hex dumps
> +within RFCOMM data frames -- btmon does not parse AT command syntax.
> +
> +SDP Discovery
> +~~~~~~~~~~~~~~
> +
> +HFP uses SDP to discover the remote device's Hands-Free or Audio
> +Gateway service record and its RFCOMM channel number::
> +
> + < ACL Data TX: Handle 1 flags 0x00 dlen 25
> + Channel: 64 len 21 [PSM 1 mode Basic (0x00)] {chan 0}
> + SDP: Service Search Attribute Request (0x06) tid 1 len 16
> + Search pattern: [len 5]
> + Sequence (6) with 3 byte(s) [8 extra bits] len 5
> + UUID (3) with 2 byte(s) [0 extra bits] len 3
> + Handsfree Audio Gateway (0x111f)
> + Max record count: 65535
> + Attribute list: [len 5]
> + Sequence (6) with 3 byte(s) [8 extra bits] len 5
> + Unsigned Integer (1) with 4 byte(s) [0 extra bits] len 5
> + 0x0000ffff
> + Continuation state: 0
> +
> +The response contains the service record with the RFCOMM channel::
> +
> + > ACL Data RX: Handle 1 flags 0x02 dlen 89
> + Channel: 64 len 85 [PSM 1 mode Basic (0x00)] {chan 0}
> + SDP: Service Search Attribute Response (0x07) tid 1 len 80
> + Attribute bytes: 77
> + Attribute list: [len 75] {position 0}
> + Attribute: Service Class ID List (0x0001) [len 2]
> + Handsfree Audio Gateway (0x111f)
> + Attribute: Protocol Descriptor List (0x0004) [len 2]
> + L2CAP (0x0100)
> + RFCOMM (0x0003)
> + Channel: 1
> + Attribute: Bluetooth Profile Descriptor List (0x0009) [len 2]
> + Handsfree (0x111e)
> + Version: 0x0108
> + Continuation state: 0
> +
> +Key fields to extract:
> +
> +- **Service Class** -- ``Handsfree (0x111e)`` for HF role,
> + ``Handsfree Audio Gateway (0x111f)`` for AG role
> +- **RFCOMM Channel** -- The channel number under ``RFCOMM (0x0003)``
> + in the Protocol Descriptor List (e.g., channel 1)
> +- **Profile Version** -- Under the Bluetooth Profile Descriptor List
> + (e.g., ``0x0108`` = HFP 1.8, ``0x0109`` = HFP 1.9)
> +
> +RFCOMM Connection Setup
> +~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +RFCOMM runs over L2CAP PSM 3. The connection proceeds in stages:
> +multiplexer session on DLCI 0, parameter negotiation, then the data
> +channel on the target DLCI.
> +
> +**L2CAP connection for RFCOMM**::
> +
> + < ACL Data TX: Handle 1 flags 0x00 dlen 12
> + L2CAP: Connection Request (0x02) ident 2 len 4
> + PSM: 3 (0x0003)
> + Source CID: 65
> +
> + > ACL Data RX: Handle 1 flags 0x02 dlen 16
> + L2CAP: Connection Response (0x03) ident 2 len 8
> + Destination CID: 65
> + Source CID: 65
> + Result: Connection successful (0x0000)
> + Status: No further information available (0x0000)
> +
> +**SABM/UA on DLCI 0** (multiplexer session)::
> +
> + < ACL Data TX: Handle 1 flags 0x00 dlen 12
> + Channel: 65 len 4 [PSM 3 mode Basic (0x00)] {chan 1}
> + RFCOMM: Set Async Balance Mode (SABM) (0x2f)
> + Address: 0x03 cr 1 dlci 0x00
> + Control: 0x3f poll/final 1
> + Length: 0
> + FCS: 0x1c
> +
> + > ACL Data RX: Handle 1 flags 0x02 dlen 12
> + Channel: 65 len 4 [PSM 3 mode Basic (0x00)] {chan 1}
> + RFCOMM: Unnumbered Ack (UA) (0x63)
> + Address: 0x03 cr 1 dlci 0x00
> + Control: 0x73 poll/final 1
> + Length: 0
> + FCS: 0xd7
> +
> +**Parameter Negotiation** (MCC on DLCI 0)::
> +
> + Channel: 65 len 14 [PSM 3 mode Basic (0x00)] {chan 1}
> + RFCOMM: Unnumbered Info with Header Check (UIH) (0xef)
> + Address: 0x03 cr 1 dlci 0x00
> + Control: 0xef poll/final 0
> + Length: 10
> + FCS: 0x70
> + MCC Message type: DLC Parameter Negotiation CMD (0x20)
> + Length: 8
> + dlci 2 frame_type 0 credit_flow 15 pri 7
> + ack_timer 0 frame_size 127 max_retrans 0 credits 7
> +
> +The DLCI in the PN command identifies the target channel. For RFCOMM
> +channel N, DLCI = N * 2 (or N * 2 + 1 depending on the initiator
> +role).
> +
> +**SABM/UA on target DLCI** (data channel)::
> +
> + Channel: 65 len 4 [PSM 3 mode Basic (0x00)] {chan 1}
> + RFCOMM: Set Async Balance Mode (SABM) (0x2f)
> + Address: 0x0b cr 1 dlci 0x02
> + Control: 0x3f poll/final 1
> + Length: 0
> + FCS: 0x59
> +
> + Channel: 65 len 4 [PSM 3 mode Basic (0x00)] {chan 1}
> + RFCOMM: Unnumbered Ack (UA) (0x63)
> + Address: 0x0b cr 1 dlci 0x02
> + Control: 0x73 poll/final 1
> + Length: 0
> + FCS: 0x92
> +
> +**Modem Status Command** (signals readiness)::
> +
> + Channel: 65 len 8 [PSM 3 mode Basic (0x00)] {chan 1}
> + RFCOMM: Unnumbered Info with Header Check (UIH) (0xef)
> + Address: 0x03 cr 1 dlci 0x00
> + Control: 0xef poll/final 0
> + Length: 4
> + FCS: 0x70
> + MCC Message type: Modem Status Command CMD (0x38)
> + Length: 2
> + dlci 2
> + fc 0 rtc 1 rtr 1 ic 0 dv 1
> +
> +AT Command Exchange (SLC Setup)
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +HFP uses AT commands over RFCOMM for call control and feature
> +negotiation. btmon shows these as RFCOMM UIH frames with the AT
> +command text visible in the hex dump.
> +
> +**AT command in RFCOMM UIH frame**::
> +
> + Channel: 65 len 21 [PSM 3 mode Basic (0x00)] {chan 1}
> + RFCOMM: Unnumbered Info with Header Check (UIH) (0xef)
> + Address: 0x09 cr 0 dlci 0x02
> + Control: 0xff poll/final 1
> + Length: 14
> + FCS: 0x86
> + Credits: 1
> + 41 54 2b 42 52 53 46 3d 32 30 35 35 0d AT+BRSF=2055.
> +
> +The AT command text is readable in the ASCII column of the hex dump
> +(right side). The Service Level Connection (SLC) setup sequence
> +exchanges device features and capabilities:
> +
> +1. ``AT+BRSF=<features>`` / ``+BRSF:<features>`` -- Supported
> + features bitmask exchange
> +2. ``AT+BAC=1,2`` -- Available codecs (if codec negotiation supported).
> + Codec IDs: 1 = CVSD, 2 = mSBC, 3 = LC3-SWB
> +3. ``AT+CIND=?`` / ``+CIND:(...)`` -- Indicator mapping query
> +4. ``AT+CIND?`` / ``+CIND:values`` -- Current indicator values
> +5. ``AT+CMER=3,0,0,1`` -- Enable indicator status reporting
> +6. ``AT+CHLD=?`` / ``+CHLD:(0,1,2,3,4)`` -- Three-way calling support
You may add here the optional commands for the HF Indicator feature, i.e.
7. ``AT+BIND=<HF supported HF indicators>`` -- Supported HF indicators
by HF (if HF indicators are supported)
8. ``AT+BIND=?`` / ``+BIND:(...)`` -- Supported HF indicators by AG (if
HF indicators are supported)
9. ``AT+BIND?`` / ``+BIND:anum,state``-- Enable HF indicator status
reporting (if HF indicators are supported)
> +
> +Key HFP feature bits (from ``AT+BRSF``):
> +
> +.. list-table::
> + :header-rows: 1
> + :widths: 10 25 25
> +
> + * - Bit
> + - HF Feature
> + - AG Feature
> + * - 0
> + - EC/NR
> + - Three-way calling
> + * - 1
> + - Three-way calling
> + - EC/NR
> + * - 2
> + - CLI presentation
> + - Voice recognition
> + * - 3
> + - Voice recognition
> + - In-band ring tone
> + * - 4
> + - Remote volume
> + - Voice tag
> + * - 5
> + - Enhanced call status
> + - Reject call
> + * - 6
> + - Enhanced call control
> + - Enhanced call status
> + * - 7
> + - Codec negotiation
> + - Enhanced call control
> + * - 8
> + - HF indicators
> + - Extended error codes
> + * - 9
> + - eSCO S4 (T2)
> + - Codec negotiation
> + * - 11
> + -
> + - eSCO S4 (T2)
> +
> +Codec Connection Setup
> +~~~~~~~~~~~~~~~~~~~~~~~
> +
> +When both sides support codec negotiation (feature bit 7 on HF, bit 9
> +on AG), the AG selects a codec before establishing the audio link.
> +This appears as AT commands in RFCOMM UIH frames::
> +
> + AG -> HF: +BCS:2 (select mSBC)
> + HF -> AG: AT+BCS=2 (confirm mSBC)
> + AG -> HF: OK
> +
> +HFP codec IDs (used in ``AT+BAC`` and ``AT+BCS``):
> +
> +.. list-table::
> + :header-rows: 1
> + :widths: 10 20 30
> +
> + * - ID
> + - Codec
> + - Description
> + * - 1
> + - CVSD
> + - Narrow band (8 kHz), mandatory
> + * - 2
> + - mSBC
> + - Wide band speech (16 kHz)
> + * - 3
> + - LC3-SWB
> + - Super wide band (32 kHz), HFP 1.9+
> +
> +These HFP-level codec IDs differ from HCI codec IDs.
> +
> +Voice Setting
> +~~~~~~~~~~~~~~
> +
> +Before SCO/eSCO setup, the host configures the voice setting. For
> +CVSD, the air coding format is CVSD; for mSBC or LC3-SWB, it must be
> +set to Transparent Data::
> +
> + < HCI Command: Write Voice Setting (0x0c|0x0026) plen 2
> + Setting: 0x0063
> + Input Coding: Linear
> + Input Data Format: 2's complement
> + Input Sample Size: 16-bit
> + # of bits padding at MSB: 0
> + Air Coding Format: Transparent Data
> +
> +For CVSD::
> +
> + < HCI Command: Write Voice Setting (0x0c|0x0026) plen 2
> + Setting: 0x0060
> + Input Coding: Linear
> + Input Data Format: 2's complement
> + Input Sample Size: 16-bit
> + # of bits padding at MSB: 0
> + Air Coding Format: CVSD
This seems a bit confusing to me. Shouldn't it better with:
Before SCO/eSCO setup, the host configures the voice setting. For
CVSD, the air coding format is CVSD:
< HCI Command: Write Voice Setting (0x0c|0x0026) plen 2
Setting: 0x0060
Input Coding: Linear
Input Data Format: 2's complement
Input Sample Size: 16-bit
# of bits padding at MSB: 0
Air Coding Format: CVSD
For mSBC or LC3-SWB, the air coding format must be set to
Transparent Data::
< HCI Command: Write Voice Setting (0x0c|0x0026) plen 2
Setting: 0x0063
Input Coding: Linear
Input Data Format: 2's complement
Input Sample Size: 16-bit
# of bits padding at MSB: 0
Air Coding Format: Transparent Data
> +
> +SCO/eSCO Connection Setup
> +~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +After codec negotiation, the host establishes a synchronous connection
> +for voice audio.
> +
> +**Setup Synchronous Connection** (basic)::
> +
> + < HCI Command: Setup Synchronous Connection (0x01|0x0028) plen 17
> + Handle: 1
> + Transmit bandwidth: 8000
> + Receive bandwidth: 8000
> + Max latency: 13
> + Setting: 0x0063
> + Input Coding: Linear
> + Input Data Format: 2's complement
> + Input Sample Size: 16-bit
> + # of bits padding at MSB: 0
> + Air Coding Format: Transparent Data
> + Retransmission effort: Optimize for link quality (0x02)
> + Packet type: 0x0008
> + EV3 may be used
> +
> +**Enhanced Setup Synchronous Connection** (codec-aware)::
> +
> + < HCI Command: Enhanced Setup Synchronous Connection (0x01|0x003d) plen 59
> + Handle: 1
> + Transmit bandwidth: 8000
> + Receive bandwidth: 8000
> + Transmit Coding Format:
> + Codec: mSBC (0x05)
> + Receive Coding Format:
> + Codec: mSBC (0x05)
> + Transmit Codec Frame Size: 60
> + Receive Codec Frame Size: 60
> + Input Coding Format:
> + Codec: mSBC (0x05)
> + Output Coding Format:
> + Codec: mSBC (0x05)
> + Input Coded Data Size: 16
> + Output Coded Data Size: 16
> + Input PCM Data Format: 2's complement
> + Output PCM Data Format: 2's complement
> + Input PCM Sample Payload MSB Position: 0
> + Output PCM Sample Payload MSB Position: 0
> + Input Data Path: HCI
> + Output Data Path: HCI
> + Input Transport Unit Size: 60
> + Output Transport Unit Size: 60
> + Max latency: 13
> + Packet type: 0x0008
> + EV3 may be used
> + Retransmission effort: Optimize for link quality (0x02)
> +
> +HCI codec IDs displayed by btmon:
> +
> +.. list-table::
> + :header-rows: 1
> + :widths: 10 20 30
> +
> + * - ID
> + - btmon Name
> + - Used For
> + * - 0x02
> + - CVSD
> + - Narrow band voice
> + * - 0x03
> + - Transparent
> + - Transparent data mode
> + * - 0x04
> + - Linear PCM
> + - Uncompressed PCM input/output
> + * - 0x05
> + - mSBC
> + - Wide band speech
> + * - 0x06
> + - LC3
> + - Super wide band (LC3-SWB)
> +
> +**Synchronous Connection Complete** (result)::
> +
> + > HCI Event: Synchronous Connection Complete (0x2c) plen 17
> + Status: Success (0x00)
> + Handle: 257
> + Address: 11:22:33:44:55:66 (OUI 11-22-33)
> + Link type: eSCO (0x02)
> + Transmission interval: 0x0c
> + Retransmission window: 0x06
> + RX packet length: 60
> + TX packet length: 60
> + Air mode: Transparent (0x03)
> +
> +Key fields:
> +
> +- **Link type** -- ``SCO (0x00)`` for legacy, ``eSCO (0x02)`` for
> + enhanced (used by mSBC and LC3-SWB)
> +- **Air mode** -- ``CVSD (0x02)`` for narrow band,
> + ``Transparent (0x03)`` for mSBC or LC3-SWB
> +- **RX/TX packet length** -- 60 bytes typical for mSBC T2 settings
> +
> +SCO Data Packets
> +~~~~~~~~~~~~~~~~~
> +
> +After the synchronous connection is established, voice data flows as
> +SCO/eSCO data packets::
> +
> + > BR-ESCO: Handle 257 flags 0x00 dlen 60
> + < BR-ESCO: Handle 257 flags 0x00 dlen 60
> +
> +btmon labels packets based on the connection type established in
> +Synchronous Connection Complete:
> +
> +- ``BR-SCO`` -- Legacy SCO connection
> +- ``BR-ESCO`` -- Enhanced SCO connection (mSBC, LC3-SWB, or eSCO CVSD)
> +
> +SCO data payload is **not displayed by default**. It requires the
> +``--show-sco-data`` filter to see the hex dump of voice data.
> +
> +Codec-Specific Connection Summary
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +**CVSD (narrow band)**:
> +
> +- HFP codec ID: 1
> +- HCI codec: CVSD (0x02)
> +- Voice setting: 0x0060 (Air Coding Format: CVSD)
> +- Air mode: CVSD (0x02)
> +- Link type: SCO or eSCO
> +- Typical packet size: 48 bytes (HV3) or 60 bytes (EV3)
> +
> +**mSBC (wide band speech)**:
> +
> +- HFP codec ID: 2
> +- HCI codec: mSBC (0x05)
> +- Voice setting: 0x0063 (Air Coding Format: Transparent Data)
> +- Air mode: Transparent (0x03)
> +- Link type: eSCO
> +- Typical packet size: 60 bytes (EV3, T2 settings)
> +
> +**LC3-SWB (super wide band)**:
> +
> +- HFP codec ID: 3
> +- HCI codec: LC3 (0x06)
> +- Voice setting: 0x0063 (Air Coding Format: Transparent Data)
> +- Air mode: Transparent (0x03)
> +- Link type: eSCO
> +- Note: btmon displays ``LC3``, not ``LC3-SWB``
> +
> +Automating HFP Analysis
> +~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +**Identify HFP activity** -- look for RFCOMM on PSM 3::
> +
> + grep -n "PSM: 3\|RFCOMM:" output.txt
> +
> +**Read AT commands** -- search hex dump ASCII for AT command patterns::
> +
> + grep -n "AT+B\|AT+C\|+BRSF\|+CIND\|+CHLD\|+BCS" output.txt
> +
> +**Check codec negotiation** -- look for BCS (Bluetooth Codec
> +Selection)::
> +
> + grep -n "+BCS\|AT+BAC\|AT+BCS" output.txt
> +
> +**Verify SCO/eSCO setup**::
> +
> + grep -n "Setup Synchronous\|Enhanced Setup Synchronous\|Synchronous Connection Complete\|Write Voice Setting" output.txt
> +
> +**Check voice codec** -- confirm air mode and coding format::
> +
> + grep -n "Air mode:\|Air Coding Format:\|Codec:" output.txt
> +
> +**Detect SCO failures** -- check Synchronous Connection Complete
> +status::
> +
> + grep -n "Synchronous Connection Complete" output.txt
> +
> +Then examine the next line for ``Status:``. Common failures:
> +
> +- ``Connection Rejected due to Limited Resources (0x0d)`` -- controller
> + cannot allocate bandwidth
> +- ``SCO Offset Rejected (0x2b)`` -- timing parameters rejected
> +- ``SCO Interval Rejected (0x2c)`` -- interval parameters rejected
> +
> +**Track call state** -- look for CIEV indicator updates::
> +
> + grep -n "+CIEV\|AT+CHUP\|ATD\|ATA\|AT+CLCC\|RING" output.txt
> +
> +**Full HFP diagnosis pattern**:
> +
> +1. Find SDP query for UUID 0x111e/0x111f -- confirms HFP discovery
> +2. Find L2CAP Connection Request for PSM 3 -- RFCOMM channel setup
> +3. Find RFCOMM SABM/UA on DLCI 0 then target DLCI -- multiplexer and
> + data channel
> +4. Find AT+BRSF in hex dumps -- feature exchange, check codec
> + negotiation bit
> +5. Find AT+BAC in hex dumps -- available codecs reported
> +6. Find +BCS/AT+BCS in hex dumps -- codec selected for audio
> +7. Find Write Voice Setting -- verify air coding format matches codec
> +8. Find Setup Synchronous Connection or Enhanced variant -- SCO setup
> +9. Find Synchronous Connection Complete -- check Status, Link type,
> + Air mode
> +10. Find BR-SCO or BR-ESCO packets -- voice data flowing
^ permalink raw reply [flat|nested] 11+ messages in thread
end of thread, other threads:[~2026-03-26 11:29 UTC | newest]
Thread overview: 11+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2026-03-24 19:49 [PATCH BlueZ v2 1/9] doc/btmon: Split Advertising and Scanning into btmon-advertising.rst Luiz Augusto von Dentz
2026-03-24 19:49 ` [PATCH BlueZ v2 2/9] doc/btmon: Split LE Audio Protocol Flow into btmon-le-audio.rst Luiz Augusto von Dentz
2026-03-24 19:49 ` [PATCH BlueZ v2 3/9] doc/btmon: Split L2CAP Channel Tracking into btmon-l2cap.rst Luiz Augusto von Dentz
2026-03-24 19:49 ` [PATCH BlueZ v2 4/9] doc/btmon: Split SMP Pairing Flow into btmon-smp.rst Luiz Augusto von Dentz
2026-03-24 19:49 ` [PATCH BlueZ v2 5/9] doc/btmon: Split GATT Database Reconstruction into btmon-gatt.rst Luiz Augusto von Dentz
2026-03-24 19:49 ` [PATCH BlueZ v2 6/9] doc/btmon: Split Connection Tracking into btmon-connections.rst Luiz Augusto von Dentz
2026-03-24 19:49 ` [PATCH BlueZ v2 7/9] doc/btmon: Add HCI initialization sequence documentation Luiz Augusto von Dentz
2026-03-24 19:49 ` [PATCH BlueZ v2 8/9] doc/btmon: Add A2DP/AVDTP protocol flow documentation Luiz Augusto von Dentz
2026-03-24 19:49 ` [PATCH BlueZ v2 9/9] doc/btmon: Add HFP " Luiz Augusto von Dentz
2026-03-26 11:28 ` Frédéric Danis
2026-03-24 20:44 ` [BlueZ,v2,1/9] doc/btmon: Split Advertising and Scanning into btmon-advertising.rst bluez.test.bot
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox