ha

2026-02-10 19:44:35 -06:00
parent 09d9b010b7
commit 535fdc2f86
18 changed files with 2646 additions and 389 deletions
--- a/docs/modules/homeassistant.md
+++ b/docs/modules/homeassistant.md
@@ -0,0 +1,190 @@
+# 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