The Best Way to Use Z-Wave with Home Assistant

Updated on 15th Sep 2020 14:05 in Home Assistant, Tutorial

Z-Wave is really cool, it has so many great features that can provide both ease of use for regular users and advanced features for use by power users. How can you get the power of Z-Wave into a DIY platform like Home Assistant or OpenHAB? Sometimes, you also want to have a different device act as the network than the one that's running your smart home software. 

Disclaimer: This post contains affiliate links. As an Amazon Associate, I earn from qualifying purchases. 

How to connect Z-Wave devices with Home Assistant or other DIY Platform?

Z-Wave is its own unique protocol and as such software like HASS need a way to communicate wirelessly with networked devices. For most regular use cases, there are products know as "Z-Wave Sticks" which can plug into a USB port like any other wireless dongle and offer connectivity to the host computer. In essence, the computer becomes the hub in this configuration.

Other than the sticks, there also exists a product known as the RaZberry, which is a GPIO hat for the Raspberry Pi that also provides network connectivity but without using a USB port. In some cases, the RaZberry can be found on sale for less than the regular sticks making for an attractive option. Personally, I use the RaZberry as it was at least 20$ cheaper than the other comparable sticks I could find.

All of these options are actually quite similar though, they all have an antenna inside that connects with a control board which implements the Z-Wave protocol. They then act as a bridge between the wireless network and the computer they are connected to, allowing the use of a regular serial port (such as USB) to send commands over the Z-Wave net. The device will also notify the computer anytime an event occurs that it should know about, such as the manual operation of a light switch.

Picking a Z-Wave stick

There are different kinds of sticks available, most of them being Z-Wave Plus these days. The other type you might find are just called "Z-Wave", and that's the old standard before Z-Wave Plus really existed. Since most of the device that can be bought will be Plus it is a good idea to get a stick that supports this as otherwise, you might not be able to use those devices with your smart home.

One crucial element to pay attention to is the frequency of the stick. Different regions use different frequencies, and buying a stick that uses the wrong frequency could mean that none of the devices you buy will work! It's especially important to pay attention to this when purchasing online as devices can ship in from anywhere with little regulation. If you are buying a stick online, ensure to buy the right one for your region.

How will the software understand the stick?

While this depends a lot on the software being used, there is usually a plugin available that will interface with the stick over a serial link, allowing the computer to send commands to Z-Wave nodes. Home Assistant offers a native integration for this purpose, and since it is part of the core, there is no additional software to install! Just add the required "zwave:" line to your configuration and get going!

The only downside with this approach is that the stick needs to be accessible directly by the software, meaning that whichever computer will host the device must also be the one running the plugin. This might not seem like an issue, but in some setups, the system running the software might be relatively far away from the Z-Wave network, meaning a poor connection. 

It's worth noting that not all Z-Wave devices will be supported by these plugins, although most common devices will be supported out of the box. One of the strengths of using Z-Wave is that the protocol treats nodes as being in different categories that each have sets of capabilities. This means that even if the plugin doesn't understand how to speak to the specific brand of switch you might own, it can use the generic commands to control it without ever knowing the specifics about it.

What if the computer that runs the software won't be the one with the stick?

At first, this seems like a bit of a problem. Every plugin I could find required the stick or GPIO hat to be plugged directly into the computer it was running on. In my specific case, I wanted to run Home Assistant in a virtual machine, but the stick I have is the RaZberry which obviously only works on a Raspberry Pi.

Another case where this problem could appear is if all the server type of tech is located in the basement of your home, which is a typical setup. In this situation, it can be difficult for the signal to pass through the basement and all the way to the other devices. Some smart homes may only make use of Z-Wave on the top floor as an example. If the system running HASS is not located upstairs, the signal would have to travel all the way upstairs!

There must be a better way to have the antenna closer without moving the entire computer, and lucky for us, there is! The software is called Zwave2Mqtt, and it allows a computer with a connected stick to make its capabilities available to other devices via MQTT. If you want to know more about MQTT, be sure to check out this article about converting a cloud locked Meross device into an offline device completely DIY.

MQTT is really great because it allows clients, such as a light bulb or in this case a network bridge, to make various "topics" available that can be used by other clients to command and fetch information from that particular node. It is usually run over the network, which means it is super easy to place a remote device in a more optimal location while still having the smart home software running wherever is best.

Personally, I use Zwave2Mqtt on a Raspberry Pi with the RaZberry hat on to connect to all of my Z-Wave devices while making them available over a TCP (usually used for internet, WiFi, etc..) connection using MQTT. This means that I can have my Pi running upstairs where there are more devices while having the HASS instance run on a much more powerful server all the way in the basement.

