# 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