# rtl_433

Setting up rtl_433 hardware by hand, in `weewx.conf`.

Generated by `tools/build_protocols.py`. What each protocol needs is written in that
tool; what it is called and what goes into the console comes from the code. Do not edit
by hand.

> **There is a web interface for all of this.** It is on by default, and the driver
> prints its address when WeeWX starts:
>
> ```
> INFO user.ultimatepush.driver: The web interface is at
> http://1.2.3.4:8080/?token=abcdefg12345
> ```
>
> Everything on this page can be done there instead, and one thing is much easier:
> deciding which reading goes into which database column. See
> [Web interface](Web-interface).

## What it is

Any 433, 868 or 915 MHz sensor rtl_433 decodes, heard with an RTL-SDR stick: outdoor
thermometers, soil probes, rain gauges, pool sensors

| | |
|---|---|
| In `protocols = auto` | no, it has to be named |
| Named by | its `model`, `id` and `channel` together |
| Recording from | whichever sensors you let in |

## The smallest configuration that works

```ini
[Station]
    station_type = UltimatePush

[UltimatePush]
    driver = user.ultimatepush.driver
    port = 8000
    protocols = rtl433

    [[stations]]
        [[[garden]]]
            id = Bresser-6in1/8455/0
```

The identity is what the sensor puts on the air and cannot be chosen, so this line
cannot be written until it has been heard once. The log prints it, ready to copy.
Nothing is adopted here, not even the first sensor heard: a receiver was pointed at
nothing and hears over the fence, so every sensor waits to be let in and only the ones
you let in are recorded. The port does not have to be written down either, unless you
told rtl_433 to use a different one: `udp_port` defaults to the one in the command
above.

## What else it takes

rtl_433 is a separate program and is not part of this driver. Install it with your
package manager, then have it send here.

Run it with `-C si`, which asks it to convert what it can itself, and `-F
syslog:127.0.0.1:1433`, which is how it sends.

One stick hears every sensor in range, including your neighbours'. Each one shows here
as a station waiting to be let in, and only the ones you let in are recorded.

Many of these sensors pick a new id when their batteries are changed. When that happens
the station stops recording and a new one appears; the web interface can move the old
station onto the new id and keep its columns.

## Options of its own

None. Everything that applies to this protocol applies to all of them, and is in
[Configuration](Configuration#driver-options).

## Worth knowing

rtl_433 is a separate program and none of it is part of this driver. Install it, and
have it send here:

```bash
sudo apt install rtl-433
rtl_433 -C si -F syslog:127.0.0.1:1433
```

`-C si` asks it to convert what it can itself, which costs nothing and means one less
thing that can be wrong. `-F syslog:` is how it sends: one datagram per message, which
is why nothing has to start or supervise it.

Leave it running with a unit of its own rather than starting it by hand. Put this in
`/etc/systemd/system/rtl_433.service`:

```ini
[Unit]
Description=rtl_433
After=network.target

[Service]
ExecStart=/usr/bin/rtl_433 -C si -F syslog:127.0.0.1:1433
Restart=always
User=nobody

[Install]
WantedBy=multi-user.target
```

then `sudo systemctl enable --now rtl_433`. The receiver is a USB device and belongs to
root until a udev rule says otherwise; rtl-433's package installs one.

**Everything in range turns up, including the neighbours'.** That is the nature of
listening rather than being sent to, so nothing is recorded until you say which sensors
are yours. They appear in the web interface, most often heard first, which is a good
guide: something heard sixty times an hour is close by and transmitting on a schedule,
and something heard once was a car going past. *Not mine* takes one off the list for
good.

**A battery change can rename a sensor.** rtl_433's own documentation says an id may be
programmed in or may be chosen afresh at each power on. When one of yours does that it
stops recording and turns up as something new; the web interface can move the station
onto the new id, which keeps its name, its channel and the columns it had.

No receiver yet? `python -m user.ultimatepush --fake-rtl433` sends what rtl_433 sends,
three sensors at a time, one of them a neighbour's.

## When nothing arrives

Nothing arrives at all. rtl_433 is not running, or is sending somewhere else. `rtl_433
-C si -F json` in a terminal prints what it hears, which settles whether the radio is
working before anything about this driver comes into it.

Everything is refused. That is what happens until a sensor is let in, and it is on
purpose: a receiver hears over the fence. The log names each one.

A sensor was recording and stopped. Look for a new one in the waiting list with the same
model and a different id: that is what a battery change does.

The temperature is right and the rain is nonsense. Nearly every one of these gauges
sends the total since its battery went in, and WeeWX has to be told to difference it.
That is `[StdWXCalculate]` and the driver says so at startup if it is not set.

## More than one station

This is one station among however many others. Which of them fills `outTemp`, and where
the rest of their readings go, is in [Several stations](Several-stations).