Home Automation Guide: Home Assistant, Siri, Alexa, Z-Wave, and iCloud

I dove head-first into home automation in December of 2016 after discovering Home Assistant, an open-source home automation platform running on Python 3. It’s a lot of fun to set up, but it can be challenging for newcomers. Therefore, I’ve put together this start-to-finish walkthrough for the hardware and software setup process. I’ve also got some tips for in-wall switch installation, since I put in about 40 of the darned things. But keep in mind that I’m not a licensed electrician, so take my advice with a grain of salt.

The guide assumes that you have at least some idea of what you want to do and why. It also assumes that you have general ability to use a Linux shell environment. If you don’t know what you want to do or whether you’re up to the task, read on to find out!

Keep in Mind…

I’m putting this stuff at the top, since it’s good for you to know ahead of time:

This blog post was written/updated for Home Assistant v0.53.1. They modify it frequently. I’ll try to keep it up to date as much as possible, but make sure you know which version you’re installing.

If you need help, commenting on this post is probably not the most efficient approach. You can find a lot of great material on the Home Assistant Help page (forum, chat, bug reports, etc.).

The majority of this post will still apply to your system even if you are changing or omitting one or two of the described components (e.g. Zigbee instead of Z-Wave, no Alexa, no Siri, etc.).

System Capabilities

Home Assistant is incredibly flexible, and it can integrate with many other popular systems like Philips Hue, Samsung SmartThings, Wink, and others. However, you don’t necessarily need these (I don’t have any of them). All you do need is a computing platform to run Home Assistant on and compatible RF controller(s) for the technologies you want to support. In my case, that means an Ubuntu Linux installation (optionally virtualized) and a Z-Wave USB stick.

This setup acts as a customizable Z-Wave network controller capable of managing a 50-node home-wide collection of switches, dimmers, fan controllers, and various sensors. Most of the magic happens in software. I can do things like:

Control the state of any light or group of lights in the house from anywhere

Instantly adjust all living room lights to a dim “TV time” scene with a request to Siri or Alexa

Send a text message if the garage door is open and nobody is home

Turn off all of the lights in the basement at midnight if I accidentally left them on

Turn on the garage entry and stairwell landing lights when we arrive at home

The possibilities are only as limited as my creativity. These automations take a bit of time to set up, but you can do whatever you want.

Also—and this is a big deal to me—the system does not require any subscription fees and still runs perfectly (in most ways) without an internet connection. Internet access opens up cool possibilities and is required for iCloud-powered geofencing, but it isn’t a core requirement for most features.

Recommended Hardware

The hardware you need to buy depends greatly on what you want to do. To make it easier for you, here’s a list of products that I use, all of which are available from Amazon:

[If you don’t see anything here, it’s because you have ad-blocking enabled. I totally get that, but you’re missing out on a great, concise list of tested hardware! I promise this site has no ugly or intrusive ads.]

Keep in mind that you do not necessarily need everything on this list! I created it as a guideline, and chose those parts because I actually use those exact items. You may want to wait on the mini PC in particular until after you try setting up your system in a virtual machine. You may find that keeping the virtual machine works perfectly well, at least to start with.

Also, buying through these links gives me a small kickback through Amazon. If you appreciate this guide and want to buy some of the above hardware, that’s a great way to say thanks without it costing you anything extra.

Step 1: Installing Home Assistant

I will assume that you have the base operating system already installed and connected to the internet. This might mean Ubuntu Server running in VMWare Player, or Raspbian on a Raspberry Pi, or even Debian on some other hardware. The Home Assistant team provides a ready-made RasPi3 image called Hassbian, but I am not using that for this guide because it’s not hard to install in an existing environment and you get a little more transparent control over the process when you do. This becomes important for certain underlying customizations necessary for some Z-Wave devices, including two of the ones that I use.

The method we’ll use here is what the HA website calls “installing in a Python virtualenv,” and fortunately they already have very good documentation describing the procedure. I’ll reproduce the important parts here for convenience, but please review the official documentation for extra details.

Connect to your server via SSH or other terminal and type the following commands as a normal user (not root):

These two commands will create and then switch to the new Python virtual environment, which is a relatively isolated set of Python binaries and libraries that will only be available to Home Assistant. After the second command, the shell prompt should include (homeassistant).

Finally, run the following command to install Home Assistant inside the virtualenv container:

pip3 install --upgrade homeassistant

The --upgrade flag means you can use the same command to perform an upgrade to the latest version later, after the Home Assistant team creates a new release (which happens surprisingly often).

Finally, start Home Assistant manually with the “hass” command to make sure that it works as expected:

hass

You should get a bunch of console output with no obvious error messages. To confirm that it’s working, open a web browser on a computer on the same network and navigate to http://<ip_address>:8123, which is the default web server port for Home Assistant. You should see something like the following:

If you see this, you’ve successfully installed Home Assistant. Now press Ctrl+C in the terminal exit the process and return to the shell, and exit the virtualenv sub-shell with the following command:

exit

The console should now return to the normal non-root user shell that you started with, which doesn’t have the (homeassistant) prefix.

Step 2: Configuring Home Assistant to start automatically

Be default, Home Assistant in a Python virtualenv doesn’t start automatically on boot. To fix that, we follow a slightly modified version of the official autostart documentation, with small tweaks that are unique to the virtualenv setup:

The autostart instructions will work just fine, just be sure to replace /usr/bin/hass with /srv/homeassistant/bin/hass and specify the homeassistant user where appropriate.

The exact steps required here depends on the underlying Linux environment. This guide assumes Ubuntu 16.04 or later, or Debian 8 or later, which uses the systemd method. These instructions will not work if you don’t have a systemd-based installation. The official documentation describes how to configure the service definition for certain variables, but if you have followed the instructions so far, you can use the file and template contents below directly.

