btmon(1)

Name
btmon - Bluetooth monitor

SYNOPSIS

btmon [OPTIONS ...]

DESCRIPTION

The btmon(1) command provides access to the Bluetooth subsystem monitor infrastructure for reading HCI traces.

OPTIONS

-r FILE, --read FILE
    Read traces in btsnoop format from FILE.

-w FILE, --write FILE
    Save traces in btsnoop format to FILE.

-a FILE, --analyze FILE
    Analyze traces in btsnoop format from FILE. It displays the devices found in the FILE with its packets by type. If gnuplot is installed on the system it also attempts to plot packet latency graph.

-s SOCKET, --server SOCKET
    Start monitor server socket.

-p PRIORITY, --priority PRIORITY
    Show only priority or lower for user log.
    PRIORITY | NAME
    3 | Error
    4 | Warning
    6 | Information (Default)
    7 | Debug. debug can be used.

-i NUM, --index NUM
    Show only specified controller. hciNUM is also acceptable. This is useful to capture the traces from the specific controller when the multiple controllers are presented.

-d TTY, --tty TTY
    Read data from TTY.

-B SPEED, --rate SPEED
    Set TTY speed. The default SPEED is 115300

-V COMPID, --vendor COMPID
    Set the default company identifier. The COMPID is a unique number assigned by the Bluetooth SIG to a member company and can be found/searched from the Bluetooth SIG webpage.

    For example, Intel is 2 and Realtek is 93.

-M, --mgmt
    Open channel for mgmt events.

-K, --kernel
    Open kmsg for kernel messages.

-t, --time
    Show a time instead of time offset.

-T, --date
    Show a time and date information instead of time offset.

-N, --no-time
    Suppress the time offset display entirely.

-S, --sco
    Dump SCO traffic in raw hex format.

-A, --a2dp
    Dump A2DP stream traffic in a raw hex format.

-I, --iso
    Dump ISO stream traffic in raw hex format. Required to see LE Audio isochronous data in the output.

-E IP, --ellisys IP
    Send Ellisys HCI Injection.

-P, --no-pager
    Disable pager usage while reading the log file.

-J OPTIONS, --jlink OPTIONS
    Read data from RTT. Each options are comma(,) separated without spaces.
    OPTIONS | Description
    DEVICE | Required. Set the target device.
    SERIALNO | (Optional) Set the USB serial number. Default is 0.
    INTERFACE | (Optional) Target interface. Default is swd.
    SPEED | (Optional) Set target interface speed in kHz. Default is 1000.

-R OPTIONS, --rtt OPTIONS
    RTT control block parameters. Each options are comma(,) separated without spaces.
    OPTIONS | Description
    ADDRESS | (Optional) Address of RTT buffer. Default is 0x00
    AREA | (Optional) Size of range to search in RTT buffer. Default is 0
    NAME | (Optional) Buffer name. Default is btmonitor

-C WIDTH, --columns WIDTH
    Output width if not a terminal

-c MODE, --color MODE
    Set output color. The possible MODE values are: auto|always|never.

    Default value is auto

-v, --version
    Show version

-h, --help
    Show help options

READING THE OUTPUT

btmon output is organized as a stream of frames, each representing a single event in the Bluetooth subsystem. Understanding the output format is essential for debugging Bluetooth issues.

  Line Prefixes

Every frame begins with a single-character prefix that identifies its source and type:
Prefix | Meaning | Description
< | HCI Command / Data TX | Sent from host to controller (outgoing). HCI commands, ACL/SCO/ISO data transmitted to the controller.
> | HCI Event / Data RX | Received from controller to host (incoming). HCI events, ACL/SCO/ISO data received from the controller.
@ | Management traffic | Management interface (MGMT) commands and events between bluetoothd and the kernel management layer.
 | System notes | System-level annotations: kernel information, index changes, process log messages, and D-Bus signals.

  HCI Traffic (< and >)

HCI frames represent the actual communication between the host software and the Bluetooth controller hardware.

Anatomy of an HCI command line:

    < HCI Command: Reset (0x03|0x0003) plen 0             #5 [hci0] 12:35:01.843185
    │                    │    │    │          │              │  │       │
    │                    │    │    │          │              │  │       └─ Timestamp
    │                    │    │    │          │              │  └─ Controller
    │                    │    │    │          │              └─ Frame number
    │                    │    │    │          └─ Parameter length (bytes)
    │                    │    │    └─ Full opcode (16-bit)
    │                    │    └─ OGF|OCF (Opcode Group / Command Field)
    │                    └─ Command name (human-readable)
    └─ Direction: < = Host to Controller (outgoing)

Anatomy of an HCI event line:

    > HCI Event: Command Complete (0x0e) plen 4           #6 [hci0] 12:35:01.864922
    │                              │      │                │  │       │
    │                              │      │                │  │       └─ Timestamp
    │                              │      │                │  └─ Controller
    │                              │      │                └─ Frame number
    │                              │      └─ Parameter length
    │                              └─ Event code
    │
    └─ Direction: > = Controller to Host (incoming)

The < direction means the host is sending to the controller (commands and data). The > direction means the controller is sending to the host (events and data). Think of it from the controller's perspective: < is input going into the controller, > is output coming from it.

HCI commands with parameters are followed by indented detail lines:

    < HCI Command: LE Set Extende.. (0x08|0x0039) plen 2  #1 [hci0] 12:35:01.738352
            Extended advertising: Disabled (0x00)
            Number of sets: Disable all sets (0x00)

HCI event responses reference the command they complete:

    > HCI Event: Command Complete (0x0e) plen 4           #6 [hci0] 12:35:01.864922
          Reset (0x03|0x0003) ncmd 2
            Status: Success (0x00)

Here ncmd 2 indicates the controller can accept 2 more commands (HCI flow control). The indented body shows the command this event completes and the result status.

LE Meta Events contain a subevent type:

    > HCI Event: LE Meta Event (0x3e) plen 31           #487 [hci0] 12:36:18.974201
          LE Enhanced Connection Complete (0x0a)
            Status: Success (0x00)
            Handle: 2048
            Role: Peripheral (0x01)
            Peer address type: Public (0x00)
            Peer address: AA:BB:CC:DD:EE:FF (OUI Company)
            Connection interval: 60.00 msec (0x0030)
            Connection latency: 0 (0x0000)
            Supervision timeout: 9600 msec (0x03c0)

ACL Data shows data plane traffic with handle and protocol decoding:

    < LE-ACL: Handle 2048 [66:B0:26:F1:D3:BC] [1/6] flags 0x00 dlen 16  #493 [hci0] 12:36:18.977915
    │   │            │     │                   │          │         │    │    │     │
    │   │            │     │                   │          │         │    │    │     └─ Timestamp
    │   │            │     │                   │          │         │    │    └─ Controller
    │   │            │     │                   │          │         │    └─ Frame number
    │   │            │     │                   │          │         └─ Data length
    │   │            │     │                   │          └─ flags
    │   │            │     │                   └─ Buffer tracking (optional)
    │   │            │     └─ Peer address (optional)
    │   │            └─ Handle number
    │   └─ Connection-type-aware label (e.g. BR-ACL, LE-ACL, BR-SCO, LE-ISO)
    └─ Direction marker: '<' = host->controller (TX), '>' = controller->host (RX)

ACL data is automatically decoded into higher-layer protocols:

    < LE-ACL: Handle 2048 [2/6] flags 0x00 dlen 7  #494 [hci0] 12:36:18.978488
          ATT: Exchange MTU Request (0x02) len 2
            Client RX MTU: 517
    > LE-ACL: Handle 2048 flags 0x02 dlen 11       #497 [hci0] 12:36:19.000048
          SMP: Pairing Request (0x01) len 6
            IO capability: NoInputNoOutput (0x03)
            OOB data: Authentication data not present (0x00)
            Authentication requirement: Bonding, MITM, SC, No Keypresses, CT2 (0x2d)
            Max encryption key size: 16

  Management Traffic (@)

Lines starting with @ show management interface traffic -- the structured command/event protocol between bluetoothd and the kernel (see doc/mgmt-protocol.rst).

Anatomy of a management line:

    @ MGMT Command: Set Powered (0x0005) plen 1     {0x0001} [hci0] 12:35:04.033564
    │                            │        │           │        │       │
    │                            │        │           │        │       └─ Timestamp
    │                            │        │           │        └─ Controller
    │                            │        │           └─ MGMT socket ID
    │                            │        └─ Parameter length
    │                            └─ MGMT opcode
    └─ @ = Management channel

The {0x0001} is the management socket identifier -- it distinguishes between multiple management clients (e.g. bluetoothd and btmgmt running simultaneously).

MGMT Open/Close track when processes connect to the management channel:

    @ MGMT Open: bluetoothd (privileged) version 1.23      {0x0001} 12:34:49.881936
    @ MGMT Close: bluetoothd                               {0x0001} 12:35:01.866256

These show the process name, privilege level, and protocol version.

MGMT commands with parameters:

    @ MGMT Command: Set Powered (0x0005) plen 1     {0x0001} [hci0] 12:35:04.033564
            Powered: Enabled (0x01)

MGMT events (responses and notifications):

    @ MGMT Event: Command Complete (0x0001) plen 7  {0x0001} [hci0] 12:35:04.114789
          Set Powered (0x0005) plen 4
            Status: Success (0x00)
            Current settings: 0x004e0ac1
              Powered
              Secure Simple Pairing

MGMT without controller index (global operations):

    @ MGMT Command: Read Management Ver.. (0x0001) plen 0  {0x0001} 12:35:04.027771
    @ MGMT Event: Command Complete (0x0001) plen 6         {0x0001} 12:35:04.027776

Notice there is no [hci0] -- these operate at the system level, not on a specific controller.

  System Notes (=)

Lines starting with = are system-level annotations injected by the kernel or by processes via the monitor channel. They are not HCI or MGMT protocol traffic.

Kernel information (shown at startup):

    = Note: Linux version 6.16.0-rc6-0903 (x86_64)                  12:34:49.881926
    = Note: Bluetooth subsystem version 2.22                        12:34:49.881930

Index lifecycle (controller added/removed/opened/closed):

    = New Index: 00:11:22:33:44:55 (Primary,USB,hci0)        [hci0] 12:34:49.881932
    = Open Index: 00:11:22:33:44:55                          [hci0] 12:34:49.881933
    = Index Info: 00:11:22:33:44:55 (OUI Company)              [hci0] 12:34:49.881934
    = Close Index: 00:11:22:33:44:55                         [hci0] 12:35:01.865125

•   New Index -- a controller was registered with the kernel

•   Open Index -- a controller was activated

•   Index Info -- controller vendor information

