Files

T

rsp2k 9db76af626 Measure dropped samples from stream timestamps instead of hiding them

Overflows were counted but the samples the driver dropped were simply
missing, so a 5 s capture with 300 overflows still read as a clean 5.000 s
file. Each read's hardware timestamp is now compared with where the
previous read ended; gaps are sized exactly, zero-filled by default so the
file timeline stays true, and reported as completed_with_gaps with a
warning, samples_dropped and a gap list. This also catches drops the
plugin never flags as overflows (libusb transfer timeouts).

Timestamps are differenced before rounding: rounding each absolute
timestamp to a sample index flips by +/-1 near half-sample boundaries
and produced phantom 1-sample gaps.

- stream buffers 128 x 64K samples (~280 ms at 30 Msps, was ~4 ms)
- reject out-of-range gain, frequency, rate and bandwidth instead of
  letting the plugin clamp silently; default bandwidth clamps to range
- spectrum returns a max-hold decimated summary (256 points) plus
  noise_floor_db; full arrays were 139 KB at fft_size 4096
- capture_iq background=True with stream_status polling, so
  stop_capture is reachable; device-changing tools refuse while it runs
- OSError returned in the error shape; status drops "unknown" fields
- README: gap accounting, keep captures off tmpfs; captures/ ignored

2026-10-25 11:57:25 -06:00

6.4 KiB

Raw Blame History

mcbladerf

MCP server for Nuand BladeRF SDR control via SoapySDR.

Overview

mcbladerf provides Model Context Protocol (MCP) tools for controlling Nuand BladeRF software-defined radios. It enables AI assistants to configure RF parameters, capture IQ samples, and perform spectrum analysis through a simple tool-based interface.

Features

Device Management: Enumerate, connect, and disconnect BladeRF devices
RF Configuration: Set/get frequency, sample rate, bandwidth, and gain stages
IQ Capture: Stream samples to files in CF32 or CS16 format
Spectrum Analysis: Capture and compute FFT power spectra
Advanced Operations: FPGA loading, firmware flashing, DC calibration

Requirements

Python 3.14+ (must match system SoapySDR installation)
SoapySDR with BladeRF support (system packages)
bladeRF CLI tools (for advanced operations)
BladeRF 1.0 or 2.0 hardware

System Dependencies (Arch Linux)

sudo pacman -S soapysdr soapysdr-bladerf bladerf

Installation

SoapySDR is a C++ library with Python bindings that must be installed system-wide. The venv needs access to system site-packages:

cd mcbladerf

# One-time setup (creates venv with system site-packages access)
make setup

# Or manually:
uv venv --system-site-packages --python 3.14
uv pip install -e .

Running

# After setup, run with:
uv run mcbladerf

# Or via make:
make run

Usage with Claude Code

# Add to Claude Code (with full path)
claude mcp add mcbladerf -- uv run --directory /path/to/mcbladerf mcbladerf

The .mcp.json is already configured for local use:

claude -p "show bladerf status" --mcp-config .mcp.json --allowedTools "mcp__mcbladerf__*"

Available Tools

Device Management

bladerf_status - Get comprehensive device status
bladerf_list_devices - Enumerate connected devices
bladerf_connect - Connect to a device by serial or index
bladerf_disconnect - Close the current connection

RF Configuration

bladerf_get_frequency / bladerf_set_frequency - Center frequency
bladerf_get_sample_rate / bladerf_set_sample_rate - Sample rate
bladerf_get_bandwidth / bladerf_set_bandwidth - Analog bandwidth
bladerf_get_gain / bladerf_set_gain - Individual gain stages
bladerf_list_gains - Enumerate available gain stages
bladerf_get_frequency_range / bladerf_get_sample_rate_range - Hardware limits

IQ Capture

bladerf_capture_iq - Stream samples to file (CF32/CS16)
bladerf_capture_spectrum - Capture and compute FFT, power in dBFS
bladerf_stream_status - Capture progress, or the result of a background capture
bladerf_stop_capture - Abort running capture

