Getting Started With Home Assistant on Raspberry Pi (2 ways)

Installing Home Assistant on a Raspberry Pi is a popular project for any Raspberry Pi owner. It’s popular because once connected to all your smart devices, it makes the Raspberry Pi really useful in your home setup (which is not the case with all projects). In this tutorial, I’ll show you each step to get it running so you can begin automating your home.

Home Assistant is available as an image for the Raspberry Pi, which can be flashed to an SD card as a complete system. It’s also possible to create a docker container with Home Assistant, making it possible to use this application with other services installed on the same system.

I’ll explain these two installation methods. Use the first method if your Raspberry Pi is dedicated to Home Assistant, as it’ll be much simpler for you in the long run. But if you already have a few other services on Raspberry Pi OS and want to keep them running, you can follow the second method (with Docker) and have everything on the same SD card. I’ll then give you a few tips to get started the right way, whatever installation method you choose.

If you’re looking to quickly progress on Raspberry Pi, you can check out my e-book here. It’s a 30-day challenge where you learn one new thing every day until you become a Raspberry Pi expert. The first third of the book teaches you the basics, but the following chapters include projects you can try on your own.

Home Assistant Installation (dedicated system)

The easiest way to install Home Assistant on Raspberry Pi is to follow the same method as with any operating system:

• Download the Home Assistant image from the official website.
• Flash it on an SD card with Balena Etcher.
• Insert the SD card into the Raspberry Pi.

I will explain each step in detail now.

Download Home Assistant

Home Assistant officially supports the Raspberry Pi 3 and 4, so it offers an image built for it. You can even choose between 32 or 64 bits:

• Open this page from the official website.
• Scroll down a bit to find this box:
  
• Copy the URL corresponding to your Raspberry Pi model. I didn’t notice any issues with the 64-bit version, so you can try this one first.

The documentation explains how to use this URL directly in Etcher, without downloading the image beforehand. If you prefer, or if you use another tool, you can paste this link in your web browser URL bar to download the file on your computer. You can then flash it with any tool you are used too.

Flash Home Assistant on a new SD card

• Download and install Balena Etcher, if you don’t have it already.
  It’s a free tool to easily install a new system, copying the file from a system image to the SD card.
• Insert the SD card into your computer. You will probably need an SD/MicroSD card adapter.
  And if you don’t have an SD card reader in your computer, you can use a USB adapter like this one.
  You’ll use it all the time with your Raspberry Pi, so it’s worth it to have one.
• Open Balena Etcher, it looks like that:
  
• On the left, click on “Flash from URL” and paste the link you copied in the previous step.
  If you downloaded the file already, just click “Flash from file” and select it.
• Then select the target (your SD card or USB drive), and click on “Flash!” to start the copy.

After a few minutes, the SD card should be ready to use, you can eject it from your computer.

First boot with Home Assistant

We can now start Home Assistant for the first time. To make things easier, please plug your Raspberry Pi into a network cable before starting it:

• Insert the SD card into your Raspberry Pi.
• Make sure everything else is plugged (especially network & monitor).
• Power it on and wait a few minutes.

Home Assistant is a web interface to manage everything, so there is nothing to do on the monitor directly, except taking note of the URL. Just wait a bit to get the Home Assistant CLI showing up, and you can then move to the next step (skip the next part of this tutorial).

Home Assistant Installation with Docker

Installing Home Assistant with Docker is great if you already have Raspberry Pi OS (or any other distribution) running on your Raspberry Pi, and want to add it like an additional application, without losing the other services.

Update your system

I’m testing this setup on the latest Raspberry Pi OS version available at the time of writing (Bullseye 64-bits), but it should work on any Debian-like distribution. If you are using other Linux systems like Manjaro or Fedora, you’ll need to adapt some of these commands.

Before anything else, make sure your system is up-to-date, to avoid any issue during the installation:
sudo apt update
sudo apt upgrade

If there are a lot of updated packages, a reboot is recommended before going further:
sudo reboot

Are you a bit lost in the Linux command line? Check this article first for the most important commands to remember and a free downloadable cheat sheet so you can have the commands at your fingertips.

How to Install Docker on Raspberry Pi

The official documentation doesn’t explain how to set up Docker on the Raspberry Pi first, which is where you might be lost, so I’ll answer your questions here.