•   Close Index -- a controller was deactivated

    Process log messages (debug output from bluetoothd and other daemons):

        = bluetoothd: src/adapter.c:connected_callback() hci0 devic..   12:36:18.975307
          │           │                                                  │
          │           │                                                  └─ Timestamp
          │           └─ Source file, function, and message (may be truncated)
          └─ Process name

    These appear when bluetoothd is running with debug enabled (-d) or when a process writes to the kernel logging channel. They show the source file path, function name, and a log message -- invaluable for correlating daemon-internal decisions with the HCI traffic around them.

    D-Bus activity (signals and method calls):

        = bluetoothd: [:1.21220:method_call] > org.freedesktop.DBus..   12:34:53.912508
        = bluetoothd: [:1.21220:method_return] < [#5]                   12:34:53.912546
        = bluetoothd: [signal] org.freedesktop.DBus.ObjectManager.I..   12:36:18.975691

    The format is [bus_name:message_type] followed by > (outgoing) or < (incoming). Note that > and < within D-Bus system notes indicate D-Bus message direction, not HCI direction.

  Right-Side Metadata

Every line has metadata right-aligned at the end. The exact fields depend on the line type:

    ┌─ Main content (left-aligned, variable width)
    │                                        ┌─ Frame # ─┐ ┌Controller┐ ┌─ Timestamp ─┐
    │                                        │            │ │          │ │              │
    < HCI Command: Reset (0x03|0x0003) plen 0             #5 [hci0] 12:35:01.843185
    > HCI Event: Command Complete (0x0e) plen 4           #6 [hci0] 12:35:01.864922
    @ MGMT Command: Set Powered (0x0005) plen 1     {0x0001} [hci0] 12:35:04.033564
    = Note: Linux version 6.16.0-rc6-0903 (x86_64)                  12:34:49.881926
    = Open Index: 00:11:22:33:44:55                          [hci0] 12:34:49.881933

Frame number (#N): Sequential counter for HCI frames only. Useful for identifying specific packets in a trace. Only HCI traffic (< and >) gets frame numbers -- MGMT (@) and system notes (=) do not.

Controller ([hciN]): Identifies which Bluetooth controller the frame belongs to. Absent for global operations (kernel notes, MGMT commands without a controller index).

MGMT socket ID ({0xNNNN}): Shown on @ lines instead of frame numbers. Identifies which management socket (process) sent the command.

Timestamp: Always the rightmost field. The format depends on the command-line option used:
Option | Format | Example
(default) | Seconds since trace start | 0.881932
-t | Time of day (HH:MM:SS.usec) | 12:35:01.843185
-T | Full date and time | 2026-01-13 12:34:49.881926

  Indented Detail Lines

Lines indented below a frame header contain the decoded payload of that frame. The indentation level indicates the protocol layer:

•   First level (6 spaces): direct payload of the HCI/MGMT frame

•   Second level (8 spaces): decoded fields within the payload

•   Third level (10+ spaces): nested protocol data (e.g. L2CAP inside ACL, ATT inside L2CAP)

    Example of protocol layering in ACL data:

        > ACL: Handle 2048 flags 0x02 dlen 11       #497 [hci0] 12:36:19.000048
              SMP: Pairing Request (0x01) len 6                          ← L2CAP/SMP layer
                IO capability: NoInputNoOutput (0x03)                    ← SMP fields
                OOB data: Authentication data not present (0x00)
                Authentication requirement: Bonding, MITM, SC (0x2d)
                Max encryption key size: 16

  Timestamp Notes

When reading btsnoop files with -t or -T, timestamps reflect the wall-clock time recorded in the btsnoop file. The precision depends on the source:

•   Live capture (btmon monitor channel): Microsecond precision from the kernel.

•   btsnoop files: The btsnoop format stores timestamps as microseconds since epoch, so full microsecond precision is preserved. Trailing zeros in the display (e.g., 14:38:46.589000) indicate the original capture source had millisecond granularity.

    The default timestamp mode shows seconds elapsed since the first packet in the trace, which is useful for measuring intervals between events without needing to know the absolute time.

  Frame Numbers vs Line Numbers

btmon assigns sequential frame numbers (#N) to HCI packets. These are stable identifiers for specific packets regardless of output formatting. However, when processing btmon text output with tools like grep or sed, the relevant unit is line numbers in the output file. The two are unrelated:

•   A single frame may produce many output lines (header + decoded fields).

•   Frame numbers only apply to HCI traffic (< and >). MGMT (@) and system notes (=) do not have frame numbers.

•   When referencing specific packets, prefer frame numbers (#487) over line numbers, as frame numbers are stable across different terminal widths and formatting options.

  Practical Reading Guide

Typical command-response pair:

    < HCI Command: Read BD ADDR (0x04|0x0009) plen 0     #13 [hci0] 12:35:04.057866
    > HCI Event: Command Complete (0x0e) plen 10         #14 [hci0] 12:35:04.058750
          Read BD ADDR (0x04|0x0009) ncmd 1
            Status: Success (0x00)
            Address: 00:11:22:33:44:55 (OUI Company)

Read this as: Frame #13, the host asked the controller for its Bluetooth address. Frame #14, the controller replied with success and the address 00:11:22:33:44:55. The response arrived ~0.9ms later.

Typical MGMT flow showing relation to HCI:

    @ MGMT Command: Set Powered (0x0005) plen 1     {0x0001} [hci0] 12:35:04.033564
            Powered: Enabled (0x01)
    < HCI Command: Reset (0x03|0x0003) plen 0             #7 [hci0] 12:35:04.033907
    > HCI Event: Command Complete (0x0e) plen 4           #8 [hci0] 12:35:04.055753
          Reset (0x03|0x0003) ncmd 2
            Status: Success (0x00)
      ... (more HCI commands to configure the controller) ...
    @ MGMT Event: Command Complete (0x0001) plen 7  {0x0001} [hci0] 12:35:04.114789
          Set Powered (0x0005) plen 4
            Status: Success (0x00)

Read this as: bluetoothd sent Set Powered via MGMT. The kernel translated this into a sequence of HCI commands (Reset, then configuration). After all HCI commands completed, the kernel sent the MGMT Command Complete event back to bluetoothd.

Connection establishment flow:

    > HCI Event: LE Meta Event (0x3e) plen 31           #487 [hci0] 12:36:18.974201
          LE Enhanced Connection Complete (0x0a)
            Status: Success (0x00)
            Handle: 2048
            Role: Peripheral (0x01)
            Peer address: AA:BB:CC:DD:EE:FF (OUI Company)
    @ MGMT Event: Device Connec.. (0x000b) plen 13  {0x0001} [hci0] 12:36:18.974319
    = bluetoothd: src/adapter.c:connected_callback() hci0 devic..   12:36:18.975307
    < ACL: Handle 2048 [1.. flags 0x00 dlen 16  #493 [hci0] 12:36:18.977915
          LE L2CAP: Connection Parameter Update Request (0x12) ident 1 len 8
    < ACL: Handle 2048 [2/6] flags 0x00 dlen 7  #494 [hci0] 12:36:18.978488
          ATT: Exchange MTU Request (0x02) len 2
            Client RX MTU: 517

Read this as: The controller reported a new LE connection (HCI event). 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.

ANALYZE MODE

The -a (--analyze) option reads a btsnoop file and produces a statistical summary instead of the full decoded trace.

  Usage

    $ btmon -a hcidump.log

  Output Contents

Analyze mode reports, for each controller found in the trace:

•   Packet counts: Total HCI packets broken down by type (commands, events, ACL, SCO, ISO, vendor diagnostics, system notes, user logs, control messages).

•   Per-connection statistics: For each connection handle found:

•   Connection type (BR-ACL, LE-ACL, BR-SCO, BR-ESCO, LE-ISO)

•   Device address

•   TX and RX packet counts and completion counts

•   Latency statistics (min, max, median) in milliseconds

•   Packet size statistics (min, max, average) in octets

•   Throughput estimate in Kb/s

•   Per-channel statistics: For each L2CAP channel within a connection, the same packet/latency/size statistics.

•

Latency plots: If gnuplot is installed, ASCII-art latency
    distribution plots are rendered in the terminal.

PROTOCOL ERROR CODES

btmon automatically decodes error codes from multiple protocol layers. This section provides a reference for interpreting errors seen across ATT, SMP, and L2CAP layers.

  ATT Error Codes

ATT errors appear in Error Response (0x01) PDUs. Beyond the GATT discovery context (where Attribute Not Found is normal), these errors indicate real problems:
Code | Error | Diagnostic Meaning
0x01 | Invalid Handle | Client used a handle that does not exist
0x02 | Read Not Permitted | Characteristic does not allow reads
0x03 | Write Not Permitted | Characteristic does not allow writes
0x05 | Authentication Insufficient | Operation requires an authenticated (MITM-protected) bond. Triggers SMP pairing if not yet bonded.
0x06 | Request Not Supported | Server does not support this ATT operation
0x07 | Invalid Offset | Read/write blob offset exceeds attribute length
0x08 | Authorization Insufficient | Server requires additional authorization
0x09 | Prepare Queue Full | Too many prepared writes queued
0x0a | Attribute Not Found | No attributes in requested range. Normal termination for GATT discovery procedures.
0x0b | Attribute Not Long | Attribute cannot be read with Read Blob
0x0c | Insufficient Encryption Key Size | Encryption key is too short
0x0d | Invalid Attribute Value Length | Write value length is incorrect for this attribute
0x0e | Unlikely Error | Generic unlikely error
0x0f | Insufficient Encryption | Link is not encrypted. Triggers encryption setup.
0x10 | Unsupported Group Type | Attribute type is not a valid grouping type
0x11 | Insufficient Resources | Server out of resources
0x12 | Value Not Allowed | Value is not within permitted range
0x80-0x9f | Application Error | Application-specific error; meaning depends on the profile/service. ASCS uses these for ASE-specific errors.
0xfc | Write Request Rejected | Write rejected (CSIP, ASCS)
0xfd | CCC Descriptor Improperly Configured | CCC must be enabled before certain operations
0xfe | Procedure Already in Progress | Another procedure is already running
0xff | Out of Range | Value is outside valid range

  L2CAP Connection Response Results

L2CAP Connection Response and LE Connection Response include a result code:
Code | Result | Diagnostic Meaning
0x0000 | Connection successful | Channel established normally
0x0001 | Connection pending | Connection in progress (BR/EDR only)
0x0002 | Connection refused - PSM not supported | Remote does not have a server for this protocol
0x0003 | Connection refused - security block | Security requirements not met
0x0004 | Connection refused - no resources | Remote ran out of channel resources
0x0005 | Connection refused - invalid Source CID | Source CID is invalid or already in use
0x0006 | Connection refused - Source CID already allocated | CID collision
0x0007 | Connection refused - unacceptable parameters | LE credit-based: MTU, MPS, or credits unacceptable
0x0008 | Connection refused - invalid parameters | Parameter values are invalid
0x0009 | Connection refused - insufficient authentication | Not authenticated
0x000a | Connection refused - insufficient authorization | Not authorized
0x000b | Connection refused - insufficient encryption key size | Encryption key too short
0x000c | Connection refused - insufficient encryption | Link not encrypted

  Automating Error Detection

Find all ATT errors (excluding normal discovery termination):

    grep -n "Error Response" output.txt

Then check whether each error is Attribute Not Found (0x0a) within a discovery sequence (normal) or a different error code (problem).

Find all authentication/encryption related errors:

    grep -n "Authentication Insufficient\|Insufficient Encryption\|Insufficient Security\|security block" output.txt

These indicate the link needs pairing or encryption. Check whether SMP pairing follows.

Find all L2CAP channel rejections:

    grep -n "Connection refused" output.txt

Cross-layer error correlation:

Errors often cascade across layers. Common patterns:

1.  ATT Insufficient Encryption (0x0f) → triggers HCI LE Start Encryption → Encryption Change success → ATT operation retried

2.  ATT Authentication Insufficient (0x05) → triggers SMP Pairing Request → pairing completes → ATT operation retried

3.  SMP Pairing Failed → Disconnect Complete with reason Authentication Failure (0x05)

4.  L2CAP Connection refused - security block → triggers SMP pairing

PROTOCOL FLOWS

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:
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:
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
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)
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)
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
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
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
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
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:
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.

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:
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
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).

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:
    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:
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.

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:
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

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:
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:
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.

  Throughput Estimation

btmon's --analyze (-a) mode computes per-channel statistics including throughput. For each L2CAP channel it reports:

•   Speed: Computed as bytes * 8 / latency_sum_ms where latency_sum_ms is the sum of inter-packet deltas (not wall-clock duration). This means idle gaps are excluded, so the figure represents the active sending rate rather than application-level throughput.

•   Min/Avg/Max latency: Per-packet inter-arrival time range.

    Example output:

        Found TX L2CAP channel with CID 64
              PSM 128 (0x0080)
              Mode: LE Credit
              MTU: 672
              MPS: 490
              TX packets: 29120/29114
              TX Latency: 1-79 msec (~29 msec)
              TX size: 494-494 octets (~494 octets)
              TX speed: ~571 Kb/s

    Channel details shown in analyze mode:

•   Fixed channels (CID <= 7) display their protocol name (e.g., ATT, L2CAP Signaling (LE)).

•   PSM is shown in both decimal and hexadecimal.

•   Mode is decoded from Configure Request options (BR/EDR) or LE signaling (Basic, ERTM, LE Credit, Enhanced Credit, etc.).

•   MTU and MPS are extracted from signaling exchanges.

    Throughput caveats:

1.  The speed value uses inter-packet latency sums as the denominator, not wall-clock elapsed time. If the sender pauses (e.g., waiting for credits), the idle period is not counted, which inflates the reported speed relative to overall throughput.

2.  TX latency is measured from command submission to completion event. RX latency is the inter-arrival time between consecutive packets. These measure different things, so TX and RX speeds for the same channel are not directly comparable.

3.  For windowed throughput (min/avg/max), btsnoop-analyzer uses 1-second sampling windows over wall-clock time, which provides a more realistic view of application-level bandwidth variation.

    Automated throughput extraction from btmon analyze output:

        btmon -a trace.btsnoop 2>/dev/null | grep -E "speed:|Mode:|MTU:|MPS:|PSM"

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:
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)

  Bidirectional Streams (Source + Sink)

A device may expose multiple ASEs with different directions. In the conversational (telephony) use case, the remote device typically has at least one Sink ASE (receives audio, e.g., speaker) and one Source ASE (sends audio, e.g., microphone). Both ASEs share the same CIG and often the same CIS, using the bidirectional capability of Connected Isochronous Streams.

Direction indicators in btmon traces:

•   The Receiver Start Ready command is only sent for Source ASEs (ASEs that send audio toward the local device). The server issues this command to indicate it is ready to transmit.

•   The Receiver Stop Ready command likewise applies to Source ASEs.

•   Sink ASEs transition directly from Enabling to Streaming without Receiver Start Ready.

    Typical bidirectional setup sequence (two ASEs on one CIS):

        Config Codec  ASE ID=1 (Sink)    → Codec Configured
        Config Codec  ASE ID=3 (Source)  → Codec Configured
        Config QoS    ASE ID=1           → QoS Configured (CIG=X, CIS=Y)
        Config QoS    ASE ID=3           → QoS Configured (CIG=X, CIS=Y)
        Enable        ASE ID=1           → Enabling → Streaming (immediate)
        Enable        ASE ID=3           → Enabling
        CIS Established (Success)
        Setup ISO Data Path  Input  (Host→Controller, for Sink)
        Setup ISO Data Path  Output (Controller→Host, for Source)
        Receiver Start Ready ASE ID=3   → Streaming

    Both ASEs may reach Streaming at different times. The Sink ASE can start receiving audio as soon as CIS is established, while the Source ASE waits for the Receiver Start Ready handshake.

    Note: This is normal behavior. Seeing one Source ASE and one Sink ASE on the same connection is the standard bidirectional (conversational) configuration. It is not an error or misconfiguration. Both directions sharing a single CIS is efficient and expected.

    Multiple ASEs per direction are also valid. For example, a stereo headset may expose two Sink ASEs (left and right channels) and one Source ASE (mono microphone), each with its own GATT handle for ASE state notifications.

  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 (Controller to Host) (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 (Controller to Host) (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.

CHANNEL SOUNDING PROTOCOL FLOW

Channel Sounding (CS) enables precise distance measurement between two Bluetooth LE devices. It uses dedicated HCI commands and events to configure and execute measurement procedures that exchange tones and timing packets on multiple channels. btmon fully decodes all CS operations including step-level result data.

CS uses two roles: the Initiator sends CS packets first in each step, and the Reflector responds. Both devices must support CS (feature bits 46--48 in the LE feature set).

  Capability Exchange

Before any CS activity, both devices must learn each other's CS capabilities. The local controller's capabilities are read once, and the remote device's capabilities are fetched over the air.

Read local CS capabilities:

    < HCI Command: LE CS Read Local Supported Capabilities (0x08|0x0089) plen 0  #100 [hci0]
    > HCI Event: Command Complete (0x0e) plen 42                 #101 [hci0]
          LE CS Read Local Supported Capabilities (0x08|0x0089) ncmd 1
            Status: Success (0x00)
            Num Config Supported: 4
            Max Consecutive Procedures Supported: 255
            Num Antennas Supported: 2
            Max Antenna Paths Supported: 4
            Roles Supported: 0x03
              Initiator
              Reflector
            Modes Supported: 0x03
            RTT Capability: 0x03
            RTT AA Only N: 10
            RTT Sounding N: 10
            RTT Random Payload N: 10
            CS Sync PHYs Supported: 0x02
              LE 2M
            T_IP1 Times Supported: 0x0005
              10 us
              30 us
            T_IP2 Times Supported: 0x0005
              10 us
              30 us
            T_FCS Times Supported: 0x0009
              15 us
              50 us
            T_PM Times Supported: 0x0003
              10 us
              20 us

Key capability fields:

•   Roles Supported -- Bitmask: bit 0 = Initiator, bit 1 = Reflector. A device must support at least one role.

•   Modes Supported -- Bitmask of CS measurement modes the controller can perform (Mode 1 = RTT, Mode 2 = PBR tone, Mode 3 = both).

•   CS Sync PHYs -- Physical layers available for CS sync exchange. LE 2M is the most common.

•   Num Antennas / Max Antenna Paths -- Determines multi-antenna Phase-Based Ranging capability.

•   T_IP / T_FCS / T_PM times -- Timing parameters the controller supports for inter-step and tone durations.

    Read remote CS capabilities (over the air via LL):

        < HCI Command: LE CS Read Remote Supported Capabilities (0x08|0x008a) plen 2  #110 [hci0]
              Handle: 2048
        > HCI Event: Command Status (0x0f) plen 4                   #111 [hci0]
              LE CS Read Remote Supported Capabilities (0x08|0x008a) ncmd 1
                Status: Success (0x00)
        > HCI Event: LE Meta Event (0x3e) plen 42                   #115 [hci0]
              LE CS Read Remote Supported Capabilities Complete (0x2c)
                Status: Success (0x00)
                Handle: 2048
                Num Config Supported: 4
                Max Consecutive Procedures Supported: 128
                Num Antennas Supported: 1
                Max Antenna Paths Supported: 1
                Roles Supported: 0x03
                  Initiator
                  Reflector
                Modes Supported: 0x03
                ...

    This is an asynchronous command -- the controller sends Command Status immediately, then the completion event arrives after the LL exchange. If this fails with a non-zero status, the remote device may not support CS or the connection may have dropped.

    Cached capabilities can be written directly instead of reading over the air, using LE CS Write Cached Remote Supported Capabilities.

  Security Enable

CS security must be enabled on the connection before creating configurations. This performs a CS security start procedure over the LL to exchange nonces:

    < HCI Command: LE CS Security Enable (0x08|0x008c) plen 2   #120 [hci0]
          Handle: 2048
    > HCI Event: Command Status (0x0f) plen 4                   #121 [hci0]
          LE CS Security Enable (0x08|0x008c) ncmd 1
            Status: Success (0x00)
    > HCI Event: LE Meta Event (0x3e) plen 3                    #125 [hci0]
          LE CS Security Enable Complete (0x2e)
            Status: Success (0x00)
            Handle: 2048

Security Enable must complete successfully before configuration or procedure commands. If this fails, the link may lack encryption or the remote does not support CS security.

  Default Settings

Default settings configure which roles the local device is willing to accept and the antenna/power preferences for this connection:

    < HCI Command: LE CS Set Default Settings (0x08|0x008d) plen 5  #130 [hci0]
          Handle: 2048
          Role Enable: 0x03
            Initiator
            Reflector
          CS Sync Antenna Selection: 0x01
          Max TX Power: 20
    > HCI Event: Command Complete (0x0e) plen 5                 #131 [hci0]
          LE CS Set Default Settings (0x08|0x008d) ncmd 1
            Status: Success (0x00)
            Handle: 2048

•   Role Enable -- Bitmask of roles the device is willing to perform. Both sides typically enable both roles for flexibility.

•   CS Sync Antenna Selection -- Preferred antenna for CS sync exchange.

•   Max TX Power -- Upper bound on transmit power for CS procedures (dBm, signed).

  FAE Table Exchange

The Frequency Actuation Error (FAE) table contains per-channel calibration data that improves distance accuracy. Like capabilities, it can be read from the remote or written from a cache.

Read remote FAE table:

    < HCI Command: LE CS Read Remote FAE Table (0x08|0x008e) plen 2  #135 [hci0]
          Handle: 2048
    > HCI Event: Command Status (0x0f) plen 4                   #136 [hci0]
          LE CS Read Remote FAE Table (0x08|0x008e) ncmd 1
            Status: Success (0x00)
    > HCI Event: LE Meta Event (0x3e) plen 75                   #140 [hci0]
          LE CS Read Remote FAE Table Complete (0x2d)
            Status: Success (0x00)
            Handle: 2048

The FAE table is 72 bytes (one byte per channel). Values are signed offsets in 0.5 ppm units. A value of 0x7f means the channel is unused or not measured.

  Configuration

A CS configuration defines the measurement parameters: mode, role, channel map, and step counts. Up to 4 configurations can exist simultaneously per connection (config_id 0--3).

Create a CS configuration:

    < HCI Command: LE CS Create Config (0x08|0x0090) plen 20    #150 [hci0]
          Handle: 2048
          Config ID: 0
          Create Context: 0x00
          Main Mode Type: 0x01
          Sub Mode Type: 0xff
          Min Main Mode Steps: 2
          Max Main Mode Steps: 5
          Main Mode Repetition: 0
          Mode 0 Steps: 3
          Role: Initiator (0x00)
          RTT Type: 0x01
          CS Sync PHY: LE 2M (0x01)
          Channel Map: ffffffffff7f0000000000000000
          Channel Map Repetition: 1
          Channel Selection Type: 0x00
          Ch3c Shape: 0x00
          Ch3c Jump: 0x00
    > HCI Event: Command Status (0x0f) plen 4                   #151 [hci0]
          LE CS Create Config (0x08|0x0090) ncmd 1
            Status: Success (0x00)
    > HCI Event: LE Meta Event (0x3e) plen 30                   #155 [hci0]
          LE CS Config Complete (0x2f)
            Status: Success (0x00)
            Handle: 2048
            Config ID: 0
            Action: 0x00
            Main Mode Type: 0x01
            Sub Mode Type: 0xff
            Min Main Mode Steps: 2
            Max Main Mode Steps: 5
            Main Mode Repetition: 0
            Mode 0 Steps: 3
            Role: Initiator (0x00)
            RTT Type: 0x01
            CS Sync PHY: LE 2M (0x01)
            Channel Map: ffffffffff7f0000000000000000
            Channel Map Repetition: 1
            Channel Selection Type: 0x00
            Ch3c Shape: 0x00
            Ch3c Jump: 0x00
            T_IP1 Time: 30 us
            T_IP2 Time: 30 us
            T_FCS Time: 50 us
            T_PM Time: 10 us

Key configuration fields:

•   Main Mode Type -- The primary CS measurement mode: 0x01 = Mode 1 (RTT only), 0x02 = Mode 2 (PBR/tone only), 0x03 = Mode 3 (RTT + PBR combined).

•   Sub Mode Type -- Secondary mode interleaved with main mode. 0xff = no sub mode.

•   Mode 0 Steps -- Number of frequency calibration (sync) steps per subevent. Mode 0 is always present for frequency offset compensation.

•   Main/Min/Max Mode Steps -- Controls how many measurement steps are performed per subevent.

•   Role -- 0x00 = Initiator, 0x01 = Reflector. This is the local device's role in this configuration.

•   RTT Type -- Round-trip time measurement variant (AA only, sounding sequence, random sequence).

•   Channel Map -- 10-byte bitmask of channels available for CS. Must have at least 15 channels enabled.

•   T_IP1/T_IP2/T_FCS/T_PM -- Timing parameters selected by the controller from the intersection of both devices' capabilities. Reported in the Config Complete event.

    The Config Complete event confirms the negotiated parameters. The controller may adjust timing values based on both devices' capabilities.

    Remove a CS configuration:

        < HCI Command: LE CS Remove Config (0x08|0x0091) plen 3     #160 [hci0]
              Handle: 2048
              Config ID: 0
        > HCI Event: Command Status (0x0f) plen 4                   #161 [hci0]
              LE CS Remove Config (0x08|0x0091) ncmd 1
                Status: Success (0x00)

  Procedure Parameters

Before enabling a procedure, its scheduling and antenna parameters are configured:

    < HCI Command: LE CS Set Procedure Parameters (0x08|0x0093) plen 16  #170 [hci0]
          Handle: 2048
          Config ID: 0
          Max Procedure Len: 200
          Min Procedure Interval: 10
          Max Procedure Interval: 20
          Max Procedure Count: 0
          Min Subevent Len: 5000 us
          Max Subevent Len: 10000 us
          Tone Antenna Config Selection: 0x01
          PHY: LE 2M (0x02)
          TX Power Delta: 0
          Preferred Peer Antenna: 0x01
          SNR Control Initiator: 0x00
          SNR Control Reflector: 0x00
    > HCI Event: Command Complete (0x0e) plen 5                 #171 [hci0]
          LE CS Set Procedure Parameters (0x08|0x0093) ncmd 1
            Status: Success (0x00)
            Handle: 2048

•   Max Procedure Len -- Maximum duration of a single CS procedure in units of 0.625 ms.

•   Procedure Interval -- Spacing between repeated procedures (in connection events).

•   Max Procedure Count -- 0 means indefinite repetition until explicitly disabled.

•   Subevent Len -- Duration bounds for each subevent within a procedure (in microseconds, 24-bit).

•   Tone Antenna Config Selection -- Which antenna pattern to use for tone exchange.

•   SNR Control -- Signal-to-noise ratio requirements for Initiator and Reflector.

  Procedure Enable / Disable

Once configuration and parameters are set, the CS procedure is started and stopped with enable/disable commands.

Enable a CS procedure:

    < HCI Command: LE CS Procedure Enable (0x08|0x0094) plen 4  #180 [hci0]
          Handle: 2048
          Config ID: 0
          Enable: 0x01
    > HCI Event: Command Status (0x0f) plen 4                   #181 [hci0]
          LE CS Procedure Enable (0x08|0x0094) ncmd 1
            Status: Success (0x00)
    > HCI Event: LE Meta Event (0x3e) plen 20                   #185 [hci0]
          LE CS Procedure Enable Complete (0x30)
            Status: Success (0x00)
            Handle: 2048
            Config ID: 0
            State: 0x01
            Tone Antenna Config Selection: 0x01
            Selected TX Power: 12
            Subevent Len: 5000 us
            Subevents Per Event: 2
            Subevent Interval: 3750
            Event Interval: 10
            Procedure Interval: 10
            Procedure Count: 100
            Max Procedure Len: 200

The Procedure Enable Complete event confirms the actual scheduling parameters chosen by the controller. Important fields:

•   State -- 0x01 = procedure enabled, 0x00 = disabled.

•   Subevents Per Event -- How many subevents fit in each connection event.

•   Procedure Count -- Actual number of procedures that will be executed (may differ from the requested maximum).

    Disable a CS procedure:

        < HCI Command: LE CS Procedure Enable (0x08|0x0094) plen 4  #300 [hci0]
              Handle: 2048
              Config ID: 0
              Enable: 0x00
        > HCI Event: Command Status (0x0f) plen 4                   #301 [hci0]
              LE CS Procedure Enable (0x08|0x0094) ncmd 1
                Status: Success (0x00)
        > HCI Event: LE Meta Event (0x3e) plen 20                   #305 [hci0]
              LE CS Procedure Enable Complete (0x30)
                Status: Success (0x00)
                Handle: 2048
                Config ID: 0
                State: 0x00
                ...

  Channel Classification

The host can restrict which channels CS uses by marking noisy channels as unused:

    < HCI Command: LE CS Set Channel Classification (0x08|0x0092) plen 10  #145 [hci0]
          Channel Map: ffffffffff7f0000000000
    > HCI Event: Command Complete (0x0e) plen 1                 #146 [hci0]
          LE CS Set Channel Classification (0x08|0x0092) ncmd 1
            Status: Success (0x00)

The channel map is a 10-byte (80-bit) bitmask. Bit N = 1 means channel N is available for CS. At least 15 channels must remain enabled or the procedure will abort.

  Subevent Results

While a CS procedure is running, the controller reports measurement results via subevent result events. Each subevent contains multiple steps, and each step contains mode-specific measurement data.

Subevent Result:

    > HCI Event: LE Meta Event (0x3e) plen 50                   #200 [hci0]
          LE CS Subevent Result (0x31)
            Handle: 2048
            Config ID: 0
            Start ACL Conn Event Counter: 1200
            Procedure Counter: 0
            Frequency Compensation: 0x0000
            Reference Power Level: -20
            Procedure Done Status: Partial results (0x01)
            Subevent Done Status: All results complete (0x00)
            Abort Reason: 0x00
            Num Antenna Paths: 1
            Num Steps Reported: 8
            Step Data:
              Mode: 0  Channel: 10  Length: 5
                Packet Quality: 0x00
                Packet RSSI: -45
                Packet Antenna: 0
                Measured Freq Offset: 150
              Mode: 1  Channel: 20  Length: 6
                Packet Quality: 0x00
                Packet NADM: Attack is extremely unlikely (0x00)
                Packet RSSI: -42
                ToA/ToD: 1234
                Packet Antenna: 0
              Mode: 2  Channel: 30  Length: 5
                Antenna Permutation Index: 0
                  PCT[0]: I=1024, Q=-512
                  Tone Quality: High (0x00)
              ...

Result events can be split across multiple events when data is large:

Subevent Result Continue (continuation fragment):

    > HCI Event: LE Meta Event (0x3e) plen 40                   #202 [hci0]
          LE CS Subevent Result Continue (0x32)
            Handle: 2048
            Config ID: 0
            Procedure Done Status: Partial results (0x01)
            Subevent Done Status: All results complete (0x00)
            Abort Reason: 0x00
            Num Antenna Paths: 1
            Num Steps Reported: 4
            Step Data:
              ...

  CS Step Modes

Each CS subevent consists of steps executed on different channels. Each step operates in one of four modes:

Mode 0 -- Frequency Calibration (CS Sync)

Mode 0 steps are always present at the start of each subevent. They exchange a known CS sync sequence to calibrate frequency offsets between the two devices.

Fields reported:

•   Packet Quality -- 0x00 = CS Access Address matched, 0x01 = bit errors detected, 0x02 = not found.

•   Packet RSSI -- Received signal strength (signed, dBm).

•   Packet Antenna -- Antenna index used.

•   Measured Freq Offset -- Frequency offset in 0.01 ppm units (15-bit value). Only present when data length is 5.

    Mode 1 -- Round-Trip Time (RTT)

    Mode 1 measures the time-of-arrival and time-of-departure to compute round-trip delay for distance estimation.

    Fields reported:

•   Packet Quality -- Same as Mode 0.

•   Packet NADM -- Normalized Attack Detector Metric, indicates likelihood that the RTT measurement has been tampered with:

•   0x00 = attack extremely unlikely

•   0x01 = attack very unlikely

•   0x02 = attack unlikely

•   0x03 = attack possible

•   0x04 = attack likely

•   0x05 = attack very likely

•   0x06 = attack extremely likely

•   0xff = unknown

•   ToA/ToD -- Time-of-Arrival minus Time-of-Departure difference (signed 16-bit). 0x8000 = measurement not available.

•   PCT1/PCT2 -- Phase Correction Terms (I/Q, 12 bits each). Present only with certain RTT types.

    Mode 2 -- Phase-Based Ranging (PBR / Tone Exchange)

    Mode 2 exchanges tones for high-precision phase measurement. Multiple antenna paths can be measured simultaneously.

    Fields reported:

•   Antenna Permutation Index -- Identifies the antenna switching pattern used.

•   PCT (per antenna path) -- Phase Correction Term with I component (bits 0--11) and Q component (bits 12--23).

•   Tone Quality Indicator -- Low nibble:

•   0x00 = high quality

•   0x01 = medium quality

•   0x02 = low quality

•   0x03 = not available

    High nibble (tone extension slot):

•   0x00 = not a tone extension slot

•   0x01 = tone extension slot, tone not expected

•   0x02 = tone extension slot, tone expected

    Mode 3 -- Combined RTT + Tone

    Mode 3 combines Mode 1 and Mode 2 in a single step. The initial fields match Mode 1 (quality, NADM, RSSI, ToA/ToD, antenna), followed by Mode 2 tone data.

  Result Status Fields

Each subevent result event contains status fields that indicate whether the procedure and subevent completed normally.

Procedure Done Status:

•   0x00 -- All results complete for this CS procedure

•   0x01 -- Partial results, more events will follow

•   0x0f -- All subsequent procedures aborted

    Subevent Done Status:

•   0x00 -- All results complete for this subevent

•   0x01 -- Partial results, continuation event will follow

•   0x0f -- Current subevent aborted

    Abort Reason (packed byte):

    Low nibble (procedure abort reason):

•   0x00 -- No abort

•   0x01 -- Aborted by local Host or remote request

•   0x02 -- Channel map has fewer than 15 channels

•   0x03 -- Channel map update instant has passed

•   0x0f -- Unspecified reason

    High nibble (subevent abort reason):

•   0x00 -- No abort

•   0x01 -- Aborted by local Host or remote request

•   0x02 -- No CS_SYNC (Mode 0) received

•   0x03 -- Scheduling conflict or limited resources

•   0x0f -- Unspecified reason

  CS State Machine

A CS configuration transitions through these states on each device. The state is not reported explicitly in a single field -- it is inferred from the sequence of HCI commands and events:

    ┌──────────┐
    │   IDLE   │
    └────┬─────┘
         │ LE CS Read Local/Remote Supported Capabilities
         │ LE CS Security Enable Complete
         │ LE CS Set Default Settings
         ▼
    ┌──────────────────┐
    │ CAPABILITIES     │  Both devices' CS parameters are known.
    │ EXCHANGED        │  Security is established.
    └────┬─────────────┘
         │ LE CS Create Config
         │ ──► LE CS Config Complete (status=0x00)
         ▼
    ┌──────────────────┐
    │ CONFIGURED       │  Config ID N exists with negotiated params.
    │ (config_id=N)    │  Can create up to 4 configs simultaneously.
    └────┬─────────────┘
         │ LE CS Set Procedure Parameters
         ▼
    ┌──────────────────┐
    │ PARAMETERS SET   │  Scheduling and antenna params are locked.
    │ (config_id=N)    │
    └────┬─────────────┘
         │ LE CS Procedure Enable (enable=1)
         │ ──► LE CS Procedure Enable Complete (state=1)
         ▼
    ┌──────────────────┐
    │ PROCEDURE        │  Controller is actively measuring.
    │ RUNNING          │  Subevent Result events stream in.
    │ (config_id=N)    │
    └────┬─────────────┘
         │ LE CS Procedure Enable (enable=0)
         │ ──► LE CS Procedure Enable Complete (state=0)
         ▼
    ┌──────────────────┐
    │ CONFIGURED       │  Config still exists, can re-enable.
    │ (config_id=N)    │
    └────┬─────────────┘
         │ LE CS Remove Config
         ▼
    ┌──────────┐
    │   IDLE   │
    └──────────┘

Multiple configurations can coexist. Removing one config does not affect others.

  Typical CS Setup Sequence

A complete HCI-only CS distance measurement session follows this flow. The left column shows the Host ──► Controller commands, and the right column shows the resulting state:

     Host ──► Controller                            State
    ═══════════════════════════════════════════════════════════════
     LE CS Read Local Supported Capabilities        IDLE
       ◄── Command Complete (capabilities)
                                                    │
     LE CS Read Remote Supported Capabilities       │
       ◄── Command Status                           │
       ◄── LE CS Read Remote Supp. Cap. Complete    │
                                                    │
     LE CS Security Enable                          │
       ◄── Command Status                           │
       ◄── LE CS Security Enable Complete           │
                                                    │
     LE CS Set Default Settings                     │
       ◄── Command Complete                         ▼
                                                    CAPABILITIES EXCHANGED
     LE CS Read Remote FAE Table        (optional)  │
       ◄── LE CS Read Remote FAE Complete           │
                                                    │
     LE CS Set Channel Classification   (optional)  │
       ◄── Command Complete                         │
                                                    │
     LE CS Create Config (config_id=0)              │
       ◄── Command Status                           │
       ◄── LE CS Config Complete                    ▼
                                                    CONFIGURED (id=0)
     LE CS Set Procedure Parameters (config_id=0)   │
       ◄── Command Complete                         ▼
                                                    PARAMETERS SET (id=0)
     LE CS Procedure Enable (id=0, enable=1)        │
       ◄── Command Status                           │
       ◄── LE CS Procedure Enable Complete (state=1)▼
                                                    PROCEDURE RUNNING (id=0)
       ◄── LE CS Subevent Result        ┐           │
       ◄── LE CS Subevent Result Cont.  │(repeated) │
       ◄── LE CS Subevent Result        ┘           │
                                                    │
     LE CS Procedure Enable (id=0, enable=0)        │
       ◄── Command Status                           │
       ◄── LE CS Procedure Enable Complete (state=0)▼
                                                    CONFIGURED (id=0)
     LE CS Remove Config (id=0)         (optional)  │
       ◄── Command Status                           ▼
                                                    IDLE

Steps above the first LE CS Create Config are one-time setup per connection. The config/params/enable/disable cycle can be repeated.

  CS Test Mode

CS Test mode allows the controller to run CS procedures without a remote device, for manufacturing and validation purposes:

    < HCI Command: LE CS Test (0x08|0x0095) plen 34             #400 [hci0]
          Main Mode Type: 0x01
          Sub Mode Type: 0xff
          Main Mode Repetition: 0
          Mode 0 Steps: 3
          Role: Initiator (0x00)
          RTT Type: 0x01
          CS Sync PHY: LE 2M (0x01)
          CS Sync Antenna Selection: 0x01
          Subevent Len: 5000 us
          Subevent Interval: 0
          Max Num Subevents: 1
          Transmit Power Level: 10
          T_IP1 Time: 30 us
          T_IP2 Time: 30 us
          T_FCS Time: 50 us
          T_PM Time: 10 us
          T_SW Time: 0 us
          Tone Antenna Config Selection: 0x01
          SNR Control Initiator: 0x00
          SNR Control Reflector: 0x00
          DRBG Nonce: 0x0000
          Channel Map Repetition: 1
          Override Config: 0x0000
    > HCI Event: Command Complete (0x0e) plen 5                 #401 [hci0]
          LE CS Test (0x08|0x0095) ncmd 1
            Status: Success (0x00)

Results arrive as normal LE CS Subevent Result events. The test is terminated with:

    < HCI Command: LE CS Test End (0x08|0x0096) plen 0          #450 [hci0]
    > HCI Event: LE Meta Event (0x3e) plen 1                    #451 [hci0]
          LE CS Test End Complete (0x33)
            Status: Success (0x00)

  Common Issues

Security Enable fails
    The connection must be encrypted before CS Security Enable. Check that SMP pairing and LE Encrypt have completed. Also verify both devices advertise CS support in their LE feature set.

Config Complete with error
    The controller may reject a configuration if the requested parameters are incompatible with the intersection of both devices' capabilities. Check that main mode, PHY, and timing parameters fall within both devices' supported ranges.

Channel map too small
    CS requires at least 15 channels. If channel classification or interference eliminates too many channels, the procedure aborts with abort reason 0x02 (low nibble).

No Mode 0 sync received
    Subevent abort reason 0x02 (high nibble) means the Initiator's Mode 0 sync packet was not received by the Reflector (or vice versa). This indicates an RF issue, scheduling miss, or device out of range.

Procedure aborted by host
    Abort reason 0x01 in either nibble means the local host or remote device requested termination, typically via Procedure Enable with enable=0.

ToA/ToD not available (0x8000)
    The controller could not compute a valid time measurement for this step. Common with weak signals or when the CS Access Address was not detected (packet quality = 0x02).

RANGING SERVICE (RAS) / RANGING PROFILE (RAP)

The Ranging Service (RAS) is a GATT service that transfers CS measurement data between devices at the application layer. It complements the HCI-level CS procedure by providing a standardized way to exchange, acknowledge, and retrieve ranging results over ATT. The Ranging Profile (RAP) defines how a device discovers and interacts with RAS on a remote device.

btmon decodes all RAS characteristics automatically when it sees ATT operations on the RAS UUIDs.

RAS Service UUID: 0x185B

  RAS Characteristics
Characteristic | UUID | Properties | Description
RAS Features | 0x2C14 | Read | Bitmask of supported RAS capabilities
RAS Real-time Ranging Data | 0x2C15 | Notify, Indicate | Streaming ranging results as they are produced
RAS On-demand Ranging Data | 0x2C16 | Notify, Indicate | Ranging results retrieved on request
RAS Control Point | 0x2C17 | Write Without Response, Indicate | Command interface for data retrieval and filtering
RAS Ranging Data Ready | 0x2C18 | Read, Notify, Indicate | Signals that a new ranging dataset is available
RAS Ranging Data Overwritten | 0x2C19 | Read, Notify, Indicate | Signals that a stored dataset was overwritten

All characteristics except RAS Features use Client Characteristic Configuration (CCC) descriptors to enable notifications/indications. The typical GATT attribute layout uses 18 handles total.

  RAS Features

The RAS Features characteristic is a 4-byte bitmask read by the client to discover the server's capabilities:

    > ACL Data RX: Handle 2048 flags 0x02 dlen 11               #200 [hci0]
          ATT: Read Response (0x0b) len 4
            Handle: 0x0003
              Features: 0x0000000f
                Real-time Ranging Data (0x00000001)
                Retrieve Lost Ranging Data Segments (0x00000002)
                Abort Operation (0x00000004)
                Filter Ranging Data (0x00000008)

Feature bits:

•   Bit 0 -- Real-time Ranging Data: the server can stream results via the Real-time Ranging Data characteristic as CS procedures run.

•   Bit 1 -- Retrieve Lost Ranging Data Segments: the client can request retransmission of missing data segments.

•   Bit 2 -- Abort Operation: the client can cancel an in-progress data transfer.

•   Bit 3 -- Filter Ranging Data: the client can configure which fields are included in ranging data notifications.

  RAS Ranging Data Ready

When a CS procedure completes and results are stored, the server notifies the client that data is available for retrieval:

    > ACL Data RX: Handle 2048 flags 0x02 dlen 9                #250 [hci0]
          ATT: Handle Value Notification (0x1b) len 2
            Handle: 0x000e
              Counter: 42

The counter value identifies the specific ranging dataset. The client uses this counter in subsequent Control Point commands to request or acknowledge the data.

  RAS Ranging Data Overwritten

If the server's buffer is full and older results are discarded, this characteristic notifies the client:

    > ACL Data RX: Handle 2048 flags 0x02 dlen 9                #260 [hci0]
          ATT: Handle Value Notification (0x1b) len 2
            Handle: 0x0011
              Overwritten Count: 38

This tells the client that ranging data with counter value 38 (and possibly earlier) has been overwritten and can no longer be retrieved.

  RAS Control Point

The RAS Control Point is the command interface for managing ranging data transfers. The client writes commands, and the server responds via indications on the same characteristic.

Opcodes:
Opcode | Command | Description
0x00 | Get Ranging Data | Request on-demand transfer of a specific dataset
0x01 | ACK Ranging Data | Acknowledge receipt of a dataset
0x02 | Retrieve Lost Ranging Data Segments | Re-request specific missing segments
0x03 | Abort Operation | Cancel an in-progress data transfer
0x04 | Set Filter | Configure which data fields are included

Get Ranging Data -- requests transfer of a stored dataset:

    < ACL Data TX: Handle 2048 flags 0x00 dlen 10               #270 [hci0]
          ATT: Write Command (0x52) len 3
            Handle: 0x000b
              Opcode: Get Ranging Data (0x00)
              Ranging Counter: 0x002a

After this command, the server sends the data as a sequence of notifications on the On-demand Ranging Data characteristic (0x2C16).

ACK Ranging Data -- confirms the client received a complete dataset, allowing the server to free the buffer:

    < ACL Data TX: Handle 2048 flags 0x00 dlen 10               #290 [hci0]
          ATT: Write Command (0x52) len 3
            Handle: 0x000b
              Opcode: ACK Ranging Data (0x01)
              Ranging Counter: 0x002a

Retrieve Lost Ranging Data Segments -- requests retransmission of specific segments that were missed or corrupted:

    < ACL Data TX: Handle 2048 flags 0x00 dlen 12               #295 [hci0]
          ATT: Write Command (0x52) len 5
            Handle: 0x000b
              Opcode: Retrieve Lost Ranging Data Segments (0x02)
              Ranging Counter: 0x002a
              First Segment Index: 3
              Last Segment Index: 5

A Last Segment Index of 0xFF means "all remaining segments from the first index onward."

Abort Operation -- cancels any in-progress data transfer:

    < ACL Data TX: Handle 2048 flags 0x00 dlen 8                #298 [hci0]
          ATT: Write Command (0x52) len 1
            Handle: 0x000b
              Opcode: Abort Operation (0x03)

Set Filter -- configures which fields to include in ranging data notifications:

    < ACL Data TX: Handle 2048 flags 0x00 dlen 10               #265 [hci0]
          ATT: Write Command (0x52) len 3
            Handle: 0x000b
              Opcode: Set Filter (0x04)
              Filter Configuration: 0x0001
                Mode: 1
                Filter Bit Mask: 0x0000

The filter configuration is a 16-bit value: bits [1:0] select the filter mode, and bits [15:2] provide a field bitmask.

  Ranging Data Format

Both Real-time (0x2C15) and On-demand (0x2C16) Ranging Data characteristics use the same segmented data format. Large datasets are split across multiple ATT notifications.

Segmentation Header (1 byte, present in every notification):

    > ACL Data RX: Handle 2048 flags 0x02 dlen 30               #275 [hci0]
          ATT: Handle Value Notification (0x1b) len 25
            Handle: 0x0005
              Segmentation Header: 0x01
                First Segment: True
                Last Segment: False
                Segment Index: 0
              Ranging Data Body:
                Ranging Counter: 0x02a
                Configuration ID: 0
                Selected TX Power: 12 dBm
                Antenna Paths Mask: 0x03
                  Antenna Path 1 (0x01)
                  Antenna Path 2 (0x02)
                Subevent #0:
                  Start ACL Connection Event: 1200
                  Frequency Compensation: 150 (0.01 ppm)
                  Ranging Done Status: Partial results (0x1)
                  Subevent Done Status: All results complete (0x0)
                  Ranging Abort Reason: No abort (0x0)
                  Subevent Abort Reason: No abort (0x0)
                  Reference Power Level: -20 dBm
                  Number of Steps Reported: 8
              Remaining Ranging Data Segment: ...

Segmentation header fields:

•   First Segment (bit 0) -- True for the first notification of a dataset. Only the first segment contains the Ranging Header.

•   Last Segment (bit 1) -- True for the final notification. When both bits are set, the entire dataset fits in one notification.

•   Segment Index (bits [7:2]) -- Sequential index for reassembly.

    Ranging Header (4 bytes, only in first segment):

•   Ranging Counter (bits [11:0]) -- Matches the counter from the Data Ready notification; identifies the CS procedure instance.

•   Configuration ID (bits [15:12]) -- The CS configuration ID (0--3) used for this measurement.

•   Selected TX Power (1 byte, signed) -- Actual transmit power used, in dBm.

•   Antenna Paths Mask (1 byte) -- Bitmask indicating which antenna paths have data: bit 0 = path 1, bit 1 = path 2, etc.

    Subevent Header (per subevent within the ranging data):

•   Start ACL Connection Event -- The ACL connection event counter at which this CS subevent started.

•   Frequency Compensation -- Measured frequency offset in 0.01 ppm units (signed 16-bit).

•   Ranging Done Status -- Same codes as HCI subevent results: 0x0 = complete, 0x1 = partial, 0xF = aborted.

•   Subevent Done Status -- 0x0 = complete, 0xF = aborted.

•   Ranging/Subevent Abort Reason -- Same abort reason codes as HCI: 0x0 = no abort, 0x1 = host/remote request, 0x2 = channel map / no sync, 0x3 = scheduling, 0xF = unspecified.

•   Reference Power Level -- RSSI reference in dBm (signed).

•   Number of Steps Reported -- Count of CS step results that follow.

    The step data following the subevent header uses the same mode-specific format as HCI CS Subevent Result events (Mode 0--3), described in the CS Step Modes section above.

    Continuation segments contain only the Segmentation Header followed by raw ranging data bytes that are reassembled with the previous segments.

  RAS Data Transfer State Machine

The RAS data transfer for a single ranging dataset transitions through these states:

    ┌───────────────┐
    │  IDLE         │  No active data transfer.
    └─────┬─────────┘
          │ Server: CS procedure completes (HCI level)
          │ Server: notifies Ranging Data Ready (counter=N)
          ▼
    ┌───────────────┐
    │  DATA READY   │  Dataset N is buffered on server.
    │  (counter=N)  │  Client has been notified.
    └─────┬─────────┘
          │ Client writes: Get Ranging Data (counter=N)
          │ ── OR ── (real-time mode: automatic push)
          ▼
    ┌───────────────┐
    │  TRANSFERRING  │  Server sends segmented notifications.
    │  (counter=N)   │  Segment Index increments: 0, 1, 2, ...
    └─────┬──────┬──┘
          │      │ Segment lost? Client writes:
          │      │   Retrieve Lost Segments (counter=N, first, last)
          │      │ Server re-sends missing segments.
          │      │ (loops back to TRANSFERRING)
          │      │
          │      │ Client writes: Abort Operation
          │      └──────────────────────┐
          │ Last Segment received       │
          ▼                             ▼
    ┌───────────────┐           ┌───────────────┐
    │  COMPLETE     │           │  ABORTED      │
    │  (counter=N)  │           └───────┬───────┘
    └─────┬─────────┘                   │
          │ Client writes:              │
          │   ACK Ranging Data          │
          │   (counter=N)               │
          ▼                             ▼
    ┌───────────────┐
    │  IDLE         │  Server may free buffer for counter=N.
    └───────────────┘

If the server's buffer fills before the client retrieves data, a Ranging Data Overwritten notification is sent and the dataset transitions directly from DATA READY to overwritten (lost).

  Typical RAS Data Flow

A complete RAS session for on-demand data retrieval:

    1. Client discovers RAS (UUID 0x185B) via GATT primary service discovery
    2. Client reads RAS Features (0x2C14) to learn capabilities
    3. Client enables CCC notifications on:
         - RAS Ranging Data Ready (0x2C18)
         - RAS Ranging Data Overwritten (0x2C19)
         - RAS On-demand Ranging Data (0x2C16) or
           RAS Real-time Ranging Data (0x2C15)
    4. CS procedure runs (HCI level)
    5. Server notifies Ranging Data Ready with counter=N
    6. Client writes Control Point: Get Ranging Data (counter=N)
    7. Server sends On-demand Ranging Data notifications (segmented)
    8. Client writes Control Point: ACK Ranging Data (counter=N)

For real-time streaming, step 6 is skipped -- the server pushes data on the Real-time Ranging Data characteristic (0x2C15) as each CS subevent completes, using the same segmented format.

If segments are lost (e.g., due to ATT MTU limitations or missed notifications), the client uses Retrieve Lost Ranging Data Segments to request retransmission of specific segment indices.

  Combined HCI + GATT Flow

The following chart shows the full interleaved timeline of HCI CS operations and GATT RAS operations as they appear in a btmon trace. The left column is HCI traffic (< HCI / > HCI), the center shows GATT ATT traffic (< ACL / > ACL), and the right column shows the combined state:

     HCI (CS)                        GATT (RAS)                  State
    ══════════════════════════════════════════════════════════════════════════
    --- One-time connection setup ---
     < LE CS Read Local Supp. Cap.                                IDLE
     > Command Complete                                           │
     < LE CS Read Remote Supp. Cap.                               │
     > Command Status                                             │
     > LE CS Read Remote Supp.                                    │
       Cap. Complete                                              │
     < LE CS Security Enable                                      │
     > Command Status                                             │
     > LE CS Security Enable                                      │
       Complete                                                   │
     < LE CS Set Default Settings                                 │
     > Command Complete                                           ▼
                                                                  CAPS EXCHANGED
                                     < ATT: Find By Type Value    │
                                       (RAS UUID 0x185B)          │
                                     > ATT: Find By Type Value    │
                                       Response                   │
                                     < ATT: Read Request           │
                                       (RAS Features 0x2C14)      │
                                     > ATT: Read Response          │
                                       Features: 0x0000000f       │
                                     < ATT: Write Request          │
                                       (CCC: Ready 0x2C18)        │
                                     > ATT: Write Response         │
                                     < ATT: Write Request          │
                                       (CCC: On-demand 0x2C16)    │
                                     > ATT: Write Response         ▼
                                                                  RAS READY
    --- Per-measurement cycle (repeatable) ---
     < LE CS Create Config (id=0)                                 │
     > Command Status                                             │
     > LE CS Config Complete                                      ▼
                                                                  CONFIGURED (id=0)
     < LE CS Set Proc. Params (id=0)                              │
     > Command Complete                                           ▼
                                                                  PARAMS SET (id=0)
     < LE CS Proc. Enable                                         │
       (id=0, enable=1)                                           │
     > Command Status                                             │
     > LE CS Proc. Enable                                         │
       Complete (state=1)                                         ▼
                                                                  PROCEDURE RUNNING
     > LE CS Subevent Result  ─┐                                  │
     > LE CS Subevent Result   │ (measurement data                │
       Continue                │  streams from                    │
     > LE CS Subevent Result   │  controller)                     │
     > LE CS Subevent Result  ─┘                                  │
                                                                  │
     > LE CS Subevent Result                                      │
       (Procedure Done=0x00)                                      ▼
                                                                  PROCEDURE COMPLETE
                                     > ATT: Notification           │
                                       (Data Ready 0x2C18)        │
                                       Counter: N                  ▼
                                                                  DATA READY (N)
                                     < ATT: Write Command          │
                                       (Control Point 0x2C17)     │
                                       Get Ranging Data            │
                                       Counter: N                  ▼
                                                                  TRANSFERRING (N)
                                     > ATT: Notification           │
                                       (On-demand 0x2C16)          │
                                       Seg[0]: First=T Last=F     │
                                       Ranging Header + data       │
                                     > ATT: Notification           │
                                       (On-demand 0x2C16)          │
                                       Seg[1]: First=F Last=F     │
                                     > ATT: Notification           │
                                       (On-demand 0x2C16)          │
                                       Seg[2]: First=F Last=T     ▼
                                                                  TRANSFER COMPLETE (N)
                                     < ATT: Write Command          │
                                       (Control Point 0x2C17)     │
                                       ACK Ranging Data            │
                                       Counter: N                  ▼
                                                                  IDLE (buffer freed)
    --- Cleanup (optional) ---
     < LE CS Remove Config (id=0)
     > Command Status                                             IDLE

  Real-time Streaming Flow

When the server supports real-time ranging data (Features bit 0), results are pushed immediately as CS subevents complete, without waiting for a Get Ranging Data request:

     HCI (CS)                        GATT (RAS)                  State
    ══════════════════════════════════════════════════════════════════════════
     < LE CS Proc. Enable                                         PARAMS SET
       (id=0, enable=1)
     > LE CS Proc. Enable Complete                                ▼
                                                                  PROCEDURE RUNNING
     > LE CS Subevent Result ──┐
                               │     > ATT: Notification
                               │       (Real-time 0x2C15)
                               │       Seg[0]: First=T Last=T
                               │       Ranging Header +
                               │       subevent data
     > LE CS Subevent Result ──┤
                               │     > ATT: Notification
                               │       (Real-time 0x2C15)
                               │       Seg[0]: First=T Last=F
                               │     > ATT: Notification
                               │       (Real-time 0x2C15)
                               │       Seg[1]: First=F Last=T
     > LE CS Subevent Result ──┘
                                     > ATT: Notification
                                       (Real-time 0x2C15)
                                       ...
     > LE CS Subevent Result                                      │
       (Procedure Done=0x00)                                      ▼
                                                                  PROCEDURE COMPLETE
                                     < ATT: Write Command
                                       ACK Ranging Data
                                       Counter: N                  ▼
                                                                  IDLE

In real-time mode, each HCI Subevent Result triggers one or more GATT notifications immediately. The Ranging Counter in the data header increments with each procedure. If a notification segment is lost, the client can use Retrieve Lost Segments after the procedure completes (if Features bit 1 is set).

  Lost Segment Recovery Flow

When segments are missed during transfer, the client requests retransmission:

     GATT (RAS)                                      State
    ══════════════════════════════════════════════════════════════
     > ATT: Notification (On-demand 0x2C16)           TRANSFERRING
       Seg[0]: First=T Last=F  ── received
     > ATT: Notification (On-demand 0x2C16)
       Seg[1]: First=F Last=F  ── received
                                                      │
       Seg[2] ── LOST (not received)                  │
                                                      │
     > ATT: Notification (On-demand 0x2C16)           │
       Seg[3]: First=F Last=T  ── received            │
                                                      │
     (Client detects gap: Seg[2] missing)             ▼
                                                      INCOMPLETE
     < ATT: Write Command (Control Point 0x2C17)
       Retrieve Lost Ranging Data Segments
       Counter: N
       First Segment Index: 2
       Last Segment Index: 2                          ▼
                                                      RECOVERING
     > ATT: Notification (On-demand 0x2C16)
       Seg[2]: First=F Last=F  ── re-sent             ▼
                                                      TRANSFER COMPLETE
     < ATT: Write Command (Control Point 0x2C17)
       ACK Ranging Data
       Counter: N                                     ▼
                                                      IDLE

  RAS Common Issues

Features read returns 0x00000000
    The server does not support any optional RAS features. Only basic on-demand data retrieval via Control Point is available.

Ranging Data Ready not received
    Check that CCC notifications are enabled on handle 0x2C18. Also verify the CS procedure actually completed -- if the procedure was aborted, no Data Ready notification is sent.

Segmentation reassembly errors
    Verify that Segment Index values are sequential and that the First Segment flag is set on the initial notification. A missing segment triggers the Retrieve Lost Segments mechanism if the server supports it (Features bit 1).

Data Overwritten before retrieval
    The server has limited buffer space. If the client does not retrieve and ACK data promptly, older datasets are overwritten. The Data Overwritten notification indicates the counter value of the lost data.

Control Point write rejected
    The connection must be encrypted. RAS Control Point requires write permission with encryption (WRITE_ENCRYPT). Verify that SMP pairing has completed.

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.

  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:
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:
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

  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):
    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):
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:
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

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:
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

MGMT PROTOCOL FLOWS

The Management Interface (MGMT) is the structured command/event protocol between userspace (typically bluetoothd) and the kernel Bluetooth subsystem. In btmon output, MGMT traffic is prefixed with @ and provides insight into adapter configuration, device discovery, pairing, and connection management at a higher level than raw HCI. This section covers common MGMT protocol flows as seen through btmon.

For MGMT output format basics (line anatomy, Open/Close, parameters, events), see the "Management Traffic" subsection in READING THE OUTPUT above.

  Initialization and Version Handshake

When bluetoothd starts, it opens a management socket and queries the kernel for protocol version and supported features. This handshake must succeed before any controller operations:

    @ MGMT Open: bluetoothd (privileged) version 1.23      {0x0001} 12:34:49.881936
    @ MGMT Command: Read Management Ver.. (0x0001) plen 0  {0x0001} 12:34:49.882003
    @ MGMT Event: Command Complete (0x0001) plen 6         {0x0001} 12:34:49.882010
          Read Management Version Information (0x0001) plen 3
            Status: Success (0x00)
            Version: 1.23
    @ MGMT Command: Read Management Sup.. (0x0002) plen 0  {0x0001} 12:34:49.882050
    @ MGMT Event: Command Complete (0x0001) plen 58        {0x0001} 12:34:49.882055
          Read Supported Commands (0x0002) plen 55
            Status: Success (0x00)
            Num of commands: 120
            Num of events: 38

After the version check, bluetoothd reads the controller list and queries each controller's information:

    @ MGMT Command: Read Controller Index List (0x0003) plen 0  {0x0001} 12:34:49.882100
    @ MGMT Event: Command Complete (0x0001) plen 7              {0x0001} 12:34:49.882105
          Read Controller Index List (0x0003) plen 4
            Status: Success (0x00)
            Num controllers: 1
            Controller: hci0
    @ MGMT Command: Read Controller Inf.. (0x0004) plen 0  {0x0001} [hci0] 12:34:49.882200
    @ MGMT Event: Command Complete (0x0001) plen 283       {0x0001} [hci0] 12:34:49.882210
          Read Controller Information (0x0004) plen 280
            Status: Success (0x00)
            Address: 00:11:22:33:44:55
            Bluetooth version: 5.4
            Manufacturer: Intel (2)
            Supported settings: 0x003effff
            Current settings: 0x00000080

Key things to check in the initialization flow:

•   MGMT Open -- Confirms bluetoothd connected. If missing, the daemon did not start or crashed before reaching MGMT setup.

•   Version mismatch -- If bluetoothd expects a newer MGMT version than the kernel provides, some features may be unavailable.

•   Num controllers: 0 -- No Bluetooth hardware detected. Check dmesg for driver issues.

•   Current settings -- The bitmask shows what is currently enabled on the controller (Powered, LE, BR/EDR, SSP, etc.).

  Adapter Configuration

After reading controller info, bluetoothd configures the adapter with a series of MGMT commands before powering it on. The exact sequence depends on main.conf settings and adapter capabilities.

Loading stored keys:

    @ MGMT Command: Load Link Keys (0x0012) plen 3  {0x0001} [hci0] 12:34:50.001200
          Debug keys: Disabled (0x00)
          Key count: 0
    @ MGMT Event: Command Complete (0x0001) plen 4   {0x0001} [hci0] 12:34:50.001220
          Load Link Keys (0x0012) plen 1
            Status: Success (0x00)
    @ MGMT Command: Load Long Term Keys (0x0013) plen 2  {0x0001} [hci0] 12:34:50.001300
          Key count: 0
    @ MGMT Event: Command Complete (0x0001) plen 4        {0x0001} [hci0] 12:34:50.001315
          Load Long Term Keys (0x0013) plen 1
            Status: Success (0x00)
    @ MGMT Command: Load Identity Resolving Keys (0x0030) plen 2  {0x0001} [hci0] 12:34:50.001400
          Key count: 0
    @ MGMT Event: Command Complete (0x0001) plen 4                {0x0001} [hci0] 12:34:50.001415
          Load Identity Resolving Keys (0x0030) plen 1
            Status: Success (0x00)

When bonded devices exist, the Key count will be non-zero and btmon will list each key entry. A large number of keys can indicate many paired devices; this is normal.

Setting adapter properties:

    @ MGMT Command: Set Secure Connections (0x002d) plen 1  {0x0001} [hci0] 12:34:50.002100
          Secure connections: Enabled (0x01)
    @ MGMT Event: Command Complete (0x0001) plen 7          {0x0001} [hci0] 12:34:50.002120
          Set Secure Connections (0x002d) plen 4
            Status: Success (0x00)
            Current settings: 0x004e0a81
    @ MGMT Command: Set Bondable (0x0009) plen 1            {0x0001} [hci0] 12:34:50.002200
          Bondable: Enabled (0x01)
    @ MGMT Event: Command Complete (0x0001) plen 7          {0x0001} [hci0] 12:34:50.002220
          Set Bondable (0x0009) plen 4
            Status: Success (0x00)
            Current settings: 0x004e0a91

Powering on:

    @ MGMT Command: Set Powered (0x0005) plen 1     {0x0001} [hci0] 12:35:04.033564
          Powered: Enabled (0x01)
    @ MGMT Event: Command Complete (0x0001) plen 7   {0x0001} [hci0] 12:35:04.114789
          Set Powered (0x0005) plen 4
            Status: Success (0x00)
            Current settings: 0x004e0ac1

Between the Set Powered command and its response, btmon will show the HCI commands the kernel sends to initialize the radio (see HCI INITIALIZATION SEQUENCE).

  Discovery

Device discovery is initiated through MGMT rather than raw HCI commands. bluetoothd (or btmgmt) sends a Start Discovery command specifying which transport types to scan.

Starting discovery:

    @ MGMT Command: Start Discovery (0x0023) plen 1  {0x0001} [hci0] 12:36:00.100200
          Address type: 0x07
            BR/EDR
            LE Public
            LE Random
    @ MGMT Event: Command Complete (0x0001) plen 5   {0x0001} [hci0] 12:36:00.100500
          Start Discovery (0x0023) plen 2
            Status: Success (0x00)
            Address type: 0x07

After this, btmon shows the HCI-level scan commands the kernel issues (LE Set Scan Parameters, LE Set Scan Enable, and/or Inquiry for BR/EDR). Discovered devices appear as MGMT events:

    @ MGMT Event: Device Found (0x0012) plen 38      {0x0001} [hci0] 12:36:00.250003
          LE Address: AA:BB:CC:DD:EE:FF (Random)
          RSSI: -62
          Flags: 0x0000
          EIR Data:
            Name (complete): My Device
            TX power: 0

Service discovery uses a filtered variant:

    @ MGMT Command: Start Service Discovery (0x003a) plen 19  {0x0001} [hci0] 12:36:10.100200
          Address type: 0x06
            LE Public
            LE Random
          RSSI threshold: -127
          UUIDs: 1
            UUID: Heart Rate (0x180d)
    @ MGMT Event: Command Complete (0x0001) plen 5            {0x0001} [hci0] 12:36:10.100500
          Start Service Discovery (0x003a) plen 2
            Status: Success (0x00)

Stopping discovery:

    @ MGMT Command: Stop Discovery (0x0024) plen 1   {0x0001} [hci0] 12:36:15.200100
          Address type: 0x07
    @ MGMT Event: Command Complete (0x0001) plen 5    {0x0001} [hci0] 12:36:15.200400
          Stop Discovery (0x0024) plen 2
            Status: Success (0x00)
    @ MGMT Event: Discovering (0x0013) plen 2         {0x0001} [hci0] 12:36:15.200500
          Address type: 0x07
          Discovery: Disabled (0x00)

Discovery problems to look for:

•   Status: Busy (0x0a) on Start Discovery -- Another discovery session is already active.

•   Status: Not Powered (0x0f) -- The adapter is not powered on.

•   Status: RFKilled (0x12) -- The radio is blocked by rfkill.

•   No Device Found events -- The remote device may not be advertising, or address type filtering may be wrong.

  Pairing and Bonding via MGMT

MGMT provides a high-level pairing interface. The host sends a Pair Device command; the kernel coordinates SMP or SSP as appropriate and reports the result.

Initiating pairing:

    @ MGMT Command: Pair Device (0x0019) plen 8      {0x0001} [hci0] 12:37:00.500200
          LE Address: AA:BB:CC:DD:EE:FF (Random)
          Capability: KeyboardDisplay (0x04)

After this command, btmon shows the underlying SMP or SSP exchange (see SMP PAIRING FLOW and HCI INITIALIZATION SEQUENCE for details). User interaction events may appear:

    @ MGMT Event: User Confirmation Request (0x000f) plen 12  {0x0001} [hci0] 12:37:01.200100
          LE Address: AA:BB:CC:DD:EE:FF (Random)
          Value: 123456
    @ MGMT Command: User Confirmation Reply (0x001e) plen 6   {0x0001} [hci0] 12:37:03.800200
          LE Address: AA:BB:CC:DD:EE:FF (Random)
    @ MGMT Event: Command Complete (0x0001) plen 10            {0x0001} [hci0] 12:37:03.800350
          User Confirmation Reply (0x001e) plen 7
            Status: Success (0x00)

Or for passkey entry:

    @ MGMT Event: User Passkey Request (0x0010) plen 6        {0x0001} [hci0] 12:37:01.200100
          LE Address: AA:BB:CC:DD:EE:FF (Random)
    @ MGMT Command: User Passkey Reply (0x0020) plen 10       {0x0001} [hci0] 12:37:05.100200
          LE Address: AA:BB:CC:DD:EE:FF (Random)
          Passkey: 123456

Pairing success:

    @ MGMT Event: New Long Term Key (0x000a) plen 37   {0x0001} [hci0] 12:37:06.100200
          Store hint: Yes (0x01)
          LE Address: AA:BB:CC:DD:EE:FF (Random)
          Key type: Authenticated P-256 (0x03)
          Central: 0x00
          Encryption size: 16
    @ MGMT Event: New Identity Resolving Key (0x0018) plen 30  {0x0001} [hci0] 12:37:06.100300
          Store hint: Yes (0x01)
          Random address: AA:BB:CC:DD:EE:FF
          LE Address: 11:22:33:44:55:66 (Public)
          Key: 00112233445566778899aabbccddeeff
    @ MGMT Event: Command Complete (0x0001) plen 10   {0x0001} [hci0] 12:37:06.100500
          Pair Device (0x0019) plen 7
            Status: Success (0x00)
            LE Address: AA:BB:CC:DD:EE:FF (Random)

Key events to check after pairing:

•   New Long Term Key with Store hint: Yes -- The kernel is telling userspace to persist this key for future reconnections.

•   New Identity Resolving Key -- Reveals the device's real address behind an RPA. This is essential for address resolution on reconnect.

•   Key type -- Authenticated P-256 indicates Secure Connections with MITM protection. Unauthenticated P-256 means Just Works SC. Authenticated (no P-256) means Legacy with MITM.

    Pairing failure:

        @ MGMT Event: Command Complete (0x0001) plen 10   {0x0001} [hci0] 12:37:06.100500
              Pair Device (0x0019) plen 7
                Status: Authentication Failed (0x05)
                LE Address: AA:BB:CC:DD:EE:FF (Random)

    MGMT pairing error codes:
    Code | Status | Diagnostic Meaning
    0x03 | Failed | Generic failure; check SMP or HCI errors preceding this
    0x04 | Connect Failed | Could not establish connection before pairing
    0x05 | Authentication Failed | SMP or SSP authentication did not succeed; check SMP Pairing Failed reason or HCI Authentication Failure event
    0x08 | Timeout | Pairing timed out; remote device may have gone out of range
    0x0b | Rejected | Remote device rejected the pairing request
    0x0d | Invalid Parameters | Bad address type or capability value in the Pair Device command

  Device Connection and Disconnection

MGMT reports connection lifecycle events that complement the HCI-level events shown elsewhere in the trace.

Device connected:

    @ MGMT Event: Device Connected (0x000b) plen 13   {0x0001} [hci0] 12:36:18.974319
          LE Address: AA:BB:CC:DD:EE:FF (Random)
          Flags: 0x0000
          EIR Data Length: 0

This event follows the HCI LE (Enhanced) Connection Complete event. It tells userspace that a new connection is ready.

Device disconnected:

    @ MGMT Event: Device Disconnected (0x000c) plen 8  {0x0001} [hci0] 12:38:20.500200
          LE Address: AA:BB:CC:DD:EE:FF (Random)
          Reason: Connection timeout (0x01)

Disconnect reasons reported by MGMT:
Code | Reason | Diagnostic Meaning
0x00 | Unspecified | No reason provided; typically a local disconnect
0x01 | Connection timeout | Link supervision timeout expired; device may be out of range
0x02 | Connection terminated by local host | Local side initiated the disconnection
0x03 | Connection terminated by remote host | Remote device initiated the disconnection

Unpair Device removes stored keys and optionally disconnects:

    @ MGMT Command: Unpair Device (0x001a) plen 7     {0x0001} [hci0] 12:39:00.100200
          LE Address: AA:BB:CC:DD:EE:FF (Random)
          Disconnect: Enabled (0x01)
    @ MGMT Event: Command Complete (0x0001) plen 10    {0x0001} [hci0] 12:39:00.100500
          Unpair Device (0x001a) plen 7
            Status: Success (0x00)

  Advertising via MGMT

Modern BlueZ configures advertising through MGMT commands rather than sending HCI LE advertising commands directly. This provides a multi-client advertising infrastructure.

Adding an advertisement:

    @ MGMT Command: Add Advertising (0x003e) plen 22   {0x0001} [hci0] 12:40:00.100200
          Instance: 1
          Flags: 0x0006
            The connectable flag will be managed
            The limited discoverable flag will be managed
          Duration: 0
          Timeout: 0
          Advertising data length: 6
          Scan response length: 0
    @ MGMT Event: Command Complete (0x0001) plen 5      {0x0001} [hci0] 12:40:00.100500
          Add Advertising (0x003e) plen 2
            Status: Success (0x00)
            Instance: 1

Removing an advertisement:

    @ MGMT Command: Remove Advertising (0x003f) plen 1  {0x0001} [hci0] 12:41:00.100200
          Instance: 1
    @ MGMT Event: Command Complete (0x0001) plen 5       {0x0001} [hci0] 12:41:00.100500
          Remove Advertising (0x003f) plen 2
            Status: Success (0x00)
            Instance: 1

For the HCI-level advertising commands that result from these MGMT operations, see ADVERTISING AND SCANNING.

  Error Diagnosis

MGMT Command Status and Command Complete events carry error codes that are distinct from HCI error codes. When diagnosing failures, check both layers.

MGMT error in Command Complete:

    @ MGMT Event: Command Complete (0x0001) plen 4    {0x0001} [hci0] 12:42:00.100200
          Set Powered (0x0005) plen 1
            Status: RFKilled (0x12)

MGMT Command Status (asynchronous command accepted or rejected):

    @ MGMT Event: Command Status (0x0002) plen 3     {0x0001} [hci0] 12:42:01.100200
          Start Discovery (0x0023) plen 0
            Status: Busy (0x0a)

MGMT error codes:
Code | Status | Diagnostic Meaning
0x00 | Success | Command completed successfully
0x01 | Unknown Command | Kernel does not recognize the command; MGMT version may be too old
0x02 | Not Connected | Operation requires an active connection that does not exist
0x03 | Failed | Generic failure; check HCI events for root cause
0x04 | Connect Failed | Connection attempt failed at HCI level
0x05 | Authentication Failed | Pairing or authentication procedure failed
0x06 | Not Paired | Operation requires an existing bond; device not paired
0x07 | No Resources | Kernel ran out of resources (memory, handles, etc.)
0x08 | Timeout | Operation timed out
0x09 | Already Connected | Connection already exists to target device
0x0a | Busy | Another operation is in progress (e.g., discovery running)
0x0b | Rejected | Operation rejected by remote device or policy
0x0c | Not Supported | Feature not supported by this controller or kernel version
0x0d | Invalid Parameters | Bad parameters in the command
0x0e | Disconnected | Connection was lost during the operation
0x0f | Not Powered | Controller is not powered on; call Set Powered first
0x10 | Cancelled | Operation was cancelled by the user or another command
0x11 | Invalid Index | Controller index does not exist
0x12 | RFKilled | Radio is disabled by rfkill; unblock with rfkill unblock bluetooth
0x13 | Already Paired | Device is already paired; unpair first if re-pairing is needed
0x14 | Permission Denied | Process lacks required privileges (CAP_NET_ADMIN)

Correlating MGMT and HCI errors: When MGMT reports Failed (0x03) or Authentication Failed (0x05), look at the HCI events immediately preceding the MGMT response. The HCI-level error (e.g., Authentication Failure (0x05), Connection Timeout (0x08)) provides the specific hardware-level cause.

  Automating MGMT Analysis

List all MGMT commands and events:

    grep -n "@ MGMT" output.txt

Find MGMT errors (non-zero status):

    grep -n "@ MGMT" output.txt | grep -v "Status: Success"

Track adapter power state changes:

    grep -n "Set Powered\|RFKilled\|Not Powered" output.txt

Find all discovery activity:

    grep -n "Start Discovery\|Stop Discovery\|Device Found\|Discovering" output.txt

Find pairing activity via MGMT:

    grep -n "Pair Device\|User Confirmation\|User Passkey\|New Long Term Key\|New Identity Resolving Key\|Authentication Failed" output.txt

Find connection lifecycle events:

    grep -n "Device Connected\|Device Disconnected\|Unpair Device" output.txt

Identify which MGMT clients are active:

    grep -n "@ MGMT Open\|@ MGMT Close" output.txt

Full MGMT diagnosis pattern:

1.  Find MGMT Open -- confirm bluetoothd connected and note socket ID

2.  Check Read Controller Information -- verify address, version, and current settings

3.  Find Set Powered -- confirm the adapter was powered on successfully

4.  Search for non-Success status codes -- these indicate failures

5.  For pairing issues, find Pair Device and trace forward to its Command Complete response

6.  For connection issues, find Device Connected/Device Disconnected and check the disconnect reason

EXAMPLES

  Capture the traces from hci0 to hcidump.log file

    $ btmon -i hci0 -w hcidump.log

  Open the trace file

    $ btmon -r hcidump.log

  Open the trace file with wall-clock timestamps

    $ btmon -t -r hcidump.log

  Open the trace file with full date and time

    $ btmon -T -r hcidump.log

AUTOMATED TRACE ANALYSIS

This section provides guidance for analyzing btmon traces programmatically or with AI assistance. Each topic references the detailed protocol section earlier in this document.

  Recommended Workflow

1.  Get an overview: Start with btmon -a <file> to see packet counts, connection handles, device addresses, and traffic volumes.

2.  Decode with timestamps: Use btmon -t -r <file> > output.txt to produce a text file with wall-clock timestamps for analysis.

3.  Identify connections: Search for connection establishment events to build a handle-to-address mapping:

        grep -n "Connection Complete\|Enhanced Connection Complete\|CIS Established" output.txt

4.  Track disconnections: Search for disconnect events and their reasons:

        grep -n "Disconnect Complete" output.txt

    Then examine the lines following each match for the Reason: field. See HCI ERROR AND DISCONNECT REASON CODES for interpretation.

5.  Check pairing/security: Search for SMP activity (see SMP PAIRING FLOW):

        grep -n "Pairing Request\|Pairing Response\|Pairing Failed\|Encryption Change" output.txt

6.  Identify LE Audio: Search for ASCS and CIS activity (see LE AUDIO PROTOCOL FLOW):

        grep -n "ASE Control Point\|CIG Parameters\|Create Connected Isochronous\|CIS Established\|Setup ISO Data Path" output.txt

7.  Check for errors: Search across all protocol layers (see PROTOCOL ERROR CODES):

        # HCI-level errors
        grep -n "Status:" output.txt | grep -v "Success"
        # ATT-level errors
        grep -n "Error Response" output.txt
        # SMP failures
        grep -n "Pairing Failed" output.txt
        # L2CAP rejections
        grep -n "Connection refused" output.txt

8.  Extract GATT discovery: Filter the GATT service/characteristic discovery traffic (see RECONSTRUCTING A GATT DATABASE FROM SNOOP TRACES):

        # Find all service discovery responses
        grep -n "Read By Group Type Response\|Attribute group list\|Handle range.*UUID" output.txt
        # Find all characteristic discovery responses
        grep -n "Read By Type Response\|Properties:\|Value Handle:\|Value UUID:" output.txt
        # Find all descriptor discovery responses
        grep -n "Find Information Response\|Format:\|Handle:.*UUID:" output.txt
        # Find targeted service searches
        grep -n "Find By Type Value" output.txt

9.  Check L2CAP channels: Identify protocol usage and channel issues (see L2CAP CHANNEL TRACKING):

        grep -n "PSM:\|Connection Request\|Connection Response\|Parameter Update" output.txt

10. Check advertising: See what devices are visible and what they advertise (see ADVERTISING AND SCANNING):

        grep -n "Advertising Report\|Name (complete):\|Appearance:" output.txt

  Key Patterns for Connection Lifecycle

A complete connection lifecycle for an LE ACL connection follows this pattern in the trace:

1.  LE Enhanced Connection Complete -- connection established, note the Handle and Peer address

2.  LE Connection Update Complete -- connection parameters changed (may occur zero or more times)

3.  Encryption Change -- link encrypted (may show encryption algorithm). See SMP PAIRING FLOW for the SMP exchange that precedes this.

4.  ACL Data with ATT/SMP/L2CAP -- service discovery and data exchange. See RECONSTRUCTING A GATT DATABASE FROM SNOOP TRACES for GATT, L2CAP CHANNEL TRACKING for channel setup, and PROTOCOL ERROR CODES for error interpretation.

5.  Disconnect Complete -- connection ended, check Reason field. See HCI ERROR AND DISCONNECT REASON CODES for reason codes.

    For LE Audio connections, additional steps appear between 3 and 5 (see LE AUDIO PROTOCOL FLOW for full details):

•   ATT operations on PACS/ASCS characteristics (codec negotiation)

•   LE Set CIG Parameters command and response

•   LE Create CIS command

•   LE CIS Established event (note the CIS handle)

•   LE Setup ISO Data Path command

•   ISO Data TX/RX (audio streaming)

•   Disconnect Complete on CIS handle (stream ended)

•   LE Remove CIG (group removed)

  Common Debugging Scenarios

Pairing failure diagnosis:

1.  Find Pairing Request -- note IO capabilities and auth requirements

2.  Find Pairing Response -- compare to determine association model

3.  If Pairing Failed appears, the reason code identifies the failure (see SMP PAIRING FLOW)

4.  If Encryption Change shows Status: Success, pairing succeeded

5.  If no SMP traffic on reconnect but Encryption Change fails, the bond was lost on one side

    Audio streaming failure diagnosis (see LE AUDIO PROTOCOL FLOW):

1.  Check PACS reads -- do both devices support compatible codecs?

2.  Check ASE Control Point Config Codec -- was it accepted?

3.  Check ASE state notifications -- did the ASE reach Streaming?

4.  Check CIS Established -- was Status Success?

5.  Check Setup ISO Data Path -- was it configured?

6.  Check for ISO Data packets -- is audio actually flowing?

    GATT operation rejected (see PROTOCOL ERROR CODES):

1.  Find Error Response -- note the error code

2.  Insufficient Encryption (0x0f) → expect LE Start Encryption to follow

3.  Authentication Insufficient (0x05) → expect SMP pairing to follow

4.  After security is established, the ATT operation should be retried

    Connection parameter negotiation failure:

1.  Find Connection Parameter Update Request (L2CAP level)

2.  Check the Response -- rejected means the central denied it

3.  Alternatively, find LE Connection Update Complete (HCI level)

4.  Check Status -- non-zero means the controller rejected the update

  Vendor-Specific Events

Vendor-specific HCI events (event code 0xFF) contain controller-manufacturer diagnostic data. btmon decodes some vendor events for known manufacturers (Intel, Broadcom, etc.) but many sub-events show as Unknown with raw hex data. These are expected and generally not actionable without vendor documentation.

Intel controllers emit extended telemetry events (subevent 0x8780) that include connection quality metrics, error counters, and firmware state. Partial decoding is available in monitor/intel.c.

RESOURCES

<http://www.bluez.org>

REPORTING BUGS

<linux-bluetooth@vger.kernel.org>

SEE ALSO

btsnoop(7)

Author
Marcel Holtmann <marcel@holtmann.org>, Tedd Ho-Jeong An <tedd.an@intel.com>

Copyright
Free use of this software is granted under the terms of the GNU Lesser General Public Licenses (LGPL).