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

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

17 comments

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.

LAST UPDATE: January 22, 2022 with Home Assistant v2021.12.

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 v2021-12. 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, or has been open for more than 15 minutes
  • 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 your 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 a collection of products above, 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. Just in case, here are simple text links to each of the same products:

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 them. You may want to wait on the mini PC in particular until after you try setting up your system in a virtual machine. Keeping the virtual machine might work perfectly well for you, at least at the beginning.

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

There are actually a few different ways to get Home Assistant running:

  • Install inside your native Python 3.9 environment
  • Install into an isolated Python 3.9 virtualenv (the method documented in this post)
  • Install using the hass.io Docker image
  • Install using the complete hass.io or Hassbian OS image

There are pros and cons to each approach. I chose the virtualenv method because I am running it on a server that is also performing many other tasks (Plex media server, web server, file server, etc.). The virtualenv configuration provides suitable isolation from the rest of the system while still allowing complete customization of anything you might want, without any of the sometimes maddening hurdles that an otherwise convenient Docker container can impose. You can choose whatever method you want, but if you don't use the virtualenv option, much of this guide won't work without tweaks.

I will assume that you have a Debian-based operating system (Ubuntu, Mint, Debian, etc.) already installed on a physical or virtual server and connected to the internet. The Home Assistant website already has very good documentation describing the virtualenv installation procedure, but I'll reproduce the important parts here for convenience, but please review the official documentation for extra details. If you're following along exactly, I am assuming a fresh installation of Ubuntu 20.04 LTS Server Edition.

NOTE: These instructions also make use of the deadsnakes repository, which maintains a full set of all current and recent releases of Python. I've found this to be helpful due to the fact that Home Assistant occasionally requires you to update the underlying Python installation to something not yet part of the official Ubuntu/Debian repositories. If you know enough about your installation to be sure you don't need this, go ahead and skip that command. You might need to install the virtualenv package using pip instead if you choose to do this.

First, connect to your server via SSH or other terminal and type the following commands as a normal user (not root, sudo takes care of that):

sudo add-apt-repository universe
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt update
sudo apt upgrade
sudo apt install build-essential python3.9 python3.9-dev python3.9-venv libudev-dev
sudo adduser --system homeassistant
sudo addgroup homeassistant
sudo usermod -G dialout -a homeassistant
sudo mkdir /srv/homeassistant
sudo chown homeassistant:homeassistant /srv/homeassistant
sudo su -s /bin/bash homeassistant

Note that this last command will switch you from the previous user to the new homeassistant user. Now type:

python3.9 -m venv /srv/homeassistant
source /srv/homeassistant/bin/activate

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:

python3.9 -m pip 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. The first run also triggers some automatic dependency installations, so it might be a few minutes before the web UI actually becomes available. When it's ready, you will see a user creation form:

If you see this, you've successfully installed Home Assistant. This form is part of the "onboarding" process for new installations, and is one of the more recent feature additions. The user that you create here will be the master administrator for this Home Assistant instance, able to create and modify other users and change all available settings. Go ahead and fill out the form, then click the "Create Account" button.

After completing the one-time admin creation step, you must log in using the same credentials to continue:

