btsnoop - Man Page

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

NameCode (dec)Code (hex)Meaning
BTSNOOP_OPCODE_NEW_INDEX00x0000New controller index (parameters: type, bus, bdaddr, name)
BTSNOOP_OPCODE_DEL_INDEX10x0001Deleted controller index
BTSNOOP_OPCODE_COMMAND_PKT20x0002HCI Command packet
BTSNOOP_OPCODE_EVENT_PKT30x0003HCI Event packet
BTSNOOP_OPCODE_ACL_TX_PKT40x0004Outgoing ACL packet
BTSNOOP_OPCODE_ACL_RX_PKT50x0005Incoming ACL packet
BTSNOOP_OPCODE_SCO_TX_PKT60x0006Outgoing SCO packet
BTSNOOP_OPCODE_SCO_RX_PKT70x0007Incoming SCO packet
BTSNOOP_OPCODE_OPEN_INDEX80x0008HCI transport for the specified controller opened
BTSNOOP_OPCODE_CLOSE_INDEX90x0009HCI transport for the specified controller closed
BTSNOOP_OPCODE_INDEX_INFO100x000aIndex information (parameters: bdaddr, manufacturer)
BTSNOOP_OPCODE_VENDOR_DIAG110x000bVendor diagnostic information
BTSNOOP_OPCODE_SYSTEM_NOTE120x000cSystem note
BTSNOOP_OPCODE_USER_LOGGING130x000dUser logging (parameters: priority, ident_len, ident)
BTSNOOP_OPCODE_CTRL_OPEN140x000eControl channel opened
BTSNOOP_OPCODE_CTRL_CLOSE150x000fControl channel closed
BTSNOOP_OPCODE_CTRL_COMMAND160x0010Control command packet
BTSNOOP_OPCODE_CTRL_EVENT170x0011Control event packet
BTSNOOP_OPCODE_ISO_TX_PKT180x0012Outgoing ISO packet
BTSNOOP_OPCODE_ISO_RX_PKT190x0013Incoming ISO packet

New Index

Code: 0x0000

Parameters:

  • Type (1 octet)
  • Bus (1 octet)
  • BD_Addr (6 octets)
  • 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

TypeLengthMeaning
11 byteCommand drops (dropped HCI command packets)
21 byteEvent drops (dropped HCI event packets)
31 byteACL TX drops
41 byteACL RX drops
51 byteSCO TX drops
61 byteSCO RX drops
71 byteOther drops
84 bytes32-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

<http://www.bluez.org>

Reporting Bugs

<linux-bluetooth@vger.kernel.org>

See Also

btmon(1)

Referenced By

btmon(1).

February 2026 BlueZ Linux System Administration