Setting up Home Assistant

Fri 12 Mar 2021

In this article I'm going to describe the steps I took to install Home Assistant on a Raspberry Pi 3 to make my home a little bit smarter. We have various lights and devices that we can hook up to HA and make our lives easier :)

In the first part we will get our Raspberry up and running. We will be using Raspberry PI OS Lite, installing everything from scratch.

Next, installing Home Assistant by using the official Docker image. Why docker? Easier to manage. The raspberry holds up great! Performance is very good. No reason for me personally to install native.

Lastly, hardening our setup. We want to be in control of our setup and manage who can access.

Setting up your Raspberry

First I went to the software page on Raspberry's website to download the 2021-01-11 Raspberry Pi OS Lite image. This is a headless install, meaning it does not contain a DE. Obviously we won't be needing this. Home Assistant will be running it's own web interface. Flash the image and be sure to make a ssh file on the boot partition!

Raspberry OS has a feature that will look for that file. It will enable the SSH service for us. This will make accessing the Pi easy-peasy!

Now we need to find the Raspberry. Once again, they ship with a cool feature that makes this easy. You can also find both commands on my Useful command line snippets article. In short one of the two following commands should help you. Obviously the ping command will also work for *nix.

# Find raspberries on the network

# *nix variant
rob@Rathalos ~ $ nmap -sP | awk '/^Nmap/{ip=$NF}/B8:27:EB/{print ip}'

# Windows variant
C:\Users\Leszy>ping raspberrypi.local

Based on your local network configuration you could be getting a IPv4 or IPv6 address. Both work. In my case a IPv6 address returned. I've obscured the address as my Ipv6 address was a public one. This I used to get into my raspberry like the following. You will be needing ssh for this. Windows 10 happens to ship with ssh installed in cmd these days, hooray for Windows for doing something right at least!

# Works for both *nix and Windows the same
# Psssst! Password is "raspberry"
rob@Rathalos ~ $ ssh pi@ab12::78ta:3aq2:7gh2:987h

The authenticity of host 'ab12::78ta:3aq2:7gh2:987h (ab12::78ta:3aq2:7gh2:987h)' can't be established.
ECDSA key fingerprint is SHA256:18LMYM4f6l0O1flPGyrXi0HadAZ3lh9cq8OEDORfa84.
Are you sure you want to continue connecting (yes/no)? yes
Warning: Permanently added 'ab12::78ta:3aq2:7gh2:987h' (ECDSA) to the list of known hosts.
pi@ab12::78ta:3aq2:7gh2:987h's password:
Linux raspberrypi 5.4.83-v7+ #1379 SMP Mon Dec 14 13:08:57 GMT 2020 armv7l

