Install Home Assistant Core on Orange Pi Zero 3 (part two)

How to install Home Assistant as a Python software on Debian/Ubuntu based hosts running on small single board computers such as Orange Pi Zero 3

Some time ago I decided to get Home Assistant (HASS) running on a single board computer (SBC) without knowing too much about this software. As I soon found, Home Assistant is complex software and there are multiple installation methods, more or less available depending on target hardware. In short, I got an Orange Pi Zero 3 SBC with 2 GB of RAM which I intend to use as a local home automation server.

Although the SBC has sufficient processing power for Home Assistant, I shouldn't expect too much from the limited SD card storage. I decided to give it a try anyway since I really like the small form factor of Orange Pi Zero 3 (it can directly replace the old Pi Zero with only 256 MB of RAM I am currently using for hosting a local MQTT broker). Although this guide is targeted at this specific SBC, it is very probable that you can install HASS on similar Linux platforms using the same commands.

Installation methods

Home Assistant is a complex software ecosystem which is available either as an operating system, container or standalone software. You must decide in advance which installation method you want because the operating system you will install on Orange Pi depends on this choice.

The Core installation method is referring to standalone mode, where HASS is installed as Python program. It is easier to install, however you will usually get delayed updates via pip3 package manager. It depends on the system-wide Python and sometimes you will get warning messages about using an older version of Python which is no longer supported by HASS.

Prerequisites

Installing HASS as a Python program requires installing some prerequisites and creating a virtual environment. Just as with any Linux, we start with a system update followed by installation of required packages:

sudo apt update && sudo apt upgrade
sudo apt install -y python3 python3-pip python3-dev python3-venv \
libffi-dev libssl-dev libjpeg-dev zlib1g-dev autoconf build-essential \
libopenjp2-7 libtiff5 libturbojpeg0-dev tzdata

After the installation completes, check Python version with:

python3 --version

Remember the version. The next step is to configure pip3 repositories. This step is recommended by Orange Pi manual, claiming that the default repository has slow download speeds.

mkdir -p ~/.pip
nano ~/.pip/pip.conf

Paste the following contents:

[global]
timeout = 6000
index-url = https://pypi.tuna.tsinghua.edu.cn/simple
trusted-host = pypi.tuna.tsinghua.edu.cn

Press Ctrl+X, then Y and Enter to save the file.

Install Home Assistant

First of all power the SBC and connect to it via SSH (use PuTTY or the included SSH client and adjust the IP address):

ssh orangepi@192.168.1.11

A Python virtual environment is a self-contained directory with its own installation of Python interpreter and its own set of libraries/packages. This allows you to create isolated environments for different projects, preventing conflicts between cross dependencies. It essentially provides a sandboxed space where you can install and manage specific versions of Python packages without affecting the system-wide Python installation.

Let's create the virtual environment for HASS in /srv/homeassistant folder (paste each row at a time):

sudo mkdir /srv/homeassistant
sudo chown orangepi:orangepi /srv/homeassistant
cd /srv/homeassistant
python3.10 -m venv .
source bin/activate

The fourth command must be adjusted depending on Python version you have installed (you should have checked this earlier). We are now in the virtual environment and we can install HASS with (one command at a time):

python3 -m pip install wheel
pip3 install homeassistant

This will take longer. After it is done, you must run HASS while you are in the virtual environment.

hass

The first run will also take some time and it is needed to create some configuration files. Wait a few minutes (maybe even check if HASS can be accessed from the network) then kill the process with Ctrl+C. If somehow you exited the virtual environment, here is how you get back:

cd /srv/homeassistant
source bin/activate

Auto start on boot

It is not practical to enter the virtual environment and run it after each boot. Let's automate this. Ubuntu Jammy (which is what you should have running on Pi Zero 3) and modern Linux distributions commonly use systemd. We'll have to create a configuration file:

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

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

[Install]
WantedBy=multi-user.target

Note that this file is suitable for the paths I used throughout this guide. Adjust working directory and executable path if needed. Assuming you are in the command line over SSH, this is how you create the file. It has to have a specific name (orangepi in the command below must be replaced with the name of the account on which HASS will run; by default it is orangepi):

sudo nano /etc/systemd/system/home-assistant@orangepi.service

Paste the above contents inside nano editor. Then press Ctrl+X, Y followed by Enter to save. Reload and enable service with:

sudo systemctl --system daemon-reload
sudo systemctl enable home-assistant@orangepi

You can also run it now if you want and check the log:

sudo systemctl start home-assistant@orangepi
sudo journalctl -f -u home-assistant@orangepi

Feel free to restart the SBC and check if HASS starts on boot. It can be accessed from local network by entering the IP address of Orange Pi and port 8123 in a browser. It will take some time while the first user account is created.

What you need to know

Core installation method allows you to run HASS as a standalone Python program on supported Linux. Although it runs directly on the host system, there are some drawbacks.

Python version is deprecated in Home Assistant

Keep in mind that even a fresh install of HASS may throw some warnings because Python is not as frequently updated as it should on the operating system you run HASS on (at least this is true for Orange Pi Zero 3). This will prevent you from updating to a newer version of HASS.

How do you open a command line inside the virtual environment? Simply run the activate script:

cd /srv/homeassistant
source bin/activate

To update the system you must run multiple commands, for system-wide update and for pip3 packages. Here are the commands:

sudo apt update && sudo apt upgrade -y
source /srv/homeassistant/bin/activate
pip3 freeze > requirements.txt
pip3 install -r requirements.txt --upgrade

If you're looking for HASS configuration files, those are in the user folder (i.e. /home/orangepi/.homeassistant). Here is the configuration.yaml file. If migrating to a different platform, this folder should be backed up and restored.

Conclusion

The Core installation method will get Home Assistant running as Python software, directly on the host operating system (even if in a virtual environment, it is not actually a containerized installation). HASS will usually have access to hardware (USB, WiFi, Bluetooth) without requiring additional rights.  However any add-on that you want requires manual configuration and has its own installation method (there is no add-ons store). The other major drawback is the delayed update of some dependencies which will also prevent HASS from updating.

More on this subject:

• Part 1: Getting the Orange Pi Zero 3 board ready for Home Assistant.
• Part 3: Install Container version of Home Assistant (work in progress).

References

1. Orange Pi Zero 3 User Manual v1.3.
2. Autostart using systemd - Home Assistant Community Guidelines.