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

Home Assistant Automation Reference

Complete Automation Structure

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:

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:

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

Sun Trigger

Fires at sunrise/sunset:

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

Numeric State Trigger

Fires when sensor value crosses threshold:

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

Template Trigger

Fires when template evaluates to true:

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

Event Trigger

Fires on specific event:

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

Zone Trigger

Fires when device enters/leaves zone:

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:

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

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

Numeric State Condition

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

Time Condition

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

Sun Condition

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

Template Condition

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

Zone Condition

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

Multiple Conditions (AND Logic)

All conditions must be true:

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

OR Conditions

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

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

Multiple Entities

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

Delay

action:
  - delay:
      seconds: 30

Wait for Trigger

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

Conditional Action

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

Choose (If-Then-Else)

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

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

Templates

Use Jinja2 templates for dynamic values:

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.

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