Home Assistant: The Ultimate Setup Guide – a Step-by-Step Tutorial

Home Assistant is absolutely my favorite Raspberry Pi project of all time. It provides a framework for automating your home and controlling all of the various IoT devices that we all have lying around our homes these days. My own Home Assistant server for example not only controls a bunch of different lights around my home, but I have also integrated my home security system, thermostat, televisions/streaming devices, and even my robot vacuum.

Home Assistant is designed to run on a Raspberry Pi – BUT – since Raspberry Pi’s are so notoriously difficult to get your hands on due to chip shortages and global supply chain issues, I’m going to approach this guide a bit differently.

In this guide, I’m going to show you two different ways to install Home Assistant so that the lack of Raspberry Pi availability won’t stop you from automating your home and taking control of all of your various IoT devices. Let’s get started!

Network Infrastructure

Home Assistant is designed to control and automate IoT devices around your home. Many of these IoT devices ‘phone home’ and use cloud services to send information back to their parent company, or so that you can control them remotely with a smartphone app. Because these devices have connectivity into our home networks and are also reaching out to unknown servers out on the Internet, it’s a really good idea to have Home Assistant and all of your devices in a segregated IoT network that ONLY has access to the Internet, but does not have access to any of your ‘secure’ LAN segments inside your home. I’m going to be referring to this as the IoT network throughout the rest of this article.

If you’re interested in how this can be done, I’ve done a couple of videos on it in the past, though these probably need an update.

Installation Method #1 – Raspberry Pi

Since Home Assistant is designed to run on a Raspberry Pi – let’s start there. Home Assistant is available in the official Raspberry Pi Imager, which makes it super easy to flash onto a microSD card.

What you need to get started:

(1) Raspberry Pi – I would recommend a Raspberry Pi 4 model B (2GB, 4GB or 8GB RAM), but you can still use one of the older Raspberry Pi 3 models as well…you’ll just have to be sure to select the correct installation option in the Rapsberry Pi Imager.

(1) microSD card – I recommend a 32GB Class 10 microSD card – these are very common, and should be less than $10 bucks.

Start by downloading the Raspberry Pi Imager. It’s available for Windows, macOS, or Ubuntu. In this post, I’m going to be using the Windows version on Windows 10. Insert your microSD card into your card reader and run Raspberry Pi Imager. Start by clicking ‘Choose OS.’

This is where we pick with operating system we want on our microSD card – scroll down a bit and choose ‘Other specific-purpose OS.’ Then choose ‘Home assistants and home automation.’ From here, you should see the Home Assistant option.

Click on Home Assistant and you’re presented with a few options. The first two options are for Home Assistant running on either a Raspberry Pi 4/400 or Raspberry Pi 3, and the final option is for Home Assistant Yellow, which is a purpose-built server for Home Assistant that uses one of the Raspberry Pi CM4 compute modules as its brain.

Since I have a Raspberry Pi 4, we’ll select that option for this tutorial. Back as the Raspberry Pi Imager screen, now we want to select our microSD card – click ‘Choose Storage’ and select your microSD card.

Double and triple-check that you’ve selected the correct microSD storage device here – if you make a mistake, you can inadvertantly overwrite something you didn’t intend to. Since my microSD card is a 32GB card, it’s pretty easy to see which one I want to choose. Click on it to select it.

Finally, click ‘Write’ to write the image to the microSD card.

Once the write operation is complete, Raspberry Pi Imager will tell you that it was successful, and you can remove the microSD card from the microSD card reader.

Prepare the Raspberry Pi

Your Raspberry Pi basically needs two things – power and Ethernet. I’m sure you could figure out a way to run Home Assistant on the wireless NIC, but since HA requires solid connectivity in order to control your devices, Ethernet is strongly recommended.

Plug in your Ethernet cable, and then plug in power. You can also use Power over Ethernet if you have a PoE HAT for your Raspberry Pi, or if you use a PoE splitter like this one (I love these and have a bunch of them lying around).

