Skip to main content

rtl_433 (433/868 MHz) smart home integration, free and open source

rtl_433 (433/868 MHz) integration for Gladys Assistant

Weather stations, probes, meters and remotes on 433/868 MHz, via rtl_433 and an SDR dongle.

View on GitHubAll integrations

rtl_433 turns a 25 € SDR dongle (RTL2832U chip) into a radio receiver for hundreds of 433 MHz and 868 MHz devices: weather stations, thermometers and hygrometers, soil probes, energy meters (OWL), door contacts, motion and smoke detectors, remotes, tyre pressure sensors… This integration reads what rtl_433 hears and offers every sensor in the Discovery tab of Gladys. Not affiliated with the rtl_433 project.

Development version (0.1). Tested against the real rtl_433 (25.12) replaying radio recordings of its test suite, with a real Mosquitto broker, but not with a real SDR dongle yet. Feedback is welcome on the GitHub repository.

How it works​

The dongle is not plugged into Gladys: integrations get no USB access. rtl_433 runs next to the dongle, in its own Docker container (on the Gladys machine, or on a Raspberry Pi better placed in the house), and publishes what it hears to your MQTT broker. The integration reads that broker.

radio sensors ))) SDR dongle -> rtl_433 -> MQTT broker -> integration -> Gladys

Without a broker, the integration can also read rtl_433's own HTTP server (see below).

What you get​

rtl_433 fieldIn Gladys
temperature_C, temperature_Ftemperature (converted to °C)
temperature_1_C, temperature_2_C…one temperature per probe (meat thermometers, pool…)
humidityhumidity (%)
battery_okbattery (%): 100 % = OK, 0 % = low for the sensors that say OK/LOW
wind_avg_*, wind_max_*, wind_dir_degaverage wind and gusts (km/h), direction (°)
rain_mm, rain_in, rain_rate_*cumulated rain (mm) and rate (mm/h)
pressure_hPaatmospheric pressure (hPa)
light_lux, uvilight (lux), UV index
power_W, energy_kWh, currentpower (W), energy index (kWh, OWL CM180/CM160), current
moisturesoil moisture (%)
state open/closed, contact_open, openedopening (door, window)
motionmotion
detect_wet, waterwater leak
tampertamper (case opened)
smoke detectors (Smoke-GS558…)smoke
button, cmd, code, state ON/OFF + unitone button per key, and the scene trigger
pressure_kPa, pressure_PSI of a TPMS sensortyre pressure (bar), as an option

One sensor = one model + one id (+ one channel). A station sending several kinds of messages (wind, then rain) is one device, gathering all it measures.

1. The hardware​

  • An RTL-SDR dongle (RTL2832U + R820T2/R860), for example RTL-SDR Blog V3 or V4, Nooelec NESDR: about 25 €. The supplied antenna is often enough; a 433 MHz antenna (17 cm) placed high reaches further.
  • On Linux, keep the DVB-T driver from grabbing the dongle, then plug it again:
echo 'blacklist dvb_usb_rtl28xxu' | sudo tee /etc/modprobe.d/blacklist-rtl.conf

2. Run rtl_433​

With the hertzg/rtl_433 Docker image (amd64, arm64, armv7: PC, NAS, Raspberry Pi), on the machine the dongle is plugged into. Replace the broker address, user and password:

docker run -d --name rtl_433 --restart unless-stopped \
  --device /dev/bus/usb \
  hertzg/rtl_433:latest \
  -M level \
  -F "mqtt://192.168.1.10:1883,user=USER,pass=PASSWORD,retain=0,events=rtl_433[/model][/id]"

Or with Docker Compose:

services:
  rtl_433:
    image: hertzg/rtl_433:latest
    container_name: rtl_433
    restart: unless-stopped
    devices:
      - /dev/bus/usb
    command:
      - -M
      - level
      - -F
      - mqtt://192.168.1.10:1883,user=USER,pass=PASSWORD,retain=0,events=rtl_433[/model][/id]
  • The broker can be the one of the Gladys MQTT integration (port 1883, the user and password of its configuration) or your own (Mosquitto…). Without a user, remove user=…,pass=….
  • -M level adds the signal strength of each message: it helps to recognize your sensors (see below).
  • 868 MHz (some Bresser and Fine Offset stations, European sensors): add -f 868.3M -s 1024k. To listen to both bands, the simplest is one dongle per band (two containers, each with -d :<serial number>); one dongle can alternate with -f 433.92M -f 868.3M -H 60, missing the messages sent while it listens to the other band.
  • Check that rtl_433 hears something: docker logs -f rtl_433.

