FreeBSD Manual Pages
RTL_433(1) rtl_433 Commands RTL_433(1) 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 don- gles (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 op- tions follows. 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. 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. [ -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,band- width=4.5M,rfnotch_ctrl=false" for RTL-SDR use "direct_samp[=1]", "offset_tune[=1]", "digi- tal_agc[=1]", "biastee[=1]" [ -f <frequency> ] Receive frequency(s) (default: 433920000 Hz) [ -H <seconds> ] Hop interval for polling of multiple frequencies (default: 600 sec- onds) [ -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 mul- tiple times) Specify a negative number to disable a device decoding proto- col (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 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 sys- log: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 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 <modu- lation> 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 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=door- bell,m=OOK_PWM,s=400,l=800,r=7000,g=1000,match={24}0xa9878c,repeats>=3" 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), de- faults 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_PASS- WORD 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][/chan- nel][/id]" A base topic can be set with base=<topic>, default is "rtl_433/HOST- NAME". Any topic string overrides the base topic and will expand keys like [/model] E.g. -F "mqtt://localhost:1883,user=USERNAME,pass=PASSWORD,re- tain=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). [ -F influx[:[//]host[:port][/<path and options>] ] Specify InfluxDB 2.0 server with e.g. -F "influx://local- host:9999/api/v2/write?org=<org>&bucket=<bucket>,token=<authtoken>" Specify InfluxDB 1.x server with e.g. -F "influx://local- host:8086/write?db=<db>&p=<password>&u=<user>" Additional parameter -M time:unix:usec:utc for correct timestamps in InfluxDB recommended [ -F syslog[:[//]host[:port ] (default: localhost:514) Specify host/port for syslog with e.g. -F syslog:127.0.0.1:1514 [ -F trigger:/path/to/file ] Add an output that writes a "1" to the path for each event, use with a e.g. a GPIO [ -F rtl_tcp[:[//]bind[:port] ] (default: localhost:1234) Add a rtl_tcp pass-through server [ -F http[:[//]bind[:port] ] (default: 0.0.0.0:8433) Add a HTTP API server, a UI is at e.g. http://localhost:8433/ Meta information option [ -M time[:<options>]|protocol|level|noise[:<secs>]|stats|bits ] 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. 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 environ- ment variable set). "usec" and "utc" can be combined with other options, eg. "time:iso:utc" or "time:unix: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 exten- sion. 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) [ -W <filename> ] Save data stream to output file, overwrite existing file Parameters are detected from the full path, file name, and exten- sion. 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 COPYING Copyright (C) 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. rtl_433 2019-08-21 RTL_433(1)
NAME | DESCRIPTION | SYNOPSIS | OPTIONS | RESOURCES | COPYING
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=rtl_433&sektion=1&manpath=FreeBSD+Ports+15.1.quarterly>