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.
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).
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 email@example.com -> 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 firstname.lastname@example.org 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 /email@example.com -> 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.
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
I hope you appreciated this extensive guide on how to get yourself started with Home Assistant Core. Feel free to buy me a coffee.