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
