ha

2026-02-10 19:44:35 -06:00
parent 09d9b010b7
commit 535fdc2f86
18 changed files with 2646 additions and 389 deletions
--- a/docs/home-assistant/README.md
+++ b/docs/home-assistant/README.md
@@ -0,0 +1,188 @@
+# Home Assistant Configuration
+
+This document provides comprehensive information about the Home Assistant setup in this NixOS configuration.
+
+## Overview
+
+Home Assistant is configured as a NixOS service with custom components, integrations, and automations. The configuration uses a modular approach with separate files for different aspects of the setup.
+
+## Module Structure
+
+The Home Assistant configuration is organized in the following structure:
+
+```
+modules/nixos/homeassistant/
+├── automations/              # Automation configurations
+│   ├── lightswitch/          # Light switch automations
+│   └── motion-light/         # Motion-activated light automations
+├── default.nix               # Main module configuration
+├── options.nix               # Module options definition
+└── services/                 # Related service configurations
+    ├── govee2mqtt/           # Govee integration via MQTT
+    ├── homeassistant/        # Core Home Assistant service
+    ├── music-assistant/      # Music Assistant integration
+    ├── thread/               # Thread border router
+    └── zigbee2mqtt/          # Zigbee to MQTT bridge
+```
+
+## Installation
+
+The Home Assistant module is enabled in the system configuration by setting:
+
+```nix
+mjallen.services.home-assistant.enable = true;
+```
+
+This activates Home Assistant and related services such as MQTT, Zigbee2MQTT, and the Matter server.
+
+## Configuration Options
+
+The module provides several configuration options:
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `enable` | boolean | `false` | Enable Home Assistant and related services |
+| `mosquittoPort` | integer | `1883` | Port for the MQTT broker |
+| `zigbee2mqttPort` | integer | `8080` | Port for the Zigbee2MQTT web interface |
+| `zigbeeDevicePath` | string | `/dev/ttyUSB0` | Path to the Zigbee USB device |
+
+## Core Services
+
+### Home Assistant
+
+The main Home Assistant service is configured in `services/homeassistant/default.nix` with:
+
+- PostgreSQL database backend
+- Custom components
+- Custom Lovelace modules
+- HTTPS access with authentication
+- Integration with other services
+
+### MQTT
+
+MQTT is used as a messaging protocol for various smart home devices. The Mosquitto MQTT broker is automatically configured when Home Assistant is enabled.
+
+### Zigbee2MQTT
+
+Zigbee2MQTT allows integration with Zigbee devices. It's configured with:
+
+- Automatic discovery for Home Assistant
+- OTA updates for Zigbee devices
+- Web interface for management
+
+### Thread Border Router
+
+The Thread Border Router provides integration with Thread-based devices like Matter devices.
+
+## Custom Components
+
+The following custom components are included:
+
+- `ha-anycubic` - Anycubic 3D printer integration
+- `ha-bambulab` - Bambu Lab 3D printer integration
+- `ha-bedjet` - BedJet climate control integration
+- `ha-gehome` - GE Home appliance integration
+- `ha-icloud3` - Enhanced iCloud device tracking
+- `ha-local-llm` - Local LLM integration
+- `ha-mail-and-packages` - Mail and package delivery tracking
+- `ha-nanokvm` - NanoKVM integration
+- `ha-openhasp` - openHASP integration for DIY displays
+- `ha-overseerr` - Overseerr media request integration
+- `ha-petlibro` - PetLibro pet feeder integration
+- `ha-wyzeapi` - Wyze device integration
+
+## Automations
+
+### Light Switch Automations
+
+The light switch automations handle physical switch inputs for controlling smart lights.
+
+### Motion Light Automations
+
+Motion light automations turn lights on when motion is detected and off after a period of inactivity.
+
+### Custom Automations
+
+Additional automations are placed in the `/etc/hass` directory and are included in the Home Assistant configuration. These include:
+
+- `fountain_automation.yaml` - Toggles the water dispensing mode on the Dockstream Smart RFID Fountain every 15 minutes between constant and intermittent flow.
+
+## Smart Home Devices
+
+The configuration includes support for various smart home devices:
+
+### Lighting
+
+- Various smart lights throughout the home
+
+### Climate
+
+- Smart thermostat
+- Humidifier control
+
+### Pet Care
+
+- Dockstream Smart RFID Fountain with scheduling
+- Smart pet feeders for pets named Joey and Luci
+- Litter-Robot 4 smart litter box
+
+### Media
+
+- Google Cast devices
+- Smart TVs
+- Media players
+
+### Sensors
+
+- Temperature, humidity, and motion sensors
+- Door and window sensors
+- Presence detection
+
+## Integration with Other Services
+
+Home Assistant is integrated with:
+
+- **Music Assistant** - For enhanced music streaming capabilities
+- **Govee Integration** - For Govee smart devices
+- **Matter** - For Matter-compatible devices
+
+## Adding New Automations
+
+To add a new automation:
+
+1. Create a YAML file with the automation definition
+2. Place it in `/etc/hass`
+3. The automation will be automatically included in Home Assistant
+
+Example automation format:
+
+```yaml
+alias: "Automation Name"
+description: "Description of what the automation does"
+trigger:
+  - platform: state
+    entity_id: binary_sensor.motion_sensor
+    to: "on"
+condition: []
+action:
+  - service: light.turn_on
+    target:
+      entity_id: light.living_room
+mode: single
+```
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Zigbee Device Pairing Issues**
+   - Make sure the Zigbee coordinator is properly connected
+   - Check the Zigbee2MQTT logs for errors
+
+2. **Service Unavailable**
+   - Check if all related services are running
+   - Verify firewall rules allow access to the services
+
+3. **Database Issues**
+   - Check PostgreSQL service status
+   - Verify database connection settings