Optionally, you can hook up a monitor/keyboard/mouse, but beyond seeing the IP address of the Raspberry Pi, this isn’t terribly useful.

After a few minutes, you should be able to open an Internet browser and connect to http://homeassistant.local:8123 (note the add-on of the port number there), which is an mDNS (multicast DNS) domain name.

If you CAN’T connect to http://homeassistant.local:8123, this could be for a number of reasons – possibly mDNS is blocked on your network, or you’re trying to connect across from a different subnet (such as your secure LAN segment). If that’s the case, then you should connect directly to the IP address of your Home Assistant server.

How can you figure out the IP address of the server? There are a couple of ways to do this – the easiest way is to connect a monitor to the Raspberry Pi and look at the boot screen:

In the screenshot above, we can see that the IP address that was given to my Home Assistant server is 192.168.107.97, so in this case, to get to the HA web GUI, you would want to enter http://192.168.107.97:8123 in your Internet browser.

Another way to get the IP address of your HA server is to look at the DHCP leases in your firewall – in the screenshot below, we can see ‘homeassistant’ (which matches the mDNS name homeassistant.local) which was given the IP address 192.68.107.128. In this case, you would want to enter http://192.168.107.128:8123 in the browser to bring up the HA GUI.

Once you have the HA GUI open, you can skip down to the ‘Initial Setup Wizard’ portion of this tutorial.

Installation Method #2 – Virtual Machine (Synology)

If you can’t get your hands on a Raspberry Pi, another great option for your Home Assistant host server is a virtual machine. In my case, I will be using the Virtual Machine Manager on my Synology NAS (the Synology 5-bay DS1520+ – the latest model is the DS1522+), but virtual machine settings should be relatively similar regardless of the platform.

In my case, the configuration of the Synology NAS took a little bit of prep work before I was able to install the Home Assistant virtual machine. This is because you always want Home Assistant to be in your IoT network, but my Synology NAS lives in my secure LAN primarily. Because of this, I had to add a second IP address to the Synology NAS so that it lives in both my secure LAN and the IoT simultaneously.

In order to do this, I had to plug an Ethernet cable from my IoT network (an untagged VLAN port in the IoT network) into one of the 3 remaining unused Ethernet ports on the back of the Synology NAS. Since I won’t really be using the Synology interface in the IoT network much, I just let it DHCP – as long as it is aware of that IoT network, it will be able to route packets to that network.

In Synology, you can find the network settings in Control Panel –> Network –> Network Interface tab.

Once your NAS has an IP address in the IoT network, we can now get started with the installation.

First, open up Home Assistant’s website at https://home-assistant.io. Choose Documentation –> Installation, and then scroll down to ‘Alternative.’

I’m sure there are probably multiple different image files that will work with Synology’s Virtual Machine Manager, but one that I know FOR SURE works is the VirtualBox (.vdi) image file – click on it to download. The version as of the writing of this blog post is v9.5.

Once downloaded, you’ll have to unzip the .vdi file from the downloaded file.

Back in the Synology GUI, open up the Virtual Machine Manager – then click on Image and choose the ‘Disk Image’ tab. Click ‘Add’ to add a new disk image, and then choose the file that you downloaded from Home Assistant’s website.

VMM will now import that image file which takes 30-60 seconds. Once complete, it should show as ‘healthy’ status.

Next, click on Virtual Machine –> Create (drop down the arrow) –> Import.

Click ‘Import from disk images’ and then click ‘Next.’

Pick your storage device and click ‘Next.’ This is the volume on the NAS where you want to store your virtual machine.

Next, we’ll need to choose some options for the server. The minimum recommended specifications for running Home Assistant in a virtual machine are on the Home Assistant website:

Assuming you’ve got a ‘normal’ amount of IoT devices in your home, the defaults should be fine – you can always expand these later if you are running into resource issues.

