btsnoop(7) Linux System Administration btsnoop(7) Name btsnoop - BTSnoop/Monitor protocol documentation SYNOPSIS This document describes the BTSnoop/Monitor formats used to record and transport HCI/PHY traffic. The formats are used by tools such as btmon and the BlueZ btsnoop implementation. DESCRIPTION Opcode definitions The following opcodes are used by the BTSnoop/Monitor formats. The numeric values match the definitions in src/shared/btsnoop.h. BTSnoop opcodes +----------------------------+------------+------------+------------------+ |Name | Code (dec) | Code (hex) | Meaning | +----------------------------+------------+------------+------------------+ |BTSNOOP_OPCODE_NEW_INDEX | 0 | 0x0000 | New controller | | | | | index | | | | | (parameters: | | | | | type, bus, | | | | | bdaddr, name) | +----------------------------+------------+------------+------------------+ |BTSNOOP_OPCODE_DEL_INDEX | 1 | 0x0001 | Deleted | | | | | controller index | +----------------------------+------------+------------+------------------+ |BTSNOOP_OPCODE_COMMAND_PKT | 2 | 0x0002 | HCI Command | | | | | packet | +----------------------------+------------+------------+------------------+ |BTSNOOP_OPCODE_EVENT_PKT | 3 | 0x0003 | HCI Event packet | +----------------------------+------------+------------+------------------+ |BTSNOOP_OPCODE_ACL_TX_PKT | 4 | 0x0004 | Outgoing ACL | | | | | packet | +----------------------------+------------+------------+------------------+ |BTSNOOP_OPCODE_ACL_RX_PKT | 5 | 0x0005 | Incoming ACL | | | | | packet | +----------------------------+------------+------------+------------------+ |BTSNOOP_OPCODE_SCO_TX_PKT | 6 | 0x0006 | Outgoing SCO | | | | | packet | +----------------------------+------------+------------+------------------+ |BTSNOOP_OPCODE_SCO_RX_PKT | 7 | 0x0007 | Incoming SCO | | | | | packet | +----------------------------+------------+------------+------------------+ |BTSNOOP_OPCODE_OPEN_INDEX | 8 | 0x0008 | HCI transport | | | | | for the | | | | | specified | | | | | controller | | | | | opened | +----------------------------+------------+------------+------------------+ |BTSNOOP_OPCODE_CLOSE_INDEX | 9 | 0x0009 | HCI transport | | | | | for the | | | | | specified | | | | | controller | | | | | closed | +----------------------------+------------+------------+------------------+ |BTSNOOP_OPCODE_INDEX_INFO | 10 | 0x000a | Index | | | | | information | | | | | (parameters: | | | | | bdaddr, | | | | | manufacturer) | +----------------------------+------------+------------+------------------+ |BTSNOOP_OPCODE_VENDOR_DIAG | 11 | 0x000b | Vendor | | | | | diagnostic | | | | | information | +----------------------------+------------+------------+------------------+ |BTSNOOP_OPCODE_SYSTEM_NOTE | 12 | 0x000c | System note | +----------------------------+------------+------------+------------------+ |BTSNOOP_OPCODE_USER_LOGGING | 13 | 0x000d | User logging | | | | | (parameters: | | | | | priority, | | | | | ident_len, | | | | | ident) | +----------------------------+------------+------------+------------------+ |BTSNOOP_OPCODE_CTRL_OPEN | 14 | 0x000e | Control channel | | | | | opened | +----------------------------+------------+------------+------------------+ |BTSNOOP_OPCODE_CTRL_CLOSE | 15 | 0x000f | Control channel | | | | | closed | +----------------------------+------------+------------+------------------+ |BTSNOOP_OPCODE_CTRL_COMMAND | 16 | 0x0010 | Control command | | | | | packet | +----------------------------+------------+------------+------------------+ |BTSNOOP_OPCODE_CTRL_EVENT | 17 | 0x0011 | Control event | | | | | packet | +----------------------------+------------+------------+------------------+ |BTSNOOP_OPCODE_ISO_TX_PKT | 18 | 0x0012 | Outgoing ISO | | | | | packet | +----------------------------+------------+------------+------------------+ |BTSNOOP_OPCODE_ISO_RX_PKT | 19 | 0x0013 | Incoming ISO | | | | | packet | +----------------------------+------------+------------+------------------+ New Index Code: 0x0000 Parameters: o Type (1 octet) o Bus (1 octet) o BD_Addr (6 octets) o Name (8 octets) This opcode indicates that a new controller instance with a given index was added. With some transports (for example a single TTY device) the index is implicitly 0. Deleted Index Code: 0x0001 Indicates that the controller with a specific index was removed. TTY-based protocol The TTY protocol used by btmon with the --tty option is a little-endian packet format. Each packet uses this header: struct tty_hdr { uint16_t data_len; uint16_t opcode; uint8_t flags; uint8_t hdr_len; uint8_t ext_hdr[0]; } __attribute__ ((packed)); The payload starts at ext_hdr + hdr_len and has length data_len - 4 - hdr_len. Extended header format Each extension field is encoded as: struct { uint8_t type; uint8_t value[length]; }; Defined types: Extended header types +-----+---------+--------------------+ |Type | Length | Meaning | +-----+---------+--------------------+ |1 | 1 byte | Command drops | | | | (dropped HCI | | | | command packets) | +-----+---------+--------------------+ |2 | 1 byte | Event drops | | | | (dropped HCI event | | | | packets) | +-----+---------+--------------------+ |3 | 1 byte | ACL TX drops | +-----+---------+--------------------+ |4 | 1 byte | ACL RX drops | +-----+---------+--------------------+ |5 | 1 byte | SCO TX drops | +-----+---------+--------------------+ |6 | 1 byte | SCO RX drops | +-----+---------+--------------------+ |7 | 1 byte | Other drops | +-----+---------+--------------------+ |8 | 4 bytes | 32-bit timestamp | | | | (1/10th ms) | +-----+---------+--------------------+ The drops fields contain the number of packets the implementation had to drop since the last reported drop count. Extension fields must be sorted by increasing type so unknown types can be skipped and the payload location discovered. RESOURCES REPORTING BUGS SEE ALSO btmon(1) Copyright Free use of this software is granted under the terms of the GNU Lesser General Public Licenses (LGPL). BlueZ February 2026 btsnoop(7)