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