mirror of https://github.com/merbanan/rtl_433.git
596 lines
22 KiB
Markdown
596 lines
22 KiB
Markdown
# Basic rtl_433 operation
|
|
|
|
The principle buildings blocks of rtl_433 are: Inputs, Loaders, Processing, Analysis, Decoders, Dumpers, Outputs.
|
|
|
|
At startup rtl_433 will read config files and parse command line arguments, then it will loop through these steps:
|
|
|
|
- Inputs: rtl_tcp, RTL-SDR, SoapySDR
|
|
- Loaders: Raw data files (cu8, cs16, ...)
|
|
- Processing: OOK and FSK demod, pulse detector, slicers, coding
|
|
- Analysis: Show statistics on pulses
|
|
- Decoders: Over 200 protocols
|
|
- Dumpers: Raw data files (cu8, cs16, ..., sr, ...)
|
|
- Outputs: Screen (kv), JSON, CSV, MQTT, Influx, UDP (syslog), HTTP
|
|
|
|
rtl_433 will either acquire a live signal from an input or read a sample file with a loader.
|
|
Then process that signal, analyse it's properties (if enabled) and write the signal with dumpers (if enabled).
|
|
The raw data is run through decoders to produce decoded output data.
|
|
|
|
## Inputs
|
|
|
|
Possible inputs are RTL-SDR, SoapySDR, and rtl_tcp.
|
|
|
|
Inputs are selected with the `-d` option:
|
|
```
|
|
[-d <RTL-SDR USB device index> | :<RTL-SDR USB device serial> | <SoapySDR device query> | rtl_tcp | help]
|
|
```
|
|
|
|
### RTL-SDR
|
|
|
|
For RTL-SDR use the `-d` option as:
|
|
|
|
```
|
|
[-d <RTL-SDR USB device index>] (default: 0)
|
|
[-d :<RTL-SDR USB device serial (can be set with rtl_eeprom -s)>]
|
|
```
|
|
|
|
If RTL-SDR support is compiled in (see the first line of `rtl_433 -V`) the default input will be the first available RTL-SDR device.
|
|
This can also explicitly be selected with `rtl_433 -d 0`. Use e.g. `rtl_433 -d 1` to select the second device.
|
|
|
|
If you have set a serial number on your device you can use that number prefixed with a colon to select a device,
|
|
e.g. `rtl_433 -d :NESDRSMA`.
|
|
|
|
The sample format read from RTL-SDR is always `CU8`.
|
|
|
|
### SoapySDR
|
|
|
|
For SoapySDR use the `-d` option as:
|
|
|
|
```
|
|
[-d ""] Open default SoapySDR device
|
|
[-d driver=rtlsdr] Open e.g. specific SoapySDR device
|
|
```
|
|
|
|
If SoapySDR support is compiled in (see the first line of `rtl_433 -V`) and RTL-SDR is not then the default input will be the first available SoapySDR device.
|
|
This can also explicitly be selected with `rtl_433 -d ""`.
|
|
|
|
Otherwise specify a driver string to select the SoapySDR device. Use e.g. `rtl_433 -d "driver=rtlsdr"` to use RTL-SDR over Soapy.
|
|
|
|
Usual SoapySDR driver string are e.g. `"driver=remote,remote=tcp://192.168.2.1:55132"`, `"driver=plutosdr"`, etc.
|
|
|
|
The sample format read from SoapySDR is likely `CS16`.
|
|
A sample format of `CU8` is tried first, but unlikely to be supported by SoapySDR drivers.
|
|
|
|
### rtl_tcp
|
|
|
|
For rtl_tcp use the `-d` option as:
|
|
|
|
```
|
|
[-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
|
|
```
|
|
|
|
The rtl_tcp input is always available. The default host is "localhost" and default port is "1234".
|
|
|
|
Use e.g. `rtl_433 -d rtl_tcp:192.168.2.1` or `rtl_433 -d rtl_tcp:192.168.2.1:2143` to select a specific source.
|
|
|
|
### Input Gain
|
|
|
|
The input device gain can be set with the `-g` 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.
|
|
|
|
```
|
|
|
|
The default gain setting will be automatic gain (AGC enabled).
|
|
|
|
For RTL-SDR the gain is given in dB, where "0" selects automatic gain.
|
|
|
|
For SoapySDR a gain argument of `""` selects automatic gain,
|
|
a gain value in dB can be used for automatic distribution to the gain stages,
|
|
and string of gain elements sets the given gain stages individually.
|
|
|
|
Use e.g. `-g "LNA=20,TIA=8,PGA=2"` for LimeSDR.
|
|
|
|
### Antenna and settings
|
|
|
|
For SoapySDR the antenna and various other settings can be selected with `-t`:
|
|
|
|
```
|
|
[-t <settings>] apply a list of keyword=value settings for SoapySDR devices
|
|
e.g. -t "antenna=A,bandwidth=4.5M,rfnotch_ctrl=false"
|
|
```
|
|
|
|
### Center Frequency
|
|
|
|
The center frequency can be selected with `-f`:
|
|
|
|
```
|
|
[-f <frequency>] Receive frequency(s) (default: 433920000 Hz)
|
|
```
|
|
|
|
The default frequency is 433.92 MHz and can be explicitly requested with `-f 433.92M`.
|
|
|
|
You can give a frequency in Hz, like `-f 433920000` or use suffixes of `k`, `M`, or `G`,
|
|
e.g. `-f 433920k`, or `-f 433.92M`.
|
|
|
|
Other interesting frequencies are e.g. `-f 868M`, `-f 315M`, `-f 345M`, `-f 915M`.
|
|
If you fine tune the frequency to your sender device you should avoid hitting the sender frequency dead center.
|
|
The resulting DC (direct current) signal is often attenuated by receivers and hard to make out when analysing samples.
|
|
A small offset of 10 kHz to 50 kHz works best.
|
|
|
|
The `-f` option can be used multiple times to set up a list of frequency to hop.
|
|
Use the `-H` option to set up the time to stay on each frequency or list on `-H` per `-f` to set a stay time for each frequency.
|
|
(The last hop time given will be the default for all frequencies.)
|
|
|
|
### PPM correction
|
|
|
|
A PPM error correction value can be given with `-p`:
|
|
|
|
```
|
|
[-p <ppm_error] Correct rtl-sdr tuner frequency offset error (default: 0)
|
|
```
|
|
|
|
The PPM error correction is most commonly used to counter the drift in warmed up RTL-SDR devices.
|
|
|
|
### Sample rate
|
|
|
|
A sample rate value can be given with `-s`:
|
|
|
|
```
|
|
[-s <sample rate>] Set sample rate (default: 250000 Hz)
|
|
```
|
|
|
|
The default sample rate is 250 kHz and can be explicitly requested with `-s 250k`.
|
|
|
|
You can give a sample rate in Hz, like `-s 250000` or use suffixes of `k`, `M`, or `G`,
|
|
e.g. `-f 250k`, or `-f 8M`.
|
|
Note that the suffix is metric, the 1024000 Hz sample rate common with RTL-SDR has to be given as `-s 1024k`.
|
|
|
|
## Decoders
|
|
|
|
Decoders can be selected with the `-R` and `-X` option:
|
|
|
|
```
|
|
[-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)
|
|
```
|
|
|
|
By default all decoders with proper validity checking are enabled.
|
|
|
|
You can disable selected decoders with any number of `-R -<number>` options.
|
|
E.g. use `rtl_433 -R -8 -19` to disable the LaCrosse and Nexus decoders.
|
|
|
|
Some decoders have little validity checking and may share very common signal characteristics.
|
|
This will result in lots of false-positive decodes.
|
|
These decoders are not enabled by default and you need to explicitly enable them with `-R <number>`.
|
|
|
|
You can enable only selected decoders with any number of `-R <number>` options.
|
|
Note that this will override the default and not select any decoder by default.
|
|
E.g. use `rtl_433 -R 8 19` to enable only the LaCrosse and Nexus decoders.
|
|
|
|
An output line of `Registered <n> out of <N> device decoding protocols` will tersely show the enabled decoders.
|
|
|
|
Lastly the `-X` option can be used to add a custom flex decoder.
|
|
This can be used with `-R 0` to disable all default decoders.
|
|
E.g. `rtl_433 -R 0 -X "<spec>"` will only run your given custom decoder.
|
|
|
|
## Flex Decoder
|
|
|
|
A flexible general purpose decoder can be added with the `-X` option:
|
|
|
|
```
|
|
[-X <spec>] to add a flexible general purpose decoder.
|
|
<spec> is "key=value[,key=value...]"
|
|
```
|
|
Most 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>`)
|
|
|
|
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` : Pulse Code Modulation (RZ or NRZ)
|
|
- `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
|
|
- `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).
|
|
|
|
Additional 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)
|
|
- `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"` specifies:
|
|
|
|
- `name` is doorbell
|
|
- `modulation` is `OOK_PWM`
|
|
- width of a `short` bit is 400 µs
|
|
- width of a `long` bit is 800 µs
|
|
- maximum gap width to `reset` is 7000 µs
|
|
- maximum `gap` width to new row is 1000 µs
|
|
- the data needs to contain the `match` of 24 bits `0xa9878c`
|
|
- the data needs to `repeat` at least 3 times
|
|
|
|
To extract some bits:
|
|
|
|
Example: `get=battery:@4:{1}:[0:Ok 1:Empty]`
|
|
Using colon separated keys:
|
|
- name (`battery`)
|
|
- at which bit to start (`@4`)
|
|
- how many bits to read (`{1}`)
|
|
- optional mapping (map `0` to `Full`, map `1` to `Empty`)
|
|
- or an optional format specifier (`%x`)
|
|
|
|
A key starting with `%` is a format specifier for the KV output, in practice it will be something like `%x`, `%X`, `%04x`.
|
|
|
|
See the [`conf`](https://github.com/merbanan/rtl_433/tree/master/conf) folder for some examples of flex specs.
|
|
|
|
## Analysis
|
|
|
|
Signal data can be analysed with `-A`, `-a`, sample data can be dumped with `-S`:
|
|
|
|
```
|
|
[-a] Analyze mode. Print a textual description of the signal.
|
|
[-A] Pulse Analyzer. Enable pulse analysis and decode attempt.
|
|
Disable all decoders with -R 0 if you want analyzer output only.
|
|
[-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.
|
|
```
|
|
|
|
The `-a` option enables the (old) pulse decoder to print a textual description of the signal.
|
|
The output might not be too useful, best to use the newer `-A` option.
|
|
|
|
The `-A` option enables the (new) pulse analyzer.
|
|
Each received transmission will be displayed in a statistical overview.
|
|
A probable coding will be inferred and attempted to decode.
|
|
|
|
The "Pulse width distribution", "Gap width distribution", and "Pulse period distribution"
|
|
can tell you about the timing in the `width` column,
|
|
and the coding in the `count` column.
|
|
|
|
E.g. a single (or dominant count) pulse width with two gap widths is likely PPM,
|
|
E.g. a two (or dominant count) pulse widths with a sinle gap widths or single period width is likely PWM.
|
|
|
|
Disable all decoders with `-R 0` if you want to view the analyzer output only.
|
|
|
|
The `-S` option allows you to dump received transmissions for further analysis.
|
|
Use e.g. `rtl_433 -S all` to dump all signals or `rtl_433 -S unknown` to dump only signals with no successful decodes (by enabled decoders).
|
|
|
|
On file will be created per signal, see also "File names".
|
|
Note: Saves raw I/Q samples `CU8` (uint8 pcm, 2 channel) for RTL-SDR and `CS16` (int16 pcm, 2 channel) for SoapySDR.
|
|
|
|
## Loaders and Dumpers
|
|
|
|
Sample data can be loaded or dumped with `-r`, `-w`, `-W`, and codes verified with `-y`:
|
|
|
|
```
|
|
[-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
|
|
[-y <code>] Verify decoding of demodulated test data (e.g. "{25}fb2dd58") with enabled devices
|
|
```
|
|
|
|
### Read file (loaders)
|
|
|
|
Use the `-r` option or stdin to read signal data (instead of live input):
|
|
|
|
```
|
|
[-r <filename> | help] Read data from input file instead of a receiver
|
|
```
|
|
|
|
Parameters are detected from the full path, file name, and extension. See also "File names".
|
|
|
|
File content and format options are:
|
|
`cu8`, `cs16`, `cf32` (`IQ` implied), and `am.s16`.
|
|
|
|
### Write file (dumpers)
|
|
|
|
Use the `-w` and `-W` option to dump all signal data:
|
|
|
|
```
|
|
[-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 extension. See also "File names".
|
|
|
|
File content and format options are:
|
|
`cu8`, `cs16`, `cf32` (`IQ` implied),
|
|
`am.s16`, `am.f32`, `fm.s16`, `fm.f32`,
|
|
`i.f32`, `q.f32`, `logic.u8`, `ook`, and `vcd`.
|
|
|
|
For example you can dump the live decoded pulse data to stdout with `rtl_433 -w OOK:-`.
|
|
|
|
### Load bitbuffer code
|
|
|
|
Use the `-y` option to test a known code line (bitbuffer):
|
|
|
|
```
|
|
[-y <code>] Verify decoding of demodulated test data (e.g. "{25}fb2dd58") with enabled devices
|
|
```
|
|
|
|
If you are developing or testing a decoder you can skip the device input or sample loading step and directly give a known code line (bitbuffer) to the enabled decoders.
|
|
|
|
### File names
|
|
|
|
Samples recorded using the `-S` option will automatically be given filenames with some meta-data.
|
|
The signals will be stored individually in files named `g<NNN>_<FFF>M_<RRR>k.cu8` :
|
|
|
|
| Parameter | Description
|
|
|---------|------------
|
|
| **NNN** | signal grabbed number
|
|
| **FFF** | frequency
|
|
| **RRR** | sample rate
|
|
|
|
File names used with `-r`, and `-w` / `-W` (loaders and dumpers) also follow that convention.
|
|
|
|
A center frequency is detected from the filename as (fractional) number suffixed with `M`, `Hz`, `kHz`, `MHz`, or `GHz`.
|
|
|
|
A sample rate is detected from the filename as (fractional) number suffixed with `k`, `sps`, `ksps`, `Msps`, or `Gsps`.
|
|
|
|
Parameters must be separated by non-alphanumeric chars and are case-insensitive.
|
|
|
|
File content and format are detected by th extension, possible options are:
|
|
|
|
- `cu8` (`IQ` implied)
|
|
- `cs16` (`IQ` implied)
|
|
- `cf32` (`IQ` implied)
|
|
- `am.s16'`
|
|
- `am.f32`
|
|
- `fm.s16`
|
|
- `fm.f32`
|
|
- `i.f32`
|
|
- `q.f32`
|
|
- `logic.u8`
|
|
- `ook`
|
|
- `vcd`
|
|
|
|
Overrides can be prefixed to the actual filename, separated by colon (`:`).
|
|
E.g. default detection by extension: path/filename.am.s16 and forced overrides: am:s16:path/filename.ext
|
|
|
|
::: warning
|
|
Note that not all file types are supported/applicable by loaders or dumpers.
|
|
:::
|
|
|
|
## Outputs
|
|
|
|
Use the `-F` option to add outputs, use `-M`, `-K`, and `-C` to configure meta-data:
|
|
|
|
```
|
|
[-F kv | json | csv | mqtt | syslog | 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 | stats | bits | help] Add various meta data to each output.
|
|
[-K FILE | PATH | <tag>] Add an expanded token or fixed tag to every output line.
|
|
[-C native | si | customary] Convert units in decoded output.
|
|
```
|
|
|
|
Without any `-F` option the default is KV output. Use `-F null` to remove that default.
|
|
|
|
### KV output
|
|
|
|
Use `-F kv` to add an output in KV format.
|
|
|
|
A colorful, column based output intended for screen display.
|
|
|
|
Append output to file with `:<filename>` (e.g. `-F kv:log.txt`), defaults to stdout.
|
|
|
|
::: warning
|
|
Note: the `kv` output is not a machine-readable key-value format, use the JSON output for that.
|
|
:::
|
|
|
|
### JSON output
|
|
|
|
Use `-F json` to add an output in JSON format.
|
|
|
|
Universally machine-readable output.
|
|
|
|
Append output to file with `:<filename>` (e.g. `-F json:log.json`), defaults to stdout.
|
|
|
|
### CSV output
|
|
|
|
Use `-F csv` to add an output in CSV format.
|
|
|
|
Append output to file with `:<filename>` (e.g. `-F csv:log.csv`), defaults to stdout.
|
|
|
|
::: warning
|
|
Note: the `csv` output is not recommended for post-processing, use the JSON output for a machine-readable format.
|
|
:::
|
|
|
|
### MQTT output
|
|
|
|
Use `-F mqtt` to add an output in MQTT format.
|
|
|
|
Specify MQTT server with e.g. `-F mqtt://localhost:1883`.
|
|
|
|
Add MQTT options with e.g. `-F "mqtt://host:1883,opt=arg"`.
|
|
Supported MQTT options are: `user=foo`, `pass=bar`, `retain[=0|1]`, `<format>[=<topic>]`.
|
|
|
|
Supported MQTT formats: (default is all formats)
|
|
- `events`: posts JSON event data
|
|
- `states`: posts JSON state data
|
|
- `devices`: posts device and sensor info in nested topics
|
|
|
|
The `<topic>` string will expand keys like `[/model]`, see below.
|
|
E.g. `-F "mqtt://localhost:1883,user=USERNAME,pass=PASSWORD,retain=0,devices=rtl_433[/id]"`
|
|
|
|
### MQTT Format Strings
|
|
|
|
Use format strings of:
|
|
|
|
- `[token]`: expand to token or nothing
|
|
- `[token:default]` expand to token or default
|
|
- `[/token]` expand to token with leading slash or nothing
|
|
- `[/token:default]` expand to token or default with leading slash
|
|
|
|
Tokens are `type`, `model`, `subtype`, `channel`, `id`, and `protocol` for now.
|
|
|
|
Note that for `protocol` to be available you first need to add it to the meta-data with `-M protocol`.
|
|
|
|
Examples:
|
|
|
|
- `sensors[/channel:0][/id]` : always have a channel add id if available, you can also use `sensors/[channel:0][/id]`
|
|
- `sensors[/channel][/id]` : use channel and then id, each if available
|
|
- `sensors[/id][/channel]` : use id and then channel, each if available
|
|
- `sensors[/channel:0]-[id:0]` : always have a combined channel and id
|
|
- ...
|
|
|
|
Defaults are a base topic of `rtl_433/<hostname>/` continued
|
|
- for `devices` with `devices[/type][/model][/subtype][/channel][/id]`
|
|
- for `events` with `events`
|
|
- for `states` with `states`
|
|
|
|
### SYSLOG output
|
|
|
|
Use `-F syslog` to add an output in SYSLOG format.
|
|
|
|
Specify host/port for syslog with e.g. `-F syslog:127.0.0.1:1514`
|
|
|
|
A UDP output of JSON messages with Syslog compatible header data.
|
|
|
|
E.g. a UDP text payload of
|
|
```
|
|
<165>1 2019-08-29T06:38:19Z raspi.fritz.box rtl_433 - - - {"time":"2019-08-29 08:38:19","model":"Nexus-TH","id":42,"channel":2,"battery_ok":1,"temperature_C":20.5,"humidity":83}
|
|
```
|
|
See also [RFC 5424 - The Syslog Protocol](https://tools.ietf.org/html/rfc5424#page-8)
|
|
|
|
### NULL output
|
|
|
|
Without any `-F` option the default is KV output. Use `-F null` to remove that default.
|
|
|
|
### Meta information
|
|
|
|
```
|
|
[-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.
|
|
- 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:unix:utc: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).
|
|
|
|
```
|
|
[-K FILE | PATH | <tag>] Add an expanded token or fixed tag to every output line.
|
|
```
|
|
|
|
- Use `-K FILE` to add the base file name (from a loader) to every output line.
|
|
- Use `-K PATH` to add the full path name (from a loader) to every output line.
|
|
- Use `-K <tag>` to add a fixed custom tag to every output line.
|
|
|
|
### Data conversion
|
|
|
|
You can choose to normalize data by unit conversion with the `-C` option:
|
|
|
|
```
|
|
[-C native | si | customary] Convert units in decoded output.
|
|
```
|
|
|
|
The default is no conversion, you explicitly select this with `-C native`.
|
|
|
|
With `-C si` units are converted to the SI system:
|
|
- converts fields of Fahrenheit to Celsius (`_F` to `_C`)
|
|
- converts fields of Miles/h to km/h (`_mph` to `_kph`, `_mi_h` to `_km_h`)
|
|
- converts fields of Inch to mm (`_in` to `_mm`)
|
|
- converts fields of Inch/h to mm/h (`_in_h` to `_mm_h`)
|
|
- converts fields of InchHg to hPa (`_inHg` to `_hPa`)
|
|
- converts fields of PSI to kPa (`_PSI` to `_kPa`)
|
|
|
|
With `-C customary` units are converted to customary units:
|
|
- converts fields of Celsius to Fahrenheit (`_C to _F`)
|
|
- converts fields of km/h to Miles/h (`_kph to _mph`, `_km_h to _mi_h`)
|
|
- converts fields of mm to Inch (`_mm to _in`)
|
|
- converts fields of mm/h to Inch/h (`_mm_h to _in_h`)
|
|
- converts fields of hPa to InchHg (`_hPa to _inHg`)
|
|
- converts fields of kPa to PSI (`_kPa to _PSI`)
|
|
|
|
## Filter output with bridges
|
|
|
|
You can grab the decoded output from rtl_433 in various ways, then process and relay it somewhere.
|
|
|
|
### Pipes
|
|
|
|
The simplest (but not very flexible or stable) way is to use pipes.
|
|
E.g. capture the decode JSON messages and relay the to MQTT with
|
|
|
|
`rtl_433 -F json -M utc | mosquitto_pub -t home/rtl_433 -l`
|
|
|
|
See also
|
|
[rtl_433_collectd_pipe.py](https://github.com/merbanan/rtl_433/blob/master/examples/rtl_433_collectd_pipe.py), and
|
|
[rtl_433_statsd_pipe.py](https://github.com/merbanan/rtl_433/blob/master/examples/rtl_433_statsd_pipe.py)
|
|
for other examples of this method.
|
|
|
|
### UDP
|
|
|
|
A better way is to use the Syslog-compatible UDP output to capture and relay the JSON message.
|
|
|
|
See also
|
|
[rtl_433_graphite_relay.py](https://github.com/merbanan/rtl_433/blob/master/examples/rtl_433_graphite_relay.py),
|
|
[rtl_433_mqtt_relay.py](https://github.com/merbanan/rtl_433/blob/master/examples/rtl_433_mqtt_relay.py), and
|
|
[rtl_433_statsd_relay.py](https://github.com/merbanan/rtl_433/blob/master/examples/rtl_433_statsd_relay.py)
|
|
for examples of this method.
|
|
|
|
### MQTT
|
|
|
|
If you already use the MQTT output, then you can capture the MQTT data, process it and inject derived data back.
|
|
|
|
See e.g. [rtl_433_mqtt_hass.py](https://github.com/merbanan/rtl_433/blob/master/examples/rtl_433_mqtt_hass.py)
|
|
for an example of this method.
|