rtl_433/examples

rtl_433 scripts (example and useful)

This directory contains a number of scripts to process the output of rtl_433 in various ways. Some are truly examples; they worked for someone else and won't work for you but will help understanding. Some are (or will be once enhanced) actually useful to a fairly broad set of people.

It is likely that a use outside what has been contemplated will require writing new code, with some kind of filtering and transformation.

Generally, python scripts should work with Python 2 or relatively recent Python 3. (It is TBD to deprecate Python 2; it is not clear that anyone still cares.)

These scripts typically send data to some other system, store it in a database, or process it in some way. Recall that rtl_433's philosophy is to just output received transmissions, with minimal processing and with no checking/correlation of adjacent repeated frames.

This directory has a strong bias to the use of JSON; the point of that encoding is that it is machine parseble and that's what we want to do.

At some point, generally-usable scripts should perhaps be promoted from examples.

Styles of Plumbing

There are two main mechanisms: piping the output json, and syslog-style UDP with one json object per packet.

pipe

The pipe examples read JSON output from rtl_433 using a pipe, i.e.

rtl_433 -F json ... | rtl_433_statsd_pipe.py

This is in many ways simple, but the programs must be started and stopped together, and only one rtl_433 can write to the processing script.

There are only two pipe programs, collectd and statsd.

UDP syslog

The relay examples consumes the (UDP) Syslog output from rtl_433 (or a legacy plain JSON datagram). Basically run rtl_433 with -F syslog:127.0.0.1:1433 and the relay script as an unrelated process, i.e.

rtl_433_mqtt_relay.py &
rtl_433 -F syslog:127.0.0.1:1433

With this, one can run tcpdump -A -i lo0 udp and port 1433 (substitute your loopback interface) to watch the traffic. One can also run multiple rtl_433 processes.

Strategies for Processing, Transmitting and Storing

(This does not belong here, but is useful to those contemplating the scripts, so it's here pending a proper home.)

This section is speculative.

Checksums and Repeated transmissions

Many devices will send a frame multiple times, perhaps 3 or 4, as a form of redundancy. Many devices have non-robust checksums. If displaying a temperature, that is often not a big deal. If storing it in a database, bad data is troublesome. One could process multiple frames that arrive close in time and try to infer which are bad decodes and what the consensus data is, and from that output one good frame. One could further reject physically implausible data (temp of fridge has been 2C and we just got a 30C reading), but this needs to recover from arbitrary situations so that would be tricky code to write. There is no code yet; this is merely a suggestion to future hackers.

Precision

Actual precision of devices varies, and there is unit conversion. There should be some scheme to ensure reasonable values (vs 5 decimal digits of temperature). This is also for future work.

Calibration

So far, rtl_433 does not deal with calibration; the job is to output what was received. A system design where the json to mqtt program has calibration data and applies it might be sensible, but this is far from clear.

Health monitoring

The main data is logging what was received, but it is also interesting to know what channel rtl_433 is listening to, noise levels, that the translation script is up, etc. This is also for future work.