Install Home Assistant on Raspberry Pi 3B+

1/08/2022 I installed Home Assistant. This pictured compact unit is the entire hardware.

Home Assistant is a flexible, open source, home automation server. You can run it on a Raspberry Pi, but it is tricky enough to get going that I wrote this step by step guide.

A 3D printed case, a Raspberry Pi 3B+, a Sonoff Zigbee 3 dongle, and a 5v power wall wart.

I went with that Pi 3B+ because:

• I didn’t need something more expensive that would run hotter. No heat sink on it, and still the case over the CPU is cool to the touch.

• It was already in the house, unused.

• The full-sized USB ports made set up easy without attaching a keyboard and monitor.

• Home Assistant recommends either a Raspberry Pi 3 or 4 - installation is easier than with something else.

• I was able to install Home Assistant Core on Raspberry Pi Zero W, but I could not get the add-on for the Zigbee dongle to install, and the additional cabling and adapters to cope with the Zero W looked ugly.

• Because Home Assistant directly supports both the Raspberry Pi 3B+ and the Raspberry Pi 4 and 400, these same instructions will work for that hardware too.

• Although this actual installation was easy, I failed at least 5 times before. I’m writing this in the hopes of sparing you some pain.

• 3D printed case

• Raspberry Pi 3B+ $35 + shipping.

• Sonoff Zigbee 3 dongle $11 + $8 shipping

• 5v power wall wart $8 + shipping

• µSD Card (I used a 64GB µSD card $22 for 3)

(U.S. prices)

A Raspberry Pi 4 $45 + shipping should work, although you may need a different case.

A 16GB or 32GB µSD card should also work.

It’s nice to have more than one µSD to backup the Raspberry Pi’s storage.

The USB extension cord is not really needed. I just wanted to have the Zigbee dongle connected when Home Assistant first boots up.

Hardware Tools:

• A desktop computer (I used a Mac)
• 2 adapters to connect it to µSD Cards (second adapter for cloning a working µSD card for backup.)

Software Tools:

free downloads:

• Imager from raspberrypi.com/software/
• Balena Etcher from balena.io/etcher/ for backing up a working µSD card.

I used gray PLA, no support needed.

Reference: Raspberry Pi 3b+ (3b plus) sleeve cover one-piece by icefox1983 July 04, 2018

This is what tells Home Assistant to use your home WiFi. 

This is how you can do the install without a wired ethernet connection.

Format the thumb drive as MS-DOS FAT. Name it CONFIG

In that drive, create a directory named network. Inside that use a plain text editor to create a file named my-network (no extension) with contents:

[connection]
id=my-network
uuid=72111c67-4a5d-4d5c-925e-f8ee26efb3c3
type=802-11-wireless

[802-11-wireless]
mode=infrastructure
ssid="<Your Wifi Name Here>"
# Uncomment below if your SSID is not broadcasted
#hidden=true

[802-11-wireless-security]
auth-alg=open
key-mgmt=wpa-psk
psk="<Your Wifi Password Here>"

[ipv4]
method=auto

[ipv6]
addr-gen-mode=stable-privacy
method=auto

Fill in <Your Wifi Name Here> and <Your Wifi Password Here>.

If you are on Windows, remember to save the file with Unix style line separators.

If you are on Mac, double check that it really has no extension, not just a hidden .txt extension.

Reference: Raspberry Pi Headless Setup by thatiotguy Published July 11, 2020

Using Imager, and the µSD card in your desktop computer, 

• Use Imager’s poorly documented ⌘⇧X menu to set the host name, username, and wifi credentials
• click CHOOSE OS > Other Specific Purpose OS > Home Assistant (then pick the version appropriate for your Raspberry Pi: 3, 4 or 400).
• click STORAGE and select the µSD card.
• click WRITE

On my Mac, the resulting drive was a format the Mac didn’t recognize, so it put up an alert The disk you attached was not readable by this computer. with Eject / Ignore / Initialize. I choose Ignore.

Reference: Home Assistant is now an option in the official Raspberry Pi installer!

linked from: Reddit comments

This method installs the same operating system as the official Home Assistant directions using Balena Etcher, but this way there are fewer steps, and it doesn’t require you to be logged in on the Mac on an administrator account as lng as you know an administrator account name and password.

