hcitrace

hcitrace [OPTIONS]

-h, --help
    Displays usage information and exits.

-i <hci_dev>, --device <hci_dev>
    Specifies the HCI device to trace, such as hci0. If not specified, hci0 is often used by default.

-r <file>, --read <file>
    Reads HCI data from a hcidump format file instead of capturing live traffic from a device.

-t, --timestamp
    Displays a timestamp for each captured HCI packet, indicating when it was received.

-x, --hex
    Displays the raw hexadecimal data of each HCI packet in addition to the decoded information.

-V, --version
    Displays the hcitrace version information and exits.

hcitrace is a powerful Linux command-line utility designed to capture and display Bluetooth HCI (Host Controller Interface) traffic. It acts as a sniffer for the communication between the host (e.g., Linux kernel or user applications) and the Bluetooth controller hardware.

This tool is invaluable for debugging Bluetooth connectivity issues, analyzing protocol behavior, and aiding in the development of Bluetooth applications. It provides a real-time stream of HCI commands (from host to controller) and HCI events (from controller to host), often including detailed decoding of these packets. Users can specify a particular HCI device to monitor, display timestamps for events, and optionally view the raw hexadecimal data for deep analysis. While it can operate in live capture mode, it also supports reading previously recorded data from files generated by hcidump, making it versatile for both immediate diagnostics and post-mortem analysis of Bluetooth communication failures. Its primary strength lies in providing a granular view of the Bluetooth stack's interaction with the underlying hardware, essential for understanding low-level protocol exchanges.

hcitrace requires root privileges (or equivalent capabilities) to capture live HCI traffic directly from a Bluetooth device. Without these elevated permissions, it will typically fail to open the necessary device interfaces. The output can be extremely verbose, especially on busy Bluetooth systems, potentially overwhelming the terminal with data. While hcitrace decodes many standard HCI commands and events, its ability to decode proprietary or very new Bluetooth features might be limited. Furthermore, it only shows traffic that passes through the HCI layer, meaning some kernel-level optimizations or driver-specific interactions might not be visible.

The typical output of hcitrace includes a timestamp (if -t is used), an indicator of packet direction (e.g., > for host-to-controller commands, < for controller-to-host events), the general packet type (e.g., HCI Command, HCI Event), a human-readable decoded description of the command or event, and optionally, the raw hexadecimal data (if -x is used). This comprehensive output enables detailed analysis of the Bluetooth communication flow, aiding in pinpointing protocol-level issues.

For hcitrace to capture live HCI traffic directly from a Bluetooth device, it requires root privileges. This is due to the nature of accessing raw network interfaces and packet sockets, which are typically restricted for security reasons. Attempting to run hcitrace in live capture mode without sufficient permissions will usually result in an error indicating an inability to open the device. However, when using the -r option to read from a pre-recorded hcidump file, elevated privileges are not necessary, as the data is accessed from a standard file.

hcitrace is an integral part of the BlueZ project, which serves as the official Linux Bluetooth protocol stack. BlueZ has been a cornerstone of Bluetooth support on Linux since its inception in the early 2000s. hcitrace, alongside utilities like hcidump and hcitool, were among the initial suite of tools developed to enable detailed interaction and debugging of the Bluetooth stack. While the ecosystem has evolved with newer, more user-friendly tools like btmon and bluetoothctl, hcitrace retains its niche as a reliable utility for low-level, raw HCI packet inspection. Its core functionality for tracing and displaying HCI communications has remained largely consistent, making it a valuable resource for developers and network engineers involved in deep Bluetooth analysis.

hcidump(1), btmon(1)