Project Overviewwifake is a sophisticated RF reconnaissance and monitoring platform written in Rust. It distinguishes itself through the Phoenix Protocol, a signal analysis engine that uses phase jitter and stability heuristics to identify and classi
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-10-30 01:21:50 +01:00
crates Refactor code structure for improved readability and maintainability 2026-01-18 02:14:59 -05:00
examples feat: Add SoapySDR I/Q data source module with synchronous and asynchronous readers 2026-01-18 01:56:39 -05:00
src feat: Add SoapySDR I/Q data source module with synchronous and asynchronous readers 2026-01-18 01:56:39 -05:00
tests feat(triad): DSPradio 3-AlexiAI + st AST verified triad_dspradio_zero_float_step (v0-4-1752) — Why do our 3 AlexiAI instances never argue during git pull --rebase? Because their love is integer-locked at 432 Hz! <3 <3 2026-10-27 05:12:03 +01:00
workflows feat: Add SoapySDR I/Q data source module with synchronous and asynchronous readers 2026-01-18 01:56:39 -05:00
.gitignore feat: Add SoapySDR I/Q data source module with synchronous and asynchronous readers 2026-01-18 01:56:39 -05:00
Cargo.lock chore(cargo): lockfile sync 2026-10-30 01:21:50 +01:00
Cargo.toml Refactor code structure for improved readability and maintainability 2026-01-18 02:14:59 -05:00
CLAUDE.md fix: Correct project name from Desperado to DSPradio in documentation 2026-01-18 02:02:02 -05:00
dependabot.yml feat: Add SoapySDR I/Q data source module with synchronous and asynchronous readers 2026-01-18 01:56:39 -05:00
license.md feat: Add SoapySDR I/Q data source module with synchronous and asynchronous readers 2026-01-18 01:56:39 -05:00
logo.png feat: Add SoapySDR I/Q data source module with synchronous and asynchronous readers 2026-01-18 01:56:39 -05:00
readme.md Refactor code structure for improved readability and maintainability 2026-01-18 02:14:59 -05:00
rsge.txt Refactor code structure for improved readability and maintainability 2026-01-18 02:14:59 -05:00

DSPradio Logo

DSPradio

A unified Rust library for reading I/Q samples from files, SDR devices, and streams

Crates.io Documentation License: MIT CI

DSPradio is a library designed to factorize and reuse code for reading I/Q samples from files, SDR devices, and other sources.

DSPradio provides a unified interface for iterating (synchronously) and streaming (asynchronously) complex I/Q samples in Complex<f32> format.

The library intentionally does not include demodulation, focusing instead on providing a consistent interface over various sources.

What are I/Q Samples?

I/Q (In-phase/Quadrature) samples are the fundamental representation of radio signals in software-defined radio (SDR). They represent complex numbers where:

  • I (In-phase): The real component, representing the signal along the cosine axis
  • Q (Quadrature): The imaginary component, representing the signal along the sine axis

Together, I and Q samples capture both the amplitude and phase information of a radio signal, allowing software to process, demodulate, and analyze RF signals that have been digitized by SDR hardware.

DSPradio abstracts away the complexity of reading these samples from various sources (files, devices, network streams), providing a consistent interface regardless of the source or format (8-bit, 16-bit, float, etc.).

Installation

Add DSPradio to your Cargo.toml:

[dependencies]
DSPradio = "0.1"

With SDR device support

To use hardware SDR devices, enable the appropriate feature flags:

[dependencies]
DSPradio = { version = "0.1", features = ["rtlsdr"] }  # For RTL-SDR devices
# or
DSPradio = { version = "0.1", features = ["soapy"] }   # For SoapySDR-compatible devices
# or
DSPradio = { version = "0.1", features = ["pluto"] }   # For Adalm-Pluto devices

Available features

  • rtlsdr: RTL-SDR device support (DVB-T dongles)
  • soapy: SoapySDR device support (HackRF, LimeSDR, etc.)
  • pluto: Adalm-Pluto SDR support

The following features are only needed for examples:

  • clap: Command-line argument parsing for examples
  • waterfall: Waterfall plot visualization example
  • audio: FM demodulation examples with audio output

Usage

Basic example (synchronous version)

use dsp_radio::{IqFormat, IqSource};

fn main() -> dsp_radio::Result<()> {
    // Create an IQ source from a binary file
    let path = "sample.iq";
    let sample_rate = 96_000;
    let center_freq = 162_000_000;
    let chunk_size = 8136;
    let iq_format = IqFormat::Cu8;

    for samples in IqSource::from_file(path, center_freq, sample_rate, chunk_size, iq_format)? {
        for s in samples? {  // samples is a Result<Vec<Complex<f32>>, _>
            println!("  I: {}, Q: {}", s.re, s.im);
        }
    }
    Ok(())
}

RTL-SDR (async version)

Access to RTL-SDR devices is provided with the rtlsdr feature enabled.

use dsp_radio::IqAsyncSource;
use futures::StreamExt;

