1RTL_433(1) rtl_433 Commands RTL_433(1)
2
6 rtl_433 - Generic RF data receiver and decoder for ISM band devices
7 using RTL-SDR and SoapySDR.
8
10 This manual page documents briefly the rtl_433 command.
11 rtl_433 is a generic data receiver, mainly for the 433.92 MHz, 868 MHz
13 (SRD), 315 MHz, and 915 MHz ISM bands. It works with RTL-SDR and/or
14 SoapySDR. Actively tested and supported are Realtek RTL2832 based DVB
15 dongles (using RTL-SDR) and LimeSDR (LimeSDR USB and LimeSDR mini
16 engineering samples kindly provided by MyriadRf), PlutoSDR, HackRF One
17 (using SoapySDR drivers), as well as SoapyRemote.
18
20 rtl_433 [OPTION]... FILE...
21
23 A summary of options is included below. Detailed information on some
24 options follows.
25 General options
27 [ -V ] Output the version string and exit
28 [ -v ] Increase verbosity (can be used multiple times).
30 -v : verbose notice, -vv : verbose info, -vvv : debug,
31 -vvvv : trace.
32 [ -c <path> ]
34 Read config options from a file
35 Tuner options
37 [ -d <RTL-SDR USB device index> | :<RTL-SDR USB device serial> |
38 <SoapySDR device query> | rtl_tcp | help ]
39 [-g <gain> | help] (default: auto)
40 [ -t <settings> ]
42 apply a list of keyword=value settings to the SDR device
43 e.g. for SoapySDR -t
44 "antenna=A,bandwidth=4.5M,rfnotch_ctrl=false"
45 for RTL-SDR use "direct_samp[=1]", "offset_tune[=1]",
46 "digital_agc[=1]", "biastee[=1]"
47 [ -f <frequency> ]
49 Receive frequency(s) (default: 433920000 Hz)
50 [ -H <seconds> ]
52 Hop interval for polling of multiple frequencies (default: 600
53 seconds)
54 [ -p <ppm_error> ]
56 Correct rtl-sdr tuner frequency offset error (default: 0)
57 [ -s <sample rate> ]
59 Set sample rate (default: 250000 Hz)
60 [ -D restart | pause | quit | manual ]
62 Input device run mode options.
63 Demodulator options
65 [ -R <device> | help ]
66 Enable only the specified device decoding protocol (can be used
67 multiple times)
68 Specify a negative number to disable a device decoding
69 protocol (can be used multiple times)
70 [ -X <spec> | help ]
72 Add a general purpose decoder (prepend -R 0 to disable all
73 decoders)
74 [ -Y auto | classic | minmax ]
76 FSK pulse detector mode.
77 [ -Y level=<dB level> ]
79 Manual detection level used to determine pulses (-1.0 to -30.0)
80 (0=auto).
81 [ -Y minlevel=<dB level> ]
83 Manual minimum detection level used to determine pulses (-1.0 to
84 -99.0).
85 [ -Y minsnr=<dB level> ]
87 Minimum SNR to determine pulses (1.0 to 99.0).
88 [ -Y autolevel ]
90 Set minlevel automatically based on average estimated noise.
91 [ -Y squelch ]
93 Skip frames below estimated noise level to reduce cpu load.
94 [ -Y ampest | magest ]
96 Choose amplitude or magnitude level estimator.
97 Analyze/Debug options
99 [ -A ] Pulse Analyzer. Enable pulse analysis and decode attempt.
100 Disable all decoders with -R 0 if you want analyzer
101 output only.
102 [ -y <code> ]
104 Verify decoding of demodulated test data (e.g. "{25}fb2dd58")
105 with enabled devices
106 File I/O options
108 [ -S none | all | unknown | known ]
109 Signal auto save. Creates one file per signal.
110 Note: Saves raw I/Q samples (uint8 pcm, 2 channel).
111 Preferred mode for generating test files.
112 [ -r <filename> | help ]
114 Read data from input file instead of a receiver
115 [ -w <filename> | help ]
117 Save data stream to output file (a '-' dumps samples to stdout)
118 [ -W <filename> | help ]
120 Save data stream to output file, overwrite existing file
121 Data output options
123 [ -F log | kv | json | csv | mqtt | influx | syslog | trigger | null |
124 help ]
125 Produce decoded output in given format.
126 Append output to file with :<filename> (e.g. -F
127 csv:log.csv), defaults to stdout.
128 Specify host/port for syslog with e.g. -F
129 syslog:127.0.0.1:1514
130 [ -M time[:<options>] | protocol | level | noise[:<secs>] | stats |
132 bits | help ]
133 Add various meta data to each output.
134 [ -K FILE | PATH | <tag> | <key>=<tag> ]
136 Add an expanded token or fixed tag to every output line.
137 [ -C native | si | customary ]
139 Convert units in decoded output.
140 [ -n <value> ]
142 Specify number of samples to take (each sample is an I/Q pair)
143 [ -T <seconds> ]
145 Specify number of seconds to run, also 12:34 or 1h23m45s
146 [ -E hop | quit ]
148 Hop/Quit after outputting successful event(s)
149 [ -h ] Output this usage help and exit
151 Use -d, -g, -R, -X, -F, -M, -r, -w, or -W without
152 argument for more help
153 Input device selection
155 RTL-SDR device driver is available.
156 [ -d <RTL-SDR USB device index> ]
158 (default: 0)
159 [ -d :<RTL-SDR USB device serial (can be set with rtl_eeprom -s)> ]
161 To set gain for RTL-SDR use -g <gain> to set an overall gain in
162 dB.
163 SoapySDR device driver is available.
164 [ -d "" ]
166 Open default SoapySDR device
167 [ -d driver=rtlsdr ]
169 Open e.g. specific SoapySDR device
170 To set gain for SoapySDR use -g ELEM=val,ELEM=val,... e.g. -g
171 LNA=20,TIA=8,PGA=2 (for LimeSDR).
172 [ -d rtl_tcp[:[//]host[:port] ]
174 (default: localhost:1234)
175 Specify host/port to connect to with e.g. -d
176 rtl_tcp:127.0.0.1:1234
177 Gain option
179 [ -g <gain> ]
180 (default: auto)
181 For RTL-SDR: gain in dB ("0" is auto).
182 For SoapySDR: gain in dB for automatic distribution ("" is
183 auto), or string of gain elements.
184 E.g. "LNA=20,TIA=8,PGA=2" for LimeSDR.
185 Flex decoder spec
187 Use -X <spec> to add a flexible general purpose decoder.
188 <spec> is "key=value[,key=value...]" Common keys are:
190 name=<name> (or: n=<name>)
191 modulation=<modulation> (or: m=<modulation>)
192 short=<short> (or: s=<short>)
193 long=<long> (or: l=<long>)
194 sync=<sync> (or: y=<sync>)
195 reset=<reset> (or: r=<reset>)
196 gap=<gap> (or: g=<gap>)
197 tolerance=<tolerance> (or: t=<tolerance>)
198 priority=<n> : run decoder only as fallback
199 where: <name> can be any descriptive name tag you need in the output
200 <modulation> is one of:
201 OOK_MC_ZEROBIT : Manchester Code with fixed leading zero bit
202 OOK_PCM : Non Return to Zero coding (Pulse Code)
203 OOK_RZ : Return to Zero coding (Pulse Code)
204 OOK_PPM : Pulse Position Modulation
205 OOK_PWM : Pulse Width Modulation
206 OOK_DMC : Differential Manchester Code
207 OOK_PIWM_RAW : Raw Pulse Interval and Width Modulation
208 OOK_PIWM_DC : Differential Pulse Interval and Width
209 Modulation
210 OOK_MC_OSV1 : Manchester Code for OSv1 devices
211 FSK_PCM : FSK Pulse Code Modulation
212 FSK_PWM : FSK Pulse Width Modulation
213 FSK_MC_ZEROBIT : Manchester Code with fixed leading zero bit
214 <short>, <long>, <sync> are nominal modulation timings in us, <reset>,
215 <gap>, <tolerance> are maximum modulation timings in us: PCM/RZ short:
216 Nominal width of pulse [us]
217 long: Nominal width of bit period [us] PPM short: Nominal
218 width of '0' gap [us]
219 long: Nominal width of '1' gap [us] PWM short: Nominal
220 width of '1' pulse [us]
221 long: Nominal width of '0' pulse [us]
222 sync: Nominal width of sync pulse [us] (optional) common
223 gap: Maximum gap size before new row of bits [us]
224 reset: Maximum gap size before End Of Message [us]
225 tolerance: Maximum pulse deviation [us] (optional). Available
226 options are:
227 bits=<n> : only match if at least one row has <n> bits
228 rows=<n> : only match if there are <n> rows
229 repeats=<n> : only match if some row is repeated <n> times
230 use opt>=n to match at least <n> and opt<=n to match at
231 most <n>
232 invert : invert all bits
233 reflect : reflect each byte (MSB first to MSB last)
234 decode_uart : UART 8n1 (10-to-8) decode
235 decode_dm : Differential Manchester decode
236 match=<bits> : only match if the <bits> are found
237 preamble=<bits> : match and align at the <bits> preamble
238 <bits> is a row spec of {<bit count>}<bits as hex number>
239 unique : suppress duplicate row output
240 countonly : suppress detailed row output
242 E.g. -X
244 "n=doorbell,m=OOK_PWM,s=400,l=800,r=7000,g=1000,match={24}0xa9878c,repeats>=3"
245 Output format option
247 [ -F log|kv|json|csv|mqtt|influx|syslog|trigger|null ]
248 Produce decoded output in given format.
249 Without this option the default is LOG and KV output. Use "-F
250 null" to remove the default.
251 Append output to file with :<filename> (e.g. -F csv:log.csv),
252 defaults to stdout.
253 Specify MQTT server with e.g. -F mqtt://localhost:1883
254 Add MQTT options with e.g. -F "mqtt://host:1883,opt=arg"
255 MQTT options are: user=foo, pass=bar, retain[=0|1],
256 <format>[=topic]
257 Supported MQTT formats: (default is all)
258 events: posts JSON event data
259 states: posts JSON state data
260 devices: posts device and sensor info in nested topics
261 The topic string will expand keys like [/model]
262 E.g. -F
263 "mqtt://localhost:1883,user=USERNAME,pass=PASSWORD,retain=0,devices=rtl_433[/id]"
264 With MQTT each rtl_433 instance needs a distinct driver
265 selection. The MQTT Client-ID is computed from the driver
266 string.
267 If you use multiple RTL-SDR, perhaps set a serial and select by
268 that (helps not to get the wrong antenna).
269 Specify InfluxDB 2.0 server with e.g. -F
270 "influx://localhost:9999/api/v2/write?org=<org>&bucket=<bucket>,token=<authtoken>"
271 Specify InfluxDB 1.x server with e.g. -F
272 "influx://localhost:8086/write?db=<db>&p=<password>&u=<user>"
273 Additional parameter -M time:unix:usec:utc for correct
274 timestamps in InfluxDB recommended
275 Specify host/port for syslog with e.g. -F syslog:127.0.0.1:1514
276 Meta information option
278 [ -M time[:<options>]|protocol|level|noise[:<secs>]|stats|bits ]
279 Add various metadata to every output line.
280 Use "time" to add current date and time meta data (preset for
281 live inputs).
282 Use "time:rel" to add sample position meta data (preset for
283 read-file and stdin).
284 Use "time:unix" to show the seconds since unix epoch as time
285 meta data. This is always UTC.
286 Use "time:iso" to show the time with ISO-8601 format
287 (YYYY-MM-DD"T"hh:mm:ss).
288 Use "time:off" to remove time meta data.
289 Use "time:usec" to add microseconds to date time meta data.
290 Use "time:tz" to output time with timezone offset.
291 Use "time:utc" to output time in UTC.
292 (this may also be accomplished by invocation with TZ
293 environment variable set).
294 "usec" and "utc" can be combined with other options, eg.
295 "time:iso:utc" or "time:unix:usec".
296 Use "replay[:N]" to replay file inputs at (N-times) realtime.
297 Use "protocol" / "noprotocol" to output the decoder protocol
298 number meta data.
299 Use "level" to add Modulation, Frequency, RSSI, SNR, and Noise
300 meta data.
301 Use "noise[:<secs>]" to report estimated noise level at
302 intervals (default: 10 seconds).
303 Use "stats[:[<level>][:<interval>]]" to report statistics
304 (default: 600 seconds).
305 level 0: no report, 1: report successful devices, 2: report
306 active devices, 3: report all
307 Use "bits" to add bit representation to code outputs (for
308 debug).
309 Read file option
311 [ -r <filename> ]
312 Read data from input file instead of a receiver
313 Parameters are detected from the full path, file name, and
314 extension.
315 A center frequency is detected as (fractional) number suffixed
317 with 'M',
318 'Hz', 'kHz', 'MHz', or 'GHz'.
319 A sample rate is detected as (fractional) number suffixed with
321 'k',
322 'sps', 'ksps', 'Msps', or 'Gsps'.
323 File content and format are detected as parameters, possible
325 options are:
326 'cu8', 'cs16', 'cf32' ('IQ' implied), and 'am.s16'.
327 Parameters must be separated by non-alphanumeric chars and are
329 case-insensitive.
330 Overrides can be prefixed, separated by colon (':')
331 E.g. default detection by extension: path/filename.am.s16
333 forced overrides: am:s16:path/filename.ext
334 Reading from pipes also support format options.
336 E.g reading complex 32-bit float: CU32:-
337 Write file option
339 [ -w <filename> ]
340 Save data stream to output file (a '-' dumps samples to stdout)
341 [ -W <filename> ]
343 Save data stream to output file, overwrite existing file
344 Parameters are detected from the full path, file name, and
345 extension.
346 File content and format are detected as parameters, possible
348 options are:
349 'cu8', 'cs8', 'cs16', 'cf32' ('IQ' implied),
350 'am.s16', 'am.f32', 'fm.s16', 'fm.f32',
351 'i.f32', 'q.f32', 'logic.u8', 'ook', and 'vcd'.
352 Parameters must be separated by non-alphanumeric chars and are
354 case-insensitive.
355 Overrides can be prefixed, separated by colon (':')
356 E.g. default detection by extension: path/filename.am.s16
358 forced overrides: am:s16:path/filename.ext
359
362 Project web site: https://github.com/merbanan/rtl_433
363
365 Copyright © 2012-2019 Benjamin Larsson, Christian W. Zuckschwerdt, and
366 many contributors.
367 Free use of this software is granted under the terms of the GPL-2+
368 License.
369rtl_433 2019-08-21 RTL_433(1)