Add homeassistant skill in unpacked format
- Add complete homeassistant skill source to skills/ directory - Includes all scripts, references, and automation templates - Matches format of other skills in repository
This commit is contained in:
Felix Zösch
389
skills/homeassistant/references/automation_reference.md
Normal file
389
skills/homeassistant/references/automation_reference.md
Normal file
@@ -0,0 +1,389 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user