nix-config/docs/modules/homeassistant.md

Home Assistant Module

This document details the Home Assistant module configuration.

Module Structure

The Home Assistant module 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

Module Options

The module is configured through options defined in options.nix:

options.${namespace}.services.home-assistant = {
  enable = mkEnableOption "enable home-assistant";
  mosquittoPort = mkOpt types.int 1883 "Port for MQTT";
  zigbee2mqttPort = mkOpt types.int 8080 "Port for zigbee2mqtt web interface";
  zigbeeDevicePath = mkOpt types.str "/dev/ttyUSB0" "Path to zigbee usb device";
};

Main Configuration

The main module configuration in default.nix includes:

1. Activation Scripts - For setting up custom components
2. Service Configurations - For Matter, PostgreSQL, etc.
3. Firewall Rules - For allowing required ports

config = lib.mkIf cfg.enable {
  # Activation script for custom components
  system.activationScripts.installCustomComponents = ''
    chown -R hass:hass ${config.services.home-assistant.configDir}
    chmod -R 750 ${config.services.home-assistant.configDir}
  '';

  # Service configurations
  services = {
    matter-server.enable = true;
    postgresql = {
      enable = false;
      ensureDatabases = [ "hass" ];
      ensureUsers = [
        {
          name = "hass";
          ensureDBOwnership = true;
        }
      ];
    };
  };

  # Firewall rules
  networking.firewall.allowedTCPPorts = [
    cfg.mosquittoPort
    cfg.zigbee2mqttPort
    8095 # music-assistant
    8097 # home-assistant
    5580 # matter-server
  ];
};

Home Assistant Service

The core Home Assistant service configuration in services/homeassistant/default.nix includes:

1. Package Selection - Using the standard Home Assistant package
2. Component Configuration - Enabling required components
3. Custom Components - Adding custom components from packages
4. Lovelace Modules - Adding custom UI components
5. Integration Configuration - Setting up integrations with other systems

services.home-assistant = {
  enable = true;
  package = pkgs.home-assistant;
  openFirewall = true;
  configDir = "/var/lib/homeassistant";
  configWritable = true;
  
  # Components
  extraComponents = [
    "mqtt"
    "zha"
    "homekit"
    # ... many more components
  ];
  
  # Custom components
  customComponents = [
    # ... custom components
  ];
  
  # Lovelace modules
  customLovelaceModules = [
    # ... custom UI modules
  ];
  
  # Configuration
  config = {
    # ... Home Assistant configuration
  };
};

Related Services

Zigbee2MQTT

The Zigbee2MQTT service in services/zigbee2mqtt/default.nix connects Zigbee devices to MQTT:

services.zigbee2mqtt = {
  enable = true;
  settings = {
    mqtt = {
      server = "mqtt://localhost:${toString cfg.mosquittoPort}";
    };
    serial = {
      port = cfg.zigbeeDevicePath;
    };
    # ... additional settings
  };
};

MQTT

MQTT is configured as a dependency for the Home Assistant module.

Thread Border Router

The Thread Border Router in services/thread/default.nix provides Thread network connectivity for Matter devices.

Automations

The module includes predefined automations in the automations/ directory:

1. Light Switch Automations - For controlling lights via physical switches
2. Motion Light Automations - For motion-activated lighting

Using the Module

To use this module in a system configuration:

{ config, ... }:
{
  mjallen.services.home-assistant = {
    enable = true;
    # Optional: customize ports and device paths
    mosquittoPort = 1883;
    zigbee2mqttPort = 8080;
    zigbeeDevicePath = "/dev/ttyUSB0";
  };
}

Extending the Module

Adding Custom Components

To add a custom component:

1. Add the package to packages/
2. Add it to the customComponents list in services/homeassistant/default.nix

Adding Custom Automations

To add a custom automation:

1. Create a new directory in automations/
2. Implement the automation in default.nix
3. Import it in the system configuration