Next, we’re asked about storage for our virtual machine. Drop down the selection box and pick the image file that you downloaded and uploaded to the VMM previously. It should automatically populate with 32GB of available space, but you can increase that if you like. Click ‘Next.’

For network, you should now select your IoT network – remember how we made sure the NAS had a footprint in that network earlier? This is where we’re ensuring that Home Assistant lives in our secure IoT network.

In ‘Other Settings,’ make sure that UEFI is selected for ‘Firmware’ and click ‘Next.’

For Assign Power Management Permissions, select whichever Synology users you would like to have full access to this virtual machine and click ‘Next.’

Finally, on the summary page, make sure you check the box next to ‘Power on the virtual machine after creation’ and then click ‘Done.’

The Home Assistant virtual machine will now boot up, and you should see an IP address appear in the Synology NAS. You can also click ‘Connect’ and see the Home Assistant CLI which will also display the IP address.

One last bonus tip here – since you have a virtual machine set up, it’s a great idea to enable ‘Protection’ in your Synology Virtual Machine Manager. This will automatically take snapshots of your Home Assistant server on a schedule (I have mine set for weekly). This way, if anything ever happens with the virtual machine, or if you screw something up very badly, you have a fallback. Setting up Protection for your Home Assistant virtual machine is beyond the scope of this documentation, but definitely worth doing.

Now that Home Assistant has been installed on your virtual machine, you can skip down to the Initial Setup Wizard section.

Installation Method #3 – Docker (Synology)

Docker is another great option for running Home Assistant. Docker has some distinct advantages over running a virtual machine – namely that it’s less resource intensive. You don’t need to dedicate RAM and CPU power to running a full operating system virtual machine just to run Home Assistant. There are some disadvantages too however – in my scenario where I have my Synology NAS with two separate Ethernet ports in two separate networks, the device discovery does not seem to work as well with Docker. I’m sure there are many ways to ‘fix’ that problem, but for my purposes, running a virtual machine was easier.

I will say if your Synology NAS lives in the same network as your IoT devices (if it’s only in the IoT network, or if you have disregarded my previous advice and have all of your stuff running in a single network – shame on you), then Docker is actually a more lightweight option for Home Assistant than a virtual machine.

OK – with that being said…let’s go ahead and install Home Assistant in Docker. I’m going to be doing this through the Synology NAS Docker application, but these instructions should be similar for any Docker instance – or Portainer.

Open the Docker application and click on ‘Registry.’ Search for ‘Home Assistant’ in the upper right-hand search box and press ‘Enter.’ You should now see the homeassistant/home-assistant option pop up. Click on it, and then click ‘Download.’

You will be prompted to choose a version – by default the version is ‘latest,’ but you should drop down the box, scroll all the way to the bottom, and then choose ‘stable’ instead. This will ensure that your Home Assistant Docker container is always on the most recent stable version of Home Assistant.

The download is about 2GB, so it may take a few minutes depending on the speed of your Internet connection. Once it’s done, you’ll see it in ‘Image.’

One thing that we’re going to need for our Home Assistant Docker container is a place outside of the Docker container to store the configuration files. This way, when Docker updates the software inside of the container, it saves our configuration – if we DON’T do this, we’ll end up with a default install of Home Assistant when the Docker container updates which we don’t want…we want to save our configuration!

In Synology, you can create folders in your storage volumes with File Station. I created a new folder off the root called ‘docker’ for all of my docker stuff. In the docker folder, I created a ‘homeassistant’ folder and then a ‘config’ folder inside of homeassistant.

Back in Docker, click on Image, and then click on ‘homeassistant/home-assistant:stable’ and click the ‘Launch’ button.

On the ‘Network’ step, choose ‘Use the same network as Docker Host’ and then click ‘Next.’ When we do this, your Home Assistant server will run on port 8123 on the same IP address as your Synology NAS – which should be fine unless you already have something running on that port.

For General Settings, check the box next to ‘Enable auto-restart’ and then click on Advanced Settings. Enabling auto-restart means that the Home Assistant Docker container will automatically restart if it’s ever stopped (such as if you reboot the Synology NAS).

