hcitrace

hcitrace [-i ifname] [-c] [-t] [-T type] [-a] [-A] [-m size] [-f filter] [-s size] [-r] [-R] [-n] [-N] [-d] [-D] [-u] [-U] [-p pattern] [-P pattern] [-o file] [-O file] [-h]

-i, --device ifname
    Interface device name (default: hci0)

-c, --capture
    Capture mode (implies -t)

-t, --timestamp
    Print packet timestamps

-T, --type type
    Filter by HCI packet type (cmd, acl, sco, evt)

-a, --all
    Print all packet types

-A, --acl
    Print only ACL packets

-m, --mplen size
    Minimum ACL packet length filter

-f, --filter filter
    HCI socket filter expression

-s, --size size
    Snapshot size for packet capture

-r, --read
    Read captured data from file

-R, --raw
    Raw hex dump output

-n, --numeric
    Numeric opcode/output (no symbols)

-N, --no-name-resolve
    Disable BDADDR name resolution

-d, --debug
    Enable debug logging

-D, --debug-packets
    Debug packet contents

-u, --uplink
    Filter uplink (host to controller) packets

-U, --uplink-dump
    Dump uplink packets only

-p, --pattern pattern
    Hex pattern filter for packets

-P, --pattern-all pattern
    Apply pattern filter to all packet types

-o, --output file
    Output filtered packets to file

-O, --output-all file
    Output all packets to file

-h, --help
    Display help and exit

hcitrace is a diagnostic utility from the BlueZ Bluetooth stack on Linux, designed to monitor and trace Host Controller Interface (HCI) traffic between the Bluetooth kernel subsystem and the attached Bluetooth controller hardware. It captures HCI commands, events, ACL (Asynchronous Connection-Less) data packets, and SCO (Synchronous Connection-Oriented) audio packets, providing detailed insights for debugging Bluetooth connectivity issues, protocol analysis, or performance tuning.

By attaching to a specific Bluetooth interface (e.g., hci0), hcitrace dumps packet contents in human-readable or raw hex format, with optional timestamps, filters, and output redirection. This is invaluable for developers troubleshooting pairing failures, data throughput problems, or firmware interactions. It operates in real-time monitoring mode or can capture to files for offline analysis.

Key strengths include flexible filtering by packet type, length, or custom patterns, supporting both raw dumps and decoded output. However, it requires appropriate privileges and kernel support via the HCI socket API. Commonly used alongside tools like btmon for comprehensive Bluetooth logging.

Requires root privileges or CAP_NET_RAW capability. Kernel must have Bluetooth HCI socket support enabled. High traffic may overwhelm output; use filters or files. Not for production use due to performance impact.

hcitrace -i hci0 -t -a
Capture all packets on hci0 with timestamps.

hcitrace -i hci0 -T acl -o trace.pcap
Save ACL packets to file.

Packets shown as: timestamp | type | direction | length | hex dump | ASCII decode (if applicable). Use -R for pure hex.

Introduced in BlueZ 5.x series (around 2012-2014) as a specialized HCI tracer, evolving from earlier hcidump tool. Maintained in BlueZ utils for Linux Bluetooth diagnostics; enhancements in BlueZ 5.50+ include better filtering and raw modes.

btmon(1), hcitool(1), hciconfig(1), bluetoothctl(1), btmgmt(1)