Glossary
rtl_433 sits at the boundary between radio hardware and decoded sensor data, so its documentation mixes signal-processing terms with software terms. This page defines the words you will meet most often. Each entry is short and self-contained; jump straight to the one you need.
These definitions describe how the terms are used within rtl_433. Several of them (OOK, IQ, ISM) are general radio terms with broader meanings elsewhere — here they are scoped to what the tool actually does.
ISM band
The ISM bands (Industrial, Scientific, and Medical bands) are ranges of radio spectrum set aside for low-power, license-free devices. Most of the inexpensive sensors rtl_433 targets transmit here. The project describes itself as:
a generic data receiver, mainly for the 433.92 MHz, 868 MHz (SRD), 315 MHz, 345 MHz, and 915 MHz ISM bands.
Which band a given device uses depends largely on its region: 433.92 MHz and 868 MHz (the European SRD band) are common in Europe, while 315 MHz and 915 MHz are common in North America. You tell rtl_433 which frequency to tune with -f:
# Tune to the 868 MHz band at a 1024 ksps sample rate
rtl_433 -f 868M -s 1024k
A single tuner can only sit on one frequency at a time, but you can pass -f more than once and let rtl_433 hop between frequencies on a timer with -H:
# Alternate between two 433 MHz channels, hopping every 15 seconds
rtl_433 -f 433.53M -f 434.02M -H 15
OOK / ASK / FSK
These are the modulation schemes — the way a transmitter encodes bits into a radio signal — that rtl_433 knows how to demodulate.
- OOK (On-Off Keying) switches the carrier fully on and off. A pulse of carrier is one symbol; a gap of silence is the other. It is the simplest and most common scheme among cheap ISM sensors.
- ASK (Amplitude-Shift Keying) encodes data in the amplitude of the carrier. OOK is the special, all-or-nothing case of ASK, and in
rtl_433the two are handled by the same amplitude demodulator. - FSK (Frequency-Shift Keying) encodes data by shifting the carrier between two (or more) frequencies. It needs a frequency demodulator rather than an amplitude one.
On top of the modulation, devices apply a coding that maps pulse/gap timing to bits — for example Manchester code, PCM (NRZ), RZ, PPM (pulse-position) or PWM (pulse-width). rtl_433 exposes these as named modulation modes (see flex decoder below), such as OOK_PWM, OOK_PPM, OOK_MC_ZEROBIT, FSK_PCM, and FSK_PWM.
RTL-SDR
RTL-SDR refers to the family of cheap USB software-defined radio receivers built around the Realtek RTL2832U chip — originally sold as DVB-T television dongles. They are the default, lowest-cost way to feed rtl_433:
Works with RTL-SDR and/or SoapySDR.
When you run rtl_433 with no input file, it opens the first connected RTL-SDR device automatically. The native sample format produced by these receivers is .cu8 (see IQ samples).
SoapySDR
SoapySDR is a vendor-neutral abstraction layer — a common API that hides the differences between many SDR devices. Building rtl_433 against SoapySDR lets it drive hardware beyond the RTL2832 dongles, including LimeSDR, PlutoSDR, HackRF One, and remote/networked receivers. The two backends coexist: a single build can talk to RTL-SDR directly and to anything SoapySDR supports.
You do not have to choose one. RTL-SDR is the built-in fast path for the common dongles; SoapySDR is the optional, broader path for everything else. If you only own an RTL2832 dongle, the plain RTL-SDR backend is all you need.
Decoder / protocol
A decoder (also called a device protocol) is the piece of code that recognises one device family's signal and turns its bits into named fields — temperature, humidity, battery state, sensor ID, and so on. rtl_433 ships with a large library of these (300+ protocols spanning weather stations, thermometers, TPMS tire sensors, energy meters, and remotes).
Each decoder has a number. List them with -R help and enable a specific one with -R <number>:
# Print the numbered list of decoders, then run only decoder 8
rtl_433 -R help
rtl_433 -R 8
Decoded output is emitted as structured records. In JSON form, every message carries at least a timestamp and a model string; the model name follows the convention:
Human readable string concisely describing the device by manufacturer name and manufacturers model designation
in the format "<Manufacturer>-<Model>". Many messages also carry a mic field recording how integrity was checked — CRC, CHECKSUM, or PARITY.
Flex decoder
The flex decoder is a general-purpose, user-defined decoder you configure on the command line with -X (or in a config file) instead of writing C code. It is how you decode a device that has no built-in protocol yet. From the man page:
Add a general purpose decoder (prepend
-R 0to disable all decoders).
A flex spec is a comma-separated list of key=value fields describing the signal's timing. The main keys are:
| Key | Meaning |
|---|---|
n= | A name for the decoder (shown in output) |
m= | Modulation mode, e.g. OOK_PWM, OOK_PPM, FSK_PCM |
s= | Short pulse/gap width, in microseconds |
l= | Long pulse/gap width, in microseconds |
g= | Maximum gap size before new row of bits [us] |
r= | Maximum gap size before End Of Message [us] (reset) |
t= | Maximum pulse deviation [us] (tolerance, optional) |
y= | Nominal width of sync pulse [us] (optional) |
bits= | Only match if at least one row has the given bit count |
get= | Extract and label fields from the decoded bits |
The block below is an illustrative example of the syntax, not a working spec for any real device. The numbers are placeholders; real timings must be measured from the target signal (see the pulse analyzer).
rtl_433 -R 0 -X 'n=MySensor,m=OOK_PWM,s=300,l=930,r=11000,g=0,bits=36'
Anything you can pass on the command line you can also keep in a config file read with -c. A flex spec lives there on a decoder line (decoder n=...,m=...,...) — the same key=value syntax as -X, just without the option flag — which is handier than a long one-line -X string for a spec you reuse. See the project's example configuration.
IQ samples
IQ stands for "In-phase / Quadrature" — the raw complex-valued data an SDR receiver produces:
I/Q stands for 'In-phase / Quadrature', the raw data format used by SDR receivers and transmitters.
Each sample is a pair of numbers, one I value and one Q value, typically 8 to 16 bits each. Representing the signal as a complex pair lets an SDR use a usable bandwidth equal to its sample rate.
When you save raw capture to a file, the filename extension names the format. The convention is: c for complex, then the numeric type (u unsigned, s signed, f float), then the bits per value:
| Format | Meaning |
|---|---|
cu8 | Complex, unsigned, 8-bit per value (16 bits/sample) |
cs16 | Complex, signed, 16-bit per value (32 bits/sample) |
cf32 | Complex, float, 32-bit per value (64 bits/sample) |
The 'native' format for RTL-SDR receivers is
.cu8, for other receivers likely.cs16.
Capturing to a file lets you re-run decoders offline without the radio attached:
# Record raw IQ to a .cu8 file, then decode it later from that file
rtl_433 -w capture.cu8
rtl_433 -r capture.cu8
Pulse
A pulse is one on/off (or frequency-shift) event in the demodulated signal — the basic timing unit rtl_433 works from. Before any decoder runs, the demodulator reduces the IQ stream to a sequence of pulse widths and the gaps between them, measured in microseconds. A decoder then interprets those widths and gaps as bits.
The pulse analyzer (-A) is the tool for studying an unknown signal's pulses so you can write a flex decoder for it:
Pulse Analyzer. Enable pulse analysis and decode attempt.
# Run only the pulse analyzer on a captured file (no built-in decoders)
rtl_433 -R 0 -A -r capture.cu8
The analyzer reports the short/long pulse widths, gap, and reset timing it sees — exactly the s=, l=, g=, and r= values you then plug into an -X flex spec.