claude-skills/skills/homeassistant/references/automation_reference.md

# Home Assistant Automation Reference

## Complete Automation Structure

```yaml
automation:
  - alias: "Friendly Name for Display"
    id: unique_identifier_123
    description: "Optional description of what this automation does"
    initial_state: true
    mode: single

    variables:
      my_variable: "some_value"

    trigger:
      - trigger: state
        entity_id: binary_sensor.motion_sensor
        to: "on"

    condition:
      - condition: time
        after: "sunset"
        before: "sunrise"

    action:
      - action: light.turn_on
        target:
          entity_id: light.living_room
        data:
          brightness: 255
```

## Required and Optional Fields

### Required
- `trigger` - At least one trigger that initiates the automation

### Optional (Recommended)
- `alias` - Friendly name displayed in UI
- `id` - Unique identifier (essential for UI editor)
- `description` - Documentation of automation purpose
- `action` - Actions to execute (automation does nothing without actions)

### Optional (Advanced)
- `condition` - Conditions that must be true to execute actions
- `mode` - Execution behavior: `single`, `restart`, `queued`, `parallel`
- `max` - Maximum concurrent executions (for `queued`/`parallel` modes)
- `variables` - Variables available throughout automation
- `initial_state` - Whether enabled at startup (`true`/`false`)
- `trace` - Debug trace configuration

## Triggers

Triggers define when an automation runs.

### State Trigger

Fires when entity changes state:

```yaml
trigger:
  - trigger: state
    entity_id: binary_sensor.motion_detector
    from: "off"
    to: "on"
    for:
      seconds: 5  # Optional: state must persist for duration
```

### Time Trigger

Fires at specific time:

```yaml
trigger:
  - trigger: time
    at: "15:30:00"
```

### Sun Trigger

Fires at sunrise/sunset:

```yaml
trigger:
  - trigger: sun
    event: sunset
    offset: "-00:30:00"  # 30 minutes before sunset
```

### Numeric State Trigger

Fires when sensor value crosses threshold:

```yaml
trigger:
  - trigger: numeric_state
    entity_id: sensor.temperature
    above: 25
    below: 30
```

### Template Trigger

Fires when template evaluates to true:

```yaml
trigger:
  - trigger: template
    value_template: "{{ states('sensor.temperature') | float > 25 }}"
```

### Event Trigger

Fires on specific event:

```yaml
trigger:
  - trigger: event
    event_type: custom_event
    event_data:
      action: button_pressed
```

### Zone Trigger

Fires when device enters/leaves zone:

```yaml
trigger:
  - trigger: zone
    entity_id: person.john
    zone: zone.home
    event: enter  # or 'leave'
```

### Multiple Triggers (OR Logic)

List multiple triggers - any one firing will run the automation:

```yaml
trigger:
  - trigger: state
    entity_id: binary_sensor.motion_1
    to: "on"
  - trigger: state
    entity_id: binary_sensor.motion_2
    to: "on"
  - trigger: time
    at: "18:00:00"
```

## Conditions

Conditions must be true for actions to execute.

### State Condition

```yaml
condition:
  - condition: state
    entity_id: light.living_room
    state: "off"
```

### Numeric State Condition

```yaml
condition:
  - condition: numeric_state
    entity_id: sensor.temperature
    below: 20
```

### Time Condition

```yaml
condition:
  - condition: time
    after: "16:00:00"
    before: "23:00:00"
    weekday:
      - mon
      - tue
      - wed
      - thu
      - fri
```

### Sun Condition

```yaml
condition:
  - condition: sun
    after: sunset
    before: sunrise
```

### Template Condition

```yaml
condition:
  - condition: template
    value_template: "{{ states('sensor.battery') | int > 20 }}"
```

### Zone Condition

```yaml
condition:
  - condition: zone
    entity_id: person.john
    zone: zone.home
```

### Multiple Conditions (AND Logic)

All conditions must be true:

```yaml
condition:
  - condition: state
    entity_id: person.john
    state: "home"
  - condition: time
    after: "sunset"
```

### OR Conditions

```yaml
condition:
  - condition: or
    conditions:
      - condition: state
        entity_id: person.john
        state: "home"
      - condition: state
        entity_id: person.mary
        state: "home"
```

## Actions

Actions define what the automation does.

### Call Service

```yaml
action:
  - action: light.turn_on
    target:
      entity_id: light.kitchen
    data:
      brightness: 200
      color_temp: 400
```

### Multiple Entities

```yaml
action:
  - action: light.turn_on
    target:
      entity_id:
        - light.kitchen
        - light.living_room
        - light.bedroom
```

### Delay

```yaml
action:
  - delay:
      seconds: 30
```

### Wait for Trigger

```yaml
action:
  - wait_for_trigger:
      - trigger: state
        entity_id: binary_sensor.motion
        to: "off"
    timeout:
      minutes: 5
```

### Conditional Action

```yaml
action:
  - condition: state
    entity_id: sun.sun
    state: "below_horizon"
  - action: light.turn_on
    target:
      entity_id: light.porch
```

### Choose (If-Then-Else)

```yaml
action:
  - choose:
      - conditions:
          - condition: state
            entity_id: sensor.weather
            state: "sunny"
        sequence:
          - action: cover.open_cover
            target:
              entity_id: cover.blinds
      - conditions:
          - condition: state
            entity_id: sensor.weather
            state: "rainy"
        sequence:
          - action: cover.close_cover
            target:
              entity_id: cover.blinds
    default:
      - action: notify.notify
        data:
          message: "Weather is {{ states('sensor.weather') }}"
```

### Repeat

```yaml
action:
  - repeat:
      count: 3
      sequence:
        - action: light.toggle
          target:
            entity_id: light.hallway
        - delay:
            seconds: 1
```

## Templates

Use Jinja2 templates for dynamic values:

```yaml
action:
  - action: notify.notify
    data:
      message: "Temperature is {{ states('sensor.temperature') }}°C"
      title: "Weather at {{ now().strftime('%H:%M') }}"
```

### Common Template Functions

- `{{ states('entity_id') }}` - Get entity state
- `{{ state_attr('entity_id', 'attribute') }}` - Get entity attribute
- `{{ now() }}` - Current datetime
- `{{ trigger.entity_id }}` - Triggering entity ID
- `{{ trigger.to_state.state }}` - New state value
- `{{ trigger.from_state.state }}` - Old state value

## Execution Modes

- `single` (default) - Only one instance runs at a time. New triggers ignored while running.
- `restart` - Restart automation from beginning when triggered while running.
- `queued` - Queue additional triggers, run them sequentially.
- `parallel` - Allow multiple instances to run simultaneously.

```yaml
mode: parallel
max: 5  # Maximum 5 concurrent executions
```

## Best Practices

1. Always include `id` field for UI editor compatibility
2. Use meaningful `alias` names for easy identification
3. Add `description` to document complex automations
4. Prefer specific triggers over broad templates when possible
5. Use conditions to prevent unnecessary actions
6. Test automations with trace mode enabled
7. Keep automation logic simple - split complex logic into multiple automations or scripts
8. Quote state values: `state: "on"` not `state: on`
9. Use 2-space indentation, no tabs
10. Validate YAML before deploying