rtlsdr-next 📡

A high-performance, asynchronous, and safety-first Rust driver for RTL2832U-based Software Defined Radios (SDR).

Designed for the modern era (2026+), this driver moves away from the legacy C callback model toward a Tokio-native Stream architecture, with specific optimizations for high-bandwidth ARM hosts like the Raspberry Pi 5.

Caution

This a shameless "vibe-code" project. I wanted to dig into Rust and this seemed like something fun to explore when I realized the gold version C code drivers were circa 2013. Since starting, I realized there is a Rust implementation that has a more human touch here: https://github.com/ccostes/rtl-sdr-rs

✅ Confirmed Working Hardware

Dongle	Tuner	Host	Clients Tested
RTL-SDR Blog V4	R828D	Raspberry Pi 5 (Bookworm)	OpenWebRX+, GQRX, SDR++
RTL-SDR Blog V4	R828D	Windows 11 x86_64 (AMD Ryzen 7600X)	Corona SDR (iOS)
RTL-SDR Blog V4	R828D	Raspberry Pi 5 (Bookworm)	SpectralBands (iOS, WebSDR protocol)

Other RTL2832U dongles with R820T/R820T2/E4000 tuners should work — hardware verification welcome.

🚀 Key Features

Async-First Architecture: Built on Tokio. SDR data is a standard Stream with backpressure and graceful shutdown.
Full RTL-SDR Blog V4 Support: Correct R828D initialization sequence reverse-engineered from usbmon traces against librtlsdr.
Zero-Allocation Pipeline: Custom buffer pooling eliminates memory allocations in the hot path.
Auto-Vectorized DSP: LLVM auto-vectorizes to NEON on aarch64 and AVX-512 on Zen 4 x86_64 — no manual intrinsics needed.
Automatic Tuner Probing: I2C presence detection for Rafael Micro (R820T/R828D), Elonics (E4000), and Fitipower (FC0012/13).
Multi-Client Daemon: A single rtlsdr-daemon process serves rtl_tcp, WebSDR, and Unix socket clients simultaneously from one hardware handle. No resource contention.
Independent Virtual VFOs: Each WebSDR browser client can tune independently within the hardware's 1.536 MHz capture window using a per-client NCO — no hardware retune needed for in-band frequency changes.
TOML Configuration: File-based config with CLI override support. Set gain, frequency, PPM, TLS, and server addresses once in /etc/rtlsdr-next/config.toml.
Precision Frequency Correction: Integrated PPM correction for both tuner PLL and RTL2832U resampler.
Standalone Tools: Individual rtl_tcp and websdr binaries remain available for single-protocol deployments.

🛠 Hardware: The V4 Deep Dive

The RTL-SDR Blog V4 required several initialization steps discovered during reverse engineering via usbmon traces:

GPIO Reset Pulse (non-V4 only): Standard RTL-SDR dongles receive a GPIO 4 reset pulse during init. The V4 skips this entirely — librtlsdr detects the V4 by EEPROM string match and branches before the GPIO code. This driver mirrors that behavior exactly.
R828D I2C Address: The R828D responds at 0x74, not 0x34 (which is the R820T address). Probing must try both.
Low-IF Mode: The R828D uses low-IF (not Zero-IF). After tuner detection, Zero-IF mode must be explicitly disabled (page1 reg 0xb1 = 0x1a) and the In-phase ADC input enabled (page0 reg 0x08 = 0x4d).
I2C Chunk Size: The RTL2832U I2C bridge has a maximum transfer size of 8 bytes (7 data + 1 register byte). The 27-byte tuner init array must be written in chunks or the USB endpoint stalls with a pipe error.
Demod Register Sync: Every demodulator register write must be followed by a dummy read of page0 reg 0x01 — this is a hardware flush/sync requirement. Omitting it causes subsequent control transfers to stall.
EEPROM Recovery: If the dongle's EEPROM is corrupted (reverts to generic strings), restore it with the RTL-SDR Blog fork of rtl_eeprom:
```
~/rtl-sdr-blog/build/src/rtl_eeprom -m "RTLSDRBlog" -p "Blog V4" -s "00000001"
```

