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

---
title: Protocol Capture
description: 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:
```json
{
  "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
```

<Aside type="note">
Audio captures (`include_sco`, `include_a2dp`, `include_iso`) generate large files quickly.
</Aside>

## Stopping a Capture

```
bt_capture_stop capture_id="capture_abc123"
```

Returns:
```json
{
  "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:
```json
{
  "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:
```json
{
  "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

```bash
wireshark /tmp/bluetooth.btsnoop
```

Wireshark provides:
- Protocol dissection
- Conversation tracking
- Expert analysis
- Export options

## Requirements

<Aside type="caution">
Capture requires elevated privileges (root or `CAP_NET_RAW`).
</Aside>

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

```bash
# 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"

```bash
# 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:
```bash
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.