Restore mcbladerf from 2026-02-08 working copy

Recovered from editor file-history snapshots; the original directory was never committed and has since been removed.
2026-10-24 20:33:27 -06:00
commit c767166984
13 changed files with 4305 additions and 0 deletions
@@ -0,0 +1,122 @@
+# 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
+- `bladerf_stream_status` - Check capture progress
+- `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 /tmp/capture.cf32
+[Uses bladerf_capture_iq]
+
+> Show me the spectrum around 100 MHz
+[Uses bladerf_capture_spectrum]
+```
+
+## 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