mirror of
https://github.com/home-assistant/home-assistant.io.git
synced 2025-06-22 18:17:02 +00:00
272 lines
9.4 KiB
Markdown
272 lines
9.4 KiB
Markdown
---
|
|
title: "Automation YAML"
|
|
description: "How to use the automation integration with YAML."
|
|
---
|
|
|
|
Automations are created in Home Assistant via the UI, but are stored in a YAML format. If you want to edit the YAML of an automation, go to edit the automation, click on the menu button in the top right and turn on YAML mode.
|
|
|
|
The UI will write your automations to `automations.yaml`. This file is managed by the UI and should not be edited manually.
|
|
|
|
It is also possible to write your automations directly inside `configuration.yaml` or other YAML files. You can do this by adding a labeled `automation` block to your `configuration.yaml`:
|
|
|
|
```yaml
|
|
# The configuration required for the UI to work
|
|
automation: !include automations.yaml
|
|
|
|
# Labeled automation block
|
|
automation kitchen:
|
|
- trigger:
|
|
- platform: ...
|
|
```
|
|
|
|
You can add as many labeled `automation` blocks as you want.
|
|
|
|
{% configuration %}
|
|
alias:
|
|
description: Friendly name for the automation.
|
|
required: false
|
|
type: string
|
|
id:
|
|
description: A unique id for your automation, will allow you to make changes to the name and entity_id in the UI, and will enable debug traces.
|
|
required: false
|
|
type: string
|
|
description:
|
|
description: A description of the automation.
|
|
required: false
|
|
default: ''
|
|
type: string
|
|
initial_state:
|
|
description: Used to define the state of your automation at startup. When not set, the state will be restored from the last run. See [Automation initial state](#automation-initial-state).
|
|
required: false
|
|
type: boolean
|
|
default: Restored from last run
|
|
trace:
|
|
description: "Configuration values for the traces stored, currently only `stored_traces` can be configured."
|
|
required: false
|
|
default: {}
|
|
type: map
|
|
keys:
|
|
stored_traces:
|
|
description: "The number of traces which will be stored. See [Number of debug traces stored](#number-of-debug-traces-stored)."
|
|
type: integer
|
|
default: 5
|
|
required: false
|
|
variables:
|
|
description: "Variables that will be available inside your templates, both in `condition` and `action`."
|
|
required: false
|
|
default: {}
|
|
type: map
|
|
keys:
|
|
PARAMETER_NAME:
|
|
description: "The value of the variable. Any YAML is valid. Templates can also be used to pass a value to the variable."
|
|
type: any
|
|
trigger_variables:
|
|
description: "Variables that will be available inside your [templates triggers](/docs/automation/trigger/#template-trigger)."
|
|
required: false
|
|
default: {}
|
|
type: map
|
|
keys:
|
|
PARAMETER_NAME:
|
|
description: "The value of the variable. Any YAML is valid. Only [limited templates](/docs/configuration/templating/#limited-templates) can be used."
|
|
type: any
|
|
mode:
|
|
description: "Controls what happens when the automation is invoked while it is still running from one or more previous invocations. See [Automation Modes](#automation-modes)."
|
|
required: false
|
|
type: string
|
|
default: single
|
|
max:
|
|
description: "Controls maximum number of runs executing and/or queued up to run at a time. Only valid with modes `queued` and `parallel`."
|
|
required: false
|
|
type: integer
|
|
default: 10
|
|
max_exceeded:
|
|
description: "When `max` is exceeded (which is effectively 1 for `single` mode) a log message will be emitted to indicate this has happened. This option controls the severity level of that log message. See [Log Levels](/integrations/logger/#log-levels) for a list of valid options. Or `silent` may be specified to suppress the message from being emitted."
|
|
required: false
|
|
type: string
|
|
default: warning
|
|
trigger:
|
|
description: "The trigger(s) which will start the automation. Multiple triggers can be added and the automation will start when any of these triggers trigger."
|
|
required: true
|
|
type: list
|
|
keys:
|
|
id:
|
|
description: "An ID that can be used in the automation to determine which trigger caused the automation to start."
|
|
type: string
|
|
required: false
|
|
variables:
|
|
description: "Variables that will be available in the conditions and action sequence."
|
|
required: false
|
|
default: {}
|
|
type: map
|
|
keys:
|
|
PARAMETER_NAME:
|
|
description: "The value of the variable. Any YAML is valid. Templates can also be used to pass a value to the variable."
|
|
type: any
|
|
condition:
|
|
description: Conditions that have to be `true` to start the automation. By default all conditions listed have to be `true`, you can use [logical conditions](/docs/scripts/conditions/#logical-conditions) to change this default behavior.
|
|
required: false
|
|
type: list
|
|
action:
|
|
description: "The sequence of actions to be performed in the script."
|
|
required: true
|
|
type: list
|
|
{% endconfiguration %}
|
|
|
|
### Automation Modes
|
|
|
|
Mode | Description
|
|
-|-
|
|
`single` | Do not start a new run. Issue a warning.
|
|
`restart` | Start a new run after first stopping previous run.
|
|
`queued` | Start a new run after all previous runs complete. Runs are guaranteed to execute in the order they were queued.
|
|
`parallel` | Start a new, independent run in parallel with previous runs.
|
|
|
|
<p class='img'>
|
|
<img src='/images/integrations/script/script_modes.jpg'>
|
|
</p>
|
|
|
|
|
|
|
|
## YAML Example
|
|
|
|
Example of a YAML based automation that you can add to `configuration.yaml`.
|
|
|
|
{% raw %}
|
|
|
|
```yaml
|
|
# Example of entry in configuration.yaml
|
|
automation my_lights:
|
|
# Turns on lights 1 hour before sunset if people are home
|
|
# and if people get home between 16:00-23:00
|
|
- alias: "Rule 1 Light on in the evening"
|
|
trigger:
|
|
# Prefix the first line of each trigger configuration
|
|
# with a '-' to enter multiple
|
|
- platform: sun
|
|
event: sunset
|
|
offset: "-01:00:00"
|
|
- platform: state
|
|
entity_id: all
|
|
to: "home"
|
|
condition:
|
|
# Prefix the first line of each condition configuration
|
|
# with a '-'' to enter multiple
|
|
- condition: state
|
|
entity_id: all
|
|
state: "home"
|
|
- condition: time
|
|
after: "16:00:00"
|
|
before: "23:00:00"
|
|
action:
|
|
# With a single service call, we don't need a '-' before service - though you can if you want to
|
|
- service: homeassistant.turn_on
|
|
target:
|
|
entity_id: group.living_room
|
|
|
|
# Turn off lights when everybody leaves the house
|
|
- alias: "Rule 2 - Away Mode"
|
|
trigger:
|
|
- platform: state
|
|
entity_id: all
|
|
to: "not_home"
|
|
action:
|
|
- service: light.turn_off
|
|
target:
|
|
entity_id: all
|
|
|
|
# Notify when Paulus leaves the house in the evening
|
|
- alias: "Leave Home notification"
|
|
trigger:
|
|
- platform: zone
|
|
event: leave
|
|
zone: zone.home
|
|
entity_id: device_tracker.paulus
|
|
condition:
|
|
- condition: time
|
|
after: "20:00"
|
|
action:
|
|
- service: notify.notify
|
|
data:
|
|
message: "Paulus left the house"
|
|
|
|
# Send a notification via Pushover with the event of a Xiaomi cube. Custom event from the Xiaomi component.
|
|
- alias: "Xiaomi Cube Action"
|
|
initial_state: false
|
|
trigger:
|
|
- platform: event
|
|
event_type: cube_action
|
|
event_data:
|
|
entity_id: binary_sensor.cube_158d000103a3de
|
|
action:
|
|
- service: notify.pushover
|
|
data:
|
|
title: "Cube event detected"
|
|
message: "Cube has triggered this event: {{ trigger.event }}"
|
|
```
|
|
|
|
{% endraw %}
|
|
|
|
## Extra options
|
|
|
|
When writing automations directly in YAML, you will have access to advanced options that are not available in the user interface.
|
|
|
|
### Automation initial state
|
|
|
|
At startup, automations by default restore their last state of when Home Assistant ran. This can be controlled with the `initial_state` option. Set it to `false` or `true` to force initial state to be off or on.
|
|
|
|
```yaml
|
|
automation:
|
|
- alias: "Automation Name"
|
|
initial_state: false
|
|
trigger:
|
|
- platform: ...
|
|
```
|
|
|
|
### Number of debug traces stored
|
|
|
|
When using YAML you can configure the number of debugging traces stored for an automation. This is controlled with the `stored_traces` option under `trace`. Set `stored_traces` to the number of traces you wish to store for the particular automation. If not specified the default value of 5 will be used.
|
|
|
|
```yaml
|
|
automation:
|
|
- alias: "Automation Name"
|
|
trace:
|
|
stored_traces: 10
|
|
trigger:
|
|
- platform: ...
|
|
```
|
|
|
|
## Migrating your YAML automations to `automations.yaml`
|
|
|
|
If you want to migrate your manual automations to use the editor, you'll have to copy them to `automations.yaml`. Make sure that `automations.yaml` remains a list! For each automation that you copy over, you'll have to add an `id`. This can be any string as long as it's unique.
|
|
|
|
{% raw %}
|
|
|
|
```yaml
|
|
# Example automations.yaml entry. Note, automations.yaml is always a list!
|
|
- id: my_unique_id # <-- Required for editor to work, for automations created with the editor the id will be automatically generated.
|
|
alias: "Hello world"
|
|
trigger:
|
|
- platform: state
|
|
entity_id: sun.sun
|
|
from: below_horizon
|
|
to: above_horizon
|
|
condition:
|
|
- condition: numeric_state
|
|
entity_id: sensor.temperature
|
|
above: 17
|
|
below: 25
|
|
value_template: "{{ float(state.state) + 2 }}"
|
|
action:
|
|
- service: light.turn_on
|
|
```
|
|
|
|
{% endraw %}
|
|
|
|
### Deleting Automations
|
|
|
|
When automations remain visible in the Home Assistant Dashboard, even after having deleted in the YAML file, you have to delete them in the UI.
|
|
|
|
To delete them completely, go to UI **{% my entities title="Settings -> Devices & Services -> Entities" %}** and find the automation in the search field or by scrolling down.
|
|
|
|
Check the square box aside of the automation you wish to delete and from the top-right of your screen, select 'REMOVE SELECTED'.
|