🚀 Performance

Operation	Pi 5 aarch64	x86_64 (Ryzen 7600X)
`u8` → `f32` converter	1.49 GiB/s	12.67 GiB/s (AVX-512)
FIR decimator ÷8	426 MSa/s	590 MSa/s
Full pipeline ÷8	328 MiB/s	—

Both results use cargo build --release without target-cpu=native. On x86_64, LLVM auto-vectorizes the converter to AVX-512 on supported CPUs. Setting target-cpu=native on Zen 4 can cause AVX-512 frequency throttling that hurts the decimator — the default build is better balanced.

Pi 5 is memory-bandwidth-bound on the converter. x86_64 desktop has enough DDR5 bandwidth that the ALU keeps up.

🎛 Performance Tuning & Latency

Reducing Frequency Switching Lag

This driver implements a "Flush-on-Tune" mechanism. When you change frequency (e.g., click a bookmark), all stale data currently in the driver's buffers is immediately dropped. This makes tuning feel much snappier than standard librtlsdr.

However, you may still experience some lag in applications like Gqrx. This is because Gqrx maintains its own large internal audio and DSP buffers which we cannot flush.

For Gqrx Users:

Set Bandwidth to 0 (Auto) to avoid unnecessary I2C filter commands.
Reduce Audio Buffer size in Gqrx settings if audio lags behind the waterfall.
If you need ultra-low latency, you can programmatically reduce the driver's buffer count via StreamConfig.

For OpenWebRX Users:

OpenWebRX generally feels snappier because it manages its own pipeline more aggressively and benefits directly from our driver's flush mechanism.

Advanced Configuration (`StreamConfig`)

You can tune the trade-off between latency and stability by modifying the StreamConfig struct when creating a stream:

// Adjust configuration on the driver instance
driver.stream_config = rtlsdr::StreamConfig {
    num_buffers: 8,          // Default: 16. Lower = less latency, higher risk of drops.
    buffer_size: 256 * 1024, // Default: 256KB.
};

// Create the stream with the new settings
let stream = driver.stream();

📋 Prerequisites

Rust toolchain (stable)
libusb development headers
USB access (see platform setup below)

# Ubuntu/Debian
sudo apt-get install libusb-1.0-0-dev

# macOS
brew install libusb

# Windows — no libusb headers needed, but see USB driver setup below

🔌 USB Permissions

The recommended approach is a persistent udev rule rather than chmod:

# Create udev rule
echo 'SUBSYSTEM=="usb", ATTRS{idVendor}=="0bda", ATTRS{idProduct}=="2838", MODE="0666", GROUP="plugdev"' \
  | sudo tee /etc/udev/rules.d/99-rtlsdr.rules

# Reload and trigger
sudo udevadm control --reload-rules
sudo udevadm trigger

# Add yourself to plugdev if needed
sudo usermod -aG plugdev $USER

For quick testing only: sudo chmod 666 /dev/bus/usb/$(lsusb | grep RTL | awk '{print $2"/"$4}' | tr -d ':')

Windows

Windows requires a one-time driver swap via Zadig — the dongle enumerates as a DVB-T TV tuner by default and must be switched to WinUSB before libusb can claim it:

Download and open Zadig
Options → List All Devices
Select the RTL-SDR entry (look for "Bulk-In, Interface 0")
Select WinUSB in the driver dropdown
Click "Replace Driver"

This survives reboots but may need to be repeated if you plug into a different USB port. The Unix socket sharing server (SharingServer) is not available on Windows — use the rtl_tcp server for local sharing instead.

Environment Variables (Windows)

CMD: set RUST_LOG=info then run the command separately. PowerShell: $env:RUST_LOG = "info"; cargo run --release --example rtl_tcp

🏗 Building & Installation

git clone https://github.com/mattdelashaw/rtlsdr-next
cd rtlsdr-next
# Install the library and binaries globally
cargo install --path .