Now press Ctrl+X to exit and “Y” to confirm writing changes to the file. Then, create a symlink from this file to the “active” systemd location, reload the systemd configuration, and start the service:

You should now be able to open or refresh the same browser window from before and access the Home Assistant web GUI. It might take a few seconds to become available. You can verify that it starts automatically by completely rebooting the system, but this is not strictly necessary.

Step 3: Preparing the MySQL database backend

This step is not strictly necessary, but it provides a performance improvement compared to the SQLite backend that Home Assistant uses by default. It’s not hard to do, and it really helps if end up with a lot of entities in your automation network. To start, install and configure MySQL if you haven’t already:

sudo apt-get install mysql-server

Make sure you keep the root password handy after the setup process, since we’ll need it to create the Home Assistant database now from the command line after logging in:

mysql -u root -p

After entering the MySQL root password, you should now be greeted by the MySQL monitor welcome message:

Welcome to the MySQL monitor. Commands end with ; or \g.
Your MySQL connection id is 492
Server version: 5.7.18-0ubuntu0.16.04.1 (Ubuntu)
Copyright (c) 2000, 2017, Oracle and/or its affiliates. All rights reserved.
Oracle is a registered trademark of Oracle Corporation and/or its
affiliates. Other names may be trademarks of their respective
owners.
Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.
mysql>

Note that the hass user we’ll be creating here can only access the hass database from localhost, so there probably isn’t a huge security risk with having a weak password. However, there’s no reason it can’t be strong either. Enter the following commands as-is or modified as desired into the console:

Note the database name, username, and password that you choose for later inclusion in Home Assistant configuration files. Before we’re done here, we have to install some dependencies for Home Assistant to use. Run the following shell commands to install the development source files, switch to the homeassistant user, activate the virtual environment, install the Python MySQL client, and return to the standard shell and user:

Other than modifying the Home Assistant configuration file to point to the right database backend (Step 6), everything should be prepared for MySQL storage.

Step 4: Preparing the Z-Wave USB stick udev symlink

The Aeon Labs ZW090 Z Stick recommended above appears as a standard USB serial device, which has a name like /dev/ttyUSB0 or /dev/ttyAMA0 or /dev/ttyACM0, depending on the platform. The device number isn’t always “0” either, depending on how many other USB serial devices are plugged in at the same time and the order of enumeration.

Because Home Assistant needs to know the device node, we can solve the “possibly unknowable” name problem by creating a custom udev rule so that the vendor ID and product ID (VID:PID) combination always generates a special /dev/zwave symlink device node. To do this, create or open a custom udev rules definition file:

This will guarantee that Home Assistant will always talk to the right device if it’s plugged in.

Step 5: Preparing Home Assistant configuration file organization

Home Assistant uses YAML for configuration data, and if you look through any of the example configuration filesets that they provide, you’ll undoubtedly notice some patterns.

Step 6: Configuring MySQL usage in Home Assistant

The default database storage engine that Home Assistant uses is SQLite. This is simple, but it doesn’t have the best performance. This can be a real problem if you end up with a giant collection of devices in the future.

Since we set up the MySQL database back end in Step 3, putting it into use is very simple. We only have to make two changes (or just one, if you ignored the recommendation in Step 5 to create a special “secrets” configuration file).

First, open the main configuration.yaml file in an editor:

sudo nano /home/homeassistant/.homeassistant/configuration.yaml

Now, paste the following content at the bottom of the file:

recorder:
db_url: !secret recorder_db_url

Next, open the secrets.yaml file in an editor:

sudo nano /home/homeassistant/.homeassistant/secrets.yaml

Finally, add the following line:

recorder_db_url: mysql://hass:hasspass@localhost/hass

To clarify, the first “hass” is the MySQL user, “hasspass” is the password, and the last “hass” is the database name. If you changed any of these from the examples provided in Step 3, make sure you also change them in this configuration line.

That’s it for MySQL usage. Onward!

Step 7: Configuring Z-Wave behavior in Home Assistant

Remaining content coming as soon as I can manage it!

Home Automation Guide: Home Assistant, Siri, Alexa, Z-Wave, and iCloud was last modified: February 14th, 2018 by Jeff Rowberg

10 comments

ChrisJuly 17, 2017 at 6:43 am

Dude, I started to follow along and then the post stopped just as it was getting to the juicy stuff! Please continue it. There’s a real lack of step-by-step guides to setting up hass. Keep up the good work. Thanks!

Are you running each of these as individual commands? For example, “sudo apt-get upgrade” is one command, “sudo usermod -G dialout -a homeassistant” is a different command, etc? They can’t all be run together as a single command.

Hey Jeff, that worked. I am a total newb to Linux. It took me a minute to understand that unbuntu server doesn’t have a gui by default. haha.. I Got past that now I’m rolling thru your instructions. Thank you sir!

Great instructions – this helped a lot. Step 2, just before the end, has code that should be in a code block but isn’t:
“sudo systemctl –system daemon-reload sudo systemctl start home-assistant.service”

It’s clear this should be two commands – and for the first command, systemctl didn’t like the system switch. Since per the man it’s the default behavior, I left it out and it worked fine.

Thanks. There’s something funky going on in that code – it’s not auto-starting on reboots. The steps here require a “sudo systemctl start home-assistant.service” with every reboot, otherwise the web page isn’t served. It’s strange, the service file seems linked correctly and once the command is issued things run normally. But it doesn’t survive reboots. Any idea what’s going on? This is a fresh Ubuntu 16.04 install. Thanks!