Home Assistant is a very powerful, open source, community-driven smart home management platform. It can be run as a containerized solution, from a standalone device with pre-built images or as a software installation on a root-access linux device. This guide shall provide an introduction to the system and how to set up Home Assistant on a Raspberry Pi 3 Model B+. This method is referred to as Home Assistant Core. Feel free to work along with this guide to set up your own system and if you’d like to contribute to this guide, use the comment feature from Disqus below.

Prerequisites

In order to succeed with this guide, you will need the following:

  • Raspberry Pi 3 Model B+ (1.4GHz 64-bit quad-core processor, 1GB RAM, wireless LAN, PoE supported)
  • 5V 2.5A USB charger
  • microUSB charging cable
  • 16GB+ microSD card (Class 10 or faster)
  • LAN or wireless LAN
  • Internet connection
  • microSD card reader
  • Flashing software, i.e., balenaEtcher

Setup of Raspberry Pi OS

As the very first element in this guide, it is required to install Raspberry Pi OS onto your device. In this case, I have downloaded the latest RasPiOS ‘Bullseye’ for armhf architecture (32-bit) in the lite version from https://www.raspberrypi.com/software/operating-systems. Extract the zip-file and verify its MD5 or SHA1 checksum. The following example shows how to do this on macOS from Terminal.

user $ shasum Downloads/2021-10-30-raspios-bullseye-armhf-lite.img
ef38d8556924a3c758c00dcd10d71034884409c2  Downloads/2021-10-30-raspios-bullseye-armhf-lite.img

