Wiki major update

updated with recent documentation
2026-01-21 19:18:39 -05:00
parent 30e0481685
commit ef55974b50
98 changed files with 32244 additions and 10 deletions
--- a/wiki/service-docs/home-assistant.md
+++ b/wiki/service-docs/home-assistant.md
@@ -0,0 +1,615 @@
+# 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!