rtl_433.1

.TH "RTL_433" "1" "2019-08-21" "rtl_433" "rtl_433 Commands"
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.ss \n[.ss] 0
.nh
.ad l
.de URL
\fI\\$2\fP <\\$1>\\$3
..
.als MTO URL
.if \n[.g] \{\
.  mso www.tmac
.  am URL
.    ad l
.  .
.  am MTO
.    ad l
.  .
.  LINKSTYLE blue R < >
.\}
.SH "NAME"
rtl_433 \- Generic RF data receiver and decoder for ISM band devices using RTL-SDR and SoapySDR.
.SH "DESCRIPTION"
.sp
This manual page documents briefly the \fBrtl_433\fP command.
.sp
\fBrtl_433\fP 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.
.SH "SYNOPSIS"
.sp
\fBrtl_433\fP [\fIOPTION\fP]... \fIFILE\fP...
.SH "OPTIONS"
.sp
A summary of options is included below.
Detailed information on some options follows.
.\" body


  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.
.SS "General options"
.TP
[ \fB\-V\fI\fP ]
Output the version string and exit
.TP
[ \fB\-v\fI\fP ]
Increase verbosity (can be used multiple times).
       \-v : verbose notice, \-vv : verbose info, \-vvv : debug, \-vvvv : trace.
.TP
[ \fB\-c\fI <path>\fP ]
Read config options from a file
.SS "Tuner options"
.TP
[ \fB\-d\fI <RTL\-SDR USB device index> | :<RTL\-SDR USB device serial> | <SoapySDR device query> | rtl_tcp | help\fP ]
[\-g <gain> | help] (default: auto)
.TP
[ \fB\-t\fI <settings>\fP ]
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]"
.TP
[ \fB\-f\fI <frequency>\fP ]
Receive frequency(s) (default: 433920000 Hz)
.TP
[ \fB\-H\fI <seconds>\fP ]
Hop interval for polling of multiple frequencies (default: 600 seconds)
.TP
[ \fB\-p\fI <ppm_error>\fP ]
Correct rtl\-sdr tuner frequency offset error (default: 0)
.TP
[ \fB\-s\fI <sample rate>\fP ]
Set sample rate (default: 250000 Hz)
.TP
[ \fB\-D\fI restart | pause | quit | manual\fP ]
Input device run mode options.
.SS "Demodulator options"
.TP
[ \fB\-R\fI <device> | help\fP ]
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)
.TP
[ \fB\-X\fI <spec> | help\fP ]
Add a general purpose decoder (prepend \-R 0 to disable all decoders)
.TP
[ \fB\-Y\fI auto | classic | minmax\fP ]
FSK pulse detector mode.
.TP
[ \fB\-Y\fI level=<dB level>\fP ]
Manual detection level used to determine pulses (\-1.0 to \-30.0) (0=auto).
.TP
[ \fB\-Y\fI minlevel=<dB level>\fP ]
Manual minimum detection level used to determine pulses (\-1.0 to \-99.0).
.TP
[ \fB\-Y\fI minsnr=<dB level>\fP ]
Minimum SNR to determine pulses (1.0 to 99.0).
.TP
[ \fB\-Y\fI autolevel\fP ]
Set minlevel automatically based on average estimated noise.
.TP
[ \fB\-Y\fI squelch\fP ]
Skip frames below estimated noise level to reduce cpu load.
.TP
[ \fB\-Y\fI ampest | magest\fP ]
Choose amplitude or magnitude level estimator.
.SS "Analyze/Debug options"
.TP
[ \fB\-A\fI\fP ]
Pulse Analyzer. Enable pulse analysis and decode attempt.
       Disable all decoders with \-R 0 if you want analyzer output only.
.TP
[ \fB\-y\fI <code>\fP ]
Verify decoding of demodulated test data (e.g. "{25}fb2dd58") with enabled devices
.SS "File I/O options"
.TP
[ \fB\-S\fI none | all | unknown | known\fP ]
Signal auto save. Creates one file per signal.
       Note: Saves raw I/Q samples (uint8 pcm, 2 channel). Preferred mode for generating test files.
.TP
[ \fB\-r\fI <filename> | help\fP ]
Read data from input file instead of a receiver
.TP
[ \fB\-w\fI <filename> | help\fP ]
Save data stream to output file (a '\-' dumps samples to stdout)
.TP
[ \fB\-W\fI <filename> | help\fP ]
Save data stream to output file, overwrite existing file
.SS "Data output options"
.TP
[ \fB\-F\fI log | kv | json | csv | mqtt | influx | syslog | trigger | null | help\fP ]
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
.TP
[ \fB\-M\fI time[:<options>] | protocol | level | noise[:<secs>] | stats | bits | help\fP ]
Add various meta data to each output.
.TP
[ \fB\-K\fI FILE | PATH | <tag> | <key>=<tag>\fP ]
Add an expanded token or fixed tag to every output line.
.TP
[ \fB\-C\fI native | si | customary\fP ]
Convert units in decoded output.
.TP
[ \fB\-n\fI <value>\fP ]
Specify number of samples to take (each sample is an I/Q pair)
.TP
[ \fB\-T\fI <seconds>\fP ]
Specify number of seconds to run, also 12:34 or 1h23m45s
.TP
[ \fB\-E\fI hop | quit\fP ]
Hop/Quit after outputting successful event(s)
.TP
[ \fB\-h\fI\fP ]
Output this usage help and exit
       Use \-d, \-g, \-R, \-X, \-F, \-M, \-r, \-w, or \-W without argument for more help
