616 lines
15 KiB
Markdown
616 lines
15 KiB
Markdown
# Home Assistant - Home Automation Platform
|
|
|
|
## Table of Contents
|
|
- [Overview](#overview)
|
|
- [What is Home Assistant?](#what-is-home-assistant)
|
|
- [Why Use Home Assistant?](#why-use-home-assistant)
|
|
- [Key Concepts](#key-concepts)
|
|
- [Configuration in AI-Homelab](#configuration-in-ai-homelab)
|
|
- [Official Resources](#official-resources)
|
|
- [Educational Resources](#educational-resources)
|
|
- [Docker Configuration](#docker-configuration)
|
|
- [Initial Setup](#initial-setup)
|
|
- [Integrations](#integrations)
|
|
- [Automations](#automations)
|
|
- [Add-ons vs Docker](#add-ons-vs-docker)
|
|
- [Troubleshooting](#troubleshooting)
|
|
- [Advanced Topics](#advanced-topics)
|
|
|
|
## Overview
|
|
|
|
**Category:** Home Automation
|
|
**Docker Image:** [homeassistant/home-assistant](https://hub.docker.com/r/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?
|
|
|
|
1. **Universal Integration:** Control everything from one place
|
|
2. **Local Control:** Works without internet
|
|
3. **Privacy:** Data never leaves your network
|
|
4. **No Cloud Required:** Unlike SmartThings, Alexa routines
|
|
5. **Powerful Automations:** Complex logic possible
|
|
6. **Active Development:** Updates every 3 weeks
|
|
7. **Community:** Massive community support
|
|
8. **Cost:** Free forever, no subscriptions
|
|
9. **Customizable:** Unlimited flexibility
|
|
10. **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
|
|
|
|
```bash
|
|
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
|
|
1. **Everything Smart Home** - https://www.youtube.com/@EverythingSmartHome
|
|
- Best Home Assistant tutorials
|
|
- Device reviews and integrations
|
|
- Automation ideas
|
|
|
|
2. **Smart Home Junkie** - https://www.youtube.com/@SmartHomeJunkie
|
|
- In-depth Home Assistant guides
|
|
- Zigbee, Z-Wave, ESPHome
|
|
- Advanced automations
|
|
|
|
3. **Intermit.Tech** - https://www.youtube.com/@intermittechnology
|
|
- Technical deep dives
|
|
- Docker Home Assistant setup
|
|
- Integration tutorials
|
|
|
|
4. **BeardedTinker** - https://www.youtube.com/@BeardedTinker
|
|
- German/English tutorials
|
|
- Creative automation ideas
|
|
- Device comparisons
|
|
|
|
### Articles & Guides
|
|
1. **Official Getting Started:** https://www.home-assistant.io/getting-started
|
|
2. **Home Assistant Course:** https://www.home-assistant.io/course
|
|
3. **Community Guides:** https://community.home-assistant.io/c/guides/37
|
|
|
|
### Books
|
|
1. **"Home Assistant Cookbook"** by Marco Bruni
|
|
2. **"Practical Home Assistant"** by Alan Tse
|
|
|
|
## Docker Configuration
|
|
|
|
```yaml
|
|
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
|
|
|
|
1. **Start Container:**
|
|
```bash
|
|
docker compose up -d home-assistant
|
|
```
|
|
|
|
2. **Access UI:** `http://SERVER_IP:8123`
|
|
|
|
3. **Create Account:**
|
|
- Name, username, password
|
|
- This is your admin account
|
|
- Secure password required
|
|
|
|
4. **Set Location:**
|
|
- Used for weather, sun position
|
|
- Important for automations
|
|
|
|
5. **Scan for Devices:**
|
|
- Home Assistant auto-discovers many devices
|
|
- Check discovered integrations
|
|
|
|
6. **Install HACS (Highly Recommended):**
|
|
|
|
HACS provides thousands of community integrations and themes.
|
|
|
|
```bash
|
|
# 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:**
|
|
1. Settings → Devices & Services
|
|
2. "+ Add Integration"
|
|
3. Search for integration
|
|
4. Follow setup wizard
|
|
|
|
**YAML Method (configuration.yaml):**
|
|
```yaml
|
|
# Example: MQTT
|
|
mqtt:
|
|
broker: mosquitto
|
|
port: 1883
|
|
username: !secret mqtt_user
|
|
password: !secret mqtt_pass
|
|
```
|
|
|
|
## Automations
|
|
|
|
### Visual Editor
|
|
|
|
1. **Settings → Automations & Scenes → Create Automation**
|
|
|
|
2. **Choose Trigger:**
|
|
- Time
|
|
- Device state change
|
|
- Numeric state (temperature > 75°F)
|
|
- Event
|
|
- Webhook
|
|
|
|
3. **Add Conditions (Optional):**
|
|
- Time of day
|
|
- Day of week
|
|
- Device states
|
|
- Numeric comparisons
|
|
|
|
4. **Choose Actions:**
|
|
- Turn on/off devices
|
|
- Send notifications
|
|
- Call services
|
|
- Delays
|
|
- Repeat actions
|
|
|
|
### YAML Automations
|
|
|
|
**Example: Motion-Activated Lights**
|
|
|
|
```yaml
|
|
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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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:**
|
|
```bash
|
|
# 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:**
|
|
```yaml
|
|
mqtt_user: homeassistant
|
|
mqtt_pass: your_secure_password
|
|
api_key: abc123xyz789
|
|
```
|
|
|
|
**configuration.yaml:**
|
|
```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:**
|
|
1. HACS → Integrations
|
|
2. Search for integration
|
|
3. Download
|
|
4. Restart Home Assistant
|
|
5. Add integration via UI
|
|
|
|
### Templating
|
|
|
|
Jinja2 templates for dynamic values:
|
|
|
|
```yaml
|
|
# 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!
|