Advanced

bladerf_load_fpga - Load FPGA bitstream (RAM)
bladerf_flash_firmware - Flash FX3 firmware
bladerf_calibrate_dc - Run DC offset calibration
bladerf_get_hardware_info - Detailed hardware info
bladerf_set_loopback - Configure loopback mode
bladerf_probe - Device diagnostics

Example Session

> Connect to my BladeRF and show status
[Uses bladerf_connect and bladerf_status]

> Set frequency to 915 MHz with 2 MHz sample rate
[Uses bladerf_set_frequency and bladerf_set_sample_rate]

> Capture 1 second of IQ data to ~/claude/sdr/mcbladerf/captures/capture.cf32
[Uses bladerf_capture_iq]

> Show me the spectrum around 100 MHz
[Uses bladerf_capture_spectrum]

Capture Files and Readings

CF32 files are complex64 scaled to ±1.0. CS16 files are the device's raw SC16 Q11 integers, interleaved I/Q with full scale 2048, the same layout bladeRF-cli writes with format=bin. Spectrum power is dBFS, so a full-scale tone reads 0. Every capture reports clipped_samples and peak_dbfs, so check those before trusting the data.

When the host falls behind, the driver drops samples, and not always with an overflow error (a libusb transfer timeout drops data silently). Each read carries a hardware timestamp, so every gap is measured exactly and, by default, zero-filled: sample N of the file is always N / rate seconds after the first. Such captures finish as completed_with_gaps with a warning, samples_dropped and a gap list in output-sample offsets. Pass fill_gaps=false to get a shorter file with the same report instead.

Long captures should use background=true: the call returns at once, bladerf_stream_status shows progress and then the result, and bladerf_stop_capture ends it early. Spectra come back as a 256-point max-hold summary with noise_floor_db; peak and floor are computed at full resolution. Out-of-range gain, frequency, rate or bandwidth values are rejected, not clamped. The sample rate resets to 4 MHz each time the device is opened, so always set it.

Write captures to disk, not /tmp. On many Linux systems /tmp is a tmpfs held in RAM, and 30 Msps CS16 is 120 MB per second, so a few long captures can push the machine into swap and the OOM killer. Once the host stalls, the stream drops samples. The project's captures/ directory is gitignored for this.

Gains you leave out keep whatever the device last had, including values set by another process. The radio is often shared, so set all three RX gains explicitly.

While connected, the server holds the USB device and nothing else can open it. The bladeRF-cli backed tools (probe, calibrate, FPGA load, firmware flash, hardware info) release it for the duration and restore the RX/TX settings afterwards. Call bladerf_disconnect when you are done so other tools can use the radio.

Troubleshooting

setupStream() -3 / bladerf_sync_config() returned -3. The SoapySDR plugin was built against an older libbladeRF. libbladeRF 2025.10 inserted BLADERF_FORMAT_SC16_Q11_PACKED into the bladerf_format enum without changing the soname, so a stale soapybladerf requests the wrong format and bladeRF1 rejects it. Rebuild soapybladerf against the installed headers (the Arch PKGBUILD needs -DCMAKE_POLICY_VERSION_MINIMUM=3.5 under CMake 4).

No device(s) available (-7) with the board plugged in. Another process has the device open. Check pgrep -xa bladeRF-cli; pgrep -f can match your own shell.

No module named 'SoapySDR'. The venv must see system site-packages. Recreate it with make setup.

BladeRF 1.0 x40 Specifications

Frequency: 237.5 MHz - 3.8 GHz
Sample rates: 80 Ksps - 40 Msps
RX Gain stages: lna (0/3/6 dB), rxvga1 (5-30 dB), rxvga2 (0-30 dB)
TX Gain stages: txvga1 (-35 to -4 dB), txvga2 (0-25 dB)

License

MIT

6.4 KiB Raw Blame History