RTL_433(1)

📦
version 26.07 · 7 versions
, in ubuntu stonking

📻 NAME

rtl_433 — a generic RF data receiver and decoder for ISM band devices, using RTL-SDR and SoapySDR. Bestie, this is from the rtl_433 Commands manual and it is lowkey the whole toolbox.

💖 DESCRIPTION

Okay so first things first: 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. The ones that are actively tested and supported are:

  • Realtek RTL2832 based DVB dongles (using RTL-SDR)
  • LimeSDR (LimeSDR USB and LimeSDR mini engineering samples kindly provided by MyriadRf)
  • PlutoSDR
  • HackRF One (using SoapySDR drivers)
  • SoapyRemote

SoapyRemote girlies rise up ✨

🎀 SYNOPSIS

rtl_433 [OPTION]... FILE...

✨ OPTIONS ✨

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

Not me dropping the biggest glow-up: a "rtl_433.conf" file is searched in "./", XDG_CONFIG_HOME e.g. "$HOME/.config/rtl_433/", SYSCONFDIR e.g. "/usr/local/etc/rtl_433/", then command line args will be parsed in order. in order, bestie. Order matters. 💅

🦋 General options

  • -V — Output the version string and exit.
  • -v — Increase verbosity (can be used multiple times). -v : verbose notice, -vv : verbose info, -vvv : debug, -vvvv : trace. Stack 'em like accessories. 👑
  • -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 to the SDR device. e.g. for SoapySDR -t "antenna=A,bandwidth=4.5M,rfnotch_ctrl=false", for RTL-SDR use "direct_samp[=1]", "offset_tune[=1]", "digital_agc[=1]", "biastee[=1]". keywords=values, it's giving config glow-up.
  • -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).
  • -D quit | restart | pause | manual — Input device run mode options (default: quit).

🌸 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 — 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.
Overwrite existing file means what it says bestie, -W does not play nice. 🙈

📊 Data output options

  • -F log | kv | json | csv | mqtt | influx | syslog | trigger | rtl_tcp | http | 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 | noise[:<secs>] | stats | bits | help — 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. Free extra lore, no cap.

🔌 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=<8n1|8n2|8o1> : UART 8n1 (10-to-8), 8n2, 8o1 (11-to-8) decode
    decode_dm : Differential Manchester decode
    decode_mc : Manchester decode
    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"

One -X and you've got a whole custom decoder, main character energy. 💅

🌈 Output format option

  • -F log|kv|json|csv|mqtt|influx|syslog|trigger|rtl_tcp|http|null — Produce decoded output in given format. Without this option the default is LOG and KV output. Use "-F null" to remove the default. Append output to file with :<filename> (e.g. -F csv:log.csv), defaults to stdout.
  • -F mqtt[s][:[//]host[:port][,<options>] — (default: localhost:1883) Specify MQTT server with e.g. -F mqtt://localhost:1883 Default user and password are read from MQTT_USERNAME and MQTT_PASSWORD env vars. 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)
    • availability: posts availability (online/offline)
    • events: posts JSON event data, default "<base>/events"
    • states: posts JSON state data, default "<base>/states"
    • devices: posts device and sensor info in nested topics, default "<base>/devices[/type][/model][/subtype][/channel][/id]"

A base topic can be set with base=<topic>, default is "rtl_433/HOSTNAME". Any topic string overrides the base topic and will expand keys like [/model] E.g. -F "mqtt://localhost:1883,user=USERNAME,pass=PASSWORD,retain=0,devices=rtl_433[/id]" For TLS use e.g. -F "mqtts://host,tls_cert=<path>,tls_key=<path>,tls_ca_cert=<path>" 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).

Not the "wrong antenna" warning 😭 bestie if you've got multiple RTL-SDRs, set a serial and select by it, fr fr. The MQTT Client-ID is derived from the driver string so each instance needs its own driver selection, periodt.
  • -F influx[:[//]host[:port][/<path and options>]] — okay so this one pipes your lil readings straight into InfluxDB and honestly? iconic. Two flavors, pick ur fighter. ✨

For InfluxDB 2.0 you point it at a server like this:

-F "influx://localhost:9999/api/v2/write?org=<org>&bucket=<bucket>,token=<authtoken>"

For InfluxDB 1.x it's giving this instead:

-F "influx://localhost:8086/write?db=<db>&p=<password>&u=<user>"
heads up bestie: adding the extra parameter -M time:unix:usec:utc is recommended so your timestamps actually come out correct in InfluxDB. no cap. 🕰️
  • -F syslog[:[//]host[:port]] — default is localhost:514. Wanna send it somewhere else? Specify host/port for syslog like -F syslog:127.0.0.1:1514. 🫶
  • -F trigger:/path/to/file — adds an output that writes a "1" to that path for each event. Use it with, like, a GPIO. one lil 1 per vibe. 💅
  • -F rtl_tcp[:[//]bind[:port]] — default is localhost:1234. Adds an rtl_tcp pass-through server. 🌈
  • -F http[:[//]bind[:port]] — default is 0.0.0.0:8433. Adds a HTTP API server, and there's a whole UI waiting for you at e.g. http://localhost:8433/. go look at it. it's cute. 💖

🌸 Meta information option 🌸

  • -M time[:<options>]|protocol|level|noise[:<secs>]|stats|bits — the glow-up option fr. Adds 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. This is always UTC.
    • 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:iso:utc" or "time:unix:usec". mix and match bestie 🎀
    • 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. yes, you can just feed it a file. she doesn't need a radio to eat. 🍓

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> — save data stream to output file (a '-' dumps samples to stdout). lowkey the simplest girl here. 💜
  • -W <filename> — same energy, but it overwrites existing file. she does not ask. 😭

Parameters are detected from the full path, file name, and extension.

  • File content and format are detected as parameters, possible options are: 'cu8', 'cs8', 'cs16', 'cf32' ('IQ' implied), 'am.s16', 'am.f32', 'fm.s16', 'fm.f32', 'i.f32', 'q.f32', 'logic.u8', 'ook', and 'vcd'.

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 🔥

🦋 RESOURCES 🦋

Project web site: https://github.com/merbanan/rtl_433

go snoop. main character energy only. 👑

💖 COPYING 💖

Copyright © 2012-2019 Benjamin Larsson, Christian W. Zuckschwerdt, and many contributors.

Free use of this software is granted under the terms of the GPL-2+ License. periodt. 💅

and that's the whole page bestie — this is rtl_433, dated 2019-08-21, and you officially read the entire RTL_433(1) manual without falling asleep. so proud of you fr fr 🫶✨🎀

📦 where this page comes from