References: Home Assistant Raspberry Pi

The Zigbee dongle blocks the USB ports, so connect it using the USB extension cord to the USB socket it will be directly connected to later. I use the lower socket closest to the ethernet connection.

Attach the thumb drive to one of the other USB sockets on the Pi.

Insert the µSD card in the Pi (underneath the Pi).

Apply power using the wall wart.

Wait about 3 minutes.

On the computer, in the command line (i.e., using Terminal on Mac) type:

ping homeassistant.local

followed by <Return>. ( <Control>C to quit ping).

You should see something like:

PING homeassistant.local (192.168.4.52): 56 data bytes
64 bytes from 192.168.4.52: icmp_seq=0 ttl=64 time=7.068 ms
64 bytes from 192.168.4.52: icmp_seq=1 ttl=64 time=14.552 ms
64 bytes from 192.168.4.52: icmp_seq=2 ttl=64 time=18.378 ms
…

This means:

• The Pi is alive
• It has connected to your WiFi
• It has started the Bonjour server to register the name ‘homeassistant.local’ on your local WiFi network.

Now, in a web browser you can go to http://homeassistant.local:8123 and you should see the blue-framed preparing screen.

This means:

• Docker is running
• Home Assistant Supervisor is running

You can click on the central pulsing blue dot to see an extended log of how far it has gotten.

• Wait 20 minutes. (I only needed to wait 5 minutes).
• Refresh the page. It should redirect to http://homeassistant.local:8123/onboarding.html
• Follow the official directions to get through this page to the next one, on to device configuration.
• Do not configure any devices on the initial configuration screen. Just click the Finish button on the lower right. This is because, as I write this, Home Assistant incorrectly identifies some of the devices, so it is better to ignore its suggestions for now, and configure your devices manually later.
• At this point, you can connect to Home Assistant either through a web browser at  http://homeassistant.local:8123 or by using the iOS or Android Home Assistant mobile app.

in Short:

• Click on Configuration > Devices & Services > + Add Integration > scroll to Zigbee Home Automation and configure it.
• Click on <Your Name> (in bottom left) > scroll to Advanced Mode and turn it on.
• Click on Configuration > People & Zones > + Add Person and add additional people who will be using the Home Assistant user interface.
• Click on Configuration > Add Ons, Backups & Supervisor > + Add-on Store and add, one at a time:
• Check Home Assistant configuration
• File Editor
• SSH & Web Terminal (You must be in Advanced Mode to see it)
• Click on Configuration > Add Ons, Backups & Supervisor > Backups > + Create Backup and give it a name.

Reference: https://www.home-assistant.io/getting-started/onboarding/

The following steps cover this step in more detail.

ZHA (Zigbee Home Assistant) is how Home Assistant controls the zigbee dongle.

In the Home Assistant user interface, click on the Configuration link on the lower left.

Click on Devices & Services

Click on + ADD INTEGRATION on the lower right of the window.

Scroll down and click on Zigbee Home Automation.

In the resulting alert, select the port that your zigbee device is connected to and click it submit dialog.

Click on your name, at the bottom of the right column.

Scroll down and click to turn the Advanced Mode on/off control to on.

Click on the Configuration item in the left column, then click on People and Zones.

Click the + ADD PERSONS button on the lower right and set up accounts for additional people who will be using Home Assistant.

Click on the Configuration item in the left column, then click on Add-ons, Backups, & Supervisor

click the + ADD-ON STORE button to see the catalog of add ons. You should add 3 add-ons:

• Check Home Assistant configuration
• File Editor
• SSH & Web Terminal (You must be in Advanced Mode to see this add on)

Once you have SSH & Web Terminal you must configure it to use it. With it selected, tap on configure in the upper right, and enter the username and password that will be using SSH. Then save that.

Click on the Configuration item in the left column, then click on Add-ons, Backups, & Supervisor.

This time click on Backups, near the top of the window.

Clock on + CREATE BACKUP on the lower right, and give your backup a simple name, like today's date.

Click on the Configuration item in the left column, then click on Add-ons, Backups, & Supervisor.

This time click on Supervisor, near the top of the window.

Click on SHUTDOWN HOST

Wait 3 minutes, then unplug power from the Raspberry Pi.