In Advanced Settings, we need to add a new variable that tells Home Assistant what our time zone is. In my case it’s America/Los_Angeles. I know this from the list of tz database time zones which you can find HERE.

To do this, first click ‘Add’ to add a new variable. For the variable name, enter ‘TZ’ and for the Value, enter in your time zone from the link above. Then click ‘Save.’

Now you can click ‘Next’ on the ‘General Settings’ screen. This will take your to ‘Volume Settings.’ Remember how we added a folder in File Station earlier for our Home Assistant Docker container config files? This is where we’re gonna use it!

Click ‘Add Folder’ and then select the folder you want to use. Once selected, click ‘Select.’

Now that we’ve picked the folder on the Synology side, we also need to tell Docker where to mount that folder for the inside of that Docker container. Enter in ‘/config’ for the ‘Mount path’ and click ‘Next.’

Click ‘Done’ on the summary screen, and your Home Assistant Docker container will start! Make sure ‘Run this container after the wizard is finished’ is checked.

Let Home Assistant boot up for a minute or so, and then browse to the GUI interface which should be the IP address of your Synology NAS – so, for instance, if your Synology NAS is 192.168.1.100, then you’ll want to open up http://192.168.1.100:8123 in your browser.

Once you have that page up, move onto the Initial Setup Wizard!

Initial Setup Wizard

Home Assistant lives on port 8123, so to get to the HA GUI, you’ll need to open up a web browser, and then enter in http://[IP of Home Assistant]:8123. So, for example, if your Home Assistant IP address is 192.168.107.128, then you’ll want to enter http://192.168.107.128:8123 in the browser to bring up the GUI.

When you first connect to the HA GUI, you may see a notice that looks like this:

This just means you’ll have to wait a bit longer. While you’re waiting, you can always buy me a coffee or a beer if you’re enjoying the effort that went into creating this tutorial!

Once Home Assistant is ready to go, you’re prompted to enter your name, a username, and a password for accessing Home Assistant (you can add additional users later if you need to).

Once you click ‘Create Account,’ you’ll be prompted to enter in some location details about your Home Assistant installation – populate this information and click ‘Next.’

Next, you’re given a screen that prompts you to enable anonymous usage data that helps Home Assistant better – make your selections and click ‘Next.’

WOW – on the next screen, you’re shown the IoT devices that HA has already found in your network! If you have everything in your IoT network, it should pretty much find all of the common items. Click ‘Finish’ to close out the wizard.

The Home Assistant GUI

The main ‘Overview’ dashboard is pretty sparse when you first log in, but this is where ALL of your IoT devices will show up once configured for use with Home Assistant. Typically, you’ll leave Overview alone and create your own separate dashboards for various areas of your house, or collections of IoT devices.

Settings is where you will do the bulk of configuration including updating HA, adding new devices and integrations, creating and managing automations, and managing dashboards as well as general server settings.

Updating Home Assistant

It looks like we have a notice in settings as you can tell by the yellow ‘1’ next to Settings – click on Settings to see what it’s trying to tell us.

After clicking on settings, we can see that we have an update to Home Assistant available. Go ahead and click on the update.

Here we can see that HA wants us to update from 2023.3.5 to 2023.3.6 – go ahead and click ‘Install’ and the update will run – it should only take a few minutes to complete.

Once the update is complete, you will be prompted to log back in, and you should be back at the Settings screen. Click on ‘Notifications’ in the left-hand menu.

Home Assistant Notifications

Notifications will show you any available updates or when new devices are found on your network – since we have 1 new notification, let’s take a look!

OK – so yea…LOTS of devices found after clicking on ‘Check it out’ in the Notifications slide-out. You can also get to this same screen by clicking Settings –> Devices & Services. Any new devices will be outlined in blue and say ‘Discovered’ at the top of the outline.

Set Up an Integration

