# 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