3. Configure the integration​

  1. Address of the MQTT broker: as seen from the Gladys machine, its LAN IP address, not localhost (the integration runs in its own container). Examples: mqtt://192.168.1.10:1883, mqtts://broker.lan:8883.
  2. The user name and password of the broker, if it asks for them.
  3. MQTT topic of rtl_433: keep rtl_433/#, which covers the command above as well as rtl_433's default topics (rtl_433/<host>/events).
  4. Click Test the connection: the integration waits for the first message of rtl_433 (up to 20 s) and names the sensor heard.

4. Add YOUR sensors​

Open the Discovery tab: every sensor heard shows up, named after its model, id and channel (Nexus-TH 201 ch3). The list grows over the minutes (sensors transmit every 30 to 60 s; a remote, when pressed).

The neighbours' sensors are heard too. To recognize yours, click List the sensors heard in the configuration: the sensors heard last are shown with their values, their number of messages and their signal strength. The strongest signal (dB closest to 0) is usually the nearest sensor. Tip: warm a probe in your hand, or press the remote, then list again.

Only add your sensors: the others cost nothing (nothing is sent to Gladys for a device not added) and leave the list after 24 h of silence.

Tyre pressure sensors (TPMS): every car driving by is heard, so they are left out by default. Turn the option on to follow the tyres of your car (they transmit while driving, for example when coming back to the garage).

Battery change: many cheap sensors draw a new id at every battery change. The sensor then shows up as a new device in Discovery: add it and delete the old one.

Scenes​

  • Remotes get one button per key ("Button 1", "Button 192"…), usable in the "Device state change" trigger: press (click), or on/off for the ON/OFF remotes (Nexa, KlikAanKlikUit, Waveman…). Every press is sent, the same one twice in a row too; the repeats of the radio frame of one press (1.5 s) count once.
  • The 433 MHz remote or button trigger receives every press of an added remote, filtered by remote, code (1, 192…) and action (press, on, off), with the model and the received message as variables.
  • Motion and smoke detectors only say "detected": they go back to 0 by themselves 60 s after their last message.
  • Door contacts send open and closed: their state follows the door.

Options​

OptionDefaultRole
MQTT topic of rtl_433rtl_433/#to change only if rtl_433 publishes elsewhere
Verify the TLS certificateyesturn off for a broker with a self-signed certificate on your network
Offer the TPMS sensorsnosee above
Minimum interval of a sensor30 sa meter transmitting every 6 s is recorded at this pace only (last value)

Openings, motion, alarms and remotes are never delayed. Gladys accepts 300 states per minute per integration: the integration only sends the values that change, and spreads the rest.

Without an MQTT broker: rtl_433's HTTP server​

rtl_433 can serve its messages over HTTP itself. Run it with:

docker run -d --name rtl_433 --restart unless-stopped \
  --device /dev/bus/usb -p 8433:8433 \
  hertzg/rtl_433:latest -M level -F http:0.0.0.0:8433

and type http://<IP address of that machine>:8433 as the address in the configuration. The user, password and topic fields are not used.

