Bluetooth HCI Log Viewer

Android records HCI traffic in the btsnoop format with datalink 1002 (HCI UART H4). Each record starts with the H4 packet type byte.

1. Enable Developer options: open Settings, then About phone, and tap Build number seven times. Some devices list it under Software information.
2. In Developer options, set Enable Bluetooth HCI snoop log to Enabled. Enabled Filtered keeps HCI commands and events but can remove or shorten ACL payloads, which can hide ATT values.
3. Turn Bluetooth off and on again. The setting takes effect when the Bluetooth stack restarts.
4. Reproduce the problem.
5. Collect a bug report with adb bugreport bugreport.zip. The archive contains the log directory FS/data/misc/bluetooth/logs/. Open btsnoop_hci.log from it. Filtered mode adds a .filtered suffix to the name.
6. Set the option back to Disabled when the capture is complete. The full log contains data exchanged with every device.

Android starts a new file after 65,535 packets by default and when Bluetooth restarts, and keeps the previous one as btsnoop_hci.log.last. Open both files for a long session.

On userdebug or rooted devices the file can be read directly from /data/misc/bluetooth/logs/btsnoop_hci.log with adb pull. Reference: Android Bluetooth verifying and debugging.

BlueZ ships btmon, which reads the kernel HCI monitor channel for every controller. Start it before reproducing the problem:

sudo btmon -w capture.btsnoop

Stop it with Ctrl+C. The file uses datalink 2001 (Linux monitor): the record flags carry the controller index in the upper 16 bits and a monitor opcode in the lower 16 bits, so commands, events, ACL data, controller index changes, system notes and log messages share one timeline. btmon -r capture.btsnoop prints the same file as text.

The viewer reads btsnoop version 1. The 16-byte file header holds the identification pattern btsnoop followed by a null byte, the version and the datalink type, all big-endian. Supported datalinks are 1001 (unencapsulated HCI, where the flags distinguish commands, events and data), 1002 (HCI UART H4) and 2001 (Linux monitor). Datalinks 1003 (BCSP), 1004 (three-wire UART) and 2002 (BlueZ simulator) are reported as unsupported.

Each record has a 24-byte header: original length, included length, flags, cumulative drops and a 64-bit timestamp in microseconds since midnight on January 1, 0 AD. The Unix epoch is 0x00DCDDB30F2F8000 in that scale. An included length below the original length means the record was stored truncated, as Android does in filtered mode. A file that ends inside a record is decoded up to the last complete record and the truncation is reported.

Apple PacketLogger files (.pklg) use a different record layout without a file header and are not supported. pcap, pcapng, ZIP and gzip files are identified and rejected with a specific message. Extract btsnoop_hci.log from an Android bug report before opening it.

• Time is relative to the first record. The detail panel shows the absolute UTC time when the timestamps are wall-clock values.
• Direction is relative to the host: commands and outgoing ACL data go from Host to Controller, events and incoming ACL data from Controller to Host.
• A command is answered by Command Status (the procedure started) or Command Complete (the command finished). The detail panel links the event to its command. Status 0x00 is success; any other value is an HCI error code.
• ACL rows show the connection handle and packet boundary flag. A start fragment followed by continuation fragments is reassembled into one L2CAP PDU, decoded on the row of the last fragment.
• L2CAP channel 0x0004 carries ATT, 0x0005 LE signaling such as Connection Parameter Update, and 0x0006 the Security Manager. ATT responses are linked to their request, so a Read Response shows the handle that was read.
• Number Of Completed Packets events return controller buffer credits to the host after the controller has transmitted or flushed ACL packets. A long delay before them means data is not leaving the controller.

Opcodes, events and subevents outside the curated tables are shown as raw OGF, OCF or event codes. Reference: Bluetooth Core ATT specification.

• Connection Failed to be Established (0x3E) as the reason of a Disconnection Complete that follows a successful LE Connection Complete within a few connection intervals: the central sent the connection request, but no packet arrived from the peripheral in the first six connection intervals. Check the advertising RSSI before the connection, whether the peripheral stopped advertising, and interference.
• Connection Timeout (0x08): the supervision timeout expired with no valid packet from the peer. Compare the time since the last ACL packet with the supervision timeout reported in the connection complete or connection update event, and check range, power loss on the peer and the interval and latency settings.
• Insufficient Authentication (0x05) or Insufficient Encryption (0x0F) in an ATT Error Response: the attribute requires a paired or encrypted link. Look for SMP pairing and an Encryption Change event before the request. The client is expected to pair or enable encryption and retry.
• PIN or Key Missing (0x06) in Encryption Change, or an SMP Pairing Failed PDU: the bond is missing on one side. Remove the bond on both devices and pair again.
• LMP or LL Response Timeout (0x22): the peer did not answer a link layer control procedure, such as a connection update, PHY update or encryption start.
• Connection Terminated due to MIC Failure (0x3D): a received packet failed its integrity check on an encrypted link, often after the keys on the two sides diverged.
• Remote User Terminated Connection (0x13) and Connection Terminated by Local Host (0x16) are intentional disconnects. The viewer does not count them as abnormal.

Every status, reason and ATT error code in the detail panel links to the Bluetooth Error Decoder. Reference: Bluetooth Core Controller Error Codes.