---
name: "btsnoop"
section: "7"
platform: "linux"
package: "bluez-utils"
version: "5.87-2"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/btsnoop"
---

# btsnoop(7)

BTSnoop/Monitor protocol documentation

## 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:

- •

  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

| | | |
| --- | --- | --- |
| 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

\<http://www.bluez.org\>

## REPORTING BUGS

\<linux-bluetooth@vger.kernel.org\>

## SEE ALSO

[btmon(1)](/btmon/1.md)

## Copyright

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