rtl_433/examples/README.md

# 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 actually useful to a fairly broad set of people and are used in
production.  Some of course are somewhere in the middle.

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 relatively recent Python 3.
(While they might work with 2.7, no one is paying attention to that.)

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.  These
scripts bridge the gap between raw output and useful information.

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.

# Orientation

We attempt to categorize and describe the scripts in this directory.

Home Assistant is abbreviated HA.

## Production Scripts

A production script could be installed as a program, if it also had a
man page.  Many people should be able to use it without having to edit
the source code.

## Generally Usable Scripts

A generally usable script will likely need minor tweaking.

  - rtl_433_mqtt_relay.py: Send data via MQTT (e.g. to HA).
  - rtl_433_mqtt_hass.py: Send HA autoconfiguration data, so that entities for the decoded sensors will automatically appear.

## True Examples

These are not likely to to be useful, except that reading them will
lead to better understanding, and bits of code may be useful..  

  - mqtt_rtl_433_test_client.py: Connect to broker and print data from rtl topics
  - rtl_433_custom.php: Receive json syslog packets in php
  - rtl_433_custom.py: Receive json syslog packets in python
  - rtl_433_gps.py: Receive json data and also gpsd data 
  - rtl_433_http_cmd.py: Custom hop controller example for rtl_433's HTTP cmd API
  - rtl_433_http_cmd.sh: Custom hop controller example for rtl_433's HTTP cmd API
  - rtl_433_http_events.py: Custom data handling example for rtl_433's HTTP (chunked) streaming API of JSON events
  - rtl_433_http_stream.php: Short example of an TCP client written in PHP for rtl_433
  - rtl_433_http_stream.py: Custom data handling example for rtl_433's HTTP (line) streaming API of JSON events
  - rtl_433_http_ws.py: Custom data handling example for rtl_433's HTTP WebSocket API of JSON events

## Uncategorized

These scripts are in the directory but have not been sorted and described.

  - rtl_433_graphite_relay.py: Send data to graphite
  - rtl_433_influxdb_relay.py: Send data to influxdb
  - rtl_433_prometheus_relay.py: Send data to prometheus
  - rtl_433_rrd_relay.py: Send data to rrd
  - rtl_433_statsd_relay.py: Send data to statsd
  - rtl_433_collectd_pipe.py: Send data to collected
  - rtl_433_statsd_pipe.py: Send data to statsd
  - rtl_433_json_to_rtlwmbus.py: convert rtl_433 wmbus json output to rtlwmbus output

# 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.