Insert your microSD card into a card reader on your computer. Use a tool to flash the image onto the microSD card. I recommend balenaEtcher (https://www.balena.io/etcher).

PerfectPrime IR-0019 Unboxing

After the image was successfully flashed onto the microSD card, ssh access needs to be enabled. Make sure the volume ‘boot’ shows up on your computer. You may need to remove and reinsert the microSD card or even unplug the card reader and reconnecting it. Use the command ‘touch’ on macOS or Linux. Create an empty file under Windows with a text editor (i.e., Sublime Text).

user $ touch /Volumes/boot/ssh

Now unmount your microSD card and insert it into the Raspberry Pi. Connect it to LAN, power it up and wait. Use your router’s client page to find the IP address of the Raspberry Pi or make use of nmap to scan for an IP address with ssh-port (22) open. In my case the IP address is 192.168.1.126. Now connect to your device using ssh via Terminal (macOS, Linux) or PuTTY (Windows). You may need to confirm the ssh certificate with yes.

user $ ssh pi@192.168.1.126
-> default password is 'raspberry'
pi $ sudo raspi-config
-> select 5 Localization Options
-> select L4 WLAN Country
-> select your country code (i.e., DE for Germany)

WiFi configuration can now also be completed inside ‘raspi-config’ if required. But let’s now update the OS and prepare for Python.

pi $ sudo apt-get update
pi $ sudo apt-get dist-upgrade
-> confirm with Y
pi $ sudo reboot
-> wait for the reboot to complete and reestablish your ssh connection via Terminal or PuTTY
pi $ sudo apt-get autoclean
pi $ sudo apt-get autoremove
pi $ sudo apt-get install liblzma-dev libncurses5-dev libreadline-dev libsqlite3-dev libssl-dev libffi-dev tk-dev libbz2-dev libgdbm-dev libgdbm-compat-dev
-> these are basic requirements for Python
pi $ sudo apt-get install rustc
-> this is required to compile python-cryptohraphy
pi $ sudo apt-get install libjpeg-dev
-> this is required to compile python-pillow
pi $ sudo apt-get install ffmpeg
-> this is for home assistant

Installation of Python 3.11

After the operating system has been comfortably set up and configured, the installation of Python 3.11 is required. Download the desired version from https://www.python.org/downloads/source and compile from source.

pi $ wget https://www.python.org/ftp/python/3.11.3/Python-3.11.3.tgz
pi $ tar zxvf Python-3.11.3.tgz
pi $ cd Python-3.11.3
pi $ ./configure --enable-optimizations
pi $ make -j -l 4
pi $ sudo make altinstall

Installation of Home Assistant

Now you need to install Home Assistant Core in a virtual environment (venv) in a separate directory. Start by adding the ‘homeassistant’ user and creating the relevant folder.

pi $ sudo useradd -rm homeassistant -G dialout,gpio,i2c
pi $ sudo mkdir /srv/homeassistant
pi $ sudo chown homeassistant:homeassistant /srv/homeassistant
pi $ sudo -u homeassistant -H -s
homeassistant $ cd /srv/homeassistant
homeassistant $ python3.11 -m venv .
homeassistant $ source bin/activate
(homeassistant) homeassistant $ python3 -m pip install wheel
(homeassistant) homeassistant $ pip3 install homeassistant

Getting Started with Home Assistant

Now let’s get started and use your Home Assistant installation. This follows immediately after the above commands, executed from the homeassistant user.

(homeassistant) homeassistant $ hass
-> this will take a while as Home Assistant will be launched for the first time

If you encounter any problems, you can enable a higher logging level. Establish a second ssh connection in parallel.

user $ ssh pi@192.168.1.126
pi $ sudo nano /home/homeassistant/.homeassistant/configuration.yaml
-> add the following inside the configuration file

logger:
  default: info

Now save the changes, close the file and switch back to the Home Assistant instance. Use ctrl-c command multiple times to stop the hass process. Launch Home Assistant again and monitor for WARNING or ERROR messages.

(homeassistant) homeassistant $ hass

Connect your web browser to Home Assistant by opening the URL http://192.168.1.126:8123 (change according to your IP address). Register your user with your full name, username and password. Follow the setup procedure of Home Assistant.

Configuring Start on Boot

When it’s all configured and running properly, you should set up Home Assistant, so that it can be launched automatically when the Raspberry Pi is powered up. This is especially useful after power-loss. First, use ctrl-c command multiple times to stop the hass process. The following commands must be executed from the default user ‘pi’, not ‘homeassistant’.

pi $ sudo nano /etc/systemd/system/homeassistant@homeassistant.service
-> copy and paste the following configuration

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

[Service]
Type=simple
User=%i
WorkingDirectory=/home/%i/.homeassistant
ExecStart=/srv/homeassistant/bin/hass -c "/home/%i/.homeassistant"
Restart=on-failure
RestartSec=5s

[Install]
WantedBy=multi-user.target

pi $ sudo systemctl daemon-reload
pi $ sudo systemctl enable homeassistant@homeassistant
pi $ sudo systemctl start homeassistant@homeassistant
pi $ sudo systemctl status homeassistant@homeassistant
-> verify that it is started

Updating Home Assistant Core

If you need to update Home Assistant Core, the following procedure will allow this. This is done from your default ‘pi’ user account. First, stop the Home Assistant service. Update Home Assistant, then start the service again.

pi $ sudo systemctl stop homeassistant@homeassistant
pi $ sudo -u homeassistant -H -s
homeassistant $ source /srv/homeassistant/bin/activate
(homeassistant) homeassistant $ pip3 install --upgrade homeassistant
(homeassistant) homeassistant $ exit
pi $ sudo systemctl start homeassistant@homeassistant

Updating homeassistant can lead to requirement changes regarding Python or the configuration file. Check the logs and solve problems as they occur.

If updating Python is required, delete /srv/homeassistant folder completely and start again from top. Configuration and database is stored under /home/homeassistant/.homeassistant/ and will not be deleted.

Future Topics

Here are some ideas that I’d like to expand this guide with in the future. These include:

  • Adding SSL certificate for HTTPS access (required, when authorization of a feature uses a callback)
  • Adding mDNS service for easier access to Raspberry Pi, i.e., http://smarthome.local:8123

The End

I hope you appreciated this extensive guide on how to get yourself started with Home Assistant Core. Feel free to buy me a coffee.