Files

kelinfoxy ef55974b50 Wiki major update

updated with recent documentation

2026-01-21 19:18:39 -05:00

15 KiB

Raw Blame History

Home Assistant - Home Automation Platform

Overview
What is Home Assistant?
Why Use Home Assistant?
Key Concepts
Configuration in AI-Homelab
Official Resources
Educational Resources
Docker Configuration
Initial Setup
Integrations
Automations
Add-ons vs Docker
Troubleshooting
Advanced Topics

Overview

Category: Home Automation
Docker Image: homeassistant/home-assistant
Default Stack: homeassistant.yml
Web UI: https://homeassistant.${DOMAIN} or http://SERVER_IP:8123
Ports: 8123
Network Mode: host (for device discovery)

What is Home Assistant?

Home Assistant is a free, open-source home automation platform that focuses on local control and privacy. It integrates thousands of different devices and services, allowing you to automate and control your entire smart home from a single interface. Unlike cloud-based solutions, Home Assistant runs entirely locally on your network.

Key Features

2000+ Integrations: Supports virtually every smart device
Local Control: Works without internet
Privacy Focused: Your data stays home
Powerful Automations: Visual and YAML-based
Voice Control: Alexa, Google, Siri compatibility
Energy Monitoring: Track usage and solar
Mobile Apps: iOS and Android
Dashboards: Customizable UI
Community: Huge active community
Free & Open Source: No subscriptions

Why Use Home Assistant?

Universal Integration: Control everything from one place
Local Control: Works without internet
Privacy: Data never leaves your network
No Cloud Required: Unlike SmartThings, Alexa routines
Powerful Automations: Complex logic possible
Active Development: Updates every 3 weeks
Community: Massive community support
Cost: Free forever, no subscriptions
Customizable: Unlimited flexibility
Future-Proof: Open-source ensures longevity

Key Concepts

Entities

The basic building blocks of Home Assistant:

Sensors: Temperature, humidity, power usage
Switches: On/off devices
Lights: Brightness, color control
Binary Sensors: Motion, door/window sensors
Climate: Thermostats
Cameras: Video feeds
Media Players: Speakers, TVs

Integrations

Connections to devices and services:

Zigbee2MQTT: Zigbee devices
ESPHome: Custom ESP devices
MQTT: Message broker protocol
HACS: Community store
Tasmota: Flashed smart plugs
UniFi: Network devices
Plex/Jellyfin: Media servers

Automations

Triggered actions:

Trigger: What starts the automation
Condition: Requirements to continue
Action: What happens

Example: Motion detected → If after sunset → Turn on lights

Scripts

Reusable action sequences:

Manual execution
Called from automations
Parameterized

Scenes

Saved states of devices:

"Movie Time" → Dims lights, closes blinds
"Good Night" → Turns off everything
One-click activation

Configuration in AI-Homelab

Directory Structure

/opt/stacks/homeassistant/home-assistant/config/
  configuration.yaml      # Main config
  automations.yaml       # Automations
  scripts.yaml           # Scripts
  secrets.yaml           # Sensitive data
  custom_components/     # HACS and custom integrations
  www/                   # Custom resources
  blueprints/            # Automation blueprints

Environment Variables

TZ=America/New_York

Network Mode: host

Home Assistant uses network_mode: host instead of bridge networking. This is required for:

Device Discovery: mDNS, UPnP, SSDP
Casting: Chromecast, Google Home
HomeKit: Apple HomeKit bridge
DLNA: Media device discovery

Trade-off: Can't use Traefik routing easily. Typically accessed via IP:8123 or DNS record pointing to server IP.

Official Resources

Website: https://www.home-assistant.io
Documentation: https://www.home-assistant.io/docs
Community: https://community.home-assistant.io
GitHub: https://github.com/home-assistant/core
YouTube: https://www.youtube.com/@homeassistant

Educational Resources

YouTube Channels

Everything Smart Home - https://www.youtube.com/@EverythingSmartHome
- Best Home Assistant tutorials
- Device reviews and integrations
- Automation ideas
Smart Home Junkie - https://www.youtube.com/@SmartHomeJunkie
- In-depth Home Assistant guides
- Zigbee, Z-Wave, ESPHome
- Advanced automations
Intermit.Tech - https://www.youtube.com/@intermittechnology
- Technical deep dives
- Docker Home Assistant setup
- Integration tutorials
BeardedTinker - https://www.youtube.com/@BeardedTinker
- German/English tutorials
- Creative automation ideas
- Device comparisons

Articles & Guides

Official Getting Started: https://www.home-assistant.io/getting-started
Home Assistant Course: https://www.home-assistant.io/course
Community Guides: https://community.home-assistant.io/c/guides/37

Books

"Home Assistant Cookbook" by Marco Bruni
"Practical Home Assistant" by Alan Tse

Docker Configuration

