Also known as: librtlsdr, rtl-sdr library, Osmocom rtl-sdr
librtlsdr is the open-source Osmocom host library that drives Realtek RTL2832U demodulator chips as software-defined radios, streaming raw 8-bit IQ samples to an application over USB.1 It is the C library at the heart of the entire RTL-SDR phenomenon: the code that discovered the chip’s undocumented “raw sampling” mode and exposed it as a general-purpose receiver API.
How it works
An application opens a device by index with rtlsdr_open, then configures it through a
uniform set of setters: rtlsdr_set_center_freq, rtlsdr_set_sample_rate,
rtlsdr_set_tuner_gain, and the frequency-correction and bias-tee controls. Under the
hood the library speaks to two chips — the RTL2832U itself and whichever tuner is
fitted (R820T, E4000, FC0013) — over libusb, translating high-level calls into the
right register writes for that tuner. The 2832U’s ADC captures at up to ~3.2 MS/s
(2.4 MS/s is the reliable ceiling) and delivers interleaved unsigned-8-bit I and Q
bytes.
The defining feature is its asynchronous read-callback model. The application calls
rtlsdr_read_async with a function pointer; librtlsdr spins a libusb transfer loop on
that thread and invokes the callback each time a buffer fills, handing over a pointer and
a length. This is a classic callback versus stream API
design: the library owns the timing and “pushes” data, rather than the app “pulling” it.
A simpler synchronous rtlsdr_read_sync also exists for quick captures, but the async
path is what real-time decoders use because it keeps USB transfers in flight and avoids
sample overruns.
Variants
The library ships with rtl_sdr (dump raw IQ to a file or pipe), rtl_fm (a compact
narrowband FM/AM demodulator), rtl_power (a swept power scanner), rtl_test, and —
most consequentially — rtl_tcp. That server reads from librtlsdr locally and re-serves
the byte stream and control commands over TCP, letting a remote client drive the dongle
as if it were attached; see rtl_tcp. Several forks exist (notably
one maintained by the rtl-sdr.com team, and one under librtlsdr’s own name) that add
direct-sampling tweaks, newer tuner support, and bias-tee fixes; they share the same
core API.
In practice
Because the API is small and stable, librtlsdr became the lowest common denominator that
almost everything else builds on. On Windows the WinUSB/Zadig driver has to replace the
DVB-T driver first before librtlsdr can claim the device. The bindings surface it into
higher layers: gr-osmosdr wraps it as a GNU Radio source, and
SoapySDR exposes it through a SoapyRTLSDR plugin, so most
applications never call librtlsdr directly — they inherit it.
Relevance to SDR
librtlsdr is arguably the single most important piece of software in hobbyist SDR: by turning a ~$25 RTL-SDR dongle into a usable IQ source it put a receiver on millions of desks and seeded the whole open-radio toolchain. For a decoder author it is a case study in host-library design — a thin, chip-specific driver that normalizes gain, tuning, and rate control and then gets out of the way of the sample stream.
GopherTrunk consumes RTL-SDR hardware, but as a pure-Go application it does not link the C
librtlsdr directly; it takes IQ over the network via rtl_tcp-style
and SoapySDR-style transports (or from recorded IQ files for
replay). Functionally, though, GT sits exactly where an rtlsdr_read_async callback would:
it accepts pushed 8-bit IQ buffers, converts them to complex baseband, and feeds its
rate-invariant decode chain — the same producer/consumer contract librtlsdr defined, moved
one hop up the stack.
Sources
-
rtl-sdr project wiki — Osmocom, the origin and documentation of the librtlsdr library, its raw-sampling discovery, and the rtl_sdr/rtl_tcp tools. ↩