Since this is a new authentication event from a previously unknown source, the web UI will display a prompt asking whether you want to save this login (basically a "remember me" option so you don't have to enter your credentials every time from the same browser). This is option, but you probably want to click the "Save Login" button.

After you log in, you'll see the Home Assistant front end with a few default items. It will look something like this:

You might see a few extra cards if Home Assistant automatically detected a few common devices on your network, such as a Harmony Hub. You can also click on the notification icon near the top right corner of the UI to see important information from the server, including components that were automatically discovered and require additional steps to configure.

One extremely helpful resource for new users can be found in the notification drawer in fresh installations: the "Welcome Home!" card with quick links to beginner topics:

For now, we'll go back and finish the server setup. This card will always be available after starting or restarting Home Assistant until you specifically remove it, so don't worry about losing the info.

Go back to the terminal where you started the hass process and press Ctrl+C to exit and return to the shell. (The web UI will stop working for now, but that's okay.) Then, 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

By 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.

First, create the service file with the following command:

sudo nano /lib/systemd/system/home-assistant@homeassistant.service

Now, paste the following content into the new file:

[Unit]
Description=Home Assistant
After=network-online.target

[Service]
Type=simple
User=%i
ExecStart=/srv/homeassistant/bin/hass -c "/home/homeassistant/.homeassistant"

[Install]
WantedBy=multi-user.target

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:

sudo ln -s /lib/systemd/system/home-assistant@homeassistant.service /etc/systemd/system/home-assistant@homeassistant.service
sudo systemctl --system daemon-reload
sudo systemctl enable home-assistant@homeassistant.service
sudo systemctl start home-assistant@homeassistant.service

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

Step 3: Switching to the MySQL database backend

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

sudo apt install mysql-server
sudo mysql_secure_installation

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:

sudo 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: 8.0.27-0ubuntu0.20.04.1 (Ubuntu)
Copyright (c) 2000, 2021, 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. If you have password validation enforced in your MySQL installation, you will need to use a password that follows whatever rules you have chosen (e.g. minimum 8 characters, symbols required, etc.). Enter the following commands as-is or modified as desired into the console:

create database hass;
create user hass@localhost identified by 'hasspass';
grant all on hass.* to hass@localhost;
flush privileges;
quit;

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:

sudo apt install libmysqlclient-dev
sudo su -s /bin/bash homeassistant
source /srv/homeassistant/bin/activate
python3.9 -m pip install --upgrade mysqlclient
exit

All that remains is to modify the Home Assistant configuration file to point to the new database backend. We only have to make two changes. 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 (it's YAML, so precise spaces are important!):

recorder:
  db_url: !secret recorder_db_url

Exit and save with Ctrl+X and "Y", and then 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. Exit and save with Ctrl+X and "Y" to continue.

While you can skip the "secrets.yaml" layer and just put the value right into the configuration.yaml file, it's good practice to keep any important private information away from your main files. This way, if you need some help on the forums or you just want to share your configuration with someone else, you can do so without manually scrubbing secret info out every time (or worse, forgetting to do so and immortalizing your iCloud password on a public forum).

Finally, make the database change take effect by restarting the Home Assistant service:

sudo systemctl restart home-assistant@homeassistant.service

That's it for MySQL usage. Onward!

Step 4: Configuring secure external HTTPS access

Many of the most useful Home Assistant features and integrations require some way for specific devices or services outside of your network to access the service, including the Home Assistant iOS app and Alexa integration. You can technically skip this if you don't need those integrations, but you'll probably want to set it up. (You can also do it later if you aren't sure.)

For this process, I will assume that you have a domain name already and that you have opened and forwarded port 80 (HTTP) and port 443 (HTTPS) on whatever routers/firewalls you have to point to the server running Home Assistant inside your network. There are plenty of resources online if you need help for this step.

It doesn't matter what domain/subdomain you use, as long as it is unique to your Home Assistant installation. For instance, you might choose "hass.yoursite.net" as a way of differentiating it from the main "yoursite.net" URL. Since you'll likely be running this from your house, you can also use a dynamic DNS service such as DuckDNS (a Home Assistant community favorite) or No-IP, or DynDNS, or many others. Personally, I have a No-IP account kept up-to-date by my Tomato router firmware, and my actual Home Assistant target domain is a CNAME subdomain record that points to my No-IP domain name. This means the URL I access my server through gets to be entirely my own, rather than something ending in ".ddns.net" or similar.

We'll be using NGINX and Let's Encrypt to create a secure reverse proxy to the Home Assistant installation, mostly following the official instructions available here. Although Home Assistant supports SSL certificates directly, I've found a reverse proxy to be a much more flexible approach. This is especially true if you have other similar sites (NodeJS, Docker, etc.) that also fit nicely into a reverse proxy setup. It also makes SSL certificate renewals simpler and avoids the need to restart Home Assistant when renewals occur.

Basically, NGINX will be acting as a very thin layer between the outside world and Home Assistant, presenting a secured HTTP service to the outside and transparently passing requests back and forth to your internal unsecured Home Assistant service.

To begin, install NGINX and certbot (from the official repository) if you don't already have them:

sudo apt install nginx
sudo snap install core
sudo snap refresh core
sudo snap install --classic certbot
sudo ln -s /snap/bin/certbot /usr/bin/certbot

Next, create a site definition file for Home Assistant:

sudo nano /etc/nginx/sites-available/homeassistant

Paste the following content into this file, making sure to change hass.yoursite.net into your actual domain name:

server {
    listen 80;
    server_name hass.yoursite.net;
}

Exit and save with Ctrl+X and "Y", and then create a symlink from this file to the /sites-enabled subfolder:

sudo ln -s /etc/nginx/sites-available/homeassistant /etc/nginx/sites-enabled/homeassistant

Finally, run certbot to obtain a certificate. (Don't worry that our web server isn't completely set up yet.)

sudo certbot

This actually is the only command necessary, if you've been following along exactly. Because we installed the NGINX authenticator/installer plugin, certbot will automatically look for suitable site definitions and ask if you want to get certificates for them. Although the definition we created above is a stub that we'll have to fill out later, the server_name directive is enough for it to be detected.

If you haven't run certbot before, you'll be asked for an email address for renewal reminders and a Terms of Service agreement confirmation, plus an optional newsletter sign-up prompt. Finally, it will ask which names you want certificates for. Select your chosen Home Assistant domain and press Enter, then also enable HTTP redirection unless you have a very good reason not to. This ensures that unsecured requests to your Home Assistant installation end up on the secured channel, avoiding accidental exposure of potentially sensitive data.

When you're done, the output should look something like this:

Which names would you like to activate HTTPS for?
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
1: hass.yoursite.net
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Select the appropriate numbers separated by commas and/or spaces, or leave input
blank to select all options shown (Enter 'c' to cancel): 1
Obtaining a new certificate
Performing the following challenges:
http-01 challenge for hass.yoursite.net
Waiting for verification...
Cleaning up challenges
Deploying Certificate to VirtualHost /etc/nginx/sites-enabled/homeassistant

Please choose whether or not to redirect HTTP traffic to HTTPS, removing HTTP access.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
1: No redirect - Make no further changes to the webserver configuration.
2: Redirect - Make all requests redirect to secure HTTPS access. Choose this for
new sites, or if you're confident your site works on HTTPS. You can undo this
change by editing your web server's configuration.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Select the appropriate number [1-2] then [enter] (press 'c' to cancel): 2
Redirecting all traffic on port 80 to ssl in /etc/nginx/sites-enabled/homeassistant

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Congratulations! You have successfully enabled https://hass.yoursite.net

The next step is to modify the site definition to include the important reverse proxy directives for Home Assistant. Open the same site definition file (now modified by certbot) in an editor:

sudo nano /etc/nginx/sites-available/homeassistant

Paste the following content into the end of the first server { ... } block (the one with the ssl on; directive):

    ssl_session_tickets off;

    location / {
        proxy_pass http://localhost:8123;
        proxy_set_header Host $host;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto https;
        proxy_set_header X-Real-IP $remote_addr;
    }

    location /api/websocket {
        proxy_pass http://localhost:8123/api/websocket;
        proxy_set_header Host $host;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto https;
        proxy_set_header X-Real-IP $remote_addr;
    }

Exit and save with Ctrl+X and "Y", and finally reload the NGINX configuration to finalize the settings:

sudo systemctl reload nginx

The final step is to modify Home Assistant to expect reverse-proxied connections, which are subtly different from direct ones in some ways. We'll also add a bit of extra security in the form of an IP ban for 5 sequential failed login attempts. Open the main configuration file in an editor:

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

Now add the following lines to the end of the configuration file (again, YAML means pay strict attention to spaces):

http:
  use_x_forwarded_for: true
  trusted_proxies: 127.0.0.1
  ip_ban_enabled: true
  login_attempts_threshold: 5

Exit and save with Ctrl+X and "Y", and then restart Home Assistant to wrap everything up:

sudo systemctl restart home-assistant@homeassistant.service

You should now be able to point a web browser at https://hass.yoursite.net and see your Home Assistant instance appear. (You might need to log in again since the domain name changed, and your browser will not know to reuse the old IP-associated stored credentials.)

NOTE: if you get a name resolution error or some similar "unable to connect" type of message, make sure that your router knows how to handle internal requests to forwarded ports. Forwarding might work fine from external networks—your work computer or your friend's house, for example—but internal connections go nowhere because your router treats them differently. This is router-specific behavior; my Tomato-based router handles it fine with no special configuration. Just be aware you should check connectivity from both sides, and if only external access works, it's not Home Assistant's (or NGINX's) fault and you may need special router settings or a local DNS server to handle what is known as loopback or hairpin NAT.

On to the next step!

Step 5: 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.

If you are using the Nortek HUSBZB-1 (another common USB dongle that supports both Z-Wave and Zigbee), two separate device nodes will be created and can be aliased in a similar way.

To add alias support for both of these dongles (though you'll only need one), create or open a custom udev rules definition file:

sudo nano /etc/udev/rules.d/99-usb-serial.rules

Then add the following lines to that file:

SUBSYSTEM=="tty", ACTION=="add", ATTRS{idVendor}=="0658", ATTRS{idProduct}=="0200", SYMLINK+="zwave"
SUBSYSTEM=="tty", ATTRS{interface}=="HubZ Z-Wave Com Port", SYMLINK+="zwave"
SUBSYSTEM=="tty", ATTRS{interface}=="HubZ ZigBee Com Port", SYMLINK+="zigbee"

Press Ctrl+X to exit and "Y" to confirm writing changes to the file, and finally restart the udev service to apply the changes:

sudo systemctl restart udev.service

If you have the Z-Wave or Z-Wave/Zigbee combo USB dongle, insert it now. If you already inserted it, you can either remove it and then reinsert it or else run the following command to cause the udev subsystem to rescan and re-alias devices as though you just plugged them in:

sudo udevadm trigger --action=add

You should now be able to see the /dev/zwave device node correctly:

ls -l /dev/z*
crw-rw-rw- 1 root root 1, 5 May  6 16:53 /dev/zero
lrwxrwxrwx 1 root root    7 Jun  4 21:06 /dev/zwave -> ttyACM0

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

Step 6: Configuring Z-Wave integration in Home Assistant

Remaining content coming as soon as I can manage it!

Appendix A: Service and Update Management Aliases

There are two processes that I frequently use while working with my own Home Assistant installation:

  1. Restart the service
  2. Update to a new release

Restarting is necessary after most types of configuration changes. Fortunately, you can restart straight from the GUI now—and in fact you should, because this method checks your configuration first and won't proceed if there is an error that would cause a startup failure. You can access this method by going to Configuration -> General -> Server management in the web UI:

Even so, having easy access to do the same thing in the console is convenient, especially when performing a release update (currently only possible from the console in this type of installation).

Updates are published almost weekly sometimes, and they often bring great new features. But because of the way virtualenv installations work, moving in and out of the correct environment to perform the update takes a few steps, and I always have to look them up to make sure I have the command syntax right. Fortunately, I happened upon a Bash script on the forum from the wonderful firstof9 to automate the whole process. Create a file in the Home Assistant user's home directory:

sudo nano /home/homeassistant/upgrade.sh

Then add the following content:

#!/bin/bash

# Update Home Assistant in virtualenv

if [ "$(id -u)" != "0" ]; then
echo "This script must be run with sudo. Use \"sudo ${0} ${*}\"" 1>&2
exit 1
fi

echo "Changing to user homeassistant"
sudo -H -u homeassistant /bin/bash <<EOF
echo "Activating virtual environment"
source /srv/homeassistant/bin/activate
echo "Updating Home Assistant to latest version"
pip3 install --upgrade homeassistant
echo "Deactivating virtual environment"
deactivate
EOF
exit 0

Finally, make this script executable:

sudo chmod +x /home/homeassistant/upgrade.sh

To help make everything more accessible within the console, I created a set of Bash aliases to work with the service as well as the upgrade script. To incorporate these aliases into your own setup, create or edit the .bash_aliases file:

nano ~/.bash_aliases

...and add the following content:

alias hastatus='sudo systemctl status home-assistant@homeassistant.service'
alias harestart='sudo systemctl restart home-assistant@homeassistant.service'
alias hastart='sudo systemctl start home-assistant@homeassistant.service'
alias hastop='sudo systemctl stop home-assistant@homeassistant.service'
alias haupgrade='sudo /home/homeassistant/upgrade.sh'
alias halog='tail -f /home/homeassistant/.homeassistant/home-assistant.log'
alias replug='sudo udevadm trigger --action=add'

Remember that entries in this file will not take effect until your next login, so if you want them to apply immediately, just paste them into your console as well the first time.

Appendix B: Troubleshooting

I strongly recommend using the community forums that Home Assistant provides. Also, monitoring the contents of home-assistant.log during start-up (will reveal the source of many issues. But I have also run into a couple of odd failures that are worth mentioning specifically. Usually, this happens as a result updating your installation.

One problem is that some subfolder of the Home Assistant installation has permissions that are preventing an automatic component update from taking place. To fix permissions so that the homeassistant user is able to make changes to the filesystem where it needs to, run the following command:

sudo chown -R homeassistant:nogroup /srv/homeassistant

That should take care of any permission-related problems.

Another problem stems from unexpected disappearance of device nodes such as /dev/zwave or /dev/zigbee, causing these main components to fail to initialize ("Why did my entire network disappear?!"). Run the following command and then restart Home Assistant:

sudo udevadm trigger --action=add

Assuming the devices haven't actually malfunctioned, this should fix the node alias problem and restore communication to Home Assistant.

You may also like

17 comments

Chris July 17, 2017 - 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!

Reply
andrew December 16, 2017 - 11:19 am

Hey, yes I agree, just got interesting and you stopped, please continue……..

Reply
R Salas January 14, 2018 - 12:18 pm

sudo apt-get upgrade sudo apt-get install python-pip python3-dev sudo pip install –upgrade virtualenv sudo adduser –system homeassistant sudo addgroup homeassistant sudo usermod -G dialout -a homeassistant sudo mkdir /srv/homeassistant sudo chown homeassistant:homeassistant /srv/homeassistant sudo su -s /bin/bash homeassistant

I’m getting a error in the install part : E: Command Line Option ‘G’ [from -G] is not understood in combination with other options.

Reply
Jeff Rowberg January 14, 2018 - 1:41 pm

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.

Reply
Jeff Rowberg January 14, 2018 - 1:48 pm

I just realized that the formatting for that list of commands got messed up at some point in the post edit history, so it looked like they all ran together. I’ve fixed it.

Reply
R Salas January 14, 2018 - 1:58 pm

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!

Reply
J Hall February 14, 2018 - 2:35 pm

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 again.

Reply
Jeff Rowberg February 14, 2018 - 2:38 pm

Thanks for the heads-up. I don’t know why some of these code blocks keep getting reverted to single lines instead of preformatted multi-line blocks. I’ll take care of it in the content.

Reply
J Hall February 14, 2018 - 8:10 pm

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!

Reply
J Hancock March 2, 2018 - 5:17 pm

I had a similar problem. Ended up deleting the link and following the instructions on HASS site on “Autostart using systemd”… Their instructions are much the same. I’m not sure what made the difference, but it works now after a reboot.

Reply
Jeff Rowberg February 24, 2019 - 10:50 pm

Got it, after all this time: you also need “sudo systemctl enable …” as well as the “start” command in order to make it automatic. I can’t believe I missed that for so long.

Reply
Mike February 14, 2018 - 11:15 pm

Thanks dude. Waiting on the rest of this very detailed walkthrough. Thanks again.

Reply
sanket July 7, 2018 - 2:45 am

I would appreciate really when you write on inclusion of zwave devices… facing a lot of issues…..

Reply
Erik February 24, 2019 - 4:36 pm

This is the best guide I’ve found. And it’s written in a way that even I understand what most of the commands I’m copy/pasting actually do. I’m having some trouble with the service not restarting after a reboot, as a few others above. But that’s minor. I’ll figure it out eventually. Everything else is fantastic! Thank you very much for sharing.

Reply
Jeff Rowberg February 24, 2019 - 5:22 pm

Thanks! Unless you followed the guide in the last two days, you might want to review the auto-start section. I just caught and fixed an omission that might have broken it (missing @homeassistant in some service names).

Reply
Jeff Rowberg February 24, 2019 - 10:39 pm

Nope, I got it now: there’s one final “enable” command that I left out:

sudo systemctl enable home-assistant@homeassistant.service

Run this during the configuration process (or anytime, really) and you should be all set. D’oh.

Reply
Erik February 25, 2019 - 4:52 pm

You are a wizard! That fixed it. Again, I’m very grateful you taking your time to share this. 🙂

Reply

Leave a Comment