rtlsdr-nusb
Rust-native RTL-SDR driver using nusb, licensed under Apache-2.0. No librtlsdr or libusb dependency. The device, streamer, close/shutdown and sync/async APIs follow hydrasdr-rs.
Hardware and controls
- RTL2832U with R820T/R820T2/R860-compatible or R828D tuners.
- R828D input selection and RTL-SDR Blog V4 HF upconversion/filter switching.
V4 detection uses USB manufacturer
RTLSDRBlogand productBlog V4. - Frequency, sample rate, automatic/manual tuner gain, ppm correction, GPIO 0 bias tee (off by default), and I/Q direct sampling on suitably wired boards.
- Typed raw unsigned eight-bit I/Q blocks or converted
Complex32samples. - Standard USB IDs
0bda:2832/0bda:2838, index/serial selection, and custom VID/PID matching through the builder.
The current range is 900,001–3,200,000 complex samples/s. Rates above 2.4 MS/s may drop samples. Positive ppm correction raises the minimum accepted rate slightly (to 900,440 samples/s at +488 ppm). Tuner operation starts at 28.8 MHz; lower frequencies require Blog V4 or a suitable direct-sampling input. The nominal upper limit is 1.766 GHz, subject to the individual tuner's PLL locking. Manual gain is an approximation based on the reference driver's LNA/mixer steps, not librtlsdr's gain table. Generic R828D boards currently assume a 28.8 MHz tuner crystal; boards with a different tuner crystal are not supported.
Hardware validation so far: an R820T-family 0bda:2838 receiver on Linux, with
blocking/async capture, retuning at 100, 433.92 and 1090 MHz, sample rates of
1.024, 2.048 and 2.4 MS/s, stop/restart, raw IQ and final-owner cleanup.
R828D/Blog V4, direct sampling and bias power switching need hardware validation.
Other tuners (E4000, FC0012/13, FC2580) and EEPROM programming are not implemented.
No Seify integration is included.
Blocking capture
Requires Rust 1.88 or newer. Add rtlsdr-nusb to your dependencies (or use a
local path dependency before the first crates.io release).
use ;
use Duration;
let mut device = builder
.frequency_hz
.sample_rate_hz
.open.wait?;
let mut rx = device.rx_stream?;
rx.start.wait?;
let mut samples = ;
let count = rx.read.wait?;
println!;
rx.close.wait?;
device.shutdown.wait?;
# Ok::
Run cargo run --example rx_sync for a complete example.
Async capture
Enable the smol feature for executor-independent native discovery/open/setup,
or tokio when using a Tokio runtime. With both enabled, nusb uses its executor-independent smol backend. Native
control transfers and streaming themselves use nusb's completion mechanism.
The blocking API needs neither feature nor a runtime.
[]
= { = "0.2", = ["smol"] }
= "2"
use ;
block_on?;
# Ok::
Run cargo run --features smol --example rx_async.
Native callers may mix .wait() and .await() sequentially on the same stream;
both use the same persistent queue. The timeout argument applies only to
blocking reads. Wrap awaited reads in your runtime's timeout when needed;
canceling a pending read leaves the queue available for the next read.
Raw IQ
Select .raw_iq() on Device::builder() and call
rx.next_block(Some(timeout)).wait()? or rx.next_block(None).await?.
A successful read returns Some(SampleBlock), exposing raw_bytes() and
sample_count(). Bytes are interleaved I, Q in 0..=255; the float mode maps
each component with (value - 127.5) / 127.5. The borrowed block holds one USB
buffer, which is resubmitted on the next read. Blocking timeout returns None.
Float reads return the number written and may fill only part of the output slice.
Eight 256 KiB USB buffers are retained per active stream. Steady-state reads allocate neither an output buffer nor a boxed future. Statistics count observed USB completions and controlled discards; the RTL-SDR data format has no sequence numbers, so device-side sample loss cannot be measured by these counters.
Ownership and cleanup
- A device permits one stream claim. Creating a stream is dormant;
startenables reception. A stopped stream retains its claim and can restart. - The stream owns a shared device session and remains usable after
Deviceis dropped. Bias power, if enabled, stays on until device shutdown/final-owner drop. closeconsumes the stream, retires its queue, stops reception and releases the claim. Dropping even an unpolled close operation performs fallback cleanup.Device::shutdownreturnsBusywhile a stream exists. After closing the stream, shutdown disables reception and bias power and powers down the tuner and demodulator. It is terminal once started, retryable after cancellation or failure, and idempotent after success. Unpolled shutdown has no effect.- Final-owner drop performs best-effort cleanup: blocking on native targets, scheduled in the background on WebUSB. Explicit close/shutdown reports errors.
- Failed or canceled configuration leaves hardware state unknown. Reapply a
complete
Configto recover; the last successful configuration remains available fromDevice::config(). Overlapping control sequences returnBusy. - Queued samples can predate a live retune. Stop, configure, then restart to discard old submissions. The queue is retained across a normal restart.
Platforms
Linux needs permission to access the USB device. Opening uses nusb's kernel interface detach/claim support. Windows needs a WinUSB-compatible driver on the RTL-SDR interface. macOS, Linux and Windows are included in the CI test matrix; only Linux hardware operation has been tested locally.
WebUSB is compile-checked for wasm32-unknown-unknown. The application's
.cargo/config.toml must include:
[]
= ["--cfg=web_sys_unstable_apis"]
Call Device::request_permission().await from a browser user gesture before
opening, or use the builder's permission method for custom IDs/serial selection.
WebUSB operations are async only. Transfer cancellation is unavailable there;
restart drains old submissions, and drop cleanup finishes in a background task.
Browser/hardware operation has not yet been tested.
Development and releases
Hardware tests are ignored by default. With exclusive access to a receiver:
RTLSDR_SERIAL=00000001
CI checks formatting, Clippy, tests/docs with default/smol/tokio/all features,
Rust 1.88, WebUSB compilation and the distributable crate. A pushed v<version>
tag runs the same checks, verifies the Cargo version, publishes to crates.io
through trusted publishing, then creates a GitHub release containing the crate
archive.
Acknowledgment and license
Based on webrtlsdr. Distributed under Apache-2.0.