I've been a long time fan of Home Automation, and have used several iterations of different protocols and tools over the years. However I've never been quite happy of the state of things, until recently. Insert, Home Assistant.
Home Assistant is an open-source home automation platform based on Python 3. It interfaces with many different types of home automation modules and products, and is a comparable product to OpenHAB (for those that are familiar). It's a vendor-agnostic, self-hosted, DIY alternative to systems such as Vera, SmartThings, or Iris.
Specifically, this guide is for install Home Assistant to use with Z-Wave bindings, utilizing an Aeon Labs Z-Stick, Gen5 as my Z-Wave controller. Furthermore, and unlike most of my posts based on CentOS 7, I will be installing on my oDroid XU4 running DietPi. DietPi is a lightweight Debian-based operating system designed for single-board computers (such as Raspberry Pi, oDroid XU3/4, Pine A64, Banana Pi, OrangePi, and others). So even though I am doing my install on an oDroid XU4, this guide should also work fine on any system running DietPi.
To start things off, you will need a SBC (Single-Board Computer) running DietPi. Hop over to the Download section to download DietPi, and then check this Getting Started post if you need help getting going. Once you have DietPi installed, booted, and are at a SSH session, come back here.
Install will be completed as the root user.
Let's Get Started!
1.) updates and pre-requisites:
apt-get update && apt-get -y upgrade # Make sure we're fully upgraded
apt-get -y install build-essential checkinstall cython3 git htop libgcrypt11-dev libgnutls28-dev libudev-dev libyaml-dev python3-dev python3-pip python3-setuptools python3-sphinx vim # Pre-requisites
2.) install home assistant:
pip3 install astral netdisco==0.7.1 pyyaml xmltodict # Install HASS prereqs (for additional functionality)
pip3 install homeassistant # Install latest Home Assistant release
mkdir /opt/homeassistant # Create Home Assistant directory
vim /etc/systemd/system/hass.service # Create hass (Home Assistant) systemd file
---
[Unit]
Description=Home Assistant (hass) Daemon
After=syslog.target network.target
[Service]
Type=forking
ExecStart=/usr/local/bin/hass -v --config /opt/homeassistant --pid-file /var/run/hass.pid --daemon
PIDFile=/var/run/hass.pid
[Install]
WantedBy=multi-user.target
---
chmod +x /etc/systemd/system/hass.service && systemctl daemon-reload # Reload systemd files
systemctl start hass.service && sleep 5 && systemctl stop hass.service # Generate configration files
3.) install python-openzwave:
cd /opt && git clone https://github.com/OpenZWave/python-openzwave.git # Grab python-openzwave
cd /opt/python-openzwave && git checkout python3 # Checkout python3 branch
PYTHON_EXEC=$(which python3) make build # Compile python-openzwave
PYTHON_EXEC=$(which python3) make install # Install python-openzwave
4.) install openzwave control panel:
cd /opt && wget ftp://ftp.gnu.org/gnu/libmicrohttpd/libmicrohttpd-0.9.19.tar.gz # Grab libmicrohttpd (dependency for OZWCP)
tar xf libmicrohttpd-0.9.19.tar.gz # Extract libmicrohttpd
mv libmicrohttpd-0.9.19 libmicrohttpd && cd libmicrohttpd # Rename package
wget -O config.sub 'http://git.savannah.gnu.org/gitweb/?p=config.git;a=blob_plain;f=config.sub;hb=HEAD' # Grab updated config.sub file
wget -O config.guess 'http://git.savannah.gnu.org/gitweb/?p=config.git;a=blob_plain;f=config.guess;hb=HEAD' # Grab updated config.guess file
./configure && make # Complie libmicrohttpd
make install # Install libmicrohttpd
cd /opt && git clone https://github.com/OpenZWave/open-zwave-control-panel.git # Grab open zwave control panel (OZWCP)
cd /opt/open-zwave-control-panel && vim Makefile # Edit Makefile
# Edit lines 24-25 to be
---
OPENZWAVE := ../python-openzwave/openzwave
LIBMICROHTTPD := /usr/local/lib/libmicrohttpd.a
---
# Uncomment line 33, and edit to be
---
GNUTLS := -lgnutls -lgcrypt
---
# Uncomment lines 37-38, and Comment out lines 44-45
make # Compile OZWCP
ln -s /opt/python-openzwave/openzwave/config # Create symlink for openzwave configs
./ozwcp -p 8888 # Start ozwcp as a test (note, OZWCP and HASS should never both be running at the same time -- stop HASS before starting OZWCP, and kill OZWCP before starting HASS)
5.) configure home assistant:
Now you will need to create a symlink for the Zwave device/module you are using, so Home Assistant is more easily configurable. If you are using an Aeon Lab Z-Stick Gen5 like I am, you can run this one command:
echo 'SUBSYSTEM=="tty", ATTRS{idVendor}=="0658", ATTRS{idProduct}=="0200", SYMLINK+="zwave"' > /etc/udev/rules.d/99-usb-serial.rules
Which will create a symlink from /dev/ttyACM0 to /dev/zwave, so you don't have to worry about the device name changing (aka, persistant device). If you are using a Zwave device other than the Z-Stick Gen5, you will need to find the idVendor and idProduct of your device. Fortunately, ou should be able to find these attributes using dmesg after plugging the device in. Otherwise, I would recommend searching around Google.
Now that the device name has been statically set (well, once we reboot), let's configure HASS to be able to speak with the Zwave device.
HASS uses a configuration.yaml file for much of it's user-configurable settings. For our install, this file exists at /opt/homeassistant/configuration.yaml. This file requires restarting the HASS service to reload any changes.
vim /opt/homeassistant/configuration.yaml # Open the file for editing
# Add this to the bottom of the file:
---
zwave:
usb_path: /dev/zwave
config_path: /usr/local/lib/python3.4/dist-packages/libopenzwave-0.3.1-py3.4-linux-aarch64.egg/config
---
This will tell HASS that the usb_path of our Zwave device, is our symlinked name of /dev/zwave. The config_path key points to the path containing several Zwave device configs, so HASS knows how it can interact with the device.
systemctl enable hass.service # Enable HASS to run at system start
rm -rf /opt/libmicrohttpd* # Cleanup unnecessary libmicrohttpd files
systemctl reboot # Reboot server
Once system is back up, HASS should be running on port 8123. Visit http://IP:8123 to access web UI. Home Assistant is now installed and configured to work with your Zwave device, although no Zwave devices/modules have been added yet. To add a device, we will use the Open Zwave Control Panel (OZWCP) that we previously installed. To do this, first stop Home Assistant:
systemctl stop hass.service # Stop the HASS service
cd /opt/open-zwave-control-panel && ./ozwcp -p 8888 # Start OZWCP
Browse to http://IP:8888 and you should now see the Open Zwave Control Panel.
Under Device name, input /dev/zwave and click Initialize.
OZWCP should now be connected to your Zwave controller (i.e., Aeon Labs Z-Stick Gen5). You should see it listed under the Devices list below. To put the controller into inclusion mode (this is how you add devices), select Add Device from the drop-down menu in the Controller section, and click Go. You are now ready to add Zwave devices/modules, by performing whatever action is needed to include the device/module (i.e., press a button, power on the device, etc -- This will vary for each different Zwave module).
Once included, you should see your new device/module listed in the Devices section. Once you've added all your devices/modules, click the Save... button in the top right, under the Backup Controller setting. This will tell OZWCP to write the Zwave config to a file, which isn't always neccessary when adding devices, but it is neccessary when doing other tasks, so get in the habit of doing this every time you finish up in OZWCP.
Click Close under the Controller section, and go back to your SSH session. Kill OZWCP (usually by hitting CTRL-X), and OZWCP is no longer running.
Inside /opt/open-zwave-control-panel you should see a new file, with a randomly generated name. Something like zwcfg_0xdaa2b3d3.xml. This is the file that was generated when you clicked Save... from OZWCP. One of the biggest reasons I personally care about this file is because I like to rename my Zwave devices to something more meaningful. I'm referring to the Entity ID within HASS, which can't be change within HASS. You can still assign a friendly_name in the configuration.yaml, but that only affects the frontend view.
The easiest way for HASS to know about this zwcfg_0xdaa2b3de.xml file is to create a symlink. You should be able to do this by running:
ln -s /opt/open-zwave-control-panel/zwcfg_*.xml /opt/homeassistant/.
Which will create the symlink regardless of what random values are in the name (zwcfg_ is also the start of the file, the bit after is a HEX code which I'm guessing is specific to each different Zwave controller module).
Lastly, let's startup HASS and we should see our Zwave device(s)!
systemctl start hass.service # Start HASS service
That's a wrap for this guide. There was a lot more reading in this one than usual, but Home Assistant has a lot of little things to know, so I hope this has been helpful! Keep an eye on my blog as I'm planning to start writing up some posts/reviews of specific Zwave devices/modules that I have and plan to get, as well as sharing cool things from my configuration.yaml and automation rules.
For those curious, here is where my HASS install currently is:
I currently only have my Z-Wave controller connected to HASS, with only 3 Z-Wave sensors (2GIG CT100 Thermostat, Yale Real Living Deadbolt, Everspring Door Sensor). It's a beautiful start, and I have lots planned for the future! my goal is to create monthly update posts for my HASS install and share my configuration.yaml, as well as my automation stuff. So check back!
Hope you enjoy, and let me know if you have any questions or problems!