btsnoop(7) Linux System Administration btsnoop(7)

# [Name](#Name)

btsnoop - BTSnoop/Monitor protocol documentation

# [SYNOPSIS](#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](#DESCRIPTION)

## [Opcode definitions](#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](#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](#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](#Deleted_Index)

Code: 0x0001

Indicates that the controller with a specific index was removed.

## [TTY-based protocol](#TTY)

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](#Extended_header_format)

Each extension field is encoded as:

```
struct {


    uint8_t type;


    uint8_t value[length];
};
```

Defined types:

## [Extended header 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](#RESOURCES)

<http://www.bluez.org>

# [REPORTING BUGS](#REPORTING_BUGS)

<linux-bluetooth@vger.kernel.org>

# [SEE ALSO](#SEE_ALSO)

[btmon(1)](/man/os/bluez/btmon.1)

# [Copyright](#Copyright)

Free use of this software is granted under the terms of the GNU Lesser General Public Licenses (LGPL).

February 2026 BlueZ

---

Document: btsnoop(7) from bluez 5.87-r2 (Chainguard OS)
Source: https://github.com/bluez/bluez