hcidump

hcidump [-i <device>] [-s <snapshot>] [-t] [-a] [-X] [-Y] [-O] [-N] [-R] [-P <file>] [-r <file>] [-w <file>] [-F <filter>] [-m <mask>] [-V] [-C] [-x] [-h]

-i <device>
    Specify the local Bluetooth device to monitor, e.g., 'hci0'.

-s <snapshot>
    Set the snapshot length for packet capture, limiting the amount of data captured per packet.

-t
    Prepend timestamps to each packet dump, showing when it was captured.

-a
    Dump all packets, including raw data. This is often the default behavior.

-X
    Dump packets in hexadecimal format.

-Y
    Dump packets in ASCII format.

-O
    Don't dump raw data, only parsed HCI events/commands/data.

-N
    Don't parse numbers in the output, displaying them as raw hex.

-R
    Reverse output order, displaying the latest packets at the end of the output.

-P <file>
    Use a specified file for input/output redirection, often in conjunction with -r or -w.

-r <file>
    Read packets from a specified PCAP file instead of capturing live traffic.

-w <file>
    Write captured packets to a specified PCAP file for later analysis.

-F <filter>
    Filter packets by type. Common filters include 'command', 'event', 'acl', 'sco', 'vendor'.

-m <mask>
    Apply a mask to the filter, typically used with numeric filters.

-V
    Display the version information of hcidump.

-C
    Only show HCI commands and events, omitting ACL (Asynchronous Connection-Less) and SCO (Synchronous Connection-Oriented) data packets.

-x
    Show raw data in hexadecimal format (similar to -X but can apply specifically to data packets when parsing is active).

-h
    Display a brief help message and exit.

hcidump is a powerful command-line utility for capturing, parsing, and displaying raw Bluetooth Host Controller Interface (HCI) packets on Linux systems. It acts as a sniffer, intercepting the communication between the Bluetooth host (typically the Linux kernel's Bluetooth stack) and the Bluetooth controller (the physical Bluetooth adapter). This tool is invaluable for developers, system administrators, and network analysts who need to debug Bluetooth connectivity issues, monitor Bluetooth traffic, or analyze the intricacies of Bluetooth protocols at a low level. It can display packets in a human-readable format, including timestamps and detailed packet dissections, and supports various output options like hexadecimal and ASCII dumps. Furthermore, hcidump can save captured data to standard PCAP files, allowing for later offline analysis with other tools like Wireshark, or read previously saved PCAP files.

Root Privileges: hcidump generally requires root privileges or appropriate capabilities to capture raw Bluetooth HCI packets directly from the device interface.
High Volume Output: With active Bluetooth traffic, the command can generate a very large volume of output, making it challenging to interpret without specific filters.
Complexity: Understanding the output requires familiarity with the Bluetooth HCI specification and general Bluetooth protocol knowledge.
Legacy Status: For live packet capture, newer BlueZ distributions often recommend using btmon(1), which offers more advanced filtering and better integration with modern Linux logging mechanisms. However, hcidump remains highly useful, especially for processing existing PCAP files.

hcidump provides powerful filtering capabilities (via -F and -m) that allow users to focus on specific types of Bluetooth traffic, such as commands, events, ACL data, or SCO data, significantly reducing noise during analysis.

A key feature is its ability to save captured packets to standard PCAP (Packet Capture) files using the -w option and to read from them with the -r option. This enables seamless integration with other network analysis tools like Wireshark, facilitating deeper graphical analysis of Bluetooth traffic.

hcidump is an integral part of the BlueZ project, the official Linux Bluetooth protocol stack. It was developed early in BlueZ's history to provide essential debugging and development capabilities for the Bluetooth stack and applications on Linux. For many years, it was the primary tool for low-level Bluetooth traffic analysis. While its role in live packet capture is increasingly being complemented or superseded by btmon(1) in contemporary BlueZ releases due to btmon's enhanced features and system integration, hcidump continues to be widely used and remains a valuable utility, particularly for its robust PCAP file handling.

hcitool(1), hciconfig(8), sdptool(1), l2ping(8), btmon(1), wireshark(1)