Now you can remove the USB thumb drive and the USB extension cable from the Pi and connect the Zigbee dongle directly to the Pi.

Now you can remove the µSD card from the Pi, put it in your adapter, in your computer, and use Balena Engraver to select it as source.

Once you’ve done that, insert the second µSD card and in Balena Engraver select it as the destination and

in Balena Engraver copy the card.

Insert the copy in the Pi.

Apply power.

Wait about 3 minutes.

You should be able to connect from a browser using http://homeassistant.local:8123

You should be able to connect from Terminal with:

ssh yourName@homeassistant.local

and you should see something like:

| |  | |                          /\           (_)   | |            | |  
| |__| | ___  _ __ ___   ___     /  \   ___ ___ _ ___| |_ __ _ _ __ | |_ 
|  __  |/ _ \| '_ \ _ \ / _ \   / /\ \ / __/ __| / __| __/ _\ | '_ \| __|
| |  | | (_) | | | | | |  __/  / ____ \\__ \__ \ \__ \ || (_| | | | | |_ 
|_|  |_|\___/|_| |_| |_|\___| /_/    \_\___/___/_|___/\__\__,_|_| |_|\__|

Welcome to the Home Assistant command line.

System information
  IPv4 addresses for eth0:  
  IPv4 addresses for wlan0: 192.168.4.52/22
  IPv6 addresses for wlan0: fe80::1235:1274:1234:12fe/64

  OS Version:               Home Assistant OS 7.1
  Home Assistant Core:      2021.12.8

  Home Assistant URL:       http://homeassistant.local:8123
  Observer URL:             http://homeassistant.local:4357

➜  ~

Here, you can use the Linux command ls /root/backup on the pi to get the actual names of the backups. Then, in another Terminal window you can say something like:

scp yourName@homeassistant.local:/root/backup/23313970.tar raspberrypi/backups

to copy a Home Assistant backup file to your computer.

In my case this full backup was a 164KB file.

Using the backup:

When it came time to actually move a backup from the computer to the pi to use it, I first had to make the directory writeable by all, then scp the backup from the computer, then restore the original directory permissions:

ssh to the Pi:

sudo chmod 777 /backup

scp 23313970.tar yourName@homeassistant.local:/backup

ssh to the Pi:

sudo chmod 755 /backup

Before I order a house full of Zigbee wall switches I tested this whole setup with a string of Giderwel Zigbee LEDs $26. Once I had the above Home Assistant environment set up I plugged the LEDs in for the first time. Home Assistant and the Zigbee dongle recognized them and took control of them, putting a nice little control panel for them on the Home Assistant Overview page.

And after my multiple reboots and reinstalls, Home Assistant continued to be able to recognize and control the LEDs.

Home assistant also found a Harmony Hub, a Roomba, and a Samsung TV on the local WiFi, an offered to let me configure them.

• Should I care which version of the firmware the Zigbee dongle has?
• Should I learn how to update the firmware on the Zigbee dongle?
• What important things do I not know?

Remember at the start of this page I said I'd failed to install Home Assistant multiple times before?

I started by installing Home Assistant Core on a Raspberry Pi Zero W with a USB hub attached to a keyboard and mouse. And it worked, but I couldn't figure out how to install the ZHA add-on to control the Zigbee dongle.

I tried doing a default Raspberry Pi install using Imager, and using the poorly documented ⌘⇧X menu to set the host name, username, and wifi credentials. That works for a default install, but did not seem to work for a Home Assistant install. And the resulting µSD card would boot and run, but I couldn't figure out how to install Docker to then install the appropriate Home Assistant Docker Container.

Once, I tried all of the steps I’m recommending, but had the Pi hang at the Preparing stage and never progress to the Onboarding step. I just gave up for the day and tried the same steps again from the beginning the next day and it worked.

Since my home automation system is important to me, I’ve order another Pi, Zigbee dongle, and µSD card. That way if the hardware fails I won’t be stuck with nothing working. And in the future I won’t be stuck needing hardware that is no longer sold.

The Home Assistant Operating System that this procedure has installed on my Raspberry Pi lacks a C compiler or a Python interpreter. Since it has plenty of disk space and CPU capacity I should probably fix that.

Congratulations on reading this this far. Now you can go back an additional devices that Home Assistant has discovered on WiFi or on through your ZigBee.