• Docker is not available in the APT repository on Raspberry Pi OS.
• The easiest way to install Docker on Raspberry Pi is to use this command:
  curl -sSL https://get.docker.com | sh

You don’t need to use sudo, the script will do it for you. Basically, this command will add a new repository to your APT sources, and install the packages from there.

If you are new to this, I recommend reading my complete guide about Docker on Raspberry Pi first. Just to make sure you understand what you’re doing here.

Install the Home Assistant container

Now that Docker is set up on your system, you can follow the documentation and create a new container with Home Assistant. Here is the command syntax to do this:

docker run -d \
--name homeassistant \
--privileged \
--restart=unless-stopped \
-e TZ=MY_TIME_ZONE \
-v /PATH_TO_YOUR_CONFIG:/config \
--network=host \
ghcr.io/home-assistant/home-assistant:stable

Yes, that is a big command, and you need to adjust it for your system:

• Replace MY_TIME_ZONE with your current timezone. The format is Country/City.
  For example: TZ=Europe/Paris
• Replace PATH_TO_YOUR_CONFIG with the folder where you want to store the configuration files.

In my case, I just used this command:

docker run -d \
--name homeassistant \
--privileged \
--restart=unless-stopped \
-e TZ=Europe/Paris \
-v /home/pi/hass:/config \
--network=host \
ghcr.io/home-assistant/home-assistant:stable

After doing this, the container will start and the web interface will be available at the same address as with the complete setup. So, you can continue this tutorial to find out how to access it and start using Home Assistant.

Note: It worked fine the first time I tried, but after a second try on another SD card, I got this error:
“docker: Got permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock”
I fixed it with:
sudo chmod 666 /var/run/docker.sock

Updates

Updating Home Assistant with the Docker installation method is a bit tricky. You can’t just run apt upgrade and hope that you’ll keep it up-to-date. After reading the documentation, the only way to update it seems to remove the container and create a new one with the new version.

Here is the command to run (in this order):
docker pull ghcr.io/home-assistant/home-assistant:stable
docker stop homeassistant
docker rm homeassistant

Then, you can use the same command as during the installation to recreate the container. Make sure to use the same path for the configuration folder if you don’t want to start from scratch.

Getting Started with Home Assistant

Once Home Assistant installed, it’s now time to connect it to all your smart devices and start having fun with it!

First access to the web interface

Whatever the installation method you chose, Home Assistant will start a web interface on the port 8123 of your Raspberry Pi. You can generally it access it with http://homeassistant:8123 or http://IP_ADDRESS:8123.

You should get a form, as seen on the above screenshot, asking you to create the first user account.
Then you will be asked a few questions to customize your setup:

• Give a name to your Home Assistant installation.
• Set your location, timezone, unit system and currency.
• Check the boxes corresponding to the data you are ready to share with the developers (or skip this screen).
• The wizard will then scan your network, and offer you to quickly add any supported smart devices:
  
• Just click on the one you want to add, or click “Finish” to do this later.
  In my case, it detected most of the ones that were connected during the installation (lights, smart plugs and NAS).
• Adding each device may require additional steps. For example, for Philips Hue lights, you need to press the button on the hub to allow Home Assistant to control it, and then assign each light to a room.
• You can obviously click “More” to add additional integrations (like websites or things that has not been detected automatically), but I recommend doing this once in the full interface.

Once this onboarding wizard completed, you should get access to the full interface, with a nice dashboard including the integrations you set up:

You can now use this interface to manage your smart devices. For example, I can switch off or on the kitchen light by clicking the corresponding button. But Home Assistant goes way further than that.

Add more integrations

First, make sure to set up all your smart devices on this interface. You can use the configuration item in the left menu to add new ones:

• Click on Configuration and then Devices & Services.
• You’ll get the same list as during the onboarding process, but you can also add new integrations.
• Home assistant is compatible with a lot of services related to home automation.
  Here are a few examples: weather websites, network devices (Unifi, Synology, …) , cloud services (Google, Apple, …), robots (vacuum), smart plugs (home, car, …), etc.
  You’ll get the full list when you click on “Add Integration”, it’s insane all of the things you can monitor and use in your automations.
• You’ll then get extra steps depending on the integration you want to add.
  For example, to connect to a weather API, you’ll generally need an API key (you can often get one for free, just by creating an account on their website).
  For a robot vacuum, you’ll probably need to press a button on it. Etc.

