Z-Wave is an interesting wireless mesh protocol for home automation devices such as various sensors and switches. With Zwave2Mqtt and a Z-Wave transceiver, you can turn a Raspberry Pi into a Z-Wave gateway, including a dashboard for managing all your devices. Moreover, by using mqtt you can easily integrate your Z-Wave devices with all kinds of home automation systems, including Home Assistant.
In this article, we are going to integrate Z-Wave devices with your home automation system via mqtt (Message Queuing Telemetry Transport). Most open source home automation controllers support this protocol, which serves to exchange messages. Home Assistant, Domoticz and openHAB are some examples. In this course we assume that you already have such a system running. At the end of this course we will show you the integration of Zwave2Mqtt with Home Assistant; integration is comparable with other home automation systems.
01 Supplies
Of course you need Z-Wave devices that you want to integrate into your home automation system. This can be sensors, switches and lamps. There are countless devices on the market. Z-Wave is a wireless mesh protocol operating in Europe at a frequency of 868.42 MHz.
So you also need a transceiver to communicate with the devices. In this article we will connect that transceiver to a Raspberry Pi (no matter which model), which then works as a Z-Wave gateway. An example of a transceivers is the RaZberry which you install on the gpio header of the Pi. An alternative is a USB transceiver that you plug into a USB port on your Pi. You connect the Raspberry Pi to your home network via an Ethernet cable or WiFi connection, after which it is connected via the software Zwave2Mqtt Z-Wave messages translate to mqtt messages on your network and vice versa.
02 Prepare Raspberry Pi and Windows
We assume you Raspbian Buster Lite installed on your Raspberry Pi. You do that by the image with balenaEtcher write on a micro SD card. Then you save an empty file called boot file in the boot partition ssh on and possibly (if you use wifi instead of ethernet) a file with the name wpa_supplicant.conf with the wifi configuration. Then insert the micro-SD card into your Pi, connect the Z-Wave transceiver to the gpio header or a USB port, connect the Ethernet cable if necessary and finally plug the power adapter into your Pi to boot .
Then you log in to your Pi via the network via OpenSSH. If you are running a Windows 10 version from April 2018 or later, you can use the ssh client built into Windows. First go to Settings / Apps / Optional items and click Add an item. Choose OpenSSH client and restart your computer. If your Windows version is older than April 2018, follow the instructions from Microsoft’s project Win32-OpenSSH or download the program PuTTY.
03 Update Raspberry Pi
Once you’ve installed the OpenSSH client, open a command prompt and login to your Pi with the following command:
ssh pi @ IP
Replace the designation IP by the IP address of your Pi, which you can find in the web interface of your router at the dhcp leases. Confirm that you trust the displayed fingerprint and enter as password raspberry in.
Once logged in, immediately change the default password with the following command:
passwd
Then update the package list and upgrade all packages to the latest version with the commands:
sudo apt update
sudo apt upgrade
04 Install the docker
Installing Zwave2Mqtt is easiest in the form of a Docker container. So install Docker first. Unfortunately, the version of Docker in Raspbian Buster contained an error at the time of writing, preventing you from installing Docker with this simple command:
sudo apt install docker.io
Therefore, download the installation script from Docker’s website and run it with this command:
curl -sSL https://get.docker.com | sh
If you get an error at the end, it is possible that the Docker service just started too soon. You can ignore that. Then give your user account permission to use Docker with:
sudo usermod pi -aG docker
If you didn’t see an error message at the end of the Docker installation, log out with exit; did you see an error message, restart your Pi with reboot. Then log in again via ssh. In the output of the command below should now active (running) should stand:
systemctl status docker
Direct Z-Wave support in Home Assistant
Home automation controllers such as Home Assistant, Domoticz and openHAB also directly support Z-Wave devices, standard or via an add-on. Why would you take the detour via Zwave2Mqtt? There are several reasons for this. Maybe you still experiment regularly with your home automation controller and you often restart it, or it sometimes lies flat due to your experiments, while you want your Z-Wave devices to be continuously usable. Or maybe you have few Z-Wave devices near your home automation controller, causing the mesh network to have poor coverage. Then place a Raspberry Pi with Zwave2Mqtt near your Z-Wave devices for more reliable operation.
05 Install Zwave2Mqtt
Then we are now ready to install Zwave2Mqtt. First create a directory where the program can store its data:
sudo mkdir / var / lib / zwave2mqtt
Then download and launch the Zwave2Mqtt Docker container as follows:
docker run -d –restart always -p 8091: 8091 –device = / dev / ttyUSB0 -e TZ = Europe / Amsterdam -v / var / lib / zwave2mqtt: / usr / src / app / store robertslando / zwave2mqtt: latest
If you get an error about the file / dev / ttyUSB0, then either your Z-Wave transceiver is not connected or it has been assigned another device file, probably / dev / ttyACM0 or / dev / ttyAMA0.
06 Installing Mosquitto
If you already have a mqtt broker running, feel free to use it for our application. For example, if you installed Home Assistant via Hass.io, you can easily install Mosquitto via the add-on Mosquitto MQTT broker. If you don’t have an mqtt broker yet, install it in a Docker container on your Raspberry Pi.
First create the directories in which the program can store its data:
sudo mkdir -p / var / lib / mosquitto / {config, data, log}
Create a configuration file for Mosquitto:
sudo nano /var/lib/mosquitto/config/mosquitto.conf
And put the following lines in it:
persistence true
persistence_location / mosquitto / data /
log_dest file /mosquitto/log/mosquitto.log
Save your changes with Ctrl + O and close nano with Ctrl + X. And then download and launch Mosquitto’s Docker container:
docker run -d –restart always -p 1883: 1883 -p 9001: 9001 -v / var / lib / mosquitto: / mosquitto eclipse-mosquitto
If you do the assignment afterwards docker ps you will see our two Docker containers running, even after a restart of your Raspberry Pi.
07 Configure Z-Wave
If all goes well, the web interface of Zwave2Mqtt now runs on port 8091 of your Raspberry Pi. Therefore, visit the web page in a browser on your PC http: // IPVANJEPI: 8091. You will now see the control panel, but first you have to adjust some settings: click on the left icon of the gear. There you will see three parts of the settings: Zwave, Mqtt and Gateway.
We go to the part first Zwave. The main institution is Serial Port: there you choose the port to which your Z-Wave transceiver is connected, the same as you specified when creating the Docker container (in our example / dev / ttyUSB0). Switch Logging, Save configuration and Assume awake and fill in Poll interval the value 60000 in (is 60 seconds). The other values ​​in this section can be left blank. If you use Z-Wave Secure devices, such as door locks, you still have to enter the Network Key. If you already have a working Z-Wave network, copy that key from your current home automation system and paste it here. The key looks something like this: 0xE5,0xB4,0xFF, 0xC3,0x67,0xE9,0x02,0xB1,0x29,0xD5,0x6A, 0x40,0x82,0xD9,0x3A, 0x34. If you are setting up this Z-Wave network for the first time, generate a key on your Pi (and paste it into the interface):
cat / dev / urandom | tr -dc ‘0-9A-F’ | fold -w 32 | head -n 1 | sed -e ‘s /(..)/ 0x 1, / g’ -e ‘s /, $ //’
Back up the key because if you ever lose it, you will no longer be able to connect to those Z-Wave Secure devices and will have to restore them to factory settings.
08 Configure mqtt and gateway
Then open the part Mqtt. Give the mqtt broker you are connecting to a name (without spaces), fill Host URL the IP address of your Pi in and as a port 1883. Bee Reconnect period (ms) you choose, for example 5000 for 5 seconds, at Prefix fill you sulfur in and with QoS you choose 2. Toggle the options Retain and Store in. The option Auth we do not enable because we use Mosquitto without authentication. As an exercise, we leave the way to limit access to the reader.
Finally, open the part Gateway. Here is the option Type most important choice you have to make. If you ValueID topics as value, Zwave2Mqtt automatically chooses mqtt topics based on the properties of your Z-Wave devices. The advantage is that you don’t have to configure each device individually to have a working installation. Only the topics are not so readable for people, so it is best to switch the option Use nodes name instead of numeric nodeIDs in.
Bee Payload type imagine what data will be in mqtt messages. If you want as much information as possible, choose Entire Z-Wave value Object. If you want to take advantage of the integration with Home Assistant, switch as well Hass Discovery in. You can adjust the other options later if you find you need them. Finally, click at the bottom Save to save all this.
09 Control panel
Click left on the icon with the four squares in front of the control panel. If all goes well and you had previously paired Z-Wave devices with your controller, you will now see (some of) your Z-Wave devices in your house, probably mainly the ones that are connected to the mains and your controller itself.
Adding a Z-Wave device (a “node”) continues in the dropdown menu at Actions at the top Add Node (inclusion) and then click the right arrow. Most Z-Wave devices require you to press a button or, for example, press a button three times in quick succession to add them to the network. See how to do this in the manual for your device. When the device is added correctly, the status of the controller changes from left to Completed. It may take a while for the device to appear in the list.
10 Manage devices
If you now click on a device, you will see in the tab below Node information about the device. Blow User off to view the values ​​of a sensor or adjust the value of a switch. below Configuration you can set parameters of the device, such as the sensitivity of a sensor. Consult the manual of the device. And below System you will find system information such as the Z-Wave version that the device supports.
If you Hass Discovery enabled in the gateway configuration, you will also see at the bottom the devices that Zwave2Mqtt automatically creates for this device for Home Assistant. Devices plural, because one Z-Wave device such as a multisensor can behave as multiple devices at the same time: temperature sensor, motion sensor, light sensor and so on.
You can also give your device a name and location. Fill it in and click on the arrow next to it. If you are in the gateway configuration Use nodes name instead of numeric nodeIDs enabled, this human-readable name is used to identify the device in the mqtt messages and in the control panel. Finally, you can also perform actions on a device. Select the desired action for this Node actions and click on the arrow next to it.
11 Integration with Home Assistant
We assume that you already have Home Assistant running. Open the file configuration.yaml of your Home Assistant installation and add the following lines:
mqtt:
discovery: true
discovery_prefix: PREFIX
broker: BROKER
birth_message:
topic: ‘hass / status’
payload: ‘online’
will_message:
topic: ‘hass / status’
payload: ‘offline’
Instead of PREFIX use the prefix you set in the mqtt configuration of Zwave2Mqtt, in our example sulfur. And instead of BROKER enter the IP address of your mqtt broker, for example that of your Pi if you have Mosquitto installed on your Pi.
Save the file and then restart Home Assistant (in the menu Settings / Server Management / Restart from the Home Assistant web interface). Wait a while for Home Assistant to restart. After that all your Z-Wave devices for Home Assistant should become visible.
Click on the three dots in the top right corner of Home Assistant and then on Unused entities. You will then see all your Z-Wave devices, and even several per Z-Wave device when it comes to complex devices with multiple sensors. Click on a device and then the gear icon to give the device a clearer name and then add the device in the Lovelace interface of Home Assistant in the desired panel.
You have now set up a flexible Z-Wave network. You can run your Z-Wave controller, mqtt broker and Home Assistant all three on the same Raspberry Pi, or each of these components on a separate Raspberry Pi or even another computer such as a nas or home server. The configuration remains the same, except for the IP addresses.
Resolving problems
If something doesn’t go as expected, don’t panic. If the problem is when running one of the Docker containers, view with the command docker ps the IDs of your containers and then ask with docker logs ID the logs of the container with the given id. You can stop the container with docker stop ID and remove the container with docker rm ID. This is useful, for example, if you have passed the wrong serial device to the Zwave2Mqtt container.
Then simply recreate the container, this time with the correct device. If you run into problems adding Z-Wave devices, open the tab Debug in the Zwave2Mqtt control panel and click Start to get debug messages. These are the same messages as the logs of the Docker container of Zwave2Mqtt. And finally something goes wrong with the mqtt communication, using an mqtt client like MQTT Explorer to see which mqtt messages Zwave2Mqtt sends out.