home-assistant:
  image: homeassistant/home-assistant:latest
  container_name: home-assistant
  restart: unless-stopped
  network_mode: host
  privileged: true  # For USB devices (Zigbee/Z-Wave sticks)
  environment:
    - TZ=America/New_York
  volumes:
    - /opt/stacks/homeassistant/home-assistant/config:/config
    - /etc/localtime:/etc/localtime:ro
    - /run/dbus:/run/dbus:ro  # For Bluetooth
  devices:
    - /dev/ttyUSB0:/dev/ttyUSB0  # Zigbee coordinator (if present)
  labels:
    - "com.centurylinklabs.watchtower.enable=false"  # Manual updates recommended

Note: network_mode: host means no Traefik routing. Access via server IP.

Initial Setup

Start Container:
```
docker compose up -d home-assistant
```
Access UI: http://SERVER_IP:8123
Create Account:
- Name, username, password
- This is your admin account
- Secure password required
Set Location:
- Used for weather, sun position
- Important for automations
Scan for Devices:
- Home Assistant auto-discovers many devices
- Check discovered integrations
Install HACS (Highly Recommended):

HACS provides thousands of community integrations and themes.
```
# Access container
docker exec -it home-assistant bash

# Download HACS
wget -O - https://get.hacs.xyz | bash -

# Restart Home Assistant
exit
docker restart home-assistant
```
Then in UI:
- Settings → Devices & Services → Add Integration
- Search "HACS"
- Authorize with GitHub account
- HACS now available in sidebar

Integrations

Essential Integrations

Zigbee2MQTT:

Connect Zigbee devices
Requires Zigbee coordinator USB stick
See zigbee2mqtt.md documentation

ESPHome:

Custom ESP8266/ESP32 devices
Flashed smart plugs, sensors
See esphome.md documentation

MQTT:

Message broker for IoT devices
Connects Zigbee2MQTT, Tasmota
See mosquitto.md documentation

Mobile App:

iOS/Android apps
Location tracking
Notifications
Remote access

Media Integrations:

Plex/Jellyfin: Media controls
Spotify: Music control
Sonos: Speaker control

Network Integrations:

UniFi: Device tracking
Pi-hole: Stats and control
Wake on LAN: Turn on computers

Adding Integrations

UI Method:

Settings → Devices & Services
"+ Add Integration"
Search for integration
Follow setup wizard

YAML Method (configuration.yaml):

# Example: MQTT
mqtt:
  broker: mosquitto
  port: 1883
  username: !secret mqtt_user
  password: !secret mqtt_pass

Automations

Visual Editor

Settings → Automations & Scenes → Create Automation
Choose Trigger:
- Time
- Device state change
- Numeric state (temperature > 75°F)
- Event
- Webhook
Add Conditions (Optional):
- Time of day
- Day of week
- Device states
- Numeric comparisons
Choose Actions:
- Turn on/off devices
- Send notifications
- Call services
- Delays
- Repeat actions

YAML Automations

Example: Motion-Activated Lights

automation:
  - alias: "Hallway Motion Lights"
    description: "Turn on hallway lights when motion detected after sunset"
    trigger:
      - platform: state
        entity_id: binary_sensor.hallway_motion
        to: "on"
    condition:
      - condition: sun
        after: sunset
    action:
      - service: light.turn_on
        target:
          entity_id: light.hallway
        data:
          brightness_pct: 75
      - delay:
          minutes: 5
      - service: light.turn_off
        target:
          entity_id: light.hallway

Automation Ideas

Security:

Notify if door opens when away
Flash lights if motion detected at night
Send camera snapshot on doorbell press

Comfort:

Adjust thermostat based on presence
Close blinds when sunny
Turn on fan if temperature > X

Energy:

Turn off devices at bedtime
Disable charging when battery full
Monitor and alert high usage

Media:

Dim lights when movie starts
Pause media on doorbell
Resume after phone call

Add-ons vs Docker

Home Assistant OS (not used in AI-Homelab) includes an "Add-ons" system. Since AI-Homelab uses Docker directly, we deploy services as separate containers instead:

Add-on	AI-Homelab Docker Service
Mosquitto Broker	mosquitto container
Zigbee2MQTT	zigbee2mqtt container
ESPHome	esphome container
Node-RED	node-red container
File Editor	code-server container

Advantages of Docker Approach:

More control
Easier backups
Standard Docker tools
Better resource management

Disadvantage:

Manual integration setup (vs automatic with add-ons)

Troubleshooting

Container Won't Start

# Check logs
docker logs home-assistant

# Common issue: Port 8123 in use
sudo netstat -tulpn | grep 8123

# Check config syntax
docker exec home-assistant python -m homeassistant --script check_config

Configuration Errors

# Validate configuration
# Settings → System → Check Configuration

# Or via command line:
docker exec home-assistant python -m homeassistant --script check_config

# View specific file
docker exec home-assistant cat /config/configuration.yaml