Try to add a few integrations. Obviously, Home Assistant is an exciting project when you have many smart devices and can make them work together by creating some automation (ex: when I open the door, light on the living room and after 10s start my favorite song). But even with a few of them and addition web services, you can already build some nice dashboards.

Create a new dashboard

By default, Home Assistant will create a basic dashboard (Overview), and another one named “Energy”. But you can edit them, delete them or create new ones. Here is how to do this:

• Go to Configuration > Dashboards.
• Choose a title and an icon:
  
• Then click on it in the left menu to open it.
• You can now click in the top-right corner menu and choose “Edit Dashboard” to customize it.
• From there, you can do everything you want: add new cards, delete some, move the existing ones up and down, etc.
• For each card, there are many templates you can use to format the data differently (button, calendar, history graph, gauge, etc.).
  
• After choosing a template, you’ll need to pick the exact value you want to display on it.
  For example, in my Weather dashboard, I can choose to display the temperature, precipitation, UV index, etc.
  

You may think it’s complicated while reading this, but try to use it. It’s pretty intuitive, so I’m sure you’ll understand everything quickly. Start with something you really want to have on your dashboard, and find the best way to display the value.

Create your first automation

Obviously, Home Assistant is not only a way to have nice dashboards and replace several apps with one. It’s also the most effective way to automate your home.

Automation is a process that will run automatically when a trigger is detected:

• If the inside temperature drop below 20 °C, turn on the heater.
• When motion is detected in the bedroom, turn on the wall light.
• If the wind is over 60 km/h, close the shutters.
• Etc.

Creating an automation is not complicated once you get the idea. Find something simple you want to try, and follow these steps to configure it:

• Go to Configuration > Automations.
• Click on “Add Automation”.
• Change the automation name to something you’ll remember.
  A one sentence telling exactly what it does is best.
• In the triggers part, set the device that will be used to start the automation.
• Then set the exact trigger sensor and value that will start the automation.
  For example, I tested with AccuWeather (a weather web service), and tell that when the cloud ceiling is below a certain threshold, it will start an automation to light on the house.
  But you can simply use the “Sun” trigger, and turn on the lights on sunset for example.
  
• You can add conditions in the next section if needed.
  Dumb example: don’t turn on the kitchen if the light is already on.
• Then, set the actions that should be triggered when the conditions are fulfilled.
  In my case: Turn on the kitchen light, for example.
  You may also tweak other settings like the brightness for lights, etc.

Try to create something simple first, and check if it’s working. Depending on the smart devices and integrations you set up, this will be more or less easy to test. The possibilities are endless, just try to think of something useful for your house.

Video

https://www.youtube.com/watch?v=dZFHyvY2Gp8

Final Thoughts

Overall, Home Assistant is a great application. The installation is pretty straightforward, and you can do almost anything with it. The interface is intuitive, it’s just getting complicated if you try to build complex automations with multiple smart devices interconnected.

If you have smart devices, but find they are not that smart, and you still need to do many tasks manually, Home Assistant could be what’s missing in your home. Try to install it and find some ways to make it useful, you’ll have an excuse to spend more time on your Raspberry Pi :-).

Domoticz and HOOBS are alternatives to consider (click on the links to read my articles about these), but I think Home Assistant is my favorite currently.

If you are using Ubuntu on your Raspberry Pi, or even on your computer, you can check this other article to get more details for this distribution: Install Home Assistant on Ubuntu: A Step-by-step guide

Whenever you’re ready, here are other ways I can help you:

The RaspberryTips Community: If you want to hang out with me and other Raspberry Pi fans, you can join the community. I share exclusive tutorials and behind-the-scenes content there. Premium members can also visit the website without ads.

Master your Raspberry Pi in 30 days: If you are looking for the best tips to become an expert on Raspberry Pi, this book is for you. Learn useful Linux skills and practice multiple projects with step-by-step guides.

The Raspberry Pi Bootcamp: Understand everything about the Raspberry Pi, stop searching for help all the time, and finally enjoy completing your projects.

Master Python on Raspberry Pi: Create, understand, and improve any Python script for your Raspberry Pi. Learn the essentials step-by-step without losing time understanding useless concepts.

You can also find all my recommendations for tools and hardware on this page.