** How to Install Home Assistant on Orange Pi 5 and 5 Plus **
In a previous post I described how to configure TrueNAS for compatibility with Carbon Copy Cloner's
sparsedisk backup option. Several weeks later I found myself referring back to that post to troubleshoot an issue.
This guide similarly serves two purposes. It shows how to install Home Assistant and provides a reference for future troubleshooting needs.
I'm using the following components:
External References:
Orange Pi 5 supports installation on 3 different types of media, all of which are bootable:
- TF Card
- This is simply a micro-SD card
- Cheap to buy, but also slowest speed around 100 MB/s
- Less reliable in the long run compared with other two options
- eMMC
- Just a tiny bit larger than micro-SD, but snaps onto the motherboard
- Supports 400 MB/s transfer speed
- Orange Pi sells 32GB, 64GB, and 256GB versions
- I have the 256GB version
- NVMe SSD
- Orange Pi 5 Plus only supports full size 2280 NVMe SSDs, which also happen to be the most common
- Orange Pi 5 (not Plus) supports the smallest size 2230 form factor
- Both provide 4 lanes of PCIe 3.0
- NVMe SSD is fastest of the three options, but also generates considerably more heat
- It may not be suitable for use in a passively cooled chassis
Orange Pi boots from TF Card (micro-SD) by default. To boot from eMMC or NVMe SSD we need to follow a special procedure provided in the Wiki page:
I experimented with both eMMC and NVMe SSD. For my
passively cooled case (lovely single piece of aluminum), the best option turns out to be eMMC because it runs significantly cooler than NVMe SSD and provides more than sufficient disk I/O for Home Assistant.
Installation Procedure: Download and Install Operating System
Home Assistant can be installed in one of
four different ways:
- Home Assistant OS (HA OS)
- Single fully integrated disk image that includes both the operating system and Home Assistant
- Container
- Provides the benefits of containerization (quick hosting on various platforms; container backups; container recovery/failover; etc.)
- But the container does not include Add-Ons as we can see in the table below
- Core
- This is for Python aficionados who want maximum flexibility in setup
- Supervised
- This installs Home Assistant on a compatible operating system
- We install the O/S ourselves, and we can install any other applications that we like
I chose
Supervised because:
- Home Assistant does not provide an HA OS image for Orange Pi; they do provide an image for Raspberry Pi 4
- I have a Z-Wave network that requires an Add-On called Z-Wave JS UI
- I wanted to run my existing HomeSeer application on the same system at least until everything from that application is fully migrated to Home Assistant
Home Assistant is compatible only with Debian Linux. Orange Pi offers
official Debian images for:
- Bullseye -- Debian 11
- Do not use this for Home Assistant because package systemd-resolved has a conflict and will not get installed
- Bookworm -- Debian 12
- Use either the Desktop or Server version
- If you use Server version, be prepared to ssh into the Orange Pi from a different computer, but it is also possible to connect a local monitor, keyboard and mouse
- If you use the Desktop version, it will provide a complete GUI desktop for local monitor, keyboard and mouse; this version will consume slightly more compute resources
- I chose the Desktop version anyway
Our first step is to download
Debian 12 (Bookworm) and burn the image to either (a) micro SD, (b) eMMC, or (c) NVMe SSD. We can use
Balena Etcher for micro SD, but for eMMC and NVMe SSD I strongly recommend following the Orange Pi guidelines that make use of their own
RKDevTool_Release_v3.15:
RKDevTool will not only install the image, it will also resize partitions to fit the full size of the disk. The instructions above will also modify boot ROM to boot from either eMMC or NVMe SSD.
RKDevTool may or may not work on Windows 11, but it works well on Windows 10. I have simply installed Windows 10 on VMWare Fusion on my Z390 Designare running macOS Sonoma 14.2. Yes we can burn the image to eMMC or NVMe SSD by running Windows in a virtual machine on macOS!
Installation Procedure: Download and Install Home Assistant
Now that Debian 12 has been installed and booted, we can open a local window to determine the IP address of our Orange Pi. In a local terminal window, typing ip addr
will give us the information we need, but we'll have to look for it as shown:
Code:
ip addr
1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000
link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
inet 127.0.0.1/8 scope host lo
valid_lft forever preferred_lft forever
inet6 ::1/128 scope host
valid_lft forever preferred_lft forever
2: enP4p65s0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc mq state UP group default qlen 1000
link/ether ...
inet 192.168.1.122/24 brd 192.168.1.255 scope global dynamic noprefixroute enP4p65s0
valid_lft 85874sec preferred_lft 85874sec
inet6 ... scope global dynamic noprefixroute
valid_lft 1634sec preferred_lft 1634sec
inet6 ... scope link noprefixroute
valid_lft forever preferred_lft forever
3: enP3p49s0: <NO-CARRIER,BROADCAST,MULTICAST,UP> mtu 1500 qdisc mq state DOWN group default qlen 1000
link/ether ...
4: wlP2p33s0: <NO-CARRIER,BROADCAST,MULTICAST,UP> mtu 1500 qdisc mq state DOWN group default qlen 1000
link/ether ...
5: wlan1: <NO-CARRIER,BROADCAST,MULTICAST,UP> mtu 1500 qdisc mq state DOWN group default qlen 1000
link/ether ...
In
item 2 we can see the IP address is 192.168.1.122. Now we can continue using the local terminal window or remotely login to the Orange Pi via ssh. In this section I'll use remote
ssh from macOS running
Terminal so I can capture screenshots for this guide,
but you should use a local terminal. Connect a monitor, keyboard and mouse to your Orange Pi 5 or 5 Plus and perform these steps from a local terminal window.
In a Terminal window we open a secure-shell (ssh) to the Orange Pi and we're greeted as follows:
The standard login IDs for Orange Pi are:
- User account:
- Login: orangepi
- Pasword: orangepi
- Root (sudo) account:
- Login: root
- Password: orangepi
We can change passwords later, but we'll use default ones for now.
Installing Home Assistant is done by invoking a couple of scripts that will both (a) download the software and (b) install the software for us. But before we can invoke those scripts, we have a few prerequisites to take care of.
Update the OS
We start by making sure we have the latest patches and other O/S updates by running these commands:
Code:
sudo apt update
...wait for update to finish...
sudo apt upgrade
... wait for upgrade to finish...
Now we'll create a new user account for Home Assistant with the adduser YOURUSERNAME
command. Choose a user name. In the example below I chose "casey". Enter a password for this user when asked.
Code:
sudo adduser casey
... this will appear as output ...
Adding user `casey' ...
Adding new group `casey' (1001) ...
Adding new user `casey' (1001) with group `casey' ...
Creating home directory `/home/casey' ...
Copying files from `/etc/skel' ...
New password:
Retype new password:
Then provide the following information when asked (optional):
Code:
passwd: password updated successfully
Changing the user information for casey
Enter the new value, or press ENTER for the default
Full Name []: Casey SJ
Room Number []:
Work Phone []:
Home Phone []:
Other []:
Is the information correct? [Y/n] Y
Now we'll add our new user to the sudo group so we have elevated system privileges (replace 'casey' with your own user name':
Code:
sudo usermod -aG sudo casey
Next, we'll install necessary packages as follows:
Code:
switch to sudo shell
sudo -i
# install dependencies
apt install apparmor jq wget curl udisks2 libglib2.0-bin network-manager dbus lsb-release systemd-journal-remote systemd-resolved -y
... wait for installation to finish ...
... select OK if you see a warning about systemd replacement ...
Do
not install Docker because it is already installed in the Orange Pi Debian image!
Now we need to make some changes to the Orange Pi boot environment. It's quite simple, as follows:
Code:
# Type this command:
orangepi-config
... if you see an error or warning message, press Enter (not CTRL-C) to continue ...
This will open the config menu as follows...
Step 1: Press
Enter to select "System and security settings"
Step 2: Press
down arrow to select "Edit boot environment" then press
Enter
Step 3: Use arrow keys to move cursor to the
last row and
just past the last character on that row so that a new line can be added by pressing Enter
Step 4: Press
Enter to add a new line:
Step 5: Copy and paste this into the new line, then press
Tab to select "Save" at the bottom of the dialog, and press
Enter
extraargs=apparmor=1 security=apparmor systemd.unified_cgroup_hierarchy=0
Finally, select
BACK and
EXIT from the screens that appear:
Now we need to reboot by issuing the reboot command:
When the system restarts, log back via local terminal or
ssh as your new username (which was 'casey' in my case), and let's verify
apparmor and
cgroups as follows:
Do you see
active (exited)
as shown:
Now we'll verify cgroups:
Code:
findmnt -lo source,target,fstype,options -t cgroup,cgroup2
Do you see a bunch of lines like this:
If everything looks good and you've made it this far, the process is nearly over!!
Now we switch back to
sudo
and finish up the process:
Code:
sudo -i
... type your user password when asked (which is the password for your new user name) ...
... then type these commands ...
cd /usr/local/src
wget https://github.com/home-assistant/os-agent/releases/download/1.6.0/os-agent_1.6.0_linux_aarch64.deb
dpkg -i os-agent_1.6.0_linux_aarch64.deb
... so far so good? then continue below ...
wget https://github.com/home-assistant/supervised-installer/releases/latest/download/homeassistant-supervised.deb
dpkg -i homeassistant-supervised.deb
Important: You will likely be asked to choose a processor architecture from a pop-up window. Choose
qemuarm-64
Congratulations!
Home Assistant operates on port 8123 by default so we can open a web browser as follows:
In my case the IP address is 192.168.1.122 so I'll type:
We can also try mDNS names:
Home Assistant will take a few minutes to get set up. And then you'll see the welcome screen:
It is a good idea to
reboot the computer when you see the 2nd screenshot above ("Welcome!"). Home Assistant will restart automatically each time. Then continue with Home Assistant setup.
Removing Home Assistant (uninstall)
To remove Home Assistant, run these commands:
Code:
sudo -i
systemctl stop hassio-supervisor.service
systemctl stop hassio-apparmor.service
systemctl disable hassio-supervisor.service
systemctl disable hassio-apparmor.service
rm -rf /usr/sbin/hassio-supervisor
rm -rf /usr/sbin/hassio-apparmor
apt remove homeassistant-supervised