Set up Home Assistant on Orange Pi Zero 3 (part one)

Install Ubuntu on Orange Pi Zero 3 and prepare it for home automation with MQTT and Home Assistant

The Orange Pi Zero 3 is a powerful Single Board Computer (SBC) that can serve as the heart of your home automation system. With its compact size, low power consumption, and ample processing power, it's an ideal choice for DIY enthusiasts looking to automate their homes. In this guide, we'll walk you through the steps to set up and use the Orange Pi Zero 3 for home automation. I have previously used a less capable SBC and even an old router to run a self hosted MQTT server. It is time for an upgrade.

The main point of this upgrade is to add functionality beyond MQTT, such as database storage, reports and Home Assistant. I really want the latter since I have some ESP8266 relays and sensors I currently use and I think ESPHome could speed up software development while being easy to integrate with Home Assistant. Note that you may use another SBC from the OrangePi family for this purpose. I chose Zero 3 because it is powerful enough while being similar in size with the existing Zero I currently use.

Getting started

When you unbox your Orange Pi Zero 3, you will find the SBC board itself in an antistatic bag, with no accessories whatsoever (unless you ordered). I chose the 2 GB version of the board since I consider it enough for my needs. You will also need: 

1. MicroSD card (high speed 16GB or larger recommended; SBC manufacturer recommends SanDisk);
2. Power adapter (5V and at least 3A; if considering USB peripherals, get one with enough current);
3. USB to serial adapter, with 3.3 V levels. I will use the cheapest available based on CH340G;
4. Keyboard and mouse (may be temporarily needed, until you configure SSH);
5. HDMI cable and monitor (may be temporarily needed, until you configure SSH and/or remote access);
6. Internet connection (Ethernet is preferred).

Consider building a 5V UPS which can store enough energy to prevent sudden shutdowns of the SBC. Explore the possibility of powering your Orange Pi Zero 3 with solar panels for energy-efficient operation.

Power failures may damage the file system and require starting all over again with installation and configuration. Also, after you're done setting it up, turn off, pull out the MicroSD card and make a backup of the entire file system.

Orange Pi Zero 3 SBC with required accessories

It is recommended to place a self-adhesive heatsink on the Allwinner CPU. It tends to get quite hot. I also prepared a distribution box where I installed the SBC along with power supply and some other hardware (LAN switch and cable TV amplifier with splitter). An enclosure is highly recommended because it prevents dust getting on the SBC, however make sure of proper ventilation (add a cooling fan) to help spread the heat produced by electronics.

Installing the operating system

Because I regularly use Ubuntu desktop and I am familiar with it, I chose it for my SBC. Being more popular means you will have access to updated and more software packages. I don't need desktop environment, therefore I will get the server version. This is the download page for Zero 3 SBC. I selected Ubuntu image, Linux 6.1 kernel version for development boards with 1 or 2 GB RAM, Jammy Server.

The easiest way to get this on the SD card is to use Etcher (on Windows or on Linux PC). Plug the microSD in a suitable adapter. Download and extract the OS image from archive (7-Zip is required). Etcher software is available for all desktop platforms and it is portable (for Linux it comes as an AppImage which you can run). User interface is very clean and straightforward. First you select source image, then the target storage. This is the step when you have to ba careful what you select. I recommend unplugging any other external storage device to avoid confusion. Etcher will not show by default your system drive. After you have selected target storage, just click on Flash! and it will start. At the beginning it needs your user password to format the SD card. It then writes the image and it also verifies it.

Etcher is ready to write Ubuntu image to SD card

When it is done, close it and unmount the SD card if it got automatically mounted by the host operating system. Pull it out from the card reader and insert it in the dedicated slot of Orange Pi board. It is time to power it.

But not so fast! First of all, you need to set up the serial terminal which will allow you to perform the initial configuration. I like to use PuTTY because it is free and works on Windows and Linux. You can get it on Ubuntu after enabling Universe repository with the following commands:

sudo add-apt-repository universe
sudo apt update
sudo apt install putty

Now take the USB to serial adapter and three dupont wires and connect everything as follows:

• On the opposite edge of micro HDMI connector, there is a 3-pin header named SIP3, with pins labelled TX, RX and GND. TX goes to RXD/RXI of the USB-serial adapter, RX goes to TXD/TXO and GND to GND. Plug the adapter in an USB extension cord and connect to computer.
• Insert microSD card if you haven't done so already.
• If you're going to make this into a server, go ahead and get a LAN cable from your local network. I do not recommend using WiFi and I will even disable it and remove the antenna.
• Launch PuTTY, select Serial mode, 115200 baud and enter correct port. How do you find it? Well, if on Windows open Device Manager and unplug then re-plug the USB serial adapter to see which COM port appears. If on Linux open a terminal and use ls /dev/tty* or to be more specific ls /dev/ttyUSB*. Repeat the command with the adapter plugged in, then unplugged. Write the port with complete path in PuTTY (i.e. /dev/ttyUSB0).
• Get the power supply ready and power the board.

Wait patiently for the first boot to complete. It is going to take a while; however you should see output in PuTTY. If you don't see any output in PuTTY while the board LED is flashing, check again the port you selected and try swapping RX and TX dupont wires.