For maximum Pi 5 performance, set the target CPU explicitly:

RUSTFLAGS="-C target-cpu=native" cargo build --release

On x86_64, target-cpu=native is not recommended — LLVM already auto-vectorizes well, and on Zen 4 CPUs AVX-512 activation causes frequency throttling that hurts sustained DSP throughput.

▶️ Usage

Unified Daemon (recommended)

rtlsdr-daemon runs a single hardware driver instance and serves any combination of protocols simultaneously. This is the recommended deployment for anything beyond a single-client use case.

# Minimal — rtl_tcp only (SDR++, GQRX, OpenWebRX+)
rtlsdr-daemon --rtl-tcp 0.0.0.0:1234

# Both servers simultaneously
rtlsdr-daemon --rtl-tcp 0.0.0.0:1234 --websdr 0.0.0.0:8080

# With TLS on the WebSDR server (wss://)
rtlsdr-daemon --websdr 0.0.0.0:8080 \
  --cert /etc/letsencrypt/live/yourdomain.com/fullchain.pem \
  --key  /etc/letsencrypt/live/yourdomain.com/privkey.pem

# From a config file (see Configuration section below)
rtlsdr-daemon -c /etc/rtlsdr-next/config.toml

# Config file with a CLI override (--gain overrides the file value)
rtlsdr-daemon -c /etc/rtlsdr-next/config.toml --gain 25.0

Full CLI reference:

