Setting up Home Assistant OS on the Raspberry Pi

In this tutorial for the Raspberry Pi, we will show you how to install and set up the popular automation tool Home Assistant.

Home Assistant is an open-source home automation software with devices like the Raspberry Pi in mind.

The software is designed to protect your privacy and keep control in the user’s hand.

Using Home Assistant, you can track the state of all the devices in your home. You can even set up an automation to interact with them.

For example, you can set it so that the Home Assistant will automatically turn on all your lights when it gets dark and while you’re at home. You can even set it up to dim the lights in your living room when you cast a movie on your Chromecast.

Thanks to the great community, the Home Assistant software can successfully integrate with a wide range of devices, including Phillips Hue and Ring.

The Raspberry Pi is a great device for running your home automation. It is small, affordable, packs a ton of connectivity features, and uses a relatively small amount of power.

If you want to continue to use your Raspberry Pi for other functions instead of just Home Assistant, you can always use the Docker container. However, there are some drawbacks of using Docker to run Home Assistant.

Equipment List

Here is a list of the equipment we recommend for setting up Home Assistant on the Raspberry Pi.

Optional

Raspberry Pi Case ( Amazon )

We tested this tutorial on setting up Home Assistant on a Raspberry Pi 4 running the latest version of the Home Assistant software.

Installing Home Assistant OS onto your Raspberry Pi

This section will show you two different ways to install Home Assistant OS on your Raspberry Pi. We use HassOS instead of manually installing Home Assistant, as everything is configured correctly for the best and most stable experience.

The first is to use the Raspberry Pi imager to handle the whole process for you. This is the best as you can install the OS to your SD card in just a few short clicks.

The other method we are covering involves going to the Home Assistant OS GitHub, downloading the latest release of the operating system, and then flashing that image using Balena.

Using Raspberry Pi Imager to Install Home Assistant

1. The first thing you must do is download and install the Raspberry Pi Imager on to your machine. Luckily, the Imager supports basically all operating systems.

You can download the imager directly from the Raspberry Pi’s website.

https://www.raspberrypi.com/software/

2. With the Raspberry Pi Imager now open, you will want to click the “CHOOSE DEVICE” button.

Clicking this button will bring up a list of the different Raspberry Pis. Select the Pi that you intend to install Home Assistant on.

3. With your Pi now selected, click the “Choose OS” button.

4. Within this menu, select the “Other specific-purpose OS” option.

5. You should now see a list of a few operating systems, but the option you want to select is the “Home assistants and home automation” option.

Select Raspberry Pi Home Assistants Menu

6. At the bottom of this list, you should see an option labeled “Home Assistant“. Click this option to continue to a list of versions of Home Assistant OS that you can install to your chosen Raspberry Pi.

Select Home Assistant for Raspberry Pi Category

7. Since we selected the Raspberry Pi 5 earlier on in this section, we should now see the correct version of Home Assistant OS that we can install.

Select the version of Home Assistant specified here to continue.

Choose Home Assistant Version to Install to Raspberry Pi

8. The last task we need to do is click the “CHOOSE STORAGE” button and select the SD card or drive that we want to write the Home Assistant operating system to.

9. To begin the image writing process, you will want to click the “Next” button.

10. You will now see a warning that the Raspberry Pi Imager will overwrite all existing data on your chosen storage device to install Home Assistant.

To continue with this process, click the “YES” button.

11. At this point, you have successfully installed Home Assistant OS on your Raspberry Pi.

If you need Wi-Fi, go to the setting up Wi-Fi on Home Assistant section. Otherwise, you can skip to our first boot section.

Manually Downloading and installing Home Assistant OS for the PI

Those who prefer not to rely on the Raspberry Pi Imager can still install Home Assistant OS manually.

We will download the official HassOS image for this section and then write it to an SD Card using Etcher.

Where to Download the Latest Release of Home Assistant OS

1. Before we get started, we must download the version of HASS that we need for our device.

In our case, this decision is based on the version of the Raspberry Pi you are using. The Home Assistant team recommends using any Pi newer than the 3. You will want to use the latest Pi for the best performance.

At the time of publishing, the latest version of the Raspberry Pi Home Assistant officially supports the Raspberry Pi 5.

To download Home Assistant, we need to go to the latest release page on the Home Assistant GitHub page.

https://github.com/home-assistant/operating-system/releases/latest

2. On this page, you will see a list of available downloads.

Find the file for the version of the Raspberry Pi that you are using and click it to begin downloading the file. The filename should end in .img.gz.

Raspberry Pi Home Assistant GitHub Download Page