The programs included with the Debian GNU/Linux system are free software;
the exact distribution terms for each program are described in the
individual files in /usr/share/doc/*/copyright.

Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extent
permitted by applicable law.

SSH is enabled and the default password for the 'pi' user has not been changed.
This is a security risk - please login as the 'pi' user and type 'passwd' to set a new password.

Wi-Fi is currently blocked by rfkill.
Use raspi-config to set the country before use.

pi@raspberrypi:~ $

If you get something like this then you are good to go! Next up is installing Home Assistant on this Raspberry with Docker.

Installing Docker

This is going to be a small chapter. We will need docker-compose and docker. You can simply install them with the following command.

pi@raspberrypi:~ $ sudo apt-get install docker-compose docker

We are not done yet! It's a small chapter but not that small! We need to create the docker group and assign pi to that group. Why? It will allow us to run docker stuff on the pi user instead of the root user. Following this guide you will be able to set this up. Otherwise you get these pesky messages:

docker: Got permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock: Post http://%2Fvar%2Frun%2Fdocker.sock/v1.39/containers/create?name=homeassistant: dial unix /var/run/docker.sock: connect: permission denied.

We actually need to create and assign the group ourselves. Docker will assume these exist even though they might not be. If the group already exists than it will tell you.

pi@raspberrypi:~ $ sudo groupadd docker

pi@raspberrypi:~ $ sudo usermod -aG docker $USER

Now, for this to take effect we need to logout and login back into the pi. When you have done this we can validate if the user is now assigned to the docker group with the following command:

pi@raspberrypi:~ $ groups
pi adm dialout cdrom sudo audio video plugdev games users input netdev docker gpio i2c spi

Furthermore, when you run docker commands you should not get those permission messages anymore.

Making it easily accessible

The IP of the raspberry is not static. It can change after a reboot and will also be difficult when pointing other devices to the raspberry. In general this also means that accessing the device can be tricky. Easy access we can fix by making a homeassistant.local DNS entry to this address; whilst also making that address static.

Doing these two things will give us great benefit of accessibility and flexibility when building on top of this.

First, to make the IP static we need the MAC address of the raspberry. You can find that by running ifconfig on there. It will look a little like this b4:65:de:41:85:0e. Now, login to your router and find that MAC in there. You can either find by hostname or MAC, we will use the MAC to verify we have the right device, as we are reserving a IP for that device.

I happen to run a PiHole in my network. A PiHole does not only block certain DNS addresses but also functions a an DNS Server. Go to Local DNS -> DNS Records. Here you can add DNS records for all of your devices for easier access. This way you can manage the ip without changing the domainname.

Installing Home Assistant

Installing Home Assistant is easier than you think. I am following this guide. They have prepped an Docker image making this really easy to do. There are some know-hows that will be explained in this article making your Home Assistant setup more robust and easier to manage.

We need to run HA. It's a good practice to prepare a config directory on the Pi in the home folder of the user. This way you can edit your config later easily.

docker run --init -d \
  --name homeassistant \
  --restart=unless-stopped \
  -v /etc/localtime:/etc/localtime:ro \
  -v /PATH_TO_YOUR_CONFIG:/config \
  --network=host \

Since we already setup docker we should be able to run the image no problem. It will start downloading it to the pi and run it afterwards. You can check the status of the image with docker ps. This should show something like the following:

pi@raspberrypi:~ $ docker ps
CONTAINER ID        IMAGE                                             COMMAND             CREATED             STATUS              PORTS               NAMES
f90d18565d70        homeassistant/raspberrypi3-homeassistant:stable   "/init"             8 minutes ago       Up 8 minutes                            homeassistant

After this you can visit the IP address in your bowser with the port attached :8123 and that should give you a onboarding screen for HA. If you have trouble finding your IP than use hostname -I to get the IPv4 address of the Pi to simplify things :)

From there it is just a matter of onboarding your devices to HA.

Adding an Z-Wave Controller to your HA

I happen to have a Aeotec Z-Wave USB controlller. Z-Wave makes a lot of sense when you are going to make a lot of things smart. Setting up this controller is easy. Plug it in. Done.

However, the software side of things at moment of writing is a tad trickier.

The Z-Wave JS integration is what I went for. This means it will connect to a local websocket to receive all Z-Wave information. You will need npm for this as a prerequisite. You can download the binaries here. Check with uname -m (-m or --machine) what ARM binary you need. The good thing about doing it this way is that your Z-Wave network will boot up aside your HA instance. I've used this package to run the server instance. After I got this up and running you simply point the integration to it. At that point you will be ready to add devices to your Z-Wave network via Home Assistant.

I've added two Neo Motion Sensors to the network. They are very affordable and perform great. Pairing following the guide went pretty much as expected. I will be setting up a custom script with these sensors later in this guide.

Hardening the security

Enable two factor authentication for your account on HA. This can be done from the menu. I always recommend to use 2FA when possible. It does not end there! I've got a few tips that can be found on their own minimal security guide.

  • Don't allow for root login with PermitRootLogin no for SSH in the /etc/ssh/sshd_config.
  • Change the password of the pi user.
  • When remote access is a wish, please use a secure VPN connection to your local network and go from there.
  • Setup a (application) Firewall up, although this is a very generic tip it is a good one.

My first custom script

Now that everything is setup and secure we can do some extra stuff. The wonderful thing about Home Assistant is that you can add scripts yourself. These are in the form of .yamlfiles. I've created my first custom script to light the lamps on the first floor and ground level during the night when you need to go to the bathroom. I'm using the Neo motion sensor as trigger for this. This script is generic and available from my Github here. I've also listed it under the forums for Blueprints.