Getting Started with Home Assistant

Home Assistant is the brain of your smart home. It collects data from your sensors, runs automation rules, and provides dashboards to monitor and control everything. Before you can connect your ESP32 devices, you need a running Home Assistant instance.

In this article, you will install Home Assistant on a Raspberry Pi, explore its interface, and learn the core concepts you need to understand before adding devices.

🔗Installation Options

Home Assistant can run on several different platforms. Here are the main options:

🔗Which Should You Choose?

If you are new to home automation, install Home Assistant OS (HAOS) on a Raspberry Pi 4 or 5. It is the officially recommended path, gives you the full feature set (including add-ons like ESPHome and Mosquitto), and the community documentation assumes this setup.

If you already have a server, running HAOS in a virtual machine (Proxmox, VirtualBox) gives you the same full experience. Docker works too, but you lose the add-on system and have to manage Mosquitto and ESPHome separately.

If you want zero setup, the Home Assistant Green (around 99 USD) is a ready-made device -- plug it in, connect Ethernet, and it is running. The Home Assistant Yellow adds a built-in Zigbee radio.

This guide walks through the Raspberry Pi installation since it is the most common and cost-effective approach.

🔗What You Will Need

• Raspberry Pi 4 (2 GB RAM or more) or Raspberry Pi 5 -- the Pi 5 is faster but either works well
• A microSD card (32 GB or larger, Class A2 recommended for speed)
• A USB-C power supply (official Raspberry Pi power supply recommended)
• An Ethernet cable (recommended for initial setup; WiFi is possible but less reliable)
• A computer with a microSD card reader (for flashing the image)

You do not need a monitor, keyboard, or mouse for the Raspberry Pi. Home Assistant is accessed entirely through a web browser on your computer or phone.

🔗Step 1: Flash Home Assistant OS

1. Download and install the Raspberry Pi Imager from raspberrypi.com/software.

2. Insert your microSD card into your computer.

3. Open Raspberry Pi Imager and configure it:

   • Click Choose Device and select your Raspberry Pi model (Pi 4 or Pi 5).
   • Click Choose OS, scroll down to Other specific-purpose OS > Home assistants and home automation > Home Assistant, and select the image for your Pi model.
   • Click Choose Storage and select your microSD card.

4. Click Next. When asked about customization, click No -- Home Assistant OS manages its own configuration.

5. Wait for the image to be written and verified. This takes a few minutes.

6. Remove the microSD card from your computer.

🔗Step 2: Boot the Raspberry Pi

1. Insert the microSD card into your Raspberry Pi.
2. Connect an Ethernet cable from your Pi to your router.
3. Connect the USB-C power supply to boot the Pi.

The first boot takes several minutes. Home Assistant needs to download and install its latest components. Be patient -- it can take 5 to 20 minutes depending on your internet speed.

🔗Step 3: Access the Web Interface

1. Open a web browser on your computer (which should be on the same network).
2. Navigate to http://homeassistant.local:8123.

If homeassistant.local does not resolve, check your router's admin page for the Raspberry Pi's IP address and use http://<IP_ADDRESS>:8123 instead. The mDNS name .local does not work on all networks.

3. You should see the Home Assistant setup wizard. If you see a "Preparing Home Assistant" screen, wait a few more minutes and refresh.

🔗Step 4: Create Your Account

The setup wizard walks you through initial configuration:

1. Create your user account -- this is your admin account. Choose a strong password.
2. Name your home and set your location on the map. Home Assistant uses this for sunrise/sunset calculations and weather data.
3. Select your country and language for localization settings.
4. Choose what data to share (anonymous usage analytics). This is optional and can be changed later.
5. Home Assistant will automatically detect some devices on your network. You can set these up now or skip and add them later.

After completing the wizard, you arrive at the main dashboard.

🔗Core Concepts

Before adding devices, it helps to understand how Home Assistant organizes things.

🔗Entities

An entity is a single data point or controllable function. Every sensor reading, every switch, and every light is an entity. Examples:

• sensor.living_room_temperature -- a temperature reading (value: 22.5)
• switch.garden_pump -- an on/off switch (state: "on" or "off")
• light.bedroom -- a dimmable light (state: "on", brightness: 180)
• binary_sensor.front_door -- a door sensor (state: "on" = open, "off" = closed)

Each entity has:

• A unique ID (like sensor.living_room_temperature)
• A state (the current value, like "22.5" or "on")
• Attributes (extra data, like unit of measurement or battery level)

🔗Devices

A device groups related entities together. For example, a BME280 sensor node might create three entities (temperature, humidity, pressure), and Home Assistant groups them under one device called "Living Room Sensor."

🔗Integrations

An integration connects Home Assistant to a service or protocol. Examples:

• The MQTT integration lets Home Assistant receive data from your ESP32 via MQTT
• The ESPHome integration auto-discovers ESPHome devices on your network
• The Met.no integration provides weather forecasts
• The Mobile App integration connects your phone

You can browse and install integrations from Settings > Devices & Services > Add Integration.

🔗Areas

Areas represent physical locations in your home (Living Room, Kitchen, Garden). Assigning devices to areas helps organize your dashboard and makes voice commands more natural ("Hey Google, what is the temperature in the kitchen?").

🔗Automations

Automations are rules that make your home smart. They follow a trigger-condition-action pattern:

• Trigger: Something happens (temperature exceeds 28 degrees, motion detected, time is 7:00 AM)
• Condition: Optional extra checks (only if it is a weekday, only if someone is home)
• Action: Do something (turn on the fan, send a notification, close the blinds)

