Check out my other article, Raspberry Pi Pivot, to understand more about how and why I use RTL-SDRs in my home automation. It also has the beginning how-to instructions. If you have any questions, please reach out in discord.
It’s almost been a decade since I purchased my first RTL-SDR. It was shortly before I started studying for my Amateur Radio License. I thought the story of the RTL-SDR chip was very cool, and enjoyed playing around with tools like GNU Radio and SDR# to surf the airwaves. Around that time, I was streaming on Twitch a lot. I started doing RTL-SDR projects during livestreams, mainly just proof of concept projects. I hooked my dongle up to large antennae in hopes of finding interesting signals to decode.
Eventually, I started trying to put those signals to good use. I followed someone else’s blog to learn how to decode radio signals into JSON objects using rtl_433. I wrote my own code around the rtl_433 binary to extract the data and expose it as a Prometheus endpoint. Here is a chart of my current Raspi set up that we will be referring to throughout this article:
Home Assistant and RTL-SDR
I use Home Assistant, and love it. My Home Assistant (AKA HA or HASS) is self-hosted on a virtual machine on a server that lives in my basement. It’s nothing impressive, an old desktop that I built 11 years ago. Home Assistant has great integrations available for rtl_433 and RTL-SDR, but I do not use them. My HA server does not have an RTL-SDR attached to it. All my RTL-SDRs are connected to Raspberry Pis and added to Home Assistant as REST Sensors.
As I mentioned, my server is in my basement. The sensors I care about most are outside. There are signal problems, and I need my RTL-SDRs to be more flexible in their deployments. With my Raspi set up, I can drop the sensors in a centrally located place for good coverage outside and inside.
I have three Raspberry Pis deployed around my house. Two are for receiving sensor data and one is for transmitting radio signals to my dumb devices in my house. The RPiTX project provides really easy ways record and replay radio signals using your GPIO pins. You will need a band pass filter to use this, but it’s a pretty fun project. The details of my Pis, and how they are exposing information are outlined above in the chart.
Getting Started
Raspberry Pi Pivot offers step-by-step instructions to set up your Rasbian install with rtl_433. It also covers installing Raspbian on a Le Potato, make sure to ignore that part if you’re using a real Pi and not a Le Potato. There is also a parts list that can help you source what you need to do this.
After following the instructions, here’s what you should have:
1. RTL-SDR Dongle plugged in to a Debian-based Linux OS (will be referencing Raspbian).
2. RTL-SDR drivers installed
3. rtl_433 built and installed
4. A device that rtl_433 will automatically decode.
5. Home Assistant instance to integrate the sensor into (Optional)
6. Prometheus server to integrate the sensor data into (Optional)
Finding a device to listen to is easier than you might think. There are 240+ protocols currently supported by rtl_433. Some of these devices are less than $10 at Home Depot. Others can be found even cheaper at places like Good Will. You may have some lying around your house and not know it, I did. If you have a wireless weather monitor somewhere in your house, or maybe the screen broke and the sensor is sitting in your junk drawer. Pretty much any wireless weather sensor on 915 or 433 MHZ will be auto-decoded by rtl_433.
Now that we are ready to go, let’s go ahead and listen for our sensor data with rtl_433: rtl_433 -f 915M -F json — make sure to replace 915M with whatever frequency you are going to be listening on (e.g. 433M for 433 MHZ).
You should see some output similar this:
Use -h for usage help and see https://triq.org/ for documentation.
Trying conf file at "rtl_433.conf"...
Trying conf file at "/home/pi/.config/rtl_433/rtl_433.conf"...
Trying conf file at "/usr/local/etc/rtl_433/rtl_433.conf"...
Trying conf file at "/etc/rtl_433/rtl_433.conf"...
New defaults active, use "-Y classic -s 250k" for the old defaults!
Registered 126 out of 154 device decoding protocols [ 1-4 8 11-12 15-17 19-21 23 25-26 29-36 38-60 63 67-71 73-100 102-105 108-116 119 121 124-128 130-149 151-154 ]
Found Rafael Micro R820T tuner
Exact sample rate is: 1000000.026491 Hz
Sample rate set to 1000000 S/s.
Tuner gain set to Auto.
Tuned to 915.000MHz.
{"time" : "2023-07-31 01:22:24", "model" : "Fineoffset-WH65B", "id" : 25, "battery_ok" : 1, "temperature_C" : 30.700, "humidity" : 40, "wind_dir_deg" : 229, "wind_avg_m_s" : 0.000, "wind_max_m_s" : 0.000, "rain_mm" : 1309.878, "uv" : 509, "uvi" : 1, "light_lux" : 24784.000, "mic" : "CRC"}It might take a moment to see JSON formatted output. This command starts your tuner listening on 915 MHZ and will automatically detect and decode known signal types that it receives. Rtl_433 makes this whole thing so easy, it’s a great tool and open source project. Next, let’s go over how to expose your own sensor data.
Exposing your sensor data to Prometheus and Home Assistant
The next steps are to go from running a command to exposing your sensor. We will do this in a very basic way, only bash commands and command line tools, no code needed.
# install apache to expose the json file to home assistant
sudo apt install -y apache2
# install your new crontab
crontab -e
# Paste this in:
*/1 * * * * rtl_433 -f 915M -E quit -F json:/tmp/sensor.json && cat /tmp/sensor.json | tail -n 1 > /var/www/html/sensor.json && echo "" > /tmp/sensor.json This is an over-simplified example that will work with one device. If you want more devices, you will have to find a more advanced solution. The purpose of this example is to break it into its most simple parts so that you can find your own path forward. The cronjob runs every minute and will run rtl_433 until it receives sensor data. It will write the sensor data to a temporary json file and automatically exit. The sensor file is then modified slightly (because rtl_433 can output multiple lines of JSON) and write to the sensor.json file hosted by apache. With default Raspian settings this should work without any chown or chmod. You should be able to view your sensor file at http://your_raspi_ip/sensor.json.
Adding the sensor to Home Assistant
You will need to make a modification to your configuration.yaml for something like this:
sensor:
- platform: rest
name: Outdoor lux
resource: http://192.168.x.x/current_weather.json
device_class: "illuminance"
unit_of_measurement: "lx"
value_template: '{{ value_json.uv }}' The above YAML block adds a sensor called “Outdoor lux” to home assistant. Its value will be the property uv in the json payload hosted at the specified IP address. Update these values so they match what you need. Make sure you restart Home Assistant before looking for the values to populate.
Adding Prometheus
You may decide that HA integration is enough for you. HA has its own Grafana Add-on, so you can get the same results through different methods. I set Grafana and Prometheus up before I had my weather data in Home Assistant. The REST sensor was kind of a retrofit to make my Prometheus set up work with HA. We are going to choose a very simple way of doing this next step.
I would recommend using the official Prometheus community json exporter. I am using one that I wrote in a few hours, because I couldn’t find an existing exporter that supported jq-style JSON selectors.
I will let you choose your own, but the next step is pretty simple. Configure the json exporter to use the /var/www/html/sensor.json and choose the fields and datatypes you want to expose. Most likely, everything will be a gauge data type. Run the exporter and add your endpoint to your Prometheus endpoints configuration.
Final Thoughts
This is not the final installation of this series. We should be in a good spot now, with an MVP set up for monitoring a radio sensor. Hopefully this will inspire you to build your own sensor network with Raspberry Pi and RTL-SDR.
Next time we will talk more in-depth about mature solutions for instrumenting these RTL-SDR sensors for both Prometheus and Home Assistant. I do not claim my approach is the best one, it undoubtedly isn’t. I have iterated on these solutions for many years. I look for high value, low complexity solutions. Hopefully this article will help you find your own. Thank you for reading.
