Basic rtl_433 operation

The principle buildings blocks of rtl_433 are: Inputs, Loaders, Processing, Analysis, Decoders, Dumpers, Outputs.

At startup rtl_433 will read config files and parse command line arguments, then it will loop through these steps:

Inputs: rtl_tcp, RTL-SDR, SoapySDR
Loaders: Raw data files (cu8, cs16, ...)
Processing: OOK and FSK demod, pulse detector, slicers, coding
Analysis: Show statistics on pulses
Decoders: Over 200 protocols
Dumpers: Raw data files (cu8, cs16, ..., sr, ...)
Outputs: Screen (kv), JSON, CSV, MQTT, Influx, UDP (syslog), HTTP

rtl_433 will either acquire a live signal from an input or read a sample file with a loader. Then process that signal, analyse it's properties (if enabled) and write the signal with dumpers (if enabled). The raw data is run through decoders to produce decoded output data.

Inputs

Possible inputs are RTL-SDR, SoapySDR, and rtl_tcp.

Inputs are selected with the -d option:

  [-d <RTL-SDR USB device index> | :<RTL-SDR USB device serial> | <SoapySDR device query> | rtl_tcp | help]

RTL-SDR

For RTL-SDR use the -d option as:

  [-d <RTL-SDR USB device index>] (default: 0)
  [-d :<RTL-SDR USB device serial (can be set with rtl_eeprom -s)>]

If RTL-SDR support is compiled in (see the first line of rtl_433 -V) the default input will be the first available RTL-SDR device. This can also explicitly be selected with rtl_433 -d 0. Use e.g. rtl_433 -d 1 to select the second device.

If you have set a serial number on your device you can use that number prefixed with a colon to select a device, e.g. rtl_433 -d :NESDRSMA.

The sample format read from RTL-SDR is always CU8.

SoapySDR

For SoapySDR use the -d option as:

  [-d ""] Open default SoapySDR device
  [-d driver=rtlsdr] Open e.g. specific SoapySDR device

If SoapySDR support is compiled in (see the first line of rtl_433 -V) and RTL-SDR is not then the default input will be the first available SoapySDR device. This can also explicitly be selected with rtl_433 -d "".

Otherwise specify a driver string to select the SoapySDR device. Use e.g. rtl_433 -d "driver=rtlsdr" to use RTL-SDR over Soapy.

Usual SoapySDR driver string are e.g. "driver=remote,remote=tcp://192.168.2.1:55132", "driver=plutosdr", etc.

The sample format read from SoapySDR is likely CS16. A sample format of CU8 is tried first, but unlikely to be supported by SoapySDR drivers.

rtl_tcp

