Home Assistant Legacy Z-Wave IntegrationIn 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.
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:
1
2
3
4
5
6
# Install Mosquitto
sudodnf install-y mosquitto
# Start it up
sudosystemctl start mosquitto
# Enable it
sudosystemctl enablemosquitto
To get this configured in Home Assistant, you just need to add the following line to your configuration.yaml file:
1
2
3
4
5
# 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:
01
02
03
04
05
06
07
08
09
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
# First you need snap installed
sudodnf install-y snapd
sudosystemctl 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:
sudosu-
# Install Snap
snap installozwdaemon
# 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
# 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 setozwdaemon 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 --enableozwdaemon.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:
1
2
3
4
# 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:
1
2
3
4
5
6
7
# 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.
If you have a dedicated server that you want to set up Home Assistant on and would like to run it natively (not in a container), then this is the tutorial for you. This tutorial focuses on using CentOS 8 because I am personally familiar with RedHat based products. But those who chose to use Ubuntu, Debian, Alpine, Arch, etc should be able to benefit from a good chunk of the information explained here too.
Minimum Requirements
While Home Assistant works awesome on a Raspberry Pi for simple things, it can start to get sluggish and feel under-powered over time as you get addicted like the rest of us and continue to add automations to it. It specifically takes a hard it once you start adding automations that involve video and get fancy with others.
Intel Nuc Kit nuc6i5syhThus, if you’re a hobbyist who plans on continuing to evolve your homes automation over time, a Raspberry Pi is not good enough. A small PC (and this tutorial of course ) is the best way to go.
>=100Mbit/s It’s strongly recommended that the server you choose to set up Home Assistant utilize a physical network cable and not WiFi.
Storage
>=32GB Storage is only really important if you plan on installing home surveillance (specifically video cameras). If you do, then target your storage to be at least 512GB or more instead. This will allow you to record with them and save the content locally (should you choose to do this).
Here is the breakdown of where the storage all goes (with respect to this tutorial):
Path
Size
Details
/etc/homeassistant/
1GB
Your configuration files are small (less then 256KB), however Home Assistant maintains what is called a Recorder which tracks itself in an SQLite database. This SQLite database tends to grow over time in size (which you can control). This is also the location of your homeassistant.log file which can also grow in size as well. By giving yourself (at least) 1GB here, you just provide enough room for future growth that will never interrupt your setup over time. More on the contents of this directory is discussed near the end of this blog.
/opt/homeassistant/
2GB
The entire installation of Home Assistant will sit here once you’ve completed this tutorial. The actual installation (with most bells and whistles) is just under 1GB. 2GB is just a suggested size because it will leave you with plenty of room for future growth.
/
6GB
Your root filesystem and all the core directories that go with it such as /boot, /tmp, /home, /usr, /var, … etc. 6GB is more than enough to host the Linux operating system and all of it’s needs while still leaving you ample space for growth.
/opt/homeassistant/video/
>128GB
I’m just throwing this in here… Those who don’t have video recording cameras at their home (inside and out) can ignore this. But consider at LEAST 32GB per camera depending on how much you want to record. You may also want to plan for an expansion down the road too; I said >=512GB earlier and I meant it. Storage is cheap these days, so plan properly at the start.
It is assumed at this point that you’ve set up your server or already had one running. Let’s set up a working environment that Home Assistant can work in. It’s important to have root or sudo privileges prior to running the commands below in each section.
General Server Preparation
The safest way to run Home Assistant is with it’s own dedicated user and permissions. The following will set up a working environment for us to build further onto:
01
02
03
04
05
06
07
08
09
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
# Again.. our basic layout will be:
# User: homeassistant
# HA Config: /etc/homeassistant
# HA Core: /opt/homeassistant
# Prepare our user:
sudouseradd-rmhomeassistant \
--home-dir/opt/homeassistant
# The dialout group allows us to access our external USB
# devices such as the Aeotec Z-Stick Series 5 (which is
# what I use). We want to add our user to this group:
sudousermod-aG dialout homeassistant
# Prepare our configuration directory
sudomkdir/etc/homeassistant
# Adjust our permissions
sudochown-R homeassistant:homeassistant \
/opt/homeassistant/etc/homeassistant
# Some of the packages later installed with pip3
# require that they are compiled in your environment
# (or it will not work) so the following is also
# required:
sudodnf install-y gccmakegcc-c++ systemd-devel \
unzip tar
Python 3.8 Setup
We need to setup Python 3.8 into our CentOS environment because it is the minimum requirement for Home Assistant to work. So basically we have 2 options here: Take the most stable version of v3.8, or take the one manged by CentOS which is sometimes outdated. Either way, I’ve explained both below:
Regardless of which route you chose to take, you can test the version out to see if you were successful:
1
2
# Test the version out:
python3.8 -V
Surveillance Video Camera Setup
Run the following commands if you have or plan on having surveillance cameras installed into your environment. Feel free to run this at a later time if you want. Basically you need a copy of ffmpeg available if you plan on accessing your camera stream in Home Assistant.
<description>Home Assistant Web Portal</description>
<port protocol="tcp"port="8123"/>
</service>
_EOF
EOF
# Reload our firewall so it can find our recently
# created configuration file (defined above)
sudofirewall-cmd --reload
# Now we'll add our new firewall service
sudofirewall-cmd --zone=public \
--add-service=home-assistant --permanent
# once again reload our firewall to open our newly
# declared port:
sudofirewall-cmd --reload
Finalizing Your Installation
You can now visit your new Home Assistant server at http://ip.to.your.server:8123 and start setting up your account for the first time.
When you first access the page you will be able to create the first system user (also the administrator account) that you can build automations with.
Home Assistant Upgrades
You’ll find that Home Assistant is rapidly expanding and always fixing issues and adding more cool features you can play with. Upgrading Home Assistant is as easy as this:
01
02
03
04
05
06
07
08
09
10
11
12
13
14
15
16
17
18
19
# Switch to our home assistant user:
sudo-u homeassistant -H -s
# Change to our home directory (if we're not there already)
cd/opt/homeassistant
# It's always VERY important you activate your
# environment before you start running pip3
# commands
. ./bin/activate
# Switch to our homeassistant user
pip3 install--upgrade homeassistant
# Return to our user with sudoer's permission
exit
# Restart Home Assistant
sudosystemctl restart home-assistant
A Quick Overview
At this point you should be all set up with a running copy of Home Assistant to play with. Here are some general files and directories that will begin appearing in your server’s filesystem in the /etc/homeassistant/ directory that you may want to know about:
homeassistant.log
All of the logs associated with Home Assistant will show up here. This is a fantastic location to begin your troubleshooting should you run into problems.
configuration.yaml
This is the core configuration that will drive your entire Home Assistant application from this point forward. Any changes to this file will require you to restart Home Assistant for the changes to take effect.
home-assistant_v2.db
This is the Home Assistant Recorder. From within your Home Assistant Dashboard, you can click on History button off of the dashboard to see the contents.
secrets.yaml
This is a simple file that allows you to map key/value pairs. The idea is to keep all of your passwords and/or tokens that you otherwise want to keep from prying eyes. This file should be given very strict permissions:
1
2
# protect this file if you intend to use it
chmod600 /etc/homeassistant/secrets.yaml
For example, you might use Apprise to send you an email notification. In order to send an email Apprise needs your personal email information. As an example, in your configuration.yaml file you might do this:
1
2
3
4
5
6
# /etc/homeassistant/configuration.yaml
# ...
notify:
name:apprise
platform:apprise
url:!secret apprise_url
Then in your secrets.yaml file you now need an entry for a new keyword you created called apprise_url. Your entry in the secrets.yaml file might look like this:
1
2
3
# /etc/homeassistant/secrets.yaml
# Define your Apprise details in a secure location:
apprise_url:mailto://myuser:mypassword@gmail.com
More details on how secrets work can be found here in the Home Assistant documentation. Also, check out the Apprise wiki to see all of the different services you can notify with it.
automations.yaml
This is where you can begin constructing your own Home Assistant automations once you’ve added a few integrations into Home Assistant.
An example of an automation you might have set up could send us an email using Apprise at sunset:
01
02
03
04
05
06
07
08
09
10
11
12
13
14
# /etc/homeassistant/automations.yaml
#
# Utilize Apprise to send a notification
#
alias:"[Interactive] - Sunset Apprise Notice"
trigger:
platform:sun
event:sunset
action:
service:notify.apprise
data:
title:"Good evening"
message:"This sun is setting."
Configuration Backup
No setup is complete without regular backups taking place. The following is just a basic configuration backup setup you can use to get you started:
01
02
03
04
05
06
07
08
09
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
# For Backups (run these commands as the homeassistant user):
This blog took me a very (,very) long time to put together and test! 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!
The Home Assistant Official Community Forum: this is probably the best place to get an answer to any question you have about your setup and/or things you can do (including how to do it).
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.
) is the best way to go.
You can now visit your new Home Assistant server at http://ip.to.your.server:8123 and start setting up your account for the first time.