188 lines
5.5 KiB
Markdown
Executable File
188 lines
5.5 KiB
Markdown
Executable File
# 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 |