These are discovered integrations. An Integration is an add-on module that controls 1 or more IoT device. For each one of these Integrations, you’ll have to click on ‘Configure’ and follow the instructions. Some of the integrations are more difficult than others to configure, but essentially what we’re doing here is entering in some form of authentication credentials that will allow Home Assistant to have control over those devices.

One of the nice things about Home Assistant is that *most* of this stuff is fairly well documented – it’s rare that you’ll get stuck trying to figure out how to configure an integration – let’s go ahead and do one as an example. Since my Lutron switches are the first integration in the list, we’ll start there.

In the case of my Lutron light switches, I have 3-4 of these throughout my home, and they’re controlled with a central base controller that I have in my office. There are a number of IoT infrastructures that work similarly such as Philips Hue. In the case of Lutron or Philips Hue, to pair with Home Assistant, we have to click ‘Submit’ and then physically press a button on the base controller, so I will do that now. You usually have to press the button within a set amount of time (typically 30 or 60 seconds).

Once we hit the button on the Lutron controller, we should see a ‘Success!’ pop up. This shows us what was found, and gives us the option of adding devices to ‘areas’ within our home. Areas aren’t mandatory, but they’re a great way to organize your devices.

In my case, I’m going to create a new area ‘Office’ and assign the Smart Bridge controller to that area, and then I’ll organize the rest of the devices into areas of my home, adding the areas if necessary.

As I mentioned earlier, Integrations are add-on software modules for groups of IoT devices. You may have a single IoT device in an Integration such as the case with a smart thermostat, or you may have multiple devices in an Integration such as the case with these Lutron switches, or a set of Philips Hue light bulbs.

Once the Integration has been configured, the blue ‘Discovered’ bar goes away, and we can see how many devices are included in that particular Integration.

If you click on the devices (or go to Settings –> Devices), you can see the individual devices.

For my Lutron switches, let’s further click into Front Foyer Sconces (which is just a fancy title for my house’s front porch lights).

In the device detail, we can see a lot of info – though not much is populated yet. The Logbook is basically the log of when this device was affected in some way (such as turning it on/off).

Controls are what you can do with the device – in the case of a simple device like these Lutron switches, it’s a simple on/off. But in the case of something like a dimmer switch, you can click on the name of the device under ‘Controls’ and see more info:

Different devices will have different control mechanisms.

You can also see any Automations, Scenes, or Scripts that this device is a part of – let’s talk about those next.

Automations are exactly what they sound like – a way to automate the control of a device. For example, you can create an automation for your outside lights to go on at sunset, and then turn off at 10:30pm. Or you can create an automation to turn down your thermostat when Home Assistant detects that no one is home – you can get really granular and creative with the automations you create.

Scenes are sets of configurations for devices. For instance, you may create a ‘morning’ scene that sets temperature and lights to a set level. Or you may have a ‘Romantic’ scene that sets lights low and plays Barry White music through Spotify on your Roku.

Scripts are workflows that you can create that triggers the control of multiple devices in sequence, or adds more functionality. For example, you may create a script that sends a notification ‘Garage is open!’ any time a garage door opens or a motion sensor is triggered. Or you can use scripts to create timed events – such as when a light is turned on, trigger a wait before turning that light off again.

Create an Automation

Of course the next step in our process of setting up a base foundation for Home Assistant is going to be to actually automate something! In this case we’re going to create a very simple automation that turns my front porch lights on at sunset, and then turns them off at 10:30pm.

From the dashboard of Home Assistant, click on Settings –> Automations & Scenes. Then click the blue ‘+ Create Automation’ button in the lower right-hand corner of the screen.

On the resulting pop-up window, select ‘Create new automation.’

Now we have 3 criteria to populate – Triggers, Conditions, and Actions.

Triggers – This is the criteria that we’re going to use to launch this automation. The trigger can be based on the sun (sunset/sunrise +/- X minutes or hours), it can be a time-based trigger (ie. do X at 9:00am), it can be triggered by a different device (ie. motion sensor detects motion), etc. There are may ways to trigger an automation – some are simple, and some are complex.