Options:
  -c, --config <PATH>          TOML config file
      --device <INDEX>         USB device index [default: 0]
      --sample-rate <HZ>       Hardware sample rate [default: 1536000]
      --freq <HZ>              Initial center frequency [default: 101100000]
      --gain <DB>              Initial RF gain in dB [default: 30.0]
      --ppm <PPM>              Crystal PPM correction [default: 0]
      --bias-t                 Enable bias tee on startup
      --buffers <N>            USB transfer buffer count [default: 16]
      --buffer-size <BYTES>    USB transfer buffer size [default: 262144]
      --rtl-tcp <ADDR>         Enable rtl_tcp server
      --websdr <ADDR>          Enable WebSDR server
      --unix <PATH>            Enable Unix socket server (Unix only)
      --cert <PATH>            TLS certificate PEM (enables wss://)
      --key <PATH>             TLS private key PEM
      --log-level <LEVEL>      error|warn|info|debug|trace [default: info]
  -h, --help
  -V, --version

📻 Independent Virtual VFOs

When multiple browser clients connect to the WebSDR server, each gets its own DSP pipeline with a dedicated Numerically Controlled Oscillator (NCO). Clients can tune independently to any frequency within the hardware's 1.536 MHz capture window without triggering a hardware retune — the NCO shifts the spectrum in software for each client independently.

If a client tunes outside the current hardware window, the daemon automatically recenters the hardware and all clients recompute their NCO offsets. Clients already listening within the new window hear no interruption.

⚙️ Configuration File

Copy config/default.toml from the repository as a starting point:

[hardware]
device_index  = 0
sample_rate   = 1_536_000   # Hz — must divide evenly to 48000 for WebSDR
initial_freq  = 101_100_000 # Hz — 101.1 MHz
initial_gain  = 30.0        # dB
ppm           = 0
bias_t        = false

[stream]
num_buffers  = 16       # increase if you hear dropouts
buffer_size  = 262144   # bytes, must be multiple of 512

[servers]
rtl_tcp     = "0.0.0.0:1234"
websdr      = "0.0.0.0:8080"
# unix_socket = "/tmp/rtlsdr.sock"  # uncomment to enable (Unix only)

[tls]
# cert = "/etc/letsencrypt/live/yourdomain.com/fullchain.pem"
# key  = "/etc/letsencrypt/live/yourdomain.com/privkey.pem"

Place it at /etc/rtlsdr-next/config.toml (system-wide) or ~/.config/rtlsdr-next/config.toml (per-user) and run:

rtlsdr-daemon -c /etc/rtlsdr-next/config.toml

🔄 Running as a systemd Service (Pi 5 / Linux)

# /etc/systemd/system/rtlsdr-daemon.service
[Unit]
Description=rtlsdr-next unified daemon
After=network.target

[Service]
ExecStart=/usr/local/bin/rtlsdr-daemon -c /etc/rtlsdr-next/config.toml
Restart=on-failure
RestartSec=5
User=pi

[Install]
WantedBy=multi-user.target

sudo systemctl enable --now rtlsdr-daemon
sudo journalctl -u rtlsdr-daemon -f

Standalone Tools

The individual binaries remain available for single-protocol deployments or when you don't need the daemon's multi-client capability.

Command	Description
`rtl_tcp`	Standard RTL-SDR TCP server. Compatible with OpenWebRX+, GQRX, SDR++. Supports `-a/--address` and `-p/--port`.
`websdr`	WebSocket SDR server. Streams decoded audio (48kHz PCM) and waterfall data. Supports `-a/--address`, `-p/--port`, and TLS/SSL (`wss://`).

# Start rtl_tcp server on all interfaces, port 1234
rtl_tcp --address 0.0.0.0 --port 1234

# Start WebSDR server (standard ws://)
websdr --address 0.0.0.0 --port 8080

# Start WebSDR server with TLS (wss://)
websdr --address 0.0.0.0 --port 8080 --cert cert.pem --key key.pem

🔒 Secure WebSDR (wss://)

To support secure connections (required by many modern browsers and iOS App Transport Security when using public domains), you can provide a PEM-encoded certificate and private key.

Using Let's Encrypt: If you have a domain pointing to your host, you can use certbot to generate a certificate and point websdr to the generated files:

websdr --port 8080 --cert /etc/letsencrypt/live/yourdomain.com/fullchain.pem --key /etc/letsencrypt/live/yourdomain.com/privkey.pem

Using Self-Signed (for testing):

openssl req -x509 -newkey rsa:4048 -keyout key.pem -out cert.pem -days 365 -nodes

Note: iOS clients will require you to manually trust the root certificate if using self-signed.

Development Examples

These demonstrate library usage and provide quick functional tests. Run them with cargo run --example.

Example	Description
`hw_probe`	Start here. Full driver smoke test — init, tune, stream 1s, report throughput. Clear PASS/FAIL output.
`fm_radio`	FM receiver with built-in demodulator. Outputs audio via the system audio device.
`monitor`	Continuous stream monitor — logs average signal magnitude and throughput every 10 blocks.

# Smoke test — run this first
RUST_LOG=info cargo run --release --example hw_probe

# FM radio
RUST_LOG=info cargo run --release --example fm_radio -- --freq 97.1e6

Diagnostic Tools

These are raw USB tools used during driver development. They bypass the driver entirely and speak directly to the hardware via libusb. Run them when you need to determine whether a problem is in the driver or the hardware.

Example	Description
`diag_write`	Scans all 8 USB control blocks for register responses. Use when debugging Pipe errors.
`diag_i2c`	Probes demod read/write encoding patterns and validates the dummy-read flush requirement.
`diag_demod`	Re-acquisition pulse — tries up to 5 times to reclaim a busy/crashed USB interface.
`diag_sys`	Dumps registers from USB/SYS/DEMOD blocks using both encoding patterns.
`diag_raw_clone`	Replays the exact V4 init sequence raw. The definitive "hardware vs driver" test.

# Is it the hardware or the driver?
RUST_LOG=debug cargo run --release --example diag_raw_clone

# Device stuck as busy after a crash?
cargo run --release --example diag_demod

# Pipe errors on demod writes?
cargo run --release --example diag_i2c

🧪 Testing

# Unit tests (no hardware required)
cargo test

# Release mode (also runs NEON/scalar agreement tests on aarch64)
cargo test --release

Hardware-in-the-loop tests require a connected dongle and are run manually via the examples.

⚙️ Environment Variables

Variable	Default	Description
`RUST_LOG`	`warn`	Log level: `error`, `warn`, `info`, `debug`, `trace`
`RTLSDR_DEVICE_INDEX`	`0`	USB device index if multiple dongles are connected

Baseline Comparisons

Measurements taken on an ARM64 host comparing the rtlsdr-next Rust implementation against the librtlsdr (v4 branch) C baseline using 256KB blocks:

Benchmark Task	librtlsdr (C)	rtlsdr-next (Rust)
Standard Converter (256KB)	172.32 µs	164.35 µs
Throughput	1.4168 GiB/s	1.4855 GiB/s
Range [min ... max]	[172.29 µs ... 172.36 µs]	[164.13 µs ... 164.78 µs]

V4 Inverted Converter	256.07 µs	170.81 µs
Throughput	976.30 MiB/s	1.4293 GiB/s
Range [min ... max]	[256.02 µs ... 256.14 µs]	[170.78 µs ... 170.84 µs]

Decimation (FIR/4)	N/A	778.40 µs
Throughput	N/A	336.77 Melem/s

Decimation (FIR/8)	N/A	615.37 µs
Throughput	N/A	425.99 Melem/s

Decimation (FIR/16)	N/A	534.04 µs
Throughput	N/A	490.87 Melem/s

Full Pipeline (FIR/4)	N/A	925.26 µs
Throughput	N/A	270.19 MiB/s

Full Pipeline (FIR/8)	N/A	761.17 µs
Throughput	N/A	328.44 MiB/s

Full Pipeline (FIR/16)	N/A	678.84 µs
Throughput	N/A	368.27 MiB/s

Note: The performance gain in conversion is primarily due to moving from cache-latency-bound lookup tables to instruction-parallel arithmetic, which better utilizes modern out-of-order CPU pipelines.

🗺 Roadmap - Phaseshifting

📝 Reference Material

Tuner Datasheets and Drivers

Another Rust Implementation

RTL-SDR-RS - probably human community driven project

Rafael Micro R820T / R820T2 / R828D

R820T Datasheet (leaked draft) — gold standard for register maps
RTL-SDR Blog V4 Guide — V4-specific hardware details
tuner_r82xx.c — reference C implementation

Elonics E4000 (legacy, up to 2.2 GHz, gap ~1.1 GHz)

Fitipower FC0012 / FC0013 (budget nano dongles)

tuner_fc0012.c

RTL2832U

Osmocom RTL-SDR Wiki — the definitive reference
librtlsdr.c — comments are essentially the RTL2832U register manual

📜 License

Licensed under the Apache License, Version 2.0.

Name		Name	Last commit message	Last commit date
Latest commit History 126 Commits
.claude/rules		.claude/rules
.gemini		.gemini
.github/workflows		.github/workflows
assets		assets
benches		benches
config		config
examples		examples
src		src
wix		wix
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
LICENSE		LICENSE
README.md		README.md
build.rs		build.rs
dist-workspace.toml		dist-workspace.toml

Folders and files

Latest commit

History

Repository files navigation

rtlsdr-next 📡

✅ Confirmed Working Hardware

🚀 Key Features

🛠 Hardware: The V4 Deep Dive

🚀 Performance

🎛 Performance Tuning & Latency

Reducing Frequency Switching Lag

Advanced Configuration (StreamConfig)

📋 Prerequisites

🔌 USB Permissions

Windows

Environment Variables (Windows)

🏗 Building & Installation

▶️ Usage

Unified Daemon (recommended)

📻 Independent Virtual VFOs

⚙️ Configuration File

🔄 Running as a systemd Service (Pi 5 / Linux)

Standalone Tools

🔒 Secure WebSDR (wss://)

Development Examples

Diagnostic Tools

🧪 Testing

⚙️ Environment Variables

Baseline Comparisons

🗺 Roadmap - Phaseshifting

📝 Reference Material

Tuner Datasheets and Drivers

RTL2832U

📜 License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 8

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Advanced Configuration (`StreamConfig`)

Packages