nix-config/docs/home-assistant

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:

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:

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