.SS "Input device selection"
.RS
RTL\-SDR device driver is available.
.RE
.TP
[ \fB\-d\fI <RTL\-SDR USB device index>\fP ]
(default: 0)
.TP
[ \fB\-d\fI :<RTL\-SDR USB device serial (can be set with rtl_eeprom \-s)>\fP ]
.RS
To set gain for RTL\-SDR use \-g <gain> to set an overall gain in dB.
.RE
.RS
SoapySDR device driver is available.
.RE
.TP
[ \fB\-d\fI ""\fP ]
Open default SoapySDR device
.TP
[ \fB\-d\fI driver=rtlsdr\fP ]
Open e.g. specific SoapySDR device
.RS
To set gain for SoapySDR use \-g ELEM=val,ELEM=val,... e.g. \-g LNA=20,TIA=8,PGA=2 (for LimeSDR).
.RE
.TP
[ \fB\-d\fI rtl_tcp[:[//]host[:port]\fP ]
(default: localhost:1234)
.RS
Specify host/port to connect to with e.g. \-d rtl_tcp:127.0.0.1:1234
.RE
.SS "Gain option"
.TP
[ \fB\-g\fI <gain>\fP ]
(default: auto)
.RS
For RTL\-SDR: gain in dB ("0" is auto).
.RE
.RS
For SoapySDR: gain in dB for automatic distribution ("" is auto), or string of gain elements.
.RE
.RS
E.g. "LNA=20,TIA=8,PGA=2" for LimeSDR.
.RE
.SS "Flex decoder spec"
Use \-X <spec> to add a flexible general purpose decoder.

<spec> is "key=value[,key=value...]"
Common keys are:
.RS
name=<name> (or: n=<name>)
.RE
.RS
modulation=<modulation> (or: m=<modulation>)
.RE
.RS
short=<short> (or: s=<short>)
.RE
.RS
long=<long> (or: l=<long>)
.RE
.RS
sync=<sync> (or: y=<sync>)
.RE
.RS
reset=<reset> (or: r=<reset>)
.RE
.RS
gap=<gap> (or: g=<gap>)
.RE
.RS
tolerance=<tolerance> (or: t=<tolerance>)
.RE
.RS
priority=<n> : run decoder only as fallback
.RE
where:
<name> can be any descriptive name tag you need in the output
<modulation> is one of:
.RS
OOK_MC_ZEROBIT :  Manchester Code with fixed leading zero bit
.RE
.RS
OOK_PCM :         Non Return to Zero coding (Pulse Code)
.RE
.RS
OOK_RZ :          Return to Zero coding (Pulse Code)
.RE
.RS
OOK_PPM :         Pulse Position Modulation
.RE
.RS
OOK_PWM :         Pulse Width Modulation
.RE
.RS
OOK_DMC :         Differential Manchester Code
.RE
.RS
OOK_PIWM_RAW :    Raw Pulse Interval and Width Modulation
.RE
.RS
OOK_PIWM_DC :     Differential Pulse Interval and Width Modulation
.RE
.RS
OOK_MC_OSV1 :     Manchester Code for OSv1 devices
.RE
.RS
FSK_PCM :         FSK Pulse Code Modulation
.RE
.RS
FSK_PWM :         FSK Pulse Width Modulation
.RE
.RS
FSK_MC_ZEROBIT :  Manchester Code with fixed leading zero bit
.RE
<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:
.RS
bits=<n> : only match if at least one row has <n> bits
.RE
.RS
rows=<n> : only match if there are <n> rows
.RE
.RS
repeats=<n> : only match if some row is repeated <n> times
.RE
.RS
	use opt>=n to match at least <n> and opt<=n to match at most <n>
.RE
.RS
invert : invert all bits
.RE
.RS
reflect : reflect each byte (MSB first to MSB last)
.RE
.RS
decode_uart : UART 8n1 (10\-to\-8) decode
.RE
.RS
decode_dm : Differential Manchester decode
.RE
.RS
match=<bits> : only match if the <bits> are found
.RE
.RS
preamble=<bits> : match and align at the <bits> preamble
.RE
.RS
	<bits> is a row spec of {<bit count>}<bits as hex number>
.RE
.RS
unique : suppress duplicate row output
.RE

.RS
countonly : suppress detailed row output
.RE

E.g. \-X "n=doorbell,m=OOK_PWM,s=400,l=800,r=7000,g=1000,match={24}0xa9878c,repeats>=3"
.SS "Output format option"
.TP
[ \fB\-F\fI log|kv|json|csv|mqtt|influx|syslog|trigger|null\fP ]
Produce decoded output in given format.
.RS
Without this option the default is LOG and KV output. Use "\-F null" to remove the default.
.RE
.RS
Append output to file with :<filename> (e.g. \-F csv:log.csv), defaults to stdout.
.RE
.RS
Specify MQTT server with e.g. \-F mqtt://localhost:1883
.RE
.RS
Default user and password are read from MQTT_USERNAME and MQTT_PASSWORD env vars.
.RE
.RS
Add MQTT options with e.g. \-F "mqtt://host:1883,opt=arg"
.RE
.RS
MQTT options are: user=foo, pass=bar, retain[=0|1], <format>[=topic]
.RE
.RS
Supported MQTT formats: (default is all)
.RE
.RS
  events: posts JSON event data, default "<base>/events"
.RE
.RS
  states: posts JSON state data, default "<base>/states"
.RE
.RS
  devices: posts device and sensor info in nested topics,
.RE
.RS
           default "<base>/devices[/type][/model][/subtype][/channel][/id]"
.RE
.RS
A base topic can be set with base=<topic>, default is "rtl_433/HOSTNAME".
.RE
.RS
Any topic string overrides the base topic and will expand keys like [/model]
.RE
.RS
E.g. \-F "mqtt://localhost:1883,user=USERNAME,pass=PASSWORD,retain=0,devices=rtl_433[/id]"
.RE
.RS
With MQTT each rtl_433 instance needs a distinct driver selection. The MQTT Client\-ID is computed from the driver string.
.RE
.RS
If you use multiple RTL\-SDR, perhaps set a serial and select by that (helps not to get the wrong antenna).
.RE
.RS
Specify InfluxDB 2.0 server with e.g. \-F "influx://localhost:9999/api/v2/write?org=<org>&bucket=<bucket>,token=<authtoken>"
.RE
.RS
Specify InfluxDB 1.x server with e.g. \-F "influx://localhost:8086/write?db=<db>&p=<password>&u=<user>"
.RE
.RS
  Additional parameter \-M time:unix:usec:utc for correct timestamps in InfluxDB recommended
.RE
.RS
Specify host/port for syslog with e.g. \-F syslog:127.0.0.1:1514
.RE
.SS "Meta information option"
.TP
[ \fB\-M\fI time[:<options>]|protocol|level|noise[:<secs>]|stats|bits\fP ]
Add various metadata to every output line.
.RS
Use "time" to add current date and time meta data (preset for live inputs).
.RE
.RS
Use "time:rel" to add sample position meta data (preset for read\-file and stdin).
.RE
.RS
Use "time:unix" to show the seconds since unix epoch as time meta data. This is always UTC.
.RE
.RS
Use "time:iso" to show the time with ISO\-8601 format (YYYY\-MM\-DD"T"hh:mm:ss).
.RE
.RS
Use "time:off" to remove time meta data.
.RE
.RS
Use "time:usec" to add microseconds to date time meta data.
.RE
.RS
Use "time:tz" to output time with timezone offset.
.RE
.RS
Use "time:utc" to output time in UTC.
.RE
.RS
	(this may also be accomplished by invocation with TZ environment variable set).
.RE
.RS
	"usec" and "utc" can be combined with other options, eg. "time:iso:utc" or "time:unix:usec".
.RE
.RS
Use "replay[:N]" to replay file inputs at (N\-times) realtime.
.RE
.RS
Use "protocol" / "noprotocol" to output the decoder protocol number meta data.
.RE
.RS
Use "level" to add Modulation, Frequency, RSSI, SNR, and Noise meta data.
.RE
.RS
Use "noise[:<secs>]" to report estimated noise level at intervals (default: 10 seconds).
.RE
.RS
Use "stats[:[<level>][:<interval>]]" to report statistics (default: 600 seconds).
.RE
.RS
  level 0: no report, 1: report successful devices, 2: report active devices, 3: report all
.RE
.RS
Use "bits" to add bit representation to code outputs (for debug).
.RE
.SS "Read file option"
.TP
[ \fB\-r\fI <filename>\fP ]
Read data from input file instead of a receiver
.RS
Parameters are detected from the full path, file name, and extension.
.RE

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

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

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

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

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

.RS
Reading from pipes also support format options.
.RE
.RS
E.g reading complex 32\-bit float: CU32:\-
.RE
.SS "Write file option"
.TP
[ \fB\-w\fI <filename>\fP ]
Save data stream to output file (a '\-' dumps samples to stdout)
.TP
[ \fB\-W\fI <filename>\fP ]
Save data stream to output file, overwrite existing file
.RS
Parameters are detected from the full path, file name, and extension.
.RE

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

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

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

.\" end
.SH "RESOURCES"
.sp
\fBProject web site:\fP \c
.URL "https://github.com/merbanan/rtl_433" "" ""
.SH "COPYING"
.sp
Copyright \(co 2012\-2019 Benjamin Larsson, Christian W. Zuckschwerdt, and many contributors.
.br
Free use of this software is granted under the terms of the GPL\-2+ License.