rtl_433(1)

Generic RF data receiver and decoder for ISM band devices using RTL-SDR and SoapySDR.

Section 1 rtl-433 bookworm source

Description

RTL_433

NAME

rtl_433 - Generic RF data receiver and decoder for ISM band devices using RTL-SDR and SoapySDR.

DESCRIPTION

This manual page documents briefly the rtl_433 command.

rtl_433 is a generic data receiver, mainly for the 433.92 MHz, 868 MHz (SRD), 315 MHz, and 915 MHz ISM bands. It works with RTL-SDR and/or SoapySDR. Actively tested and supported are Realtek RTL2832 based DVB dongles (using RTL-SDR) and LimeSDR (LimeSDR USB and LimeSDR mini engineering samples kindly provided by MyriadRf), PlutoSDR, HackRF One (using SoapySDR drivers), as well as SoapyRemote.

SYNOPSIS

rtl_433 [OPTION]... FILE...

OPTIONS

A summary of options is included below. Detailed information on some options follows.

General options

[ -V ]

Output the version string and exit

[ -v ]

Increase verbosity (can be used multiple times).
-v : verbose, -vv : verbose decoders, -vvv : debug decoders, -vvvv : trace decoding).

[ -c <path> ]

Read config options from a file

Tuner options

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

[-g <gain> | help] (default: auto)

[ -t <settings> ]

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

[ -f <frequency> ]

Receive frequency(s) (default: 433920000 Hz)

[ -H <seconds> ]

Hop interval for polling of multiple frequencies (default: 600 seconds)

[ -p <ppm_error> ]

Correct rtl-sdr tuner frequency offset error (default: 0)

[ -s <sample rate> ]

Set sample rate (default: 250000 Hz)

Demodulator options

[ -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)

[ -Y auto | classic | minmax ]

FSK pulse detector mode.

[ -Y level=<dB level> ]

Manual detection level used to determine pulses (-1.0 to -30.0) (0=auto).

[ -Y minlevel=<dB level> ]

Manual minimum detection level used to determine pulses (-1.0 to -99.0).

[ -Y minsnr=<dB level> ]

Minimum SNR to determine pulses (1.0 to 99.0).

[ -Y autolevel ]

Set minlevel automatically based on average estimated noise.

[ -Y squelch ]

Skip frames below estimated noise level to reduce cpu load.

[ -Y ampest | magest ]

Choose amplitude or magnitude level estimator.

Analyze/Debug options

[ -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.

[ -y <code> ]

Verify decoding of demodulated test data (e.g. "{25}fb2dd58") with enabled devices

File I/O options

[ -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.

[ -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

Data output options

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

Add various meta data to each output.

[ -K FILE | PATH | <tag> | <key>=<tag> ]

Add an expanded token or fixed tag to every output line.

[ -C native | si | customary ]

Convert units in decoded output.

[ -n <value> ]

Specify number of samples to take (each sample is an I/Q pair)

[ -T <seconds> ]

Specify number of seconds to run, also 12:34 or 1h23m45s

[ -E hop | quit ]

Hop/Quit after outputting successful event(s)

[ -h ]

Output this usage help and exit
Use -d, -g, -R, -X, -F, -M, -r, -w, or -W without argument for more help

Input device selection

RTL-SDR device driver is available.

[ -d <RTL-SDR USB device index> ]

(default: 0)

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

To set gain for RTL-SDR use -g <gain> to set an overall gain in dB.
SoapySDR device driver is available.

[ -d "" ]

Open default SoapySDR device

[ -d driver=rtlsdr ]

Open e.g. specific SoapySDR device
To set gain for SoapySDR use -g ELEM=val,ELEM=val,... e.g. -g LNA=20,TIA=8,PGA=2 (for LimeSDR).

[ -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

Gain 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.

Flex decoder spec

Use -X <spec> to add a flexible general purpose decoder.

<spec> is "key=value[,key=value...]" 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>)
priority=<n> : run decoder only as fallback

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 : Non Return to Zero coding (Pulse Code)
OOK_RZ : Return to Zero coding (Pulse Code)
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/RZ 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). Available 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)
decode_uart : UART 8n1 (10-to-8) decode
match=<bits> : only match if the <bits> are found
preamble=<bits> : match and align at the <bits> preamble

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"

Output format option

Produce decoded output in given format.
Without this option the default is KV output. Use "-F null" to remove the default.
Append output to file with :<filename> (e.g. -F csv:log.csv), defaults to stdout.
Specify MQTT server with e.g. -F mqtt://localhost:1883
Add MQTT options with e.g. -F "mqtt://host:1883,opt=arg"
MQTT options are: user=foo, pass=bar, retain[=0|1], <format>[=topic]
Supported MQTT formats: (default is all)
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]
E.g. -F "mqtt://localhost:1883,user=USERNAME,pass=PASSWORD,retain=0,devices=rtl_433[/id]"
With MQTT each rtl_433 instance needs a distinct driver selection. The MQTT Client-ID is computed from the driver string.
If you use multiple RTL-SDR, perhaps set a serial and select by that (helps not to get the wrong antenna).
Specify InfluxDB 2.0 server with e.g. -F "influx://localhost:9999/api/v2/write?org=<org>&bucket=<bucket>,token=<authtoken>"
Specify InfluxDB 1.x server with e.g. -F "influx://localhost:8086/write?db=<db>&p=<password>&u=<user>"
Additional parameter -M time:unix:usec:utc for correct timestamps in InfluxDB recommended
Specify host/port for syslog with e.g. -F syslog:127.0.0.1:1514

Meta information option

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).

Read file option

[ -r <filename> ]

Read data from input file instead of a receiver
Parameters are detected from the full path, file name, and extension.

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

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

File content and format are detected as parameters, possible options are:
’cu8’, ’cs16’, ’cf32’ (’IQ’ implied), and ’am.s16’.

Parameters must be separated by non-alphanumeric chars and are case-insensitive.
Overrides can be prefixed, separated by colon (’:’)

E.g. default detection by extension: path/filename.am.s16
forced overrides: am:s16:path/filename.ext

Reading from pipes also support format options.
E.g reading complex 32-bit float: CU32:-

Write file option

[ -w <filename> ]