Under the hood​

  • The messages read are the JSON objects with a model (rtl_433's events format); the devices topics (one value per topic) and states are ignored. rtl_433's availability shows in the status of the integration: a stopped rtl_433 (its offline last will) is reported, as long as no other message arrives.
  • A device is identified by model:id<id>:ch<channel>, forever. Its features are the ones its messages carried.
  • The Discovery list is published 2 s after a new sensor, at most every 30 s; at most 500 sensors are kept in memory.
  • The badge of an added device turns "unreachable" when the broker is down, or when a sensor that measures regularly (temperature, wind, energy…) has sent nothing for an hour: flat batteries, out of range. Remotes and contacts, which only transmit when used, stay "local".
  • Implausible values (a humidity of 255 %, -3276 °C…) are ignored.

Troubleshooting​

  • "No rtl_433 event" on the test: look at docker logs rtl_433. usb_claim_interface error -6: the DVB-T driver holds the dongle (see the hardware). Nothing heard: check the frequency (-f) and the antenna.
  • "The MQTT broker is unreachable": check the IP address and the port, and that the broker accepts connections from the LAN (listener 1883 in Mosquitto 2).
  • "refused the connection": wrong user name or password, or an ACL forbidding to read rtl_433/#.
  • A sensor is heard but does not show up: "List the sensors heard" says "nothing supported yet" when none of its fields is recognized yet. Open an issue with its JSON message (docker logs rtl_433).

Privacy​

Everything stays on your network: the integration only talks to your MQTT broker (or to rtl_433). The password is stored as a secret by Gladys and never shows in the logs.

Configuration settings​

These are the settings rtl_433 (433/868 MHz) asks for in its configuration screen in Gladys.

SettingTypeRequiredDescription
Your 433/868 MHz sensors, through rtl_433sectionNortl_433 turns a 25 € SDR dongle (RTL2832U) into a receiver for hundreds of radio devices: weather stations, thermometers, soil probes, energy meters (OWL), door contacts, motion detectors, remotes, tyre sensors... The dongle is not plugged into Gladys: rtl_433 runs next to it (the Docker command is in the guide) and publishes what it hears to your MQTT broker. This integration reads it and offers every sensor heard in the Discovery tab. The neighbours' sensors are heard too: add only yours, the "List the sensors heard" button shows their values and signal. Type the address of the broker as seen from the Gladys machine: its LAN IP address, not localhost. Not affiliated with the rtl_433 project.
Address of the MQTT broker (or of rtl_433)stringYesmqtt://host:1883 or mqtts://host:8883: the broker rtl_433 publishes to (-F mqtt://...). A bare IP address means mqtt:// on port 1883. Without a broker: rtl_433's own HTTP server, http://host:8433 (-F http:0.0.0.0:8433).
User namestringNo
PasswordsecretNo
MQTT topic of rtl_433stringNoWhere rtl_433 publishes its events. rtl_433/# covers its default topics (rtl_433/<host>/events) and events=rtl_433[/model][/id]. Not used with the HTTP server.
Verify the TLS certificate of the broker (mqtts, wss)booleanNoTurn off only for a broker with a self-signed certificate on your local network.
Offer the tyre pressure sensors (TPMS)booleanNoEvery car driving by is heard: leave off, unless you want the tyres of your own car (they transmit while driving).
Minimum interval between two readings of a sensor (s)numberNoAn energy meter transmits every 6 s: Gladys keeps its last reading at this pace. Contacts, motion, alarms and remotes are never delayed.

How to install rtl_433 (433/868 MHz) in Gladys​

  1. In Gladys, open Integrations: rtl_433 (433/868 MHz) appears in the catalog, next to the native integrations, with a community badge.
  2. Click Install. Gladys pulls the Docker image (ghcr.io/lm1lc3n7/gladys-rtl433:0.1.1), starts it in a sandbox isolated from the core, and generates the integration's interface (devices, discovery and configuration).
  3. Open the Configuration screen of the integration, fill in the settings, and save.
  4. You can also install it directly from its repository URL: https://github.com/LM1LC3N7/gladys-rtl433.

rtl_433 (433/868 MHz) requires Gladys >=5.1.0. The catalog inside Gladys refreshes every hour, so a new version becomes available at most one hour after its release.

Not running Gladys yet? It is free and open source: follow the installation guide to get started.

About external integrations​

rtl_433 (433/868 MHz) is an external integration: a community integration packaged as a Docker container and published on GitHub, that Gladys installs in one click and runs in a sandbox isolated from its core. It is published and maintained by LM1LC3N7, not by the Gladys core team.

Subscribe to the Gladys Assistant newsletter

A few emails per month about new releases and project news. Sent by Pierre-Gilles Leymarie, founder of the project. Unsubscribe anytime 🙂
Last updated on