For rtl_tcp use the -d option as:

  [-d rtl_tcp[:[//]host[:port]] (default: localhost:1234)
    Specify host/port to connect to with e.g. -d rtl_tcp:127.0.0.1:1234

The rtl_tcp input is always available. The default host is "localhost" and default port is "1234".

Use e.g. rtl_433 -d rtl_tcp:192.168.2.1 or rtl_433 -d rtl_tcp:192.168.2.1:2143 to select a specific source.

Input Gain

The input device gain can be set with the -g option:

  [-g <gain>] (default: auto)
    For RTL-SDR: gain in dB ("0" is auto).
    For SoapySDR: gain in dB for automatic distribution ("" is auto), or string of gain elements.
    E.g. "LNA=20,TIA=8,PGA=2" for LimeSDR.

The default gain setting will be automatic gain (AGC enabled).

For RTL-SDR the gain is given in dB, where "0" selects automatic gain.

For SoapySDR a gain argument of "" selects automatic gain, a gain value in dB can be used for automatic distribution to the gain stages, and string of gain elements sets the given gain stages individually.

Use e.g. -g "LNA=20,TIA=8,PGA=2" for LimeSDR.

Antenna and settings

For SoapySDR the antenna and various other settings can be selected with -t:

  [-t <settings>] apply a list of keyword=value settings for SoapySDR devices
       e.g. -t "antenna=A,bandwidth=4.5M,rfnotch_ctrl=false"

Center Frequency

The center frequency can be selected with -f:

  [-f <frequency>] Receive frequency(s) (default: 433920000 Hz)

The default frequency is 433.92 MHz and can be explicitly requested with -f 433.92M.

You can give a frequency in Hz, like -f 433920000 or use suffixes of k, M, or G, e.g. -f 433920k, or -f 433.92M.

Other interesting frequencies are e.g. -f 868M, -f 315M, -f 345M, -f 915M. If you fine tune the frequency to your sender device you should avoid hitting the sender frequency dead center. The resulting DC (direct current) signal is often attenuated by receivers and hard to make out when analysing samples. A small offset of 10 kHz to 50 kHz works best.

The -f option can be used multiple times to set up a list of frequency to hop. Use the -H option to set up the time to stay on each frequency or list on -H per -f to set a stay time for each frequency. (The last hop time given will be the default for all frequencies.)

PPM correction

A PPM error correction value can be given with -p:

  [-p <ppm_error] Correct rtl-sdr tuner frequency offset error (default: 0)

The PPM error correction is most commonly used to counter the drift in warmed up RTL-SDR devices.

Sample rate

A sample rate value can be given with -s:

  [-s <sample rate>] Set sample rate (default: 250000 Hz)

The default sample rate is 250 kHz and can be explicitly requested with -s 250k.

You can give a sample rate in Hz, like -s 250000 or use suffixes of k, M, or G, e.g. -f 250k, or -f 8M. Note that the suffix is metric, the 1024000 Hz sample rate common with RTL-SDR has to be given as -s 1024k.

Decoders

Decoders can be selected with the -R and -X option:

  [-R <device> | help] Enable only the specified device decoding protocol (can be used multiple times)
       Specify a negative number to disable a device decoding protocol (can be used multiple times)
  [-X <spec> | help] Add a general purpose decoder (prepend -R 0 to disable all decoders)

By default all decoders with proper validity checking are enabled.

You can disable selected decoders with any number of -R -<number> options. E.g. use rtl_433 -R -8 -19 to disable the LaCrosse and Nexus decoders.

Some decoders have little validity checking and may share very common signal characteristics. This will result in lots of false-positive decodes. These decoders are not enabled by default and you need to explicitly enable them with -R <number>.

You can enable only selected decoders with any number of -R <number> options. Note that this will override the default and not select any decoder by default. E.g. use rtl_433 -R 8 19 to enable only the LaCrosse and Nexus decoders.

An output line of Registered <n> out of <N> device decoding protocols will tersely show the enabled decoders.

Lastly the -X option can be used to add a custom flex decoder. This can be used with -R 0 to disable all default decoders. E.g. rtl_433 -R 0 -X "<spec>" will only run your given custom decoder.

Flex Decoder

A flexible general purpose decoder can be added with the -X option:

  [-X <spec>] to add a flexible general purpose decoder.
      <spec> is "key=value[,key=value...]"

Most common keys are:

name=<name> (or: n=<name>)
modulation=<modulation> (or: m=<modulation>)
short=<short> (or: s=<short>)
long=<long> (or: l=<long>)
sync=<sync> (or: y=<sync>)
reset=<reset> (or: r=<reset>)
gap=<gap> (or: g=<gap>)
tolerance=<tolerance> (or: t=<tolerance>)

where: <name> can be any descriptive name tag you need in the output.

<modulation> is one of:

OOK_MC_ZEROBIT : Manchester Code with fixed leading zero bit
OOK_PCM : Pulse Code Modulation (RZ or NRZ)
OOK_PPM : Pulse Position Modulation
OOK_PWM : Pulse Width Modulation
OOK_DMC : Differential Manchester Code
OOK_PIWM_RAW : Raw Pulse Interval and Width Modulation
OOK_PIWM_DC : Differential Pulse Interval and Width Modulation
OOK_MC_OSV1 : Manchester Code for OSv1 devices
FSK_PCM : FSK Pulse Code Modulation
FSK_PWM : FSK Pulse Width Modulation
FSK_MC_ZEROBIT : Manchester Code with fixed leading zero bit

<short>, <long>, <sync> are nominal modulation timings in us, <reset>, <gap>, <tolerance> are maximum modulation timings in us:

PCM
- short: Nominal width of pulse [us]
- long: Nominal width of bit period [us]
PPM
- short: Nominal width of 0 gap [us]
- long: Nominal width of 1 gap [us]
PWM
- short: Nominal width of 1 pulse [us]
- long: Nominal width of 0 pulse [us]
- sync: Nominal width of sync pulse [us] (optional)
common
- gap: Maximum gap size before new row of bits [us]
- reset: Maximum gap size before End Of Message [us]
- tolerance: Maximum pulse deviation [us] (optional).

Additional options are:

bits=<n> : only match if at least one row has <n> bits
rows=<n> : only match if there are <n> rows
repeats=<n> : only match if some row is repeated <n> times.
- use opt>=n to match at least <n> and opt<=n to match at most <n>
invert : invert all bits
reflect : reflect each byte (MSB first to MSB last)
match=<bits> : only match if the <bits> are found
preamble=<bits> : match and align at the <bits> preamble.
- <bits> is a row spec of {<bit count>}<bits as hex number>
unique : suppress duplicate row output
countonly : suppress detailed row output

E.g. -X "n=doorbell,m=OOK_PWM,s=400,l=800,r=7000,g=1000,match={24}0xa9878c,repeats>=3" specifies:

name is doorbell
modulation is OOK_PWM
width of a short bit is 400 µs
width of a long bit is 800 µs
maximum gap width to reset is 7000 µs
maximum gap width to new row is 1000 µs
the data needs to contain the match of 24 bits 0xa9878c
the data needs to repeat at least 3 times

To extract some bits:

Example: get=battery:@4:{1}:[0:Ok 1:Empty] Using colon separated keys:

name (battery)
at which bit to start (@4)
how many bits to read ({1})
optional mapping (map 0 to Full, map 1 to Empty)
or an optional format specifier (%x)

A key starting with % is a format specifier for the KV output, in practice it will be something like %x, %X, %04x.

See the conf folder for some examples of flex specs.

Analysis

Signal data can be analysed with -A, -a, sample data can be dumped with -S:

  [-a] Analyze mode. Print a textual description of the signal.
  [-A] Pulse Analyzer. Enable pulse analysis and decode attempt.
       Disable all decoders with -R 0 if you want analyzer output only.
  [-S none | all | unknown | known] Signal auto save. Creates one file per signal.
       Note: Saves raw I/Q samples (uint8 pcm, 2 channel). Preferred mode for generating test files.

The -a option enables the (old) pulse decoder to print a textual description of the signal. The output might not be too useful, best to use the newer -A option.

The -A option enables the (new) pulse analyzer. Each received transmission will be displayed in a statistical overview. A probable coding will be inferred and attempted to decode.

The "Pulse width distribution", "Gap width distribution", and "Pulse period distribution" can tell you about the timing in the width column, and the coding in the count column.

E.g. a single (or dominant count) pulse width with two gap widths is likely PPM, E.g. a two (or dominant count) pulse widths with a sinle gap widths or single period width is likely PWM.

Disable all decoders with -R 0 if you want to view the analyzer output only.

The -S option allows you to dump received transmissions for further analysis. Use e.g. rtl_433 -S all to dump all signals or rtl_433 -S unknown to dump only signals with no successful decodes (by enabled decoders).

On file will be created per signal, see also "File names". Note: Saves raw I/Q samples CU8 (uint8 pcm, 2 channel) for RTL-SDR and CS16 (int16 pcm, 2 channel) for SoapySDR.

Loaders and Dumpers

Sample data can be loaded or dumped with -r, -w, -W, and codes verified with -y:

  [-r <filename> | help] Read data from input file instead of a receiver
  [-w <filename> | help] Save data stream to output file (a `-` dumps samples to stdout)
  [-W <filename> | help] Save data stream to output file, overwrite existing file
  [-y <code>] Verify decoding of demodulated test data (e.g. "{25}fb2dd58") with enabled devices

Read file (loaders)

Use the -r option or stdin to read signal data (instead of live input):

  [-r <filename> | help] Read data from input file instead of a receiver

Parameters are detected from the full path, file name, and extension. See also "File names".

File content and format options are: cu8, cs16, cf32 (IQ implied), and am.s16.

Write file (dumpers)

Use the -w and -W option to dump all signal data:

  [-w <filename>] Save data stream to output file (a `-` dumps samples to stdout)
  [-W <filename>] Save data stream to output file, overwrite existing file

Parameters are detected from the full path, file name, and extension. See also "File names".

File content and format options are: cu8, cs16, cf32 (IQ implied), am.s16, am.f32, fm.s16, fm.f32, i.f32, q.f32, logic.u8, ook, and vcd.

For example you can dump the live decoded pulse data to stdout with rtl_433 -w OOK:-.

Load bitbuffer code

Use the -y option to test a known code line (bitbuffer):

  [-y <code>] Verify decoding of demodulated test data (e.g. "{25}fb2dd58") with enabled devices

If you are developing or testing a decoder you can skip the device input or sample loading step and directly give a known code line (bitbuffer) to the enabled decoders.

File names

Samples recorded using the -S option will automatically be given filenames with some meta-data. The signals will be stored individually in files named g<NNN>_<FFF>M_<RRR>k.cu8 :

Parameter	Description
NNN	signal grabbed number
FFF	frequency
RRR	sample rate

File names used with -r, and -w / -W (loaders and dumpers) also follow that convention.

A center frequency is detected from the filename as (fractional) number suffixed with M, Hz, kHz, MHz, or GHz.

A sample rate is detected from the filename as (fractional) number suffixed with k, sps, ksps, Msps, or Gsps.

Parameters must be separated by non-alphanumeric chars and are case-insensitive.

File content and format are detected by th extension, possible options are:

cu8 (IQ implied)
cs16 (IQ implied)
cf32 (IQ implied)
am.s16'
am.f32
fm.s16
fm.f32
i.f32
q.f32
logic.u8
ook
vcd

Overrides can be prefixed to the actual filename, separated by colon (:). E.g. default detection by extension: path/filename.am.s16 and forced overrides: am:s16:path/filename.ext

Warning

Note that not all file types are supported/applicable by loaders or dumpers.

Outputs

Use the -F option to add outputs, use -M, -K, and -C to configure meta-data:

  [-F kv | json | csv | mqtt | syslog | null | help] Produce decoded output in given format.
       Append output to file with :<filename> (e.g. -F csv:log.csv), defaults to stdout.
       Specify host/port for syslog with e.g. -F syslog:127.0.0.1:1514
  [-M time[:<options>] | protocol | level | stats | bits | help] Add various meta data to each output.
  [-K FILE | PATH | <tag>] Add an expanded token or fixed tag to every output line.
  [-C native | si | customary] Convert units in decoded output.

Without any -F option the default is KV output. Use -F null to remove that default.

KV output

Use -F kv to add an output in KV format.

A colorful, column based output intended for screen display.

Append output to file with :<filename> (e.g. -F kv:log.txt), defaults to stdout.

Warning

Note: the kv output is not a machine-readable key-value format, use the JSON output for that.

JSON output

Use -F json to add an output in JSON format.

Universally machine-readable output.

Append output to file with :<filename> (e.g. -F json:log.json), defaults to stdout.

CSV output

Use -F csv to add an output in CSV format.

Append output to file with :<filename> (e.g. -F csv:log.csv), defaults to stdout.

Warning

Note: the csv output is not recommended for post-processing, use the JSON output for a machine-readable format.

MQTT output

Use -F mqtt to add an output in MQTT format.

Specify MQTT server with e.g. -F mqtt://localhost:1883.

Add MQTT options with e.g. -F "mqtt://host:1883,opt=arg". Supported MQTT options are: user=foo, pass=bar, retain[=0|1], <format>[=<topic>].

Supported MQTT formats: (default is all formats)

events: posts JSON event data
states: posts JSON state data
devices: posts device and sensor info in nested topics

The <topic> string will expand keys like [/model], see below. E.g. -F "mqtt://localhost:1883,user=USERNAME,pass=PASSWORD,retain=0,devices=rtl_433[/id]"

MQTT Format Strings

Use format strings of:

[token]: expand to token or nothing
[token:default] expand to token or default
[/token] expand to token with leading slash or nothing
[/token:default] expand to token or default with leading slash

Tokens are type, model, subtype, channel, id, and protocol for now.

Note that for protocol to be available you first need to add it to the meta-data with -M protocol.

Examples:

sensors[/channel:0][/id] : always have a channel add id if available, you can also use sensors/[channel:0][/id]
sensors[/channel][/id] : use channel and then id, each if available
sensors[/id][/channel] : use id and then channel, each if available
sensors[/channel:0]-[id:0] : always have a combined channel and id
...

Defaults are a base topic of rtl_433/<hostname>/ continued

for devices with devices[/type][/model][/subtype][/channel][/id]
for events with events
for states with states

SYSLOG output

Use -F syslog to add an output in SYSLOG format.

Specify host/port for syslog with e.g. -F syslog:127.0.0.1:1514

A UDP output of JSON messages with Syslog compatible header data.

E.g. a UDP text payload of

<165>1 2019-08-29T06:38:19Z raspi.fritz.box rtl_433 - - - {"time":"2019-08-29 08:38:19","model":"Nexus-TH","id":42,"channel":2,"battery_ok":1,"temperature_C":20.5,"humidity":83}

NULL output

Without any -F option the default is KV output. Use -F null to remove that default.

Meta information

  [-M time[:<options>]|protocol|level|noise[:<secs>]|stats|bits]
    Add various metadata to every output line.

Use time to add current date and time meta data (preset for live inputs).
Use time:rel to add sample position meta data (preset for read-file and stdin).
Use time:unix to show the seconds since unix epoch as time meta data.
Use time:iso to show the time with ISO-8601 format (YYYY-MM-DD"T"hh:mm:ss).
Use time:off to remove time meta data.
Use time:usec to add microseconds to date time meta data.
Use time:tz to output time with timezone offset.
Use time:utc to output time in UTC. (this may also be accomplished by invocation with TZ environment variable set). usec and utc can be combined with other options, eg. time:unix:utc:usec.
Use replay[:N] to replay file inputs at (N-times) realtime.
Use protocol / noprotocol to output the decoder protocol number meta data.
Use level to add Modulation, Frequency, RSSI, SNR, and Noise meta data.
Use noise[:secs] to report estimated noise level at intervals (default: 10 seconds).
Use stats[:[<level>][:<interval>]] to report statistics (default: 600 seconds). level 0: no report, 1: report successful devices, 2: report active devices, 3: report all
Use bits to add bit representation to code outputs (for debug).

  [-K FILE | PATH | <tag>] Add an expanded token or fixed tag to every output line.

Use -K FILE to add the base file name (from a loader) to every output line.
Use -K PATH to add the full path name (from a loader) to every output line.
Use -K <tag> to add a fixed custom tag to every output line.

Data conversion

You can choose to normalize data by unit conversion with the -C option:

  [-C native | si | customary] Convert units in decoded output.

The default is no conversion, you explicitly select this with -C native.

With -C si units are converted to the SI system:

converts fields of Fahrenheit to Celsius (_F to _C)
converts fields of Miles/h to km/h (_mph to _kph, _mi_h to _km_h)
converts fields of Inch to mm (_in to _mm)
converts fields of Inch/h to mm/h (_in_h to _mm_h)
converts fields of InchHg to hPa (_inHg to _hPa)
converts fields of PSI to kPa (_PSI to _kPa)

With -C customary units are converted to customary units:

converts fields of Celsius to Fahrenheit (_C to _F)
converts fields of km/h to Miles/h (_kph to _mph, _km_h to _mi_h)
converts fields of mm to Inch (_mm to _in)
converts fields of mm/h to Inch/h (_mm_h to _in_h)
converts fields of hPa to InchHg (_hPa to _inHg)
converts fields of kPa to PSI (_kPa to _PSI)

Filter output with bridges

You can grab the decoded output from rtl_433 in various ways, then process and relay it somewhere.

Pipes

The simplest (but not very flexible or stable) way is to use pipes. E.g. capture the decode JSON messages and relay the to MQTT with

rtl_433 -F json -M utc | mosquitto_pub -t home/rtl_433 -l

See also rtl_433_collectd_pipe.py, and rtl_433_statsd_pipe.py for other examples of this method.

UDP

A better way is to use the Syslog-compatible UDP output to capture and relay the JSON message.

See also rtl_433_graphite_relay.py, rtl_433_mqtt_relay.py, and rtl_433_statsd_relay.py for examples of this method.

MQTT

If you already use the MQTT output, then you can capture the MQTT data, process it and inject derived data back.

See e.g. rtl_433_mqtt_hass.py for an example of this method.