Integration Not Working

# Check logs for integration
# Settings → System → Logs
# Filter by integration name

# Reload integration
# Settings → Devices & Services → Integration → Reload

# Remove and re-add if persistent
# Settings → Devices & Services → Integration → Delete
# Then add again

USB Device Not Found

# List USB devices
ls -la /dev/ttyUSB*
ls -la /dev/ttyACM*

# Check device is passed to container
docker exec home-assistant ls -la /dev/

# Verify permissions
ls -la /dev/ttyUSB0

# Add user to dialout group (host)
sudo usermod -aG dialout kelin
# Restart

# Or set permissions in docker-compose
devices:
  - /dev/ttyUSB0:/dev/ttyUSB0

Slow Performance

# Check recorder size
docker exec -it home-assistant bash
ls -lh /config/home-assistant_v2.db

# If large (>1GB), purge old data
# In UI: Settings → System → Repair → Database
# Or configure in configuration.yaml:

recorder:
  purge_keep_days: 7
  commit_interval: 5

Advanced Topics

Backup Strategy

Manual Backup:

# Stop container
docker stop home-assistant

# Backup config directory
tar -czf ha-backup-$(date +%Y%m%d).tar.gz \
  /opt/stacks/homeassistant/home-assistant/config/

# Start container
docker start home-assistant

Automated Backup: Use Home Assistant's built-in backup (Settings → System → Backups), or setup scheduled backups with the Backrest service in utilities stack.

Secrets Management

Keep passwords out of configuration:

secrets.yaml:

mqtt_user: homeassistant
mqtt_pass: your_secure_password
api_key: abc123xyz789

configuration.yaml:

mqtt:
  username: !secret mqtt_user
  password: !secret mqtt_pass

weather:
  - platform: openweathermap
    api_key: !secret api_key

Custom Components (HACS)

Thousands of community integrations:

Popular HACS Integrations:

Browser Mod: Control browser tabs
Frigate: NVR integration
Adaptive Lighting: Circadian-based lighting
Alexa Media Player: Advanced Alexa control
Waste Collection Schedule: Trash reminders
Grocy: Grocery management

Install from HACS:

HACS → Integrations
Search for integration
Download
Restart Home Assistant
Add integration via UI

Templating

Jinja2 templates for dynamic values:

# Get temperature difference
{{ states('sensor.outside_temp') | float - states('sensor.inside_temp') | float }}

# Conditional message
{% if is_state('person.john', 'home') %}
  John is home
{% else %}
  John is away
{% endif %}

# Count open windows
{{ states.binary_sensor | selectattr('entity_id', 'search', 'window')
   | selectattr('state', 'eq', 'on') | list | count }}

Voice Control

Alexa:

Settings → Integrations → Alexa
Expose entities to Alexa
"Alexa, turn on living room lights"

Google Assistant:

Requires Home Assistant Cloud ($6.50/month) or manual setup
Or use Nabu Casa Cloud for easy setup

Local Voice:

New feature (2023+)
Wake word detection
Runs fully local
Requires USB microphone

Node-RED Integration

Visual automation builder:

More flexible than HA automations
Drag-and-drop flow-based
See node-red.md documentation

Connect to HA:

Install node-red-contrib-home-assistant-websocket
Configure Home Assistant server
Long-lived access token

Summary

Home Assistant is the ultimate home automation platform offering:

2000+ device integrations
Local control and privacy
Powerful automations
Voice control
Energy monitoring
Mobile apps
Active community
Free and open-source

Perfect for:

Smart home enthusiasts
Privacy-conscious users
DIY home automation
Multi-brand device integration
Complex automation needs
Energy monitoring

Key Points:

Runs entirely locally
Works without internet
Massive device support
3-week release cycle
HACS for community add-ons
Mobile apps available
No subscriptions required

Remember:

Install HACS for extra integrations
Use secrets.yaml for passwords
Regular backups important
Community forum is helpful
Updates every 3 weeks
Read changelogs before updating

Home Assistant gives you complete control of your smart home!

15 KiB Raw Blame History

Home Assistant - Home Automation Platform

Table of Contents

Overview

What is Home Assistant?

Key Features

Why Use Home Assistant?

Key Concepts

Entities

Integrations

Automations

Scripts

Scenes

Configuration in AI-Homelab

Directory Structure

Environment Variables

Network Mode: host

Official Resources

Educational Resources

YouTube Channels

Articles & Guides

Books

Docker Configuration

Initial Setup

Integrations

Essential Integrations

Adding Integrations

Automations

Visual Editor

YAML Automations

Automation Ideas

Add-ons vs Docker

Troubleshooting

Container Won't Start

Configuration Errors

Integration Not Working

USB Device Not Found

Slow Performance

Advanced Topics

Backup Strategy

Secrets Management

Custom Components (HACS)

Templating

Voice Control

Node-RED Integration

Summary

15 KiB

Raw Blame History