BTSNOOP(7)

📦
version 5.87+2.git8750129efca8 · 5 versions
, in centos-stream 9

💖 btsnoop(7) — BTSnoop/Monitor protocol documentation 💖

okay so this is btsnoop(7), straight out of the Linux System Administration section of the manual — and bestie, it's literally the blueprint for how HCI/PHY traffic gets recorded and transported. no cap. ✨

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

like, if you've ever wondered how btmon and the BlueZ btsnoop girlies do their thing? it's this. 🫶

🌸 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

  • BTSNOOP_OPCODE_NEW_INDEX — code 0 (dec) / 0x0000 (hex) — New controller index (parameters: type, bus, bdaddr, name)
  • BTSNOOP_OPCODE_DEL_INDEX — code 1 (dec) / 0x0001 (hex) — Deleted controller index
  • BTSNOOP_OPCODE_COMMAND_PKT — code 2 (dec) / 0x0002 (hex) — HCI Command packet
  • BTSNOOP_OPCODE_EVENT_PKT — code 3 (dec) / 0x0003 (hex) — HCI Event packet
  • BTSNOOP_OPCODE_ACL_TX_PKT — code 4 (dec) / 0x0004 (hex) — Outgoing ACL packet
  • BTSNOOP_OPCODE_ACL_RX_PKT — code 5 (dec) / 0x0005 (hex) — Incoming ACL packet
  • BTSNOOP_OPCODE_SCO_TX_PKT — code 6 (dec) / 0x0006 (hex) — Outgoing SCO packet
  • BTSNOOP_OPCODE_SCO_RX_PKT — code 7 (dec) / 0x0007 (hex) — Incoming SCO packet
  • BTSNOOP_OPCODE_OPEN_INDEX — code 8 (dec) / 0x0008 (hex) — HCI transport for the specified controller opened
  • BTSNOOP_OPCODE_CLOSE_INDEX — code 9 (dec) / 0x0009 (hex) — HCI transport for the specified controller closed
  • BTSNOOP_OPCODE_INDEX_INFO — code 10 (dec) / 0x000a (hex) — Index information (parameters: bdaddr, manufacturer)
  • BTSNOOP_OPCODE_VENDOR_DIAG — code 11 (dec) / 0x000b (hex) — Vendor diagnostic information
  • BTSNOOP_OPCODE_SYSTEM_NOTE — code 12 (dec) / 0x000c (hex) — System note
  • BTSNOOP_OPCODE_USER_LOGGING — code 13 (dec) / 0x000d (hex) — User logging (parameters: priority, ident_len, ident)
  • BTSNOOP_OPCODE_CTRL_OPEN — code 14 (dec) / 0x000e (hex) — Control channel opened
  • BTSNOOP_OPCODE_CTRL_CLOSE — code 15 (dec) / 0x000f (hex) — Control channel closed
  • BTSNOOP_OPCODE_CTRL_COMMAND — code 16 (dec) / 0x0010 (hex) — Control command packet
  • BTSNOOP_OPCODE_CTRL_EVENT — code 17 (dec) / 0x0011 (hex) — Control event packet
  • BTSNOOP_OPCODE_ISO_TX_PKT — code 18 (dec) / 0x0012 (hex) — Outgoing ISO packet
  • BTSNOOP_OPCODE_ISO_RX_PKT — code 19 (dec) / 0x0013 (hex) — 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.

lowkey important: that implicit 0 thing is transport-dependent, so don't go assuming it everywhere 👀

🍓 Deleted Index

Code: 0x0001

Indicates that the controller with a specific index was removed.

bye bestie 👋 that index is gone.

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

like, that math is literally doing the most but it's giving exact byte boundaries, periodt. 💅

🌈 Extended header format

Each extension field is encoded as:

struct {
    uint8_t type;
    uint8_t value[length];
};

Defined types:

…and the actual list of defined types is literally in part 2, bestie — stay tuned 🫶✨

✨ Extended header types ✨

Okay so these are the little extension fields you can slap onto the end of a packet record, and each one has a type number and a length. Here's the whole lineup, bestie:

  • Type 1, length 1 byte — Command drops (like, dropped HCI command packets 🫳)
  • Type 2, length 1 byte — Event drops (dropped HCI event packets, rip)
  • Type 3, length 1 byte — ACL TX drops
  • Type 4, length 1 byte — ACL RX drops
  • Type 5, length 1 byte — SCO TX drops
  • Type 6, length 1 byte — SCO RX drops
  • Type 7, length 1 byte — Other drops
  • Type 8, length 4 bytes — a 32-bit timestamp, measured in 1/10th ms ⏱️

The drops fields are literally just a count — the number of packets the implementation had to drop since the last reported drop count. Not cumulative, bestie, it resets each time. 💅

And here's the rule you cannot skip: extension fields must be sorted by increasing type so that unknown types can be skipped and the payload location discovered. Yes, this is load-bearing. Do not come crying to me when you write them out of order and everything falls apart 😭

🌈 RESOURCES 🌈

http://www.bluez.org

That's the spot. Go forth. ✨

🙈 REPORTING BUGS 🙈

linux-bluetooth@vger.kernel.org

Found something cursed? Email the list, don't suffer in silence, fr fr.

🦋 SEE ALSO 🦋

btmon(1)

The other main character, obvi. Go read that one too 👑

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

Like, actually free. Slay. 🎀

And that's the whole page, bestie — brought to you by BlueZ, dated February 2026, filed under BTSNOOP(7) in the manual pages. Go capture some packets, king. 💅✨

📦 where this page comes from