# 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`:

```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

```nix
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

```nix
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:

```nix
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:

```nix
{ 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