ha

2026-02-10 19:44:35 -06:00
parent 09d9b010b7
commit 535fdc2f86
18 changed files with 2646 additions and 389 deletions
--- a/docs/home-assistant/automations.md
+++ b/docs/home-assistant/automations.md
@@ -0,0 +1,148 @@
+# Home Assistant Automations
+
+This document details the automations configured in the Home Assistant setup.
+
+## Automation Types
+
+Automations in this configuration are managed in several ways:
+
+1. **Module-Based Automations**: Defined in Nix modules within the `modules/nixos/homeassistant/automations/` directory
+2. **YAML Automations**: Defined in YAML files and included via the `automation manual` directive
+3. **UI-Created Automations**: Created through the Home Assistant UI and stored in `automations.yaml`
+
+## Module-Based Automations
+
+### Light Switch Automations
+
+**Location**: `modules/nixos/homeassistant/automations/lightswitch/`
+
+These automations link physical light switches to smart lights:
+
+- **Bedroom Light Switch**: Controls the bedroom lights
+- **Living Room Light Switch**: Controls the living room lights
+- **Bedroom Closet Lights**: Controls the closet lights
+
+### Motion-Activated Light Automations
+
+**Location**: `modules/nixos/homeassistant/automations/motion-light/`
+
+These automations turn lights on when motion is detected and off after a period of inactivity.
+
+## YAML Automations
+
+### Fountain Cycling Automation
+
+**Location**: `/etc/nixos/fountain_automation.yaml`
+
+This automation toggles the water dispensing mode on the Dockstream Smart RFID Fountain every 15 minutes:
+
+```yaml
+alias: "Fountain Cycle Mode"
+description: "Toggles fountain water mode every 15 minutes between constant and intermittent flow"
+trigger:
+  - platform: time_pattern
+    minutes: "/15"  # Every 15 minutes
+condition: []
+action:
+  - service: select.select_next
+    target:
+      entity_id: select.dockstream_smart_rfid_fountain_water_dispensing_mode
+mode: single
+id: fountain_cycle_mode
+```
+
+This automation:
+1. Triggers every 15 minutes
+2. Uses the `select.select_next` service to toggle between the two available options:
+   - "Flowing Water (Constant)"
+   - "Intermittent Water (Scheduled)"
+
+The fountain is also configured with:
+- Water Interval: 10 minutes
+- Water Dispensing Duration: 15 minutes
+
+## Creating New Automations
+
+### Method 1: Module-Based Automation
+
+For reusable, complex automations that should be managed in code:
+
+1. Create a new directory in `modules/nixos/homeassistant/automations/`
+2. Create a `default.nix` file with the automation logic
+
+Example:
+```nix
+{ config, lib, ... }:
+{
+  config = {
+    services.home-assistant.config."automation manual" = [
+      {
+        alias = "Example Automation";
+        description = "Example automation created via Nix module";
+        trigger = [
+          {
+            platform = "state";
+            entity_id = "binary_sensor.example_sensor";
+            to = "on";
+          }
+        ];
+        action = [
+          {
+            service = "light.turn_on";
+            target.entity_id = "light.example_light";
+          }
+        ];
+        mode = "single";
+      }
+    ];
+  };
+}
+```
+
+### Method 2: YAML Automation
+
+For simpler automations:
+
+1. Create a YAML file with the automation definition
+2. Place it in `/etc/hass/`
+
+Example:
+```yaml
+alias: "Example Automation"
+description: "Example automation in YAML"
+trigger:
+  - platform: state
+    entity_id: binary_sensor.example_sensor
+    to: "on"
+action:
+  - service: light.turn_on
+    target:
+      entity_id: light.example_light
+mode: single
+```
+
+### Method 3: UI Creation
+
+For quick prototyping or simple automations:
+
+1. Go to Home Assistant UI > Settings > Automations & Scenes
+2. Click "+ Add Automation"
+3. Configure using the UI editor
+
+## Testing Automations
+
+To test an automation:
+
+1. In the Home Assistant UI, go to Developer Tools > Services
+2. Select `automation.trigger` as the service
+3. Enter the entity_id of your automation in the service data field
+4. Click "Call Service" to trigger the automation manually
+
+## Troubleshooting
+
+If an automation isn't working as expected:
+
+1. Check the Home Assistant logs for errors
+2. Verify entity names and service calls are correct
+3. Test individual triggers and actions separately
+4. Use the "Debug" section in the automation editor to trace execution