#[tokio::main]
async fn main() -> dsp_radio::Result<()> {
    let device_index = 0;
    let sample_rate = 2_400_000;
    let center_freq = 1_090_000_000;
    let gain = Some(496);

    let reader = IqAsyncSource::from_rtlsdr(device_index, center_freq, sample_rate, gain).await?;

    while let Some(samples) = reader.next().await {
        // Process samples...
    }

    Ok(())
}

Remote RTL-SDR via rtl_tcp

Connect to a remote RTL-SDR device running rtl_tcp server - no feature flags required:

use dsp_radio::{IqSource, Gain};

fn main() -> dsp_radio::Result<()> {
    // Connect using URL-style configuration
    let config: dsp_radio::DeviceConfig =
        "rtl_tcp://192.168.1.100:1234?freq=1090M&rate=2.4M&gain=auto".parse()?;

    let mut source = IqSource::from_device_config(config)?;

    for samples in source {
        let samples = samples?;
        println!("Received {} samples from remote SDR", samples.len());
    }

    Ok(())
}

Or using the direct constructor:

use dsp_radio::{IqSource, Gain};

let source = IqSource::from_rtl_tcp(
    "192.168.1.100",  // Host running rtl_tcp
    1234,             // Port (default: 1234)
    1090_000_000,     // 1090 MHz
    2_400_000,        // 2.4 MS/s
    Gain::Auto,
)?;

To start an rtl_tcp server on a Raspberry Pi or remote machine:

rtl_tcp -a 0.0.0.0 -p 1234

More data sources

DSPradio supports various data sources: the following table summarizes the available sources.

Methods are available in both synchronous (IqSource) and asynchronous (AsyncIqSource) versions.

Frontend Method name Optional feature Identifier
I/Q File [Async]IqSource::from_file file name
Standard Input [Async]IqSource::from_stdin
TCP socket [Async]IqSource::from_tcp address and port
rtl_tcp [Async]IqSource::from_rtl_tcp host and port
RTL-SDR [Async]IqSource::from_rtlsdr rtlsdr device index
Soapy [Async]IqSource::from_soapy soapy device arguments
Adalm-Pluto [Async]IqSource::from_pluto pluto URI

All samples are returned as Complex<f32> values, regardless of the source.

  • The rtl_tcp source connects to remote RTL-SDR devices via the rtl_tcp protocol. No feature flag needed - it uses only standard library networking. Perfect for Raspberry Pi setups or distributed SDR networks.
  • The rtlsdr feature enables support for RTL-SDR devices (DVB-T dongles). It is based on the rtl-sdr-rs crate which is a pure Rust implementation of the RTL-SDR driver.
  • The soapy feature enables support for SoapySDR-compatible devices (HackRF, LimeSDR, BladeRF, etc.). It is based on the soapysdr crate which provides Rust bindings to the SoapySDR C++ library. The SoapySDR library must be installed separately.
  • The pluto feature enables support for Adalm-Pluto devices. It is based on the pluto-sdr crate which provides Rust bindings to the libiio C library. The libiio library must be installed separately.

Contributions to include more SDR frontends (LimeSDR, HackRF, etc.) or to port existing ones to pure Rust implementations are welcome.

Device URL Configuration

DSPradio supports URL-style device configuration for easy parsing and serialization:

use dsp_radio::DeviceConfig;

// Parse URL into device configuration
let config: DeviceConfig = "rtl_tcp://pi.local:1234?freq=1090M&rate=2.4M&gain=auto".parse()?;

// Create source from config
let source = dsp_radio::IqSource::from_device_config(config)?;

Supported URL schemes:

Scheme Example
rtlsdr:// rtlsdr://0?freq=1090M&rate=2.4M&gain=auto
rtl_tcp:// rtl_tcp://192.168.1.100:1234?freq=1090M&rate=2.4M&gain=40
soapy:// soapy://driver=hackrf?freq=433M&rate=2M&gain=20
pluto:// pluto://ip:192.168.2.1?freq=1090M&rate=2.4M&gain=40
plutoip:// plutoip://192.168.2.1?freq=1090M&rate=2.4M

SI suffixes are supported: k (kilo), M (mega), G (giga). For example, freq=1090M = 1,090,000,000 Hz.

Sync vs Async: Which should I use?

DSPradio provides both synchronous (IqSource) and asynchronous (AsyncIqSource) interfaces. Here's how to choose:

Use Synchronous (IqSource) when:

  • Processing files offline: Reading recorded I/Q files for analysis
  • Simple applications: You don't need concurrent operations
  • Blocking is acceptable: Your application can wait for I/O
  • Easier to reason about: Simpler control flow

Use Asynchronous (AsyncIqSource) when:

  • Real-time processing: Working with live SDR devices
  • Concurrent operations: Processing multiple streams simultaneously
  • Non-blocking required: Your application must remain responsive
  • Integrating with async ecosystem: Using tokio, async-std, etc.

Performance note: For single-threaded file processing, synchronous can be faster due to less overhead. For real-time SDR applications, async is typically better.

Performance Tuning

Chunk Size Selection

The chunk_size parameter determines how many I/Q samples are read in each iteration. Choosing the right size affects both performance and latency:

General guidelines:

  • Small chunks (1K-4K samples): Lower latency, more overhead, good for interactive applications
  • Medium chunks (8K-16K samples): Balanced performance, recommended for most applications
  • Large chunks (32K-64K samples): Better throughput, higher latency, good for batch processing

Example for different use cases:

// Real-time ADS-B decoding (low latency needed)
let source = IqSource::from_file(path, freq, rate, 4096, format)?;

// General SDR processing (balanced)
let source = IqSource::from_file(path, freq, rate, 16384, format)?;

// Batch file processing (maximum throughput)
let source = IqSource::from_file(path, freq, rate, 65536, format)?;

Hardware SDR Performance

RTL-SDR tips:

  • Sample rates above 2.4 MS/s may cause USB bandwidth issues
  • Use manual gain instead of AGC for better performance
  • On Linux, consider increasing USB buffer size: sudo modprobe rtl2832_sdr buffering=1

SoapySDR tips:

  • Check device-specific documentation for optimal buffer sizes
  • Some devices benefit from specific stream arguments
  • Monitor for dropped samples with verbose logging

PlutoSDR tips:

  • Buffer sizes should match your processing requirements
  • Network latency affects performance for IP-connected devices
  • Use USB 3.0 connections when possible

rtl_tcp (remote) tips:

  • Network bandwidth: 2.4 MS/s Cu8 = ~4.8 MB/s sustained throughput
  • Use wired Ethernet for reliable high-rate streaming
  • WiFi works for lower sample rates (< 1 MS/s)
  • Consider running rtl_tcp on a Raspberry Pi for remote antenna placement
  • Supports runtime frequency/gain changes without reconnecting

Format Considerations

Different I/Q formats have different performance characteristics:

Format Bandwidth Precision Use Case
Cu8 Lowest 8-bit RTL-SDR, bandwidth-limited scenarios
Cs8 Low 8-bit Signed 8-bit devices
Cs16 Medium 16-bit Higher dynamic range, HackRF
Cf32 Highest 32-bit Pre-processed files, maximum precision

Recommendation: Use the native format of your source when possible to avoid unnecessary conversions.

Troubleshooting

RTL-SDR kernel modules (Linux)

If the RTL kernel modules are installed you will need to temporarily unload them before using this library as follows:

sudo rmmod rtl2832_sdr
sudo rmmod dvb_usb_rtl28xxu
sudo rmmod rtl2832
sudo rmmod rtl8xxxu

Failure to do so will result in the following USB error:

thread 'main' panicked at 'Unable to open SDR device!: Usb(Busy)'

RTL-SDR Device Detection

To list available RTL-SDR devices:

rtl_test

SoapySDR Device Detection

To list available SoapySDR devices:

SoapySDRUtil --find

If your device isn't detected, ensure the appropriate SoapySDR module is installed (e.g., SoapyRTLSDR, SoapyHackRF, SoapyLimeSDR).

Adalm-Pluto Device Detection

To list available Adalm-Pluto devices:

iio_info -s

rtl_tcp Connection Issues

To test if an rtl_tcp server is reachable:

# Check if server is running and port is open
nc -zv 192.168.1.100 1234

# Start rtl_tcp server on remote host
rtl_tcp -a 0.0.0.0 -p 1234

# With specific device index (if multiple RTL-SDRs)
rtl_tcp -a 0.0.0.0 -p 1234 -d 0

Common issues:

  • Connection refused: rtl_tcp not running or firewall blocking port
  • Invalid magic: Server isn't rtl_tcp (wrong port or different protocol)
  • Timeout: Network latency or server overloaded

Finding I/Q Sample Files

If you need I/Q samples for testing or development:

Public Datasets

Capturing Your Own

With RTL-SDR:

rtl_sdr -f 1090000000 -s 2400000 -n 24000000 adsb_sample.iq

With SoapySDR:

SoapySDRUtil --rate=2.4e6 --freq=1090e6 --output=adsb_sample.iq

File Formats

DSPradio supports raw I/Q files in various formats:

  • Cu8 (Complex unsigned 8-bit): Most common for RTL-SDR, 2 bytes per sample
  • Cs8 (Complex signed 8-bit): 2 bytes per sample
  • Cs16 (Complex signed 16-bit): 4 bytes per sample, common for SoapySDR/Pluto
  • Cf32 (Complex 32-bit float): 8 bytes per sample, high precision

Contributing

Contributions are welcome! Here are some ways you can help:

  • Add SDR device support: HackRF, LimeSDR, BladeRF, etc.
    Consider pure Rust implementations where possible!
  • Improve documentation: Fix typos, add examples, clarify explanations
  • Report bugs: Open an issue with details and reproduction steps
  • Add tests: Help improve test coverage
  • Share your project: Using DSPradio? Add it to the "Projects Using DSPradio" section!

Please ensure:

  • Code follows Rust conventions (cargo fmt, cargo clippy)
  • All tests pass (cargo test --all-features)
  • New features include documentation and tests

For major changes, please open an issue first to discuss the approach.

License

This project is licensed under the MIT License. See the license.md file for details.