Monitor Tools

import { Aside } from ‘@astrojs/starlight/components’;

Tools for capturing and analyzing raw Bluetooth HCI (Host Controller Interface) traffic.

bt_capture_start

Start capturing Bluetooth HCI traffic.

Parameters:

Name	Type	Required	Default	Description
`output_file`	string	Yes	-	Path for btsnoop capture file
`adapter`	string	No	-	Adapter index (e.g., “0” for hci0), or all if omitted
`include_sco`	boolean	No	false	Include SCO voice traffic
`include_a2dp`	boolean	No	false	Include A2DP audio streaming
`include_iso`	boolean	No	false	Include ISO (LE Audio) traffic

Returns:

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

Example:

# Basic capture
bt_capture_start output_file="/tmp/bluetooth.btsnoop"

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

# Include audio data (large files!)
bt_capture_start output_file="/tmp/audio.btsnoop" include_a2dp=true

Notes:

Requires root or CAP_NET_RAW capability on btmon
Capture runs in background until stopped
Audio flags generate large files quickly

bt_capture_stop

Stop a running Bluetooth capture.

Parameters:

Name	Type	Required	Description
`capture_id`	string	Yes	Capture ID from bt_capture_start

Returns:

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

Example:

bt_capture_stop capture_id="capture_abc123"

Notes:

Always stop captures to ensure files are properly closed
Capture ID is returned by bt_capture_start

bt_capture_list_active

List all active Bluetooth captures.

Parameters: None

Returns:

{
  "captures": [
    {
      "capture_id": "capture_abc123",
      "output_file": "/tmp/bluetooth.btsnoop",
      "started": "2024-01-15T10:30:00",
      "adapter": "all"
    }
  ]
}

Example:

bt_capture_list_active

bt_capture_parse

Parse a btsnoop capture file and return packet summaries.

Parameters:

Name	Type	Required	Default	Description
`filepath`	string	Yes	-	Path to btsnoop file
`max_packets`	integer	No	100	Maximum packets to return (0 for all)
`packet_type_filter`	string	No	-	Filter by type: HCI_CMD, ACL_DATA, HCI_EVENT, SCO_DATA
`direction_filter`	string	No	-	Filter by direction: TX or RX

Returns:

{
  "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",
      "length": 7,
      "summary": "Inquiry"
    }
  ]
}

Example:

# Basic parse
bt_capture_parse filepath="/tmp/bluetooth.btsnoop"

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

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

# First 50 packets
bt_capture_parse filepath="..." max_packets=50

bt_capture_analyze

Analyze a btsnoop capture file with high-level statistics.

Parameters:

Name	Type	Required	Description
`filepath`	string	Yes	Path to btsnoop file

Returns:

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

Example:

bt_capture_analyze filepath="/tmp/bluetooth.btsnoop"

Notes:

Provides higher-level view than bt_capture_parse
Useful for understanding overall traffic patterns

bt_capture_read_raw

Read raw packet data with btmon-style decoding.

Parameters:

Name	Type	Required	Default	Description
`filepath`	string	Yes	-	Path to btsnoop file
`offset`	integer	No	0	Packets to skip from beginning
`count`	integer	No	50	Number of packets to display

Returns:

{
  "output": "@ MGMT Command: Read Management... (0x0001) plen 0\n..."
}

Example:

# First 50 packets
bt_capture_read_raw filepath="/tmp/bluetooth.btsnoop"

# Skip first 100, read next 20
bt_capture_read_raw filepath="..." offset=100 count=20

Notes:

Returns btmon’s human-readable packet decoding
Useful for detailed protocol analysis
Output can be large for many packets

File Format

Captures use btsnoop format, compatible with:

Tool	Description
Wireshark	Full GUI protocol analyzer
btmon	BlueZ command-line decoder
hcidump	Legacy packet dumper

Opening in Wireshark

wireshark /tmp/bluetooth.btsnoop

Wireshark provides:

Full protocol dissection
Conversation tracking
Expert analysis
Multiple export formats

Permissions

Capture requires access to the Bluetooth monitor socket:

# Option 1: Run as root
sudo btmon

# Option 2: Add capability (recommended)
sudo setcap cap_net_raw+ep /usr/bin/btmon

# Verify capability
getcap /usr/bin/btmon