hcitrace

hcitrace [-X] [-l] [-t] [-p] [-n ] [-w ] [-d ] [file]

-X
    Decode HCI data using text format.

-l
    Turn on link supervision.

-t
    Timestamp output.

-p
    Don't use /dev/bcm4329 for profiling. (Deprecated)

-n
    Capture only HCI events.

-w
    Write raw HCI data to .

-d
    Set debug level (default: 0). Valid values: 0-3.

[file]
    Read HCI data from instead of live capture.

The `hcitrace` command is a tool for capturing and analyzing Bluetooth Host Controller Interface (HCI) events. It provides a detailed view of the communication between the host system (e.g., your computer) and the Bluetooth controller (the hardware responsible for Bluetooth radio communication). This is invaluable for debugging Bluetooth connectivity issues, understanding Bluetooth protocol behavior, and developing Bluetooth applications. `hcitrace` captures HCI packets exchanged through various Bluetooth transports such as UART, USB, and others. The captured data can be saved to a file for offline analysis or viewed in real-time. Its output allows for a low-level inspection of Bluetooth traffic. The command offers filter options based on various Bluetooth parameters, like device address, packet type, and direction of communication. This makes it easy to focus on specific events. It's typically used in conjunction with other Bluetooth tools like `hciconfig` and `bluetoothctl` for a comprehensive understanding of the Bluetooth subsystem. The information captured includes packet headers, packet payloads, timestamps, and other relevant metadata. The command is part of the BlueZ Bluetooth stack.

Root privileges are often required to capture HCI events using `hcitrace` because it needs access to system-level Bluetooth devices. The raw HCI data format can be difficult to interpret without a strong understanding of the Bluetooth protocol. Newer versions of BlueZ might favor alternative methods of Bluetooth debugging.

The output of `hcitrace` shows HCI packets. Each packet includes details like the packet type (e.g., command, event, ACL data), the connection handle, the payload data, and timestamps. Analyzing these fields requires knowledge of the Bluetooth specification and the specific protocol being used (e.g., L2CAP, RFCOMM, SDP).
The `-X` option decodes the HCI data to a readable text format. Without this option the output will be a hex dump.

While `hcitrace` itself has limited filtering options, the captured data can be further processed using tools like `tcpdump` or `Wireshark` (after converting the `hcitrace` output to a compatible format) to filter based on specific Bluetooth addresses, protocols, or data patterns. These tools provide more powerful filtering and analysis capabilities.

The `hcitrace` command has been a part of the BlueZ Bluetooth stack for many years. It was initially developed to provide a low-level debugging tool for Bluetooth developers and system administrators. Over time, it has remained a core component for analyzing Bluetooth communication, although newer debugging facilities have also been introduced. Its usage has adapted to the evolving Bluetooth landscape, with adaptations for various Bluetooth versions and hardware platforms.

hciconfig(8), bluetoothctl(1)