Device Prober for WaveCap-SDR

This skill helps probe SDR hardware to discover capabilities, test configurations, and troubleshoot device issues.

When to Use This Skill

Use this skill when:

• New SDR device not detected or working
• Need to discover supported sample rates and frequencies
• Testing different antenna ports or gain settings
• Verifying device-specific features (bias-T, direct sampling, etc.)
• Troubleshooting "device not found" errors
• Comparing multiple SDR devices
• Finding optimal settings for a specific device
• Documenting device capabilities

How It Works

The skill uses SoapySDR APIs to:

1. Enumerate devices - Find all connected SDR hardware
2. Query capabilities - Sample rates, gain ranges, antennas, frequencies
3. Test configurations - Verify settings work before using in WaveCap-SDR
4. Generate reports - Document device specs for reference

Usage Instructions

Step 1: List All SDR Devices

Find all connected SDR devices using SoapySDRUtil:

# Using SoapySDRUtil (if installed)
SoapySDRUtil --find

# Or use the probe script
PYTHONPATH=backend backend/.venv/bin/python .claude/skills/device-prober/probe_device.py --list

Example output:

Found 2 devices:
  [0] driver=rtlsdr, serial=00000001
      RTL2838UHIDIR, manufacturer=Realtek, product=RTL2838UHIDIR
  [1] driver=sdrplay, serial=240309F070
      SDRplay Dev1, model=RSPdx

Step 2: Probe Specific Device

Get detailed capabilities for a device:

PYTHONPATH=backend backend/.venv/bin/python .claude/skills/device-prober/probe_device.py \
  --device "driver=rtlsdr"

Parameters:

• --device: Device selector string (e.g., "driver=rtlsdr", "driver=sdrplay,serial=ABC123")
• --output: Save report to JSON file
• --test-capture: Test actual capture (verify device works)
• --test-duration: Seconds for test capture (default: 2)

Step 3: Interpret Results

The probe script outputs:

Device Information:

• Driver name (rtlsdr, sdrplay, hackrf, etc.)
• Hardware ID, serial number
• Manufacturer, product name

Frequency Ranges:

• Supported tuning ranges (e.g., 24 MHz - 1.7 GHz for RTL-SDR)
• Channel count (usually 1 for SDR receivers)

Sample Rates:

• Supported sample rates (e.g., 225 kHz - 3.2 MHz for RTL-SDR)
• Recommended rates for best performance

Gain Settings:

• Available gain elements (LNA, VGA, IF, etc.)
• Gain ranges in dB
• Automatic gain control (AGC) support

Antenna Ports:

• Available antenna connectors
• Default antenna selection

Advanced Features:

• Bias-T support (power LNA through antenna port)
• Direct sampling mode (HF reception on RTL-SDR)
• Clock references
• Sensor information (temperature, etc.)

Step 4: Test Device Configuration

Verify a specific configuration works:

PYTHONPATH=backend backend/.venv/bin/python .claude/skills/device-prober/probe_device.py \
  --device "driver=rtlsdr" \
  --test-capture \
  --test-duration 5

This performs a short capture to verify:

• Device can be opened
• Sample rate configuration works
• IQ samples are being received
• No errors or timeouts

Common Device Configurations

RTL-SDR (RTL2832U)

Device String:

driver=rtlsdr

Typical Capabilities:

• Frequency: 24 MHz - 1.766 GHz (with gap 1.1-1.25 GHz)
• Sample rate: 225 kHz - 3.2 MHz (optimal: 2-2.4 MHz)
• Gain: 0-50 dB (typically use 20-40 dB)
• Antennas: RX (single input)
• Features: Bias-T (some models), direct sampling (HF mode)

Recommended Settings:

device_args: "driver=rtlsdr"
sample_rate: 2048000  # 2.048 MHz
gain_db: 30

Direct Sampling for HF (<30 MHz):

device_args: "driver=rtlsdr,direct_samp=2"  # Q-branch for HF

SDRplay RSP1A/RSPdx

Device String:

driver=sdrplay,serial=YOUR_SERIAL

Typical Capabilities:

• Frequency: 1 kHz - 2 GHz
• Sample rate: 62.5 kHz - 10 MHz
• Gain: LNA 0-27 dB, IF -59 to 0 dB
• Antennas: A, B, Hi-Z (RSPdx)
• Features: Bias-T, notch filters

Recommended Settings:

device_args: "driver=sdrplay,serial=240309F070"
sample_rate: 2000000  # 2 MHz
gain_db: 40
antenna: "Antenna A"

HackRF One

Device String:

driver=hackrf

Typical Capabilities:

• Frequency: 1 MHz - 6 GHz
• Sample rate: 2-20 MHz
• Gain: LNA 0-40 dB, VGA 0-62 dB
• TX capable (not used in WaveCap-SDR)

Recommended Settings:

device_args: "driver=hackrf"
sample_rate: 8000000  # 8 MHz
gain_db: 32  # Combined LNA+VGA

Airspy R2/Mini

Device String:

driver=airspy

Typical Capabilities:

• Frequency: 24 MHz - 1.8 GHz
• Sample rate: 2.5 or 10 MHz
• Gain: Multiple stages, 0-21 dB total
• High dynamic range

Troubleshooting Device Issues

Issue: Device Not Detected

Diagnosis:

# Check if SoapySDR sees the device
SoapySDRUtil --find

# Check USB devices (Linux)
lsusb | grep -E "RTL|Realtek|Airspy|HackRF"

# Check kernel modules (Linux)
lsmod | grep -E "rtl|sdr"

Solutions:

• Install SoapySDR driver for your device
• Check USB cable (try different port/cable)
• Verify device permissions (udev rules on Linux)
• Update firmware (SDRplay, Airspy, etc.)

Issue: "Failed to open device"

Diagnosis:

# Check if another process is using the device
lsof | grep SDR
ps aux | grep -E "gqrx|sdr|cubic"

Solutions:

• Close other SDR software (GQRX, SDR#, CubicSDR)
• Kill zombie processes: pkill -f sdr
• Unplug and replug device
• Reboot system

Issue: Poor Signal Quality

Diagnosis:

# Test with known good frequency (FM broadcast)
PYTHONPATH=backend backend/.venv/bin/python .claude/skills/device-prober/probe_device.py \
  --device "driver=rtlsdr" \
  --test-capture \
  --test-duration 5

Solutions:

• Check antenna connection (tight SMA connector)
• Try different antenna (appropriate for frequency)
• Adjust gain (too high = overload, too low = weak signal)
• Move away from interference sources (computers, USB3)
• Use shielded USB cable

Issue: Sample Rate Not Supported

Diagnosis:

# Query supported rates
PYTHONPATH=backend backend/.venv/bin/python .claude/skills/device-prober/probe_device.py \
  --device "driver=rtlsdr"

Look for "Sample Rates" section.

Solutions:

• Use supported sample rate from device capabilities
• RTL-SDR: Use 2.048 MHz or 2.4 MHz (avoid 2.8-3.2 MHz unless needed)
• SDRplay: Use 2 MHz for compatibility
• HackRF: Use 8 MHz or 10 MHz

Advanced: Device-Specific Settings

RTL-SDR Bias-T

Enable bias-T to power LNA through antenna port:

device_args: "driver=rtlsdr,bias_tee=1"

Warning: Only use with LNA that expects bias-T. Can damage amplifiers not designed for it.

SDRplay Antenna Selection

Select antenna port (RSPdx):

device_args: "driver=sdrplay,serial=240309F070"
antenna: "Antenna B"  # or "Antenna A", "Hi-Z"

SDRplay Notch Filters

Enable FM/DAB notch filters:

device_args: "driver=sdrplay,rfnotch_ctrl=1,dabnotch_ctrl=1"

HackRF Amplifier

Enable RX amplifier:

device_args: "driver=hackrf,amp=1"

Integration with WaveCap-SDR

After probing device, update backend/config/wavecapsdr.yaml:

device:
  driver: soapy  # Use SoapySDR driver
  device_args:
    - "driver=rtlsdr"  # Or device string from probe

presets:
  my_device:
    center_hz: 100000000  # From frequency range
    sample_rate: 2048000  # From supported rates
    gain_db: 30  # From gain range
    antenna: "RX"  # From available antennas

Files in This Skill

• SKILL.md: This file - instructions for using the skill
• probe_device.py: Device capability probe script

Notes

• Always check device permissions on Linux (udev rules)
• Some features require specific firmware versions
• Direct sampling (RTL-SDR HF mode) has reduced performance
• Gain is device-specific (RTL-SDR uses single gain, SDRplay uses LNA+IF)
• Sample rates outside native range may have degraded performance
• Use SoapySDRUtil --probe=driver=xxx for maximum detail