First boot of Orange Pi with Ubuntu Jammy

Note that since this is the server version of Ubuntu it does not have a display manager, hence the low RAM usage. If you're curious or you can't get the serial terminal working, use HDMI to connect to a monitor and plug in an USB keyboard. You will see another terminal output on monitor.

While Orange Pi is booting or already running avoid cutting power to it. Instead use sudo reboot (or sudo poweroff).

Basic configuration

The default installation comes with two user accounts, a regular account named orangepi and the root account, which have the same password: orangepi. Let's configure network with:

sudo orangepi-config

Enter password as requested after this command. After the utility launches, use arrow keys and Enter to select Network. Go to WiFi and select Deactivate, then Quit. Then go to IP and select Static, since this server has to have the same IP so you can access it over network. You need to choose an available IP address and set netmask and gateway. Make sure you select an IP address that is outside of the allowable range of the addresses which can be assigned to local clients by your router (for example, my router's DHCP server is set to assign addresses 192.168.1.100 to 192.168.1.255 to clients, therefore everything from 192.168.1.2 to 192.168.1.99 is left for static assignments of my choice). Gateway is router's IP (in my case 192.168.1.1).

Setting static IP on Orange Pi

Press Tab key after you have completed all fields, then Enter on OK to confirm. At this point you can quit PuTTY and disconnect serial adapter; you can get to the terminal over SSH at the IP you set, with PuTTY using the same credentials. However, there is no need to hurry. Let's continue configuration over the existing terminal.

Please note that the manual of Orange Pi recommends a different way of setting network configuration. It is easy and intuitive, however its main advantage is that it allows you to set more parameters, including DNS servers and IPv6 configuration. If you need advanced network interfaces configuration, use the following command:

sudo nmtui

Next, while I am in orangepi-config, I usually go to Personal section to set local timezone and I also customize Hostname (which can also be set from nmtui). If you want some services to be automatically discovered in the network, you should enable Avahi from System section. Once you are done with the configuration utility, let's close it (choose Back and Exit) and move on.

Let's update the installed software packages:

sudo apt update
sudo apt upgrade

If it says it has to modify some configuration files, you can type Y (from yes) and hit Enter to confirm. After it is done, perform a reboot. And this time disconnect the serial dupont wires. We're switching to SSH. After reboot, if there are more updates, install them using the same commands. Use PuTTY or any other SSH client to connect to the IP address of the Orange Pi. For example, I would use in Ubuntu Terminal:

ssh orangepi@192.168.1.11

Then I have to confirm I want to connect (with yes) and enter user password (which is still orangepi).

The MQTT broker

Although I will install Home Assistant, I do want to have a running MQTT server for backwards compatibility with the devices I previously built. And I want to keep the existing configuration. Skip this part if you don't have a previously configured local MQTT broker. Or follow my older posts about installing MQTT on Orange Pi.

First of all, let's install mosquitto packages:

sudo apt update
sudo apt install mosquitto mosquitto-clients

I already have an MQTT server running on an older Orange Pi. To get files from it, the easiest way is to connect over SFTP. This can be done with FileZilla (on Windows or Ubuntu) or with the File Manager (on Ubuntu). In both cases, you have to enter at least the protocol and IP address of the Orange Pi. For example:

sftp://192.168.1.11
sftp://orangepi@192.168.1.11

You can also add user in address, as I did with SSH earlier. Note that Orange Pi may also be automatically discovered in the network and in this situation, all you have to do is double click on it. See below that my newly installed opihass is detected, but the old one is not, so I have to enter its IP to connect.

Connect to Orange Pi over SFTP

When you click Connect, username and password or password only (if username provided in address) will be requested. Once it gets connected, user folder is opened (IP/home/orangepi). You must navigate to /etc/mosquitto. It has a specific structure which you will recognize:

Mosquitto configuration folder structure 

Select all items in this folder and copy them to a folder of your choice on the host machine. As an optional cleanup task, here it is safe to delete all README files inside subfolders and the base mosquitto.conf file (the actual user created configuration is in conf.d folder).

Next, SFTP connect to the new Orange Pi, the one that needs this configuration. It would be easy if you could just copy back the files and folders to /etc/mosquitto. But this is not possible as a regular user. Make a folder in user's home and place everything there. Like this:

Existing configuration folders copied on the new Orange Pi

You can disconnect from SFTP (close the File Manager). Move to SSH command line. You can check the contents of home folder with ls, if you want to. Here is the command to copy-merge the two folders:

sudo cp -rfv ~/mqtt_conf/* /etc/mosquitto

Adapt the home folder path if you use a different name. This should be the output:

Restoring mosquitto configuration on new device

After this, perform a restart of mosquitto service:

sudo systemctl restart mosquitto

This should get the server running with the existing configuration.

Conclusion

Well, this was the first part and after this long how-to I didn't even get to Home Assistant. But I have the Orange Pi ready to replace the existing MQTT server.

There are also some other steps to consider. The most important one is to change the default password. To do this, use passwd command. I opted for a different IP address for the new Orange Pi. However, if you are in this situation, you might consider discarding the old board and using its IP for the new one.

In the second part I will actually install and do some basic stuff with Home Assistant.