rtl_433-hass-addons/rtl_433

rtl_433 Home Assistant Add-on

About

This add-on is a simple wrapper around the excellent rtl_433 project that receives wireless sensor data via one of the supported SDR dongles, decodes and outputs it in a variety of formats including JSON and MQTT. The wireless sensors rtl_433 understands transmit data mostly on 433.92 MHz, 868 MHz, 315 MHz, 345 MHz, and 915 MHz ISM bands.

View the rtl_433 documentation

How it works

The only thing this add-on does is run rtl_433 under the Home Assistant OS supervisor. All you have to do is supply a config file.

By default, rtl_433 prints the data it receives to the terminal - it is up to you to configure it to publish the data to MQTT so that Home Assistant can access it, which can be done with one line in the config file.

Once you get the rtl_433 sensor data into MQTT, you'll need to help Home Assistant discover and make sense of it. You can do that in a number of ways:

• manually configure sensors and binary_sensors in HA and link them to the appropriate MQTT topics coming out of rtl_433,
• run the rtl_433_mqtt_hass.py script manually or on a schedule to do most of the configuration automatically, or
• install the rtl_433 MQTT Auto Discovery Home Assistant Add-on, which runs rtl_433_mqtt_hass.py for you.

Prerequisites

To use this add-on, you need the following:

1. An SDR dongle supported by rtl_433.

2. Home Assistant OS running on a machine with the SDR dongle plugged into it.

3. Some wireless sensors supported by rtl_433. The full list of supported protocols and devices can be found under "Supported device protocols" section of the rtl_433's README.

Installation

1. Create an rtl_433 config file that does what you need. It might work better if you do this on a computer other than the one running Home Assistant OS, so that you can experiment freely and iterate until you arrive at a configuration that works well. See below for more details.

2. Upload the config file into Home Assistant's "/config" directory using whatever method works for you (via Samba add-on, ssh/scp, File Editor add-on etc).

3. Install the add-on.

4. Plug your SDR dongle to the machine running the add-on.

5. Start the addon. A default configuration will be created in /config/rtl_433/. To add or edit additional configurations, create multiple .conf.template files in that directory.

6. Start the add-on and check the logs.

Configuration

For a "zero configuration" setup, install the Mosquitto broker addon. While other brokers may work, they are not tested and will require manual setup. Once the addon is installed, start or restart the rtl_433 and rtl_433_mqtt_autodiscovery addons to start capturing known 433 MHz protocols.

For more advanced configuration, take a look at the example config file included in the rtl_433 source code: rtl_433.example.conf

Note that since the configuration file has bash variables in it, dollar signs and other special shell characters need to be escaped. For example, to use the literal string $GPRMC in the configuration file, use \$GPRMC.

The retain option controls if MQTT's retain flag is enabled or disabled by default. It can be overridden on a per-radio basis by setting retain to true or false in the output setting.

When configuring manually, assuming that you intend to get the rtl_433 data into Home Assistant, the absolute minimum that you need to specify in the config file is the MQTT connection and authentication information:

output      mqtt://HOST:PORT,user=XXXX,pass=YYYYYYY

rtl_433 defaults to listening on 433.92MHz, but even if that's what you need, it's probably a good idea to specify the frequency explicitly to avoid confusion:

frequency   433.92M

You might also want to narrow down the list of protocols that rtl_433 should try to decode. The full list can be found under "Supported device protocols" section of the README. Let's say you want to listen to Acurite 592TXR temperature/humidity sensors:

protocol    40

Last but not least, if you decide to use the MQTT auto discovery script or add-on, its documentation recommends converting units in all of the data coming out of rtl_433 into SI:

convert     si

Assuming you have only one USB dongle attached and rtl_433 is able to automatically find it, we arrive at a minimal rtl_433 config file that looks like this:

output      mqtt://HOST:PORT,user=XXXX,pass=YYYYYYY

frequency   433.92M
protocol    40

convert     si

Please check the official rtl_433 documentation and config file examples for more information.

Credit

This add-on is based on James Fry's rtl4332mqtt Hass.IO Add-on, which is in turn based on Chris Kacerguis' project here: https://github.com/chriskacerguis/honeywell2mqtt, which is in turn based on Marco Verleun's rtl2mqtt image here: https://github.com/roflmao/rtl2mqtt.