mcbluetooth/docs-site/src/content/docs/guides/capture.md

title	description
Protocol Capture	Capture and analyze Bluetooth HCI traffic for debugging

import { Aside } from '@astrojs/starlight/components';

mcbluetooth can capture raw Bluetooth HCI (Host Controller Interface) traffic for protocol analysis and debugging.

Overview

HCI captures record all communication between the Bluetooth stack and hardware adapter. This includes:

• Device discovery packets
• Pairing and authentication
• Connection management
• Audio streaming data
• BLE GATT operations

Starting a Capture

bt_capture_start output_file="/tmp/bluetooth.btsnoop"

Returns:

{
  "status": "started",
  "capture_id": "capture_abc123",
  "output_file": "/tmp/bluetooth.btsnoop"
}

Capture Options

# Capture from specific adapter
bt_capture_start output_file="/tmp/hci0.btsnoop" adapter="0"

# Include voice data (SCO)
bt_capture_start output_file="/tmp/calls.btsnoop" include_sco=true

# Include audio streaming (A2DP)
bt_capture_start output_file="/tmp/audio.btsnoop" include_a2dp=true

# Include LE Audio (ISO)
bt_capture_start output_file="/tmp/le_audio.btsnoop" include_iso=true

Audio captures (`include_sco`, `include_a2dp`, `include_iso`) generate large files quickly.

Stopping a Capture

bt_capture_stop capture_id="capture_abc123"

Returns:

{
  "status": "stopped",
  "output_file": "/tmp/bluetooth.btsnoop",
  "packets_captured": 1542,
  "file_size": 245760
}

Listing Active Captures

bt_capture_list_active

Analyzing Captures

Quick Parse

bt_capture_parse filepath="/tmp/bluetooth.btsnoop"

Returns packet summaries:

{
  "total_packets": 1542,
  "packet_types": {
    "HCI_CMD": 234,
    "HCI_EVENT": 456,
    "ACL_DATA": 852
  },
  "packets": [
    {
      "index": 0,
      "timestamp": "2024-01-15T10:30:00.123456",
      "type": "HCI_CMD",
      "direction": "TX",
      "summary": "Inquiry"
    }
  ]
}

Filtered Parse

# Only HCI commands
bt_capture_parse filepath="..." packet_type_filter="HCI_CMD"

# Only received packets
bt_capture_parse filepath="..." direction_filter="RX"

# Limit results
bt_capture_parse filepath="..." max_packets=100

Detailed Analysis

bt_capture_analyze filepath="/tmp/bluetooth.btsnoop"

Returns high-level statistics:

{
  "duration_seconds": 45.2,
  "total_packets": 1542,
  "protocols": {
    "L2CAP": 423,
    "RFCOMM": 156,
    "SDP": 34,
    "ATT": 289
  },
  "connections": [
    {
      "address": "AA:BB:CC:DD:EE:FF",
      "packets": 892,
      "bytes": 45678
    }
  ]
}

Raw Packet Decoding

bt_capture_read_raw filepath="/tmp/bluetooth.btsnoop" offset=0 count=50

Returns btmon-style decoded output for detailed inspection.

Common Workflows

Debug Pairing Issues

# Start capture
bt_capture_start output_file="/tmp/pairing_debug.btsnoop"

# Attempt pairing
bt_pair adapter="hci0" address="AA:BB:CC:DD:EE:FF"

# Stop and analyze
bt_capture_stop capture_id="..."
bt_capture_parse filepath="/tmp/pairing_debug.btsnoop" packet_type_filter="HCI_EVENT"

Investigate Audio Glitches

# Capture with A2DP data
bt_capture_start output_file="/tmp/audio_debug.btsnoop" include_a2dp=true

# Play audio for 30 seconds

# Stop and check for errors
bt_capture_stop capture_id="..."
bt_capture_analyze filepath="/tmp/audio_debug.btsnoop"

Monitor BLE Sensor

# Start capture
bt_capture_start output_file="/tmp/ble_sensor.btsnoop"

# Connect and interact with sensor
bt_connect adapter="hci0" address="AA:BB:CC:DD:EE:FF"
bt_ble_read adapter="hci0" address="..." char_uuid="..."

# Analyze ATT/GATT traffic
bt_capture_stop capture_id="..."
bt_capture_parse filepath="/tmp/ble_sensor.btsnoop"

File Format

Captures are saved in btsnoop format, compatible with:

Tool	Usage
Wireshark	Full GUI analysis
btmon	Command-line decode
hcidump	Legacy analysis

Open in Wireshark

wireshark /tmp/bluetooth.btsnoop

Wireshark provides:

• Protocol dissection
• Conversation tracking
• Expert analysis
• Export options

Requirements

Capture requires elevated privileges (root or `CAP_NET_RAW`).

The capture functionality uses btmon which needs access to the Bluetooth monitor socket:

# Option 1: Run as root
sudo btmon

# Option 2: Add capability (one-time setup)
sudo setcap cap_net_raw+ep /usr/bin/btmon

Troubleshooting

"Permission Denied"

# Check btmon capability
getcap /usr/bin/btmon

# Add if missing
sudo setcap cap_net_raw+ep /usr/bin/btmon

Capture File Empty

• Ensure adapter is active: bt_adapter_power adapter="hci0" on=true
• Verify Bluetooth activity is occurring
• Check btmon is running: bt_capture_list_active

Very Large Files

Audio data generates significant traffic:

Content	Approximate Size
Discovery/pairing	~10 KB/min
BLE sensors	~50 KB/min
A2DP audio	~2 MB/min
HFP calls	~500 KB/min

Use without audio flags for general debugging:

bt_capture_start output_file="..." include_sco=false include_a2dp=false

Can't Open in Wireshark

Verify file format:

file /tmp/capture.btsnoop
# Should show: BTSnoop version 1, HCI UART (H4)

If corrupted, the capture may have been interrupted. Always use bt_capture_stop to properly close files.