We will cover automations in detail in a later article.

🔗Navigating the Interface

Home Assistant's web interface has several main sections accessible from the left sidebar:

🔗Overview (Dashboard)

The default dashboard automatically generates cards for your entities. Later, you can customize this with your own layout using the built-in dashboard editor (formerly called Lovelace).

You can create multiple dashboards -- one for an overview, one for detailed sensor data, one for a specific room.

🔗Settings

This is where you manage everything:

• Devices & Services -- add integrations, manage devices
• Automations & Scenes -- create automation rules
• Areas & Zones -- define rooms and geographic zones
• People -- manage users and presence detection
• Add-ons -- install additional software (ESPHome, Mosquitto, etc.)

🔗Developer Tools

The Developer Tools section is useful for testing and debugging:

• States -- view and manually change entity states
• Services -- call Home Assistant services directly (useful for testing automations)
• Template -- test Jinja2 templates used in automations
• Events -- monitor the event bus in real time

🔗Map

Shows the locations of tracked devices (phones, GPS trackers) on a map. Useful for presence detection.

🔗Logbook and History

• Logbook -- a chronological record of state changes ("Living room light turned on at 14:32")
• History -- graphs of entity state changes over time

🔗Installing Your First Add-on

Add-ons are additional software packages that run alongside Home Assistant on the same device. Two add-ons are essential for ESP32 projects:

🔗File Editor

The File Editor add-on lets you edit Home Assistant's configuration files from the web interface.

1. Go to Settings > Add-ons > Add-on Store.
2. Search for File editor.
3. Click Install, then Start.
4. Enable Show in sidebar for easy access.

You will use this to edit configuration.yaml and automation files.

🔗Mosquitto MQTT Broker

If you plan to connect ESP32 devices using Arduino + MQTT (rather than ESPHome), you need an MQTT broker.

1. Go to Settings > Add-ons > Add-on Store.
2. Search for Mosquitto broker.
3. Click Install, then Start.
4. Enable Start on boot.

After installing Mosquitto, go to Settings > Devices & Services. Home Assistant should auto-discover the MQTT integration. Click Configure to set it up.

We will cover the MQTT setup in detail in the MQTT article. For now, just install it so it is ready.

🔗ESPHome Add-on

If you want to use the YAML-based approach instead of Arduino code:

1. Go to Settings > Add-ons > Add-on Store.
2. Search for ESPHome.
3. Click Install, then Start.
4. Enable Show in sidebar.

This gives you a web-based editor for creating and flashing ESPHome firmware to your ESP32 devices.

🔗The Companion App

Home Assistant has a companion app for both iOS and Android. The app provides:

• Remote access to your dashboards (even outside your home, if configured)
• Push notifications from automations
• Phone sensors as Home Assistant entities (battery level, location, steps, connectivity)
• Actionable notifications (notification with buttons like "Turn off lights?")

Install it from the App Store or Google Play, then add the integration in Home Assistant under Settings > Devices & Services > Add Integration > Mobile App.

Remote access: By default, Home Assistant is only accessible on your local network. For remote access, the easiest option is Home Assistant Cloud (Nabu Casa) -- a paid service (6.50 USD/month) that creates a secure tunnel to your instance without port forwarding. Alternatively, you can set up your own reverse proxy or VPN, but that is beyond the scope of this guide.

🔗Customizing Your Dashboard

The default auto-generated dashboard is a good starting point, but you will want to customize it as you add devices.

1. Go to the Overview page.
2. Click the three-dot menu in the top right and select Edit Dashboard.
3. The first time, it will ask if you want to take control of the dashboard. Click Start with an empty dashboard or Keep the auto-generated dashboard depending on your preference.

From the editor, you can:

• Add cards -- buttons, gauges, graphs, entity lists, and more
• Rearrange cards by dragging
• Create sections and views (tabs) for different rooms or functions
• Use conditional cards that show/hide based on entity states

Here is an example of a simple sensor card in YAML (you can switch between visual editor and YAML editor):

type: entities
title: Living Room
entities:
  - entity: sensor.living_room_temperature
    name: Temperature
  - entity: sensor.living_room_humidity
    name: Humidity
  - entity: sensor.living_room_pressure
    name: Pressure

🔗Tips for a Smooth Setup

Use a wired Ethernet connection for your Raspberry Pi. WiFi works, but a wired connection is more reliable for a device that runs 24/7.

Set a static IP address for your Raspberry Pi in your router's DHCP settings. This ensures the address does not change, so homeassistant.local or the IP always works.

Enable automatic backups. Go to Settings > System > Backups and configure automatic backups. Store them on a network share or cloud service. SD cards can fail, and losing your entire configuration is painful.

Keep Home Assistant updated. Updates bring new features, bug fixes, and security patches. Go to Settings > System > Updates to check for updates. Read the release notes before updating -- occasionally breaking changes require configuration adjustments.

Start simple. Do not try to automate everything on day one. Add a few sensors, create a basic dashboard, and build one or two automations. Expand gradually as you learn the system.

🔗What is Next?

Your Home Assistant instance is now running and ready for devices. The next step is connecting your ESP32. You have two paths:

• ESPHome -- configure ESP32 devices with YAML, no coding required. Best for standard sensors and switches.
• Arduino + MQTT -- write your own C++ firmware and connect via MQTT. Best for custom logic and full control.

Both approaches work great with Home Assistant. Choose the one that fits your skill set and project needs -- or learn both and use whichever fits best for each device.