How to setup Zwave2Mqtt

There are many, many use cases, and we can't possibly cover them all in this article. We will, however, go over some of the most useful options involving a Raspberry Pi. Since I don't run HASS on a Pi anymore, I have an extra Pi sitting around collecting dust. The old setup I used was reliant on the RaZberry to give my system Z-Wave connectivity. Still, beyond the simple location issue, the RaZberry is only designed to run on a Raspberry Pi.

Zwave2Mqtt is perfect for this as the Pi can become a system dedicated solely to controlling the Z-Wave network based on inputs coming from MQTT while also sending any network events (such as someone manually operating the lights) down towards anyone who's listening to that MQTT topic.

Docker

This is by far the easiest way to install Zwave2Mqtt. Simply SSH into your pi, install docker using the following commands (if docker is not already installed):

curl -sSL https://get.docker.com | sh
sudo usermod -aG docker pi

This will install docker and add the pi user to the docker group, which is required to run any of the docker commands. Once that's done, it's a matter of running the docker command to download the container and spin it up:

docker run --rm -it -p 8091:8091 --device=/dev/ttyACM0 --mount source=zwave2mqtt,target=/usr/src/app/store robertslando/zwave2mqtt:latest

Ensure to replace "/dev/ttyACM0" with the correct value for your device. You can view all of the available devices by issuing:

ls /dev/tty*

Mine was /dev/ttyAMA0, but yours may be different. There's more information about the docker install on the official Github page, but really these commands should be all you need to get going! The container may take quite a while to spin up and get going properly, but once it's running you can point your browser to http://<IP_ADDRESS>:8091 to view the setup page.

The other way

If docker doesn't run well on your device (it barely ran on mine), you might want to install it natively. This, however, can prove to be quite an immense pain. The software its self is actually relatively easy to run, it uses NPM and in most cases can be installed via a few lines (as we will see later). The problem is that the software that this excellent program relies on, called OpenZwave, will likely need to be compiled for the Pi before it will work.

Unless the OpenZwave website has a prebuilt binary for your architecture (at the time of writing, there is not), you will have to build the source code before you can use it. This will not be very fun - in fact, the Github page refers to this as "Hercules' path of blight", so you can understand that this won't be trivial.

The steps are as follow:

Download the 1.6 version of OpenZwave (only one supported by Zwave2Mqtt right now) wget http://old.openzwave.com/downloads/openzwave-1.6.1240.tar.gz

Untar tar zxvf openzwave-*.gz

Build the program - on a Pi this can take a very, very long time cd openzwave-* && make && sudo make install

Setup the library paths for the OS export LD_LIBRARY_PATH=/usr/local/lib
sudo sed -i '$a LD_LIBRARY_PATH=/usr/local/lib' /etc/environment
sudo ldconfig

And finally, check if it works by issuing the following command. MinOZW

If all goes well, we will now have some output after running that last command. If there are any error messages, I recommend going back over and checking each step. Now we can install Zwave2Mqtt! This one should be easy!

cd ~
mkdir Zwave2Mqtt
cd Zwave2Mqtt
curl -s https://api.github.com/repos/OpenZWave/Zwave2Mqtt/releases/latest \ | grep "browser_download_url.*zip" \ | cut -d : -f 2,3 \ | tr -d \" \ | wget -i -
unzip zwave2mqtt-v*.zip
./zwave2mqtt

After running these commands, the program should be running and be available over at http://<IP_ADDRESS>:8091.

Setting up Zwave2Mqtt

Once you have everything installed, you can head over to the web interface that was previously linked. This interface allows all of the required settings to be easily tweaked for anything to work. There are a lot of settings, if you want details for any of them, you should take a look at the project's official Github. Most of them are pretty self-explanatory, but one that's worth mentioning is that if your MQTT server is using SSL, you must specify mqtts:// as the URL prefix for the SSL options to appear in the UI.

Don't have an MQTT server setup? Check out my Meross Offline guide to learn how to set up a server precisely like I did. Remember that if you use this method, you must upload the certificate and key along with checking the "Allow self-signed certs". 

Summary

Overall, there are a lot of ways to use Z-Wave without a normal off the shelf hub. Zwave2Mqtt offers a really great way to deal with the situation where the stick can not be plugged into the computer running Home Assistant or other smart home software. Do you use Zwave2Mqtt? What's your use case? Leave a comment below!