Setup OpenZWave on Home Assistant under CentOS 8

Introduction

Home Assistant Legacy Z-Wave Integration

In an earlier blog I created on how to set up Home Assistant natively using CentOS 8. I explained how you can set Z-Wave using a platform that the Home Assistant team plan on eventually retiring. They’re making room for a new and improved way of doing things; that’s what this blog focuses on.

The new method of setting up Z-Wave with Home Assistant is still in Beta (at the time of writing this blog) and is called OpenZWave. It is more than stable enough to add to your environment if you want to try it out.

While OpenZWave’s integration into Home Assistant is a little more complicated to set up (more moving parts too), it is a completely separately maintained component; this is a good thing! Z-Wave integration becomes much easier to maintain as a separate system (with separate release schedules).

The New OpenZWave Home Assistant Integration

Requirements

It is presumed that you have a Z-Wave Hub that is plugged into the same server hosting Home Assistant.If everything is working as expected, you should see a device (visible as /dev/ttyXXXN) that you can interact with.

I personally own a Gen5 Aeon Labs Aeotec Z-Wave Z-Stick which shows up as /dev/ttyACM0 on my system.

The other requirements (which are explained further in the next sections):

A MQTT Server (Mosquitto)
The OpenZWave Daemon

The Setup

MQTT Server

A MQTT is lightweight messaging protocol for small sensors and mobile devices, optimized for high-latency or unreliable networks. This becomes the channel to which OpenZWave can report all of your devices back to Home Assistant with. You also use this medium to trigger, and update your devices as well. Home Assistant recommends we use Mosquitto which is a light weight free tool that works great. It’s installation and setup is as easy as:

# Install Mosquitto
sudo dnf install -y mosquitto
# Start it up
sudo systemctl start mosquitto
# Enable it
sudo systemctl enable mosquitto

To get this configured in Home Assistant, you just need to add the following line to your configuration.yaml file:

# Example configuration.yaml entry
# If you followed my earlier blog, this just has to go anywhere in
# /etc/homeassistant/configuration.yaml
mqtt:
  broker: localhost

The OpenZWave Daemon

The OpenZWave Daemon is the key component that communicates to and from all of your Z-Wave devices and relays their status through the MQTT server (for Home Assistant to interpret). We can install this easily through Snapcraft:

# First you need snap installed
sudo dnf install -y snapd
sudo systemctl enable --now snapd.socket
 
# You just need  log out and back in again
# to run the next few commands (because of new environment variables
# put in place)... but this is easier; log in a root with a fresh
# environment set up:
sudo su -
 
# Install Snap
snap install ozwdaemon
 
# Get our configuration
snap get ozwdaemon -d
 
# I had to set a few things myself.  This is not really my network key
# but it's what you may need to do if you're coming from the old z-wave
# configuration; you'll want to re-import your secure key so you can still
# talk to your secure devices:
snap set ozwdaemon ozw.network-key=0x01,0x01,0x01,0x01,0x01,0x01,0x01,0x01,0x01,0x01,0x01,0x01,0x01,0x01,0x01,0x01

# By default it is already set up to use an mqtt server installed on
# localhost.  So no changes are needed here.

# It is also by default looking for your Z-Wave Hub at /dev/ttyACM0
# While this works great for me (requiring no change at all), you can
# set yours to whatever path you need like so:
snap set ozwdaemon usb-path=/dev/ttyACM0

# Connect our device to our Z-Wave USB device we configured
snap connect ozwdaemon:raw-usb

# Set up our dameon to start and restart if we ever restart our pc
snap start --enable ozwdaemon.ozwdaemon

At this point you can add the OpenZWave Integration inside Home Assistant. It should detect everything if all of the instructions went well above. This is done by:

Click on Configuration which is on the left hand side when logged into Home Assistant using an Administrator account
Click on Add Integration
Search for OpenZWave
Choose to Add this Integration

Troubleshooting

You can follow the OpenZWave logs as follows if you run into any issues:

# Follow our logs:
snap logs ozwdaemon -f
# or snapd:
journalctl -u snapd -f

You can also increase the logs provided by Home Assistant for the 2 things in question to help isolate any issues; simply add the following to your Home Assistant’s configuration.yaml file:

# Extra Z-Wave/MQTT Logging configuration.yaml entry
# If you followed my earlier blog, this just has to go anywhere in
# /etc/homeassistant/configuration.yaml
logger:
  logs:
    homeassistant.components.ozw: debug
    homeassistant.components.mqtt: debug

Older versions of the Home Assistant OpenZWave front end do not handle secure nodes properly which was identified here.

Credit

If you like what you see and wish to copy and paste this HOWTO, please reference back to this blog post at the very least. It’s really all I ask. Alternatively, I certainly won’t turn down a coffee if you wish to buy me one! 🙂

nuxref