rsp2k
9db76af626
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
145 lines
6.4 KiB
Markdown
145 lines
6.4 KiB
Markdown
# 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)
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
# After setup, run with:
|
|
uv run mcbladerf
|
|
|
|
# Or via make:
|
|
make run
|
|
```
|
|
|
|
## Usage with Claude Code
|
|
|
|
```bash
|
|
# 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:
|
|
```bash
|
|
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
|