Writing Home Assistant OS to your SD Card

3. Once you have downloaded the Home Assistant OS image, we can proceed with writing it to an SD Card. For this section, we will be making use of the image writing software called Etcher.

Etcher is a simple tool that is available on both Windows and macOS.

You can download Etcher from Balena’s website.

4. With Etcher open, you need to select the Home Assistant image you downloaded in the previous section.

Do this by clicking the “Select Image” button and using the file browser that pops up.

5. In this next step, you need to select the SD card you want to write the image to.

To do this, you need to click the “Select Target” button.

If you only have one drive that’s writeable to, Etcher will automatically select it as the target.

6. Once you are certain you have selected the correct drive to write to, click the “Flash!” button.

7. If you want to set up your Raspberry Pi to use WiFi, you will need to hold off inserting your SD card and follow the next section.

If you are using an Ethernet internet connection, you can skip down to our first boot section.

Setting Up Wi-Fi for Home Assistant on your Raspberry Pi

In this section, we will be showing you how to set up Home Assistant on your Raspberry Pi to connect to your Wi-Fi network. If possible, we highly recommend that you try and stick with using an Ethernet connection is it is significantly more reliable.

However, if you have no choice but to use Wi-Fi to connect to your Raspberry Pi, continue with the following steps.

Make sure you still have your SD Card plugged into your computer before you complete these steps, as we will need to make some changes to it.

1. On the “hassos-boot” partition, start by creating a folder called “CONFIG“.

The Home Assistant software will automatically read this folder for any configuration changes.

2. Within the “CONFIG” folder, we need to create another folder called “network“.

3. Finally, in the “network folder, we need to create a file called “my-network“.

4. Inside the “my-network" file, we need to insert the configuration that will define our network for the Home Assistant software to connect to from our Raspberry Pi.

For this step, you will need to replace three pieces of information.

You will need to first replace “<UUID>” with a new UUID. You can generate a new generic UUID using an online UUID generator.
Secondly, you will need to replace “<WIFISSID>” with the SSID of your Wi-Fi network.
Lastly, you will need to swap out “<WIFIPASSWORD>” with the password for the WiFi network you are trying to connect to.

[connection]
id=my-network
uuid=<UUID>
type=802-11-wireless

[802-11-wireless]
mode=infrastructure
ssid=<WIFISSID>
# Uncomment below if your SSID is not broadcasted
#hidden=true

[802-11-wireless-security]
auth-alg=open
key-mgmt=wpa-psk
psk=<WIFIPASSWORD>

[ipv4]
method=auto

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

5. You should now be ready to go and boot up your Raspberry Pi and start the Home Assistant software.

First Boot of Home Assistant on Your Raspberry Pi

Now that you have the Home Assistant operating system installed and running on your Raspberry Pi, you will want to know how to access it.

This section will show you how you can access this web interface and go through the initial setup experience.

Accessing the Home Assistant Web Interface

1. With the Home Assistant operating system now running on your Pi, you will want to access its web interface.

To do this, we will need to go to one of the following web addresses in your favorite web browser.

For most users, you should be able to get to the Home Assistant homepage by using the following URL.

http://homeassistant.local:8123

Alternatively, if that doesn’t work, you can also try going to the following URL. Sometimes strict network configuration can block these hostnames from working correctly.

http://homeassistant:8123

The last option requires you to know your Raspberry Pi’s IP Address. As you can’t use the terminal at this stage, you will need to likely retrieve this from your router.

Replace “[IPADDRESS]” with the IP address of your Raspberry Pi.

http://[IPADDRESS]:8123

Initial Setup of Home Assistant on your Raspberry Pi

2. The initial boot of Home Assistant on your Raspberry Pi can take some time.

If you see a “Site Can’t Be Reached” error or a screen as we have below, then try and wait at least 20 minutes.

The reason this process takes so long is that the software is downloading the latest available version of Home Assistant as well as preparing everything for you.

Prepearing Home Assistant on Raspberry Pi

3. Once the initial boot of Home Assistant has finished, you may need to refresh your web browser.

The first thing you will be asked to do is to create a user for the Home Assistant software.

Enter the details for your user (1.) then click the “CREATE ACCOUNT” button (2.)

4. This next screen will ask you to give a name to your “home” (1.)

You will also need to set your location. Setting your location helps the software handle automation tasks that take into account the sun’s position.

To make this process easy, you can click the “DETECT” button (2.). This button will try to automatically work out where you live and configure the location and time zone for you.

Next, you need to select the unit system (3.) that you use. By default, this is set to “Metric“.

