Hey all. First timer here. I wanted to share with you how I got my existing and embedded Honeywell opening sensors working with Home Assistant.

Required Components:

Working Home Assistant Installation (any platform)

Preferably a separate linux box for wireless reception. (running rtl-sdr, rtl_433, mosquitto)

A sensor or two.

an RTL-SDR USB stick receiver and an antenna (the little chincy one that comes with it suffices just fine.)

My Current Setup:

My setup is probably more complex than many will have to deal with so if I can get it working, so you can you. I’m running two VMs in virtualbox on Windows. Why virtualbox? Because USB passthrough and I don’t want to pay for VMWare. Most of you will likely do this on Raspbian or a dedicated server and that’s fine. My HA VM is an Ubuntu 16 VM with docker installed (to make handling HA updates way easier). The second VM is the one that handles radio reception and has the MQTT broker installed on it.

It’s totally ok to do your radio reception with the same machine that’s running HA. Especially for you Raspian folks. Very little CPU is used in the process. I’m going to write this assuming you’re going to follow my lead and use a separate machine to do this since this tutorial is based on mosquitto for mqtt brokering. If you’re using Docker on Windows or Mac, I would really implore you to either create a separate container or use a different VM altogether. If you’re using Docker on Windows, you’ll want to use Docker Toolbox instead of base Docker to ensure you can use Virtualbox as your hypervisor as Hyper-V doesn’t yet allow for passing through USB devices to the VM (No foggy idea why…)

Setup Steps:

On your HA box you’ll need to install rtl-sdr and associated libraries.

Please see the instructions:

For CentOS/RHEL

For Ubuntu, Debian

Once you can run rtl_test without any errors then you can move on.

Download and compile and install rtl_433

This is the software that listens and decodes M2M wireless messages in various protocols. It was originally designed around the vast number of devices that run on 433 Mhz, however you’re able to listen on any frequency and bandwidth that your receiver supports.

If you’re able to run rtl_433 -G without any errors, congratulations!

Next, if you’re not running the receiver on your HA box you’ll need to install mosquitto and its associated clients. HA already has an mqtt broker and can publish. This tutorial, however, is written with mosquitto in mind so I’m not sure how to use the built in broker that ships with HA. Be sure to start the mosquitto service with a command such as:

sudo systemctl start mosquitto

Or you’re going to have issues.

Finding your Sensors

Time to bust out notepad or grab a sheet of paper out of the printer (do people still own printers? What dismal devices) Time to find all your sensors and document their ID’s as you’ll need to reference them in your HA config later on.

Run: rtl_433 -f 344975000

rtl_433 should run and start idling listening for your sensors. Go crack open a door for about 5 seconds and then close it again. You should get some output such as this:

2017-06-01 16:41:37 : Honeywell Door/Window Sensor : 7726b : 8 : 80 : open : no

That doesn’t look inherently useful to Home Assistant and it doesn’t contain the device id we need. So let’s try a slightly different command to make rtl_433 spit out a json statement as opposed to it’s own internal preformatted data.

Run: rtl_433 -f 344975000 -F json

Now we’re cooking with dead dinosaur squeezins!

{"time" : "2017-06-01 16:44:31", "model" : "Honeywell Door/Window Sensor", "id" : 488043, "channel" : 8, "event" : 0, "state" : "closed", "heartbeat" : "no"}

Hopefully you know which door or window you just opened or closed and all you have to do is write down the "id" .

Do this for all of your applicable sensors until you have a nice list.

Getting the Data to Home Assistant

So in order to get the data to Home Assistant we’re going to use mqtt. But how do we get the output from rtl_433 to mosquitto? Pipe it! Here’s how:

rtl_433 -f 344975000 -F json -U | mosquitto_pub -t homeassistant/sensor/honeywell -l -V mqttv311

What does this command do? Well, let’s break it down. There’s a little bit to unpack about the why…

