Home Assistant on Raspberry Pi — Smart Home Without the Cloud

Introduction

Home Assistant is an open-source home automation platform that puts you in complete control of your smart home without relying on cloud services or proprietary ecosystems. Unlike commercial smart home solutions from Amazon, Google, or Apple, Home Assistant runs entirely on your own hardware—typically a Raspberry Pi—giving you full privacy, instant response times, and the flexibility to automate virtually anything.

In this guide, we'll walk through installing Home Assistant on a Raspberry Pi, setting up your first devices, building automations, and connecting wireless protocols like Zigbee and Z-Wave. Whether you're a homelab enthusiast or someone tired of cloud dependencies, this is the tutorial to get you started.

Prerequisites

Before we begin, you'll need:

• Raspberry Pi 4B or 5 (2GB RAM minimum, 4GB+ recommended; Pi 3 works but slower)
• SD Card or USB SSD (32GB+ recommended; SSD is faster and more reliable)
• Power supply (official Pi power supply recommended)
• Ethernet cable (optional but recommended for stability; WiFi works too)
• Raspberry Pi Imager (free tool from raspberrypi.com)
• A computer to flash the SD card or SSD
• Basic terminal familiarity (we'll cover commands)
• Smart devices that are Home Assistant compatible (Philips Hue, IKEA Trådfri, Tasmota-flashed devices, etc.)

Installation Methods

Home Assistant can be installed three ways:

1. Home Assistant OS (HA OS) — Recommended for beginners. A minimal Linux OS pre-configured with Home Assistant, taking ~3–5 minutes to set up.
2. Docker Container — Best if you're running other services on your Pi (Plex, Pi-hole, etc.). More flexible but requires Docker knowledge.
3. Home Assistant Core — The bare Python application. Maximum control but requires manual dependency management.

For this guide, we'll focus on HA OS (the easiest) and touch on Docker (the most flexible for multi-service setups).

Step 1 — Install Home Assistant OS

Flash Home Assistant to Your SD Card or SSD

1. Insert your SD card or USB SSD into your computer.
2. Download Raspberry Pi Imager from raspberrypi.com.
3. Open Raspberry Pi Imager and click Choose Device → select your Pi model (Pi 5 or Pi 4).
4. Click Choose OS → scroll to the bottom → select Home Assistant → Home Assistant OS.
5. Click Choose Storage and select your SD card/SSD.
6. Click the gear icon (Advanced Options) and:
   • Set hostname: homeassistant (or whatever you prefer)
   • Enable SSH (optional but useful): check "Enable SSH"
   • Set username/password if enabling SSH
   • Configure WiFi if not using Ethernet
7. Click Next, then Yes to confirm and start writing. This takes 2–5 minutes.

Boot and Access Home Assistant

1. Eject the SD card/SSD from your computer.
2. Insert it into your Raspberry Pi and power on.
3. Wait 2–3 minutes for the first boot and initialization.
4. Open your browser and navigate to http://homeassistant.local:8123/ (or http://<pi-ip>:8123/ if using an IP address).
5. You should see the Home Assistant onboarding screen.

Step 2 — Initial Setup

When you first access Home Assistant, you'll see the Onboarding Wizard:

1. Create your account — Choose a username and password. This is your Home Assistant admin account.
2. Set your home name — E.g., "My Home" (used in automations and dashboards).
3. Set location and timezone — Important for automation rules like sunrise/sunset.
4. Unit system — Choose Metric or Imperial.
5. Click Finish.

You're now in the Home Assistant dashboard. Congratulations! Home Assistant is running and you're ready to add devices.

Step 3 — Add Your First Device

Let's add a smart light or smart plug to demonstrate integrations.

Example: Adding a Philips Hue Light

1. In Home Assistant, go to Settings → Devices & Services → Integrations.
2. Click Create Automation in the bottom-right corner (orange button).
3. Search for "Philips Hue" and click it.
4. Follow the prompts to discover your Hue Bridge on the network.
5. When the Hue Bridge is found, press the physical button on the bridge to authorize.
6. Home Assistant will import all your Hue lights.

Example: Adding a Tasmota-Flashed Smart Plug

If you've flashed a smart plug with Tasmota:

1. Go to Settings → Devices & Services → Integrations.
2. Search for "Tasmota" and click Create Automation.
3. Enter the IP address of your Tasmota device.
4. Home Assistant will auto-discover the device and create entities (power switch, power usage, etc.).

Each device you add appears in the Devices list and creates entities (a light, a temperature sensor, etc.). Entities are the building blocks of automations.

Step 4 — Create Your First Automation

Automations are the heart of Home Assistant. Let's create two examples: one using the UI and one using YAML.

Example 1: Turn On Lights at Sunset (UI)

1. Go to Settings → Automations & Scenes → Automations tab.
2. Click Create Automation → Create New Automation.
3. Select Trigger → choose "Time" → select "At Sunset".
4. Select Action → choose "Call Service" → search "Light: Turn On".
5. Select the light you want to turn on.
6. Click Save.

This automation will trigger every day at sunset and turn on your chosen light.

Example 2: Motion-Activated Light (YAML)

For more advanced automation, you can write YAML. Go to Settings → Automations & Scenes → Automations → Create Automation → Edit in YAML:

alias: Motion-Activated Light
description: "Turn on hallway light when motion is detected"
trigger:
  - platform: state
    entity_id: binary_sensor.hallway_motion
    to: "on"
action:
  - service: light.turn_on
    target:
      entity_id: light.hallway
    data:
      brightness: 200
condition:
  - condition: sun
    after: sunset
    after_offset: "-00:30"
mode: single

This automation:

• Triggers when motion is detected by your motion sensor
• Turns on the hallway light at brightness 200
• Only runs after sunset (prevent false triggers during day)
• Runs in single mode (won't repeat while light is on)

Example 3: Presence-Based Automation

alias: Welcome Home
description: "Turn on lights and play music when someone arrives home"
trigger:
  - platform: state
    entity_id: person.john, person.jane
    to: "home"
    from: "not_home"
action:
  - service: light.turn_on
    target:
      entity_id: light.living_room
  - service: media_player.media_pause
    target:
      entity_id: media_player.office_speaker
  - service: logbook.log
    data:
      name: "Welcome Home"
      message: "Someone arrived home"
condition: []
mode: single

This automation detects when a family member arrives home (using the person entity, which combines GPS from their phone) and turns on lights.

Step 5 — Set Up a Dashboard

Dashboards let you visualize and control your devices. The default dashboard shows all entities, but you can customize it.

Create a Custom Dashboard

1. Go to Dashboard on the left sidebar.
2. Click the three-dot menu → Edit Dashboard.
3. Click Create New Card and choose a card type:
   • Entities — shows switches, lights, sensors
   • Button — trigger automations or services
   • Gauge — display temperature, humidity, etc.
   • History — show sensor data over time

Example Dashboard Configuration (YAML)

Click Edit Dashboard → Edit (pencil icon) and paste this:

title: Home
views:
  - title: Living Room
    cards:
      - type: entities
        title: Lights
        entities:
          - light.living_room
          - light.bedroom
          - light.kitchen
      - type: gauge
        entity: sensor.living_room_temperature
        min: 10
        max: 30
        unit: °C
        segments:
          - from: 10
            color: blue
          - from: 18
            color: green
          - from: 24
            color: orange
          - from: 28
            color: red
      - type: button
        name: "All Lights Off"
        tap_action:
          action: call-service
          service: light.turn_off
          target:
            entity_id: all

This creates a dashboard with:

• Light controls
• A temperature gauge with color zones
• A button to turn off all lights

Docker Installation

If you want to run Home Assistant alongside other services (Plex, Pi-hole, Caddy, etc.), use Docker:

Install Docker on Raspberry Pi

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER
newgrp docker

Docker Compose Setup

Create a file called docker-compose.yml:

version: "3.8"

services:
  home-assistant:
    image: ghcr.io/home-assistant/home-assistant:stable
    container_name: home-assistant
    privileged: true
    restart: unless-stopped
    network_mode: host  # Important for mDNS and device discovery
    ports:
      - "8123:8123"
    environment:
      - TZ=Europe/London  # Set your timezone
    volumes:
      - ./home-assistant:/config
      - /run/dbus:/run/dbus:ro  # For hardware features
    devices:
      - /dev/ttyUSB0:/dev/ttyUSB0  # For Zigbee dongles
      - /dev/ttyUSB1:/dev/ttyUSB1  # For Z-Wave sticks

  mosquitto:
    image: eclipse-mosquitto:latest
    container_name: mosquitto
    restart: unless-stopped
    ports:
      - "1883:1883"
    volumes:
      - ./mosquitto/config:/mosquitto/config
      - ./mosquitto/data:/mosquitto/data

Start with:

docker-compose up -d

Home Assistant will be available at http://localhost:8123/.

Key points:

• network_mode: host allows device discovery (important for Zigbee/Z-Wave)
• /dev/ttyUSB0 and /dev/ttyUSB1 allow USB dongles for wireless protocols
• Volumes persist your configuration across restarts

Zigbee & Z-Wave — Wireless Protocols

Most smart home devices use Zigbee or Z-Wave for wireless communication. Home Assistant can control these with a USB coordinator dongle.

Zigbee

Why Zigbee? Low power, mesh networking, cheap devices (IKEA Trådfri, Xiaomi Aqara, Philips Hue, Innr).

Recommended dongle: Sonoff Zigbee 3.0 USB Dongle Plus (~$15–25), available on Amazon or AliExpress.

Set Up Zigbee2MQTT (Recommended)

1. Add the Zigbee2MQTT add-on:
   • Go to Settings → Add-ons → Add-on Store (bottom right).
   • Search "Zigbee2MQTT".
   • Click Install.
2. Plug your Zigbee dongle into a USB port on the Pi.
3. In add-on config, set the serial port:

   serial:
     port: /dev/ttyUSB0
   

4. Start the add-on.
5. In Home Assistant, go to Settings → Devices & Services → Integrations → search "Zigbee Home Automation" → create.
6. Your Zigbee devices will now auto-discover and appear in Home Assistant.

Z-Wave

Why Z-Wave? More reliable range than Zigbee, popular in North America. Devices are often pricier (Aeotec, Zooz).

Recommended dongle: Aeotec Z-Stick Gen7 (~$40–60).

Setup:

1. Install the Z-Wave JS integration:
   • Go to Settings → Devices & Services → Integrations → Create Automation → search "Z-Wave JS".
2. If using the HA OS add-on, install Z-Wave JS UI from the add-on store.
3. Plug your Z-Wave dongle and configure the serial port.
4. Devices will auto-discover when you press their inclusion button.

Pairing a device:

1. In Z-Wave JS UI, click Actions → Start Inclusion.
2. Press the inclusion button on your Z-Wave device (hold for 3 seconds).
3. Wait for the device to appear in Home Assistant.

Remote Access — Control Your Home Outside the Network

By default, Home Assistant is only accessible on your local network. To access it remotely, you have three options:

Option 1: Nabu Casa (Official Cloud Service)

Simplest option: $5.99/month subscription. Home Assistant cloud handles external access securely.

• Go to Settings → Cloud → click Sign Up or log in.
• All traffic is encrypted end-to-end.
• Works instantly.

Option 2: Tailscale (VPN)

Free for personal use. Secures all traffic and works from anywhere.

1. Install Tailscale on your Raspberry Pi:

   curl -fsSL https://tailscale.com/install.sh | sh
   

2. Authenticate:

   sudo tailscale up
   

3. Access Home Assistant from the Tailscale IP (e.g., http://100.x.x.x:8123/) on any connected device.

Option 3: WireGuard (Self-Hosted VPN)

Most technical but full control. Install WireGuard on your Pi and configure clients on your phone/computer.

For a detailed WireGuard setup, see WireGuard documentation.

Useful Add-ons

Home Assistant has a rich ecosystem of add-ons (standalone services that integrate with HA):

ESPHome

Flash ESP32/ESP8266 boards with custom firmware and integrate them as Home Assistant devices. Perfect for DIY sensors and switches.

Install: Add-on Store → search "ESPHome".

Use case: Build a smart plant watering system or DIY doorbell camera.

Node-RED

Visual programming tool for complex automations and data flows. Better than YAML for advanced logic.

Install: Add-on Store → search "Node-RED".

Use case: Read data from a sensor, transform it, and send to multiple devices.

Mosquitto MQTT Broker

Message broker for MQTT-based devices. Lightweight devices communicate via MQTT to Home Assistant.

Install: Add-on Store → search "Mosquitto broker".

Use case: IoT sensors, weather stations, custom integrations.

File Editor

Web-based editor for configuration files. Useful for editing automations.yaml, secrets.yaml, etc.

Install: Add-on Store → search "File editor".

Troubleshooting

Home Assistant Starts Slowly

Cause: Too many integrations loading at once, slow SD card, insufficient Pi RAM.

Solution:

• Upgrade to a USB SSD (much faster than SD card).
• Disable or remove unused integrations.
• Upgrade to Pi 4 with 4GB+ RAM.
• Check logs: Settings → System → Logs tab.

Zigbee Device Won't Pair

Cause: Device is out of range, coordinator is not in pairing mode, device battery is low.

Solution:

• Move the device closer to the Zigbee dongle.
• Restart the Zigbee2MQTT add-on.
• Check Zigbee2MQTT logs for pairing requests.
• Replace batteries in the device (for battery-powered devices).

Automation Not Triggering

Cause: Condition not met, entity state format is wrong, automation is disabled.

Solution:

• Check automation logs: Settings → Automations & Scenes → click the automation.
• Verify the trigger entity exists: Settings → Devices & Services → Entities.
• Test the automation manually: click the three-dot menu → Test this automation.
• Check entity state format: look at the States page in Developer Tools.

SD Card Corruption / Frequent Crashes

Cause: Cheap or failing SD card, power fluctuations, improper shutdown.

Solution:

• Switch to a USB SSD for better reliability.
• Use an official Raspberry Pi power supply.
• Enable journaling on the filesystem (for non-SSD installs).
• Regularly backup your Home Assistant config: Settings → System → Backup → Create Backup.

Summary

You now have a fully functional, privacy-first smart home running on a Raspberry Pi:

1. Installed Home Assistant OS — the easiest way to get started.
2. Added devices — integrated Zigbee, Z-Wave, or WiFi-based smart home devices.
3. Created automations — from simple UI-based rules to advanced YAML automations.
4. Built a custom dashboard — organized your controls and sensors visually.
5. Learned wireless protocols — Zigbee and Z-Wave for most reliable connectivity.
6. Set up remote access — access your home from anywhere with Tailscale or Nabu Casa.

Home Assistant is incredibly flexible. From here, you can:

• Add more devices — lights, locks, cameras, thermostats, everything.
• Build advanced automations — conditional logic, notifications, voice control.
• Integrate with other services — IFTTT, Webhooks, APIs.
• Create custom integrations — Python-based extensions for niche devices.
• Join the community — forums at community.home-assistant.io are very helpful.

Your Raspberry Pi is now the brain of your smart home, with no cloud dependency, complete privacy, and total control. Happy automating!