Once done, click the “NEXT” button (4.) to proceed.

5. You will now be shown a list of devices that the Home Assistant software has already detected.

You can either set them up now by clicking the + icon (1.) above the device name or finish up the initial setup by clicking the “FINISH” button (2.).

6. You have now successfully finished the initial setup of the Home Assistant software on your Raspberry Pi.

You will now see the default Home Assistant dashboard, the more integrations you add, the more information you will see on your dashboard.

Adding Additional Integrations to Home Assistant on your Raspberry Pi

Now that you have Home Assistant up and running on your Raspberry Pi, you will want to expand the devices it is monitoring by adding additional integrations.

1. To add additional integrations, click “Configuration” in the sidebar.

2. Next, click the “Integrations” option.

3. On this next screen, you will see all the devices that Home Assistant has automatically detected from your Raspberry Pi (1.)

If you don’t see a particular device or integration, you can add them yourself by clicking the plus icon in the bottom right-hand corner of the screen. (2.)

This will bring up a search menu that allows you to look up the different integrations available through the Home Assistant software.

Add Additional Home Assistant Integrations

Conclusion

At this point, you should now have the Home Assistant software successfully running on your Raspberry Pi.

Home Assistant has become one of the go-to pieces of software for introducing automation to a home. This is helped largely by its huge community of third-party developers that basically integrate any device you can think of.

If you want to see what else you can do with this software, we have a bunch of guides dedicated to Home Assistant.

Please feel free to post a comment below if you have had any issues with getting this home automation software up and running.

If you liked this project, we recommend exploring the many other Raspberry Pi projects we have on offer.

8 Comments

8one6 on October 10, 2021 at 11:45 pm

Oh man, this took hours of banging my head against the wall. Two *very* important clarifications about the “my-network” (no file extension) file that needs to be created. 1) It *must* be ANSI encoded (not UTF-8); 2) it *must* have Linux style (LF) line endings (not Windows style CRLF). Both of these choices can be made in Notepad++, and you need to get both right. Confirming, no double quotes around either the SSID or the password…they go in quote-free. But without the two little tweaks above, the file won’t be interpreted correctly.

Brian Dalwood on February 15, 2021 at 11:58 pm

Hi, I have downloaded a RPi3 Hassio OS image and am running this on my Pi3B+.
However my Pi is not headless, it has the standard 7″ touchscreen attached.
How would I add the required dependencies to run a Kiosk view of the homeassistant app on a touchscreen on the same pi that the hassio OS is running on?

I tried the apt-get commands but it says this cmd is not recognised. I am trying to follow this article ([SNIP]) to get chromium installed but having no luck.

Any help appreciated.
Thanks
Brian

1. Emmet on February 16, 2021 at 1:31 am
  
  Editor
  
  Hi Brian,
  
  As we are using the home assistant OS in this guide it is not possible to install any additional packages.
  
  HASSIO OS is a very slimmed down operating system and does not actually feature a package manager or even a text editor.
  
  Cheers,
  Emmet
  
2. Tom on February 16, 2021 at 11:55 am
  
  I would ask this on the Home Assistant forums at community.home-assistant.io as I’m sure it’s a common requirement. Probably you can do it via a Home Assistant integration or something.
  
Daniel Lidström on January 27, 2021 at 7:21 am

How do I protect the SD card from eventual corruption? I don’t want to pour time into configuration only to have it wiped in case of unexpected power outage.

1. Emmet on January 27, 2021 at 2:00 pm
  
  Editor
  
  Hi Daniel,
  
  You can always try setting up your Raspberry Pi to boot from a USB device instead as from my experience they aren’t as prone to corruption.
  
  Alternatively you can try keeping backups of your SD card so you can always restore those.
  
  If you want to stick with a SD card there is also ways you can reduce the amount of wear and tear by using stuff like Log2RAM. That software works by moving log writes to RAM, and saving them to the disk once every day rather than constantly writing to the SD Card.
  
  Cheers,
  Emmet
  
Gerard. on March 11, 2020 at 5:51 am

Hello How do you create a configuration file ! in the step setting up for Wifi!
++++
4. Inside the “my-network” file, we need to insert the configuration that will define our network for the Home Assistant software.
+++++
is it a TXT file or ?

1. Emmet on March 11, 2020 at 10:42 am
  
  Editor
  
  Hi Gerard,
  
  The file shouldn’t have a file extension on the end of it.
  
  All you need to do is create a file called “my-network”
  
  And open it within notepad or a similar program that deals with plain text, then enter the configuration using that.
  
  Cheers,
  Emmet