rtl_433 -f 344975000 -F json -U fires up rtl_433 at a center freq of 344.975Mhz with default 250Khz bandwidth. This means that the radio is tuned to 344.975Mhz but can see 125Khz in either direction. This is to account for the multiple channels that the Honeywell sensors use along that band. It also allows for some wiggle room with regards to an uncalibrated RTL-SDR dongle.

The -F json portion tells rtl_433 to format as a json statement.

And -U tells rtl_433 to format the timestamp as UTC making it a more applicable variable for HA or other applications.

Then there’s the pipe which basically connects the output of rtl_433 with the -m input of mosquitto.

mosquitto_pub the client program we’re using the publish the mqtt message;

-t homeassistant/sensor/honeywell is the mqtt topic we’re going to publish to. You can make it whatever string of text you’d like, but for simplicity of this tutorial, this is what we’re going to use.

l (lowercase L) tells mosquitto to interpret the message (stdin) as a single line at a time instead of a paragraph.

-V mqttv311 This is the forced mqtt protocol which is crucial crucial as the latest mosquitto will have issues talking to HA without it.

Once you get this running you can just let it chooch as you’re now done here. Onto Home Assistant configuration!!

Since you’re presumably following my steps and using a second linux box for your receiver and MQTT broker, please add the following to your configuration.yaml:

mqtt: broker: <broker ip address>

Then in your sensors section of your configuration.yaml you’re going to add a single sensor entity for each of the sensors you’re radio is listening for. But you’re going to need some conditional Jinga trickery in your value_templates in order to be able to split out and parse the various sources of JSON data because we’re going to have different device ID’s and their states all being piped to the same mqtt topic. Follow me little bird, I’ll feed ya:

sensor: - platform: mqtt state_topic: "homeassistant/sensor/honeywell" name: "Back Door" qos: 0 device_class: opening #On the next line you'll input the device ID you got for your sensors when you were wandering around your house like a crazy person opening and closing doors and windows. So I know here I need the ID for the Back Door sensor. value_template: '{% if value_json.id is equalto 488043 %} {{value_json.state}} {% else %} {{states.sensor.back_door.state}} {% endif %}' - platform: mqtt state_topic: "homeassistant/sensor/honeywell" name: "Front Door" qos: 0 device_class: opening value_template: '{% if value_json.id is equalto 477731 %} {{value_json.state}} {% else %} {{states.sensor.front_door.state}} {% endif %}' - platform: mqtt state_topic: "homeassistant/sensor/honeywell" name: "Garage Door" qos: 0 device_class: opening value_template: '{% if value_json.id is equalto 294890 %} {{value_json.state}} {% else %} {{states.sensor.garage_door.state}} {% endif %}'

Notice each sensor is listening on the same topic. But we only grab the state information for the sensor we’re looking for. The key to this is the Jinga conditional filter. We check the incoming JSON for a pre-specified device id.

Take special note of the {% else %} clause. Since all of the sensor entities are listening on that same mqtt topic, if you don’t have something else for it to do and the device ID coming in on the json value doesn’t match then it’ll set the sensor state to nothing. So we tell it then to reset it with the current state: {{states.sensor.back_door.state}} So while the state value does, in fact, get overwritten, it’s overwritten with its current, pre-existing state.

In Closing (see what I did there?)

There are so many people to thank for this coming to fruition. I have yet heard of anyone else successfully integrating these sensors with HA. I know there’s another piece of software alternative to rtl_433 that works on the Raspberry Pi but I haven’t played with it. Thus far I’ve had complete success and accuracy with this setup. Additionally, you can also grab heartbeat and battery low statuses from the sensors, setup automation for notification when a sensor battery is low or add the tamper sensor to HA automation as well.

Huge thanks to github user merbanan for rtl_433, Jon Lundy for the Jinga help, Dan Englender for helping us understand these sensors and their protocol.

Happy Integrating!!!

-Joe Hancuff