Conditions – Conditions are different criteria that we can use to filter down when or when NOT to trigger the automation. For example, let’s say we wanted to have a motion sensor on our front porch to trigger the port lights on…well, we wouldn’t want to do that during the daytime, so we may have a condition that tells the automation to only trigger the porch lights on between sunset and sunrise.

Actions – Finally, we have our actions – the actions determine what we’re actually doing. For example, turning on or off a light, or a smart switch, or perhaps we want to trigger our robot vacuum to start cleaning, but only on the condition that no one is home.

You can get very creative with these three automation settings – and that’s even before you get into actual programming of custom scripts! For our purposes though, we’re just going to keep it simple in order to give you a foundation from which to build upon.

OK – so back to the automation we want to set up. We’ll actually be creating two automations – the first automation is to turn on our front porch lights at sunset. The second automation is to turn off our front porch lights at 10:30pm.

In the New Automation screen, click ‘+ Add Trigger’ and select ‘Sun.’

Then choose ‘Sunset’ since we want this action to happen as it’s getting dark. You can optionally add an offset such as -01:00:00 which would be 1 hour before sunset (sunset minus 1 hour), or 01:00:00 which would be 1 hour after sunset (sunset plus 1 hour).

Notice that you can now also add additional triggers as well if, for instance, you wanted to create separate automations for different times of the year.

We’re going to skip conditions, but click around the options and familiarize yourself with what can be done. For example, if we wanted to create an automation that automatically turns a light off, but only after no motion has been detected for 30 minutes, we would add a condition for a motion sensor that hasn’t detected activity in 30 minutes.

Under Actions, click ‘+ Add Action.’ Then choose ‘Device.’

For the Device, I’m going to choose ‘Front Foyer Sconces’ which are my front porch lights. Then for the Action, I’m going to choose ‘Turn on Front Foyer Sconces.’ Notice the 3 actions you can choose – on/off/toggle. These can be used in different ways.

Notice also that you can add additional actions – so for example, if you have multiple lights that you want to be turned on at sunset, you can add them here.

Click ‘Save’ in the bottom right-hand corner of the screen, give this automation a name and then click ‘Save’ again to complete the process.

If you now click the 3 vertical dots in the upper right-hand corner, you’re given a pop-up menu. If you choose ‘Run’ from that pop-up menu, you can run this automation to test it. If all goes well, the front porch lights should turn on!

OK – so we have now built an automation for turning our front porch lights on at sunset – let’s add another one that turns the lights off at 10:30pm.

Settings –> Automations –> Create Automation (bottom right-hand corner) –> Create new automation.

Add a new Trigger of type ‘Time’ and then choose ‘Fixed time’ and choose 10:30pm.

Add a new Action of type ‘Device,’ and choose Front Foyer Sconces and set the Action to ‘Turn off Front Foyer Sconces.’

Save and name the new automation, and then run it to test it out!

If you go back to Settings –> Automations, you should now have 2 automations – one for front porch lights on at sunset, and another for front porch lights off at 10:30pm.

Final Thoughts

So there you go! You now have a working foundation for your Home Assistant server that you can use to automate your home – your automations can be as simple as turning lights on and off at certain times of the day, or they can be super intricate…how far down the rabbit hole you go is completely up to you!

One really cool add-on for remote access to your Home Assistant server is the Cloudflare tunnels add-on – this is an integration in Home Assistant that keeps open a connection to Cloudflare tunnels so that you can easily and securely connect into your Home Assistant server remotely with HTTPS. If you’d be interested in a tutorial on how that can be accomplished, let me know down in the comments below!

Here’s an idea for an automation – how about if you enjoyed this tutorial, you automatically buy me a coffee!

[ko-fi]

And you should also check out all of the great merch in the Crosstalk store! Just click the ‘Store’ link in the menu bar above!