mirror of
https://github.com/home-assistant/home-assistant.io.git
synced 2025-07-21 08:16:53 +00:00
Reorg automation docs and add a using blueprints section (#15811)
Co-authored-by: Franck Nijhof <git@frenck.dev> Co-authored-by: Zack Barett <arnett.zackary@gmail.com>
This commit is contained in:
Paulus Schoutsen
Franck Nijhof
parent
48af733066
commit
f4cc863877
@ -3,42 +3,14 @@ title: "Automating Home Assistant"
|
|||||||
description: "Steps to help you get automation setup in Home Assistant."
|
description: "Steps to help you get automation setup in Home Assistant."
|
||||||
---
|
---
|
||||||
|
|
||||||
Home Assistant offers a wide range of automation configurations. In this section, we'll try to guide you through all the different possibilities and options. Besides this documentation, there are also a couple of people who have made their automations [publicly available](/cookbook/#example-configurationyaml).
|
Home Assistant contains information about all your devices and services. This information is not only available for the user in the dashboard, it can also be used to trigger automations. And that's fun!
|
||||||
|
|
||||||
Please see [Automation Integration](/integrations/automation/) for configuration options and services.
|
Automations in Home Assistant allow you to automatically respond to things that happen. You can turn the lights on at sunset or pause the music when you receive a call.
|
||||||
|
|
||||||
### Automation basics
|
If you are just starting out, we strongly suggest you start with blueprint automations. These are ready-made automations by the community that you only need to configure.
|
||||||
|
|
||||||
Before you can go ahead and create your own automations, it's important to learn the basics. To explore these, let's have a look at the following example home automation rule:
|
### [Learn about automation blueprints »](/docs/automation/using_blueprints/)
|
||||||
|
|
||||||
```text
|
If you got the hang of blueprints and need more, it's time for the next step. But before we can start creating automations, you will need to learn about the automation basics.
|
||||||
(trigger) When Paulus arrives home
|
|
||||||
(condition) and it is after sunset:
|
|
||||||
(action) Turn the lights in the living room on
|
|
||||||
```
|
|
||||||
|
|
||||||
The example consists of three different parts: a [trigger](/docs/automation/trigger/), a [condition](/docs/automation/condition/) and an [action](/docs/automation/action/).
|
### [Learn about automation basics »](/docs/automation/basics/)
|
||||||
|
|
||||||
The first line is the **trigger** of the automation rule. Triggers describe events that should trigger the automation rule. In this case, it is a person arriving home, which can be observed in Home Assistant by observing the state of Paulus changing from 'not_home' to 'home'.
|
|
||||||
|
|
||||||
The second line is the **condition**. Conditions are optional tests that can limit an automation rule to only work in your specific use cases. A condition will test against the current state of the system. This includes the current time, devices, people and other things like the sun. In this case, we only want to act when the sun has set.
|
|
||||||
|
|
||||||
The third part is the **action**, which will be performed when a rule is triggered and all conditions are met. For example, it can turn a light on, set the temperature on your thermostat or activate a scene.
|
|
||||||
|
|
||||||
<div class='note'>
|
|
||||||
The difference between a condition and a trigger can be confusing as they are very similar. Triggers look at the actions, while conditions look at the results: turning a light on versus a light being on.
|
|
||||||
</div>
|
|
||||||
|
|
||||||
### Exploring the internal state
|
|
||||||
|
|
||||||
Automation rules interact directly with the internal state of Home Assistant, so you'll need to familiarize yourself with it. Home Assistant exposes its current state via the developer tools. These are available at the bottom of the sidebar in the frontend. **Developer Tools** -> **States** will show all currently available states. An entity can be anything. A light, a switch, a person and even the sun. A state consists of the following parts:
|
|
||||||
|
|
||||||
| Name | Description | Example |
|
|
||||||
| ---- | ----- | ---- |
|
|
||||||
| Entity ID | Unique identifier for the entity. | `light.kitchen`
|
|
||||||
| State | The current state of the device. | `home`
|
|
||||||
| Attributes | Extra data related to the device and/or current state. | `brightness`
|
|
||||||
|
|
||||||
State changes can be used as the source of triggers and the current state can be used in conditions.
|
|
||||||
|
|
||||||
Actions are all about calling services. To explore the available services open the **Developer Tools** -> **Services**. Services allow to change anything. For example turn on a light, run a script or enable a scene. Each service has a domain and a name. For example the service `light.turn_on` is capable of turning on any light in your system. Services can be passed parameters to for example tell which device to turn on or what color to use.
|
|
||||||
|
|||||||
46
source/_docs/automation/basics.markdown
Normal file
46
source/_docs/automation/basics.markdown
Normal file
@ -0,0 +1,46 @@
|
|||||||
|
---
|
||||||
|
title: "Understanding Automations"
|
||||||
|
description: "A breakdown of what an automation consists of."
|
||||||
|
---
|
||||||
|
|
||||||
|
All automations are made up of a trigger and an action. Optionally combined with a condition. Take for example the automation:
|
||||||
|
|
||||||
|
> When Paulus arrives home and it is after sunset: Turn the lights on in the living room.".
|
||||||
|
|
||||||
|
We can break up this automation into the following three parts:
|
||||||
|
|
||||||
|
```text
|
||||||
|
(trigger) When Paulus arrives home
|
||||||
|
(condition) and it is after sunset:
|
||||||
|
(action) Turn the lights on in the living room
|
||||||
|
```
|
||||||
|
|
||||||
|
The first part is the [trigger](/docs/automation/trigger/) of the automation rule. Triggers describe events that should trigger the automation rule. In this case, it is a person arriving home, which can be observed in Home Assistant by observing the state of Paulus changing from 'not_home' to 'home'.
|
||||||
|
|
||||||
|
The second part is the [condition](/docs/automation/condition/). Conditions are optional tests that can limit an automation rule to only work in your specific use cases. A condition will test against the current state of the system. This includes the current time, devices, people and other things like the sun. In this case, we only want to act when the sun has set.
|
||||||
|
|
||||||
|
The third part is the [action](/docs/automation/action/), which will be performed when a rule is triggered and all conditions are met. For example, it can turn a light on, set the temperature on your thermostat or activate a scene.
|
||||||
|
|
||||||
|
<div class='note'>
|
||||||
|
The difference between a condition and a trigger can be confusing as they are very similar. Triggers look at the actions, while conditions look at the results: turning a light on versus a light being on.
|
||||||
|
</div>
|
||||||
|
|
||||||
|
## Exploring the internal state
|
||||||
|
|
||||||
|
Automation rules interact directly with the internal state of Home Assistant, so you'll need to familiarize yourself with it. Home Assistant exposes its current state via the developer tools. These are available at the bottom of the sidebar in the frontend. **Developer Tools** -> **States** will show all currently available states. An entity can be anything. A light, a switch, a person and even the sun. A state consists of the following parts:
|
||||||
|
|
||||||
|
| Name | Description | Example |
|
||||||
|
| ---- | ----- | ---- |
|
||||||
|
| Entity ID | Unique identifier for the entity. | `light.kitchen`
|
||||||
|
| State | The current state of the device. | `home`
|
||||||
|
| Attributes | Extra data related to the device and/or current state. | `brightness`
|
||||||
|
|
||||||
|
State changes can be used as the source of triggers and the current state can be used in conditions.
|
||||||
|
|
||||||
|
Actions are all about calling services. To explore the available services open the **Developer Tools** -> **Services**. Services allow changing anything. For example turn on a light, run a script or enable a scene. Each service has a domain and a name. For example the service `light.turn_on` is capable of turning on any light in your system. Services can be passed parameters to for example tell which device to turn on or what color to use.
|
||||||
|
|
||||||
|
## Creating automations
|
||||||
|
|
||||||
|
Now that you've got a sneak peek of what is possible, it's time to get your feet wet and create your first automation.
|
||||||
|
|
||||||
|
### [Using the automation editor »](/docs/automation/editor/)
|
||||||
@ -3,8 +3,6 @@ title: "Automation Editor"
|
|||||||
description: "Instructions on how to use the automation editor."
|
description: "Instructions on how to use the automation editor."
|
||||||
---
|
---
|
||||||
|
|
||||||
In Home Assistant 0.45 we introduced the first version of our automation editor. If you just created a new configuration with Home Assistant, then you're all set! Go to the UI and enjoy.
|
|
||||||
|
|
||||||
From the UI choose **Configuration** which is located in the sidebar, then click on **Automation** to go to the automation editor. Press the **+** sign in the lower right corner to get started. This example is based on the manual steps described in the [Getting started section](/getting-started/automation/) for a [`random` sensor](/integrations/random#sensor).
|
From the UI choose **Configuration** which is located in the sidebar, then click on **Automation** to go to the automation editor. Press the **+** sign in the lower right corner to get started. This example is based on the manual steps described in the [Getting started section](/getting-started/automation/) for a [`random` sensor](/integrations/random#sensor).
|
||||||
|
|
||||||
Choose a meaningful name for your automation rules.
|
Choose a meaningful name for your automation rules.
|
||||||
@ -27,75 +25,9 @@ Firing a [persistent notification](/integrations/persistent_notification/) is th
|
|||||||
|
|
||||||
As "Service Data" we want a simple text that is shown as part of the notification.
|
As "Service Data" we want a simple text that is shown as part of the notification.
|
||||||
|
|
||||||
```json
|
```yaml
|
||||||
{
|
message: Sensor value greater than 10
|
||||||
"message": "Sensor value greater than 10"
|
|
||||||
}
|
|
||||||
```
|
```
|
||||||
|
|
||||||
Don't forget to save your new automation rule. For your saved automation rule to come into effect, you will need to go to the **Configuration** page and click on **Reload Automation**.
|
Don't forget to save your new automation rule. For your saved automation rule to come into effect, you will need to go to the **Configuration** page and click on **Reload Automation**.
|
||||||
|
|
||||||
## Updating your configuration to use the editor
|
|
||||||
|
|
||||||
First, check that you have activated the configuration editor.
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
# Activate the configuration editor
|
|
||||||
config:
|
|
||||||
```
|
|
||||||
|
|
||||||
The automation editor reads and writes to the file `automations.yaml` in the root of your [configuration](/docs/configuration/) folder.
|
|
||||||
Currently, both the name of this file and its location are fixed.
|
|
||||||
Make sure that you have set up the automation integration to read from it:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
# Configuration.yaml example
|
|
||||||
automation: !include automations.yaml
|
|
||||||
```
|
|
||||||
|
|
||||||
If you still want to use your old automation section, add a label to the old entry:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
automation old:
|
|
||||||
- trigger:
|
|
||||||
platform: ...
|
|
||||||
```
|
|
||||||
|
|
||||||
You can use the `automation:` and `automation old:` sections at the same time:
|
|
||||||
- `automation old:` to keep your manual designed automations
|
|
||||||
- `automation:` to save the automation created by the online editor
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
automation: !include automations.yaml
|
|
||||||
automation old: !include_dir_merge_list automations
|
|
||||||
```
|
|
||||||
|
|
||||||
|
|
||||||
## Migrating your automations to `automations.yaml`
|
|
||||||
|
|
||||||
If you want to migrate your old 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.
|
|
||||||
|
|
||||||
For example, the below automation will be triggered when the sun goes from below the horizon to above the horizon. Then, if the temperature is between 17 and 25 degrees, a light will be turned on.
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
# Example automations.yaml entry
|
|
||||||
- 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: '{% raw %}{{ float(state.state) + 2 }}{% endraw %}'
|
|
||||||
action:
|
|
||||||
- service: light.turn_on
|
|
||||||
```
|
|
||||||
|
|
||||||
<div class='note'>
|
|
||||||
Any comments in the YAML file will be lost and templates will be reformatted when you update an automation via the editor.
|
|
||||||
</div>
|
|
||||||
|
|||||||
@ -1,77 +0,0 @@
|
|||||||
---
|
|
||||||
title: "Automation Examples"
|
|
||||||
description: "Some automation examples to get you started."
|
|
||||||
---
|
|
||||||
|
|
||||||
Just some sample automation rules to get you started.
|
|
||||||
|
|
||||||
{% raw %}
|
|
||||||
```yaml
|
|
||||||
# Example of entry in configuration.yaml
|
|
||||||
automation:
|
|
||||||
# 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
|
|
||||||
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
|
|
||||||
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 %}
|
|
||||||
53
source/_docs/automation/modes.markdown
Normal file
53
source/_docs/automation/modes.markdown
Normal file
@ -0,0 +1,53 @@
|
|||||||
|
---
|
||||||
|
title: "Automation Modes"
|
||||||
|
description: "How to use and configure automation modes."
|
||||||
|
---
|
||||||
|
|
||||||
|
An automation can be triggered while it is already running.
|
||||||
|
|
||||||
|
The automation's `mode` configuration option controls what happens when the automation is triggered while the actions are still running from a previous trigger.
|
||||||
|
|
||||||
|
Mode | Description
|
||||||
|
-|-
|
||||||
|
`single` | (Default) 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>
|
||||||
|
|
||||||
|
For both `queued` and `parallel` modes, configuration option `max` controls the maximum
|
||||||
|
number of runs that can be executing and/or queued up at a time. The default is 10.
|
||||||
|
|
||||||
|
When `max` is exceeded (which is effectively 1 for `single` mode) a log message will be emitted to indicate this has happened. Configuration option `max_exceeded` controls the severity level of that log message. Set it to `silent` to ignore warnings or set it to a [log level](/integrations/logger/#log-levels). The default is `warning`.
|
||||||
|
|
||||||
|
## Example throttled automation
|
||||||
|
|
||||||
|
Some automations you only want to run every 5 minutes. This can be achieved using the `single` mode and silencing the warnings when the automation is triggered while it's running.
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
automation:
|
||||||
|
- mode: single
|
||||||
|
max_exceeded: silent
|
||||||
|
trigger:
|
||||||
|
- ...
|
||||||
|
action:
|
||||||
|
- ...
|
||||||
|
- delay: 300 # seconds (=5 minutes)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Example Queued
|
||||||
|
|
||||||
|
Sometimes an automation is doing an action on a device that does not support multiple simultaneous actions. In such cases, a queue can be used. In that case, the automation will be executed once it's current invocation and queue are done.
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
automation:
|
||||||
|
- mode: queued
|
||||||
|
max: 25
|
||||||
|
trigger:
|
||||||
|
- ...
|
||||||
|
action:
|
||||||
|
- ...
|
||||||
|
```
|
||||||
46
source/_docs/automation/services.markdown
Normal file
46
source/_docs/automation/services.markdown
Normal file
@ -0,0 +1,46 @@
|
|||||||
|
---
|
||||||
|
title: "Automation Services"
|
||||||
|
description: "How to use the various automation services."
|
||||||
|
---
|
||||||
|
|
||||||
|
The automation integration has services to control automations, like turning automations on and off. This can be useful if you want to disable an automation from another automation.
|
||||||
|
|
||||||
|
## Service `automation.turn_on`
|
||||||
|
|
||||||
|
This service enables the automation's triggers.
|
||||||
|
|
||||||
|
Service data attribute | Optional | Description
|
||||||
|
-|-|-
|
||||||
|
`entity_id` | no | Entity ID of automation to turn on. Can be a list. `none` or `all` are also accepted.
|
||||||
|
|
||||||
|
## Service `automation.turn_off`
|
||||||
|
|
||||||
|
This service disables the automation's triggers, and optionally stops any currently active actions.
|
||||||
|
|
||||||
|
Service data attribute | Optional | Description
|
||||||
|
-|-|-
|
||||||
|
`entity_id` | no | Entity ID of automation to turn on. Can be a list. `none` or `all` are also accepted.
|
||||||
|
`stop_actions` | yes | Stop any currently active actions (defaults to true).
|
||||||
|
|
||||||
|
## Service `automation.toggle`
|
||||||
|
|
||||||
|
This service enables the automation's triggers if they were disabled, or disables the automation's triggers, and stops any currently active actions, if the triggers were enabled.
|
||||||
|
|
||||||
|
Service data attribute | Optional | Description
|
||||||
|
-|-|-
|
||||||
|
`entity_id` | no | Entity ID of automation to turn on. Can be a list. `none` or `all` are also accepted.
|
||||||
|
|
||||||
|
## Service `automation.trigger`
|
||||||
|
|
||||||
|
This service will trigger the action of an automation. By default it bypasses any conditions, though that can be changed via the `skip_condition` attribute.
|
||||||
|
|
||||||
|
Service data attribute | Optional | Description
|
||||||
|
-|-|-
|
||||||
|
`entity_id` | no | Entity ID of automation to trigger. Can be a list. `none` or `all` are also accepted.
|
||||||
|
`skip_condition` | yes | Whether or not the condition will be skipped (defaults to true).
|
||||||
|
|
||||||
|
## Service `automation.reload`
|
||||||
|
|
||||||
|
_This service is only required if you create/edit automations in YAML. Automations via the UI do this automatically._
|
||||||
|
|
||||||
|
This service reloads all automations, stopping all currently active automation actions.
|
||||||
45
source/_docs/automation/using_blueprints.markdown
Normal file
45
source/_docs/automation/using_blueprints.markdown
Normal file
@ -0,0 +1,45 @@
|
|||||||
|
---
|
||||||
|
title: "Using Automation Blueprints"
|
||||||
|
description: "How to crete automations based off blueprints."
|
||||||
|
---
|
||||||
|
|
||||||
|
Automation blueprints are pre-made automations that you can easily add to your Home Assistant instance. Each blueprint can be added as many times as you want.
|
||||||
|
|
||||||
|
Quick links:
|
||||||
|
- [Blueprints in the Home Assistant forums][blueprint-tag]
|
||||||
|
|
||||||
|
## Blueprint Automations
|
||||||
|
|
||||||
|
Automations based on a blueprint only need to be configured to be used. What needs to be configured differs on each blueprint.
|
||||||
|
|
||||||
|
To create your first automation based on a blueprint, go to **Configuration** and then **Blueprints**. Find the blueprint that you want to use and click on "Create Automation".
|
||||||
|
|
||||||
|
This will open the automation editor with the blueprint selected. Give it a name and configure the blueprint and click on the blue button "Save Automation" in the bottom right.
|
||||||
|
|
||||||
|
Done! If you want to revisit the configuration values, you can find it by going to **Configuration** and then **Automations**.
|
||||||
|
|
||||||
|
## Importing blueprints
|
||||||
|
|
||||||
|
Home Assistant can import blueprints from the Home Assistant forums, GitHub and GitHub gists.
|
||||||
|
|
||||||
|
To do this, first [find a blueprint you want to import][blueprint-tag]. If you just want to practice importing, you can use this URL:
|
||||||
|
|
||||||
|
```text
|
||||||
|
https://github.com/home-assistant/core/blob/dev/homeassistant/components/automation/blueprints/motion_light.yaml
|
||||||
|
```
|
||||||
|
|
||||||
|
Go to **Configuration** and then **Blueprints**. Click on the blue "Import Blueprint" button in the bottom right.
|
||||||
|
|
||||||
|
A new dialog will pop-up asking you for the URL. Enter the URL and click on "preview blueprint".
|
||||||
|
|
||||||
|
This will load the blueprint and show a preview in the import dialog. You can change the name and finish the import.
|
||||||
|
|
||||||
|
The blueprint can now be used for creating automations.
|
||||||
|
|
||||||
|
## Finding new blueprints
|
||||||
|
|
||||||
|
The Home Assistant Community forums have a specific tag for blueprints. This tag is used to collect all blueprints.
|
||||||
|
|
||||||
|
[Visit the Home Assistant forums][blueprint-tag]
|
||||||
|
|
||||||
|
[blueprint-tag]: https://community.home-assistant.io/tag/blueprint
|
||||||
145
source/_docs/automation/yaml.markdown
Normal file
145
source/_docs/automation/yaml.markdown
Normal file
@ -0,0 +1,145 @@
|
|||||||
|
---
|
||||||
|
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.
|
||||||
|
|
||||||
|
## 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
|
||||||
|
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
|
||||||
|
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: ...
|
||||||
|
```
|
||||||
|
|
||||||
|
## 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.
|
||||||
|
|
||||||
|
```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: '{% raw %}{{ float(state.state) + 2 }}{% endraw %}'
|
||||||
|
action:
|
||||||
|
- service: light.turn_on
|
||||||
|
```
|
||||||
|
|
||||||
|
### 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 **Configuration** -> **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'.
|
||||||
@ -85,12 +85,16 @@
|
|||||||
<li>
|
<li>
|
||||||
<b>{% active_link /docs/automation/ Automation %}</b>
|
<b>{% active_link /docs/automation/ Automation %}</b>
|
||||||
<ul>
|
<ul>
|
||||||
<li>{% active_link /docs/automation/examples/ Examples %}</li>
|
<li>{% active_link /docs/automation/using_blueprints/ Using Automation Blueprints %}</li>
|
||||||
|
<li>{% active_link /docs/automation/basics/ Automation Basics %}</li>
|
||||||
<li>{% active_link /docs/automation/editor/ Editor %}</li>
|
<li>{% active_link /docs/automation/editor/ Editor %}</li>
|
||||||
<li>{% active_link /docs/automation/trigger/ Triggers %}</li>
|
<li>{% active_link /docs/automation/trigger/ Triggers %}</li>
|
||||||
<li>{% active_link /docs/automation/condition/ Conditions %}</li>
|
<li>{% active_link /docs/automation/condition/ Conditions %}</li>
|
||||||
<li>{% active_link /docs/automation/action/ Actions %}</li>
|
<li>{% active_link /docs/automation/action/ Actions %}</li>
|
||||||
|
<li>{% active_link /docs/automation/modes/ Run Modes %}</li>
|
||||||
|
<li>{% active_link /docs/automation/services/ Services %}</li>
|
||||||
<li>{% active_link /docs/automation/templating/ Templates %}</li>
|
<li>{% active_link /docs/automation/templating/ Templates %}</li>
|
||||||
|
<li>{% active_link /docs/automation/yaml/ YAML %}</li>
|
||||||
<li>
|
<li>
|
||||||
{% active_link /docs/automation/troubleshooting/ Troubleshooting %}
|
{% active_link /docs/automation/troubleshooting/ Troubleshooting %}
|
||||||
</li>
|
</li>
|
||||||
|
|||||||
@ -11,112 +11,4 @@ ha_iot_class:
|
|||||||
ha_domain: automation
|
ha_domain: automation
|
||||||
---
|
---
|
||||||
|
|
||||||
Please see [Automating Home Assistant](/docs/automation/) for in-depth
|
<script>document.location.href = '/docs/automation/';</script>
|
||||||
documentation on how to use the automation integration.
|
|
||||||
|
|
||||||
<p class='img'>
|
|
||||||
<img src='/images/screenshots/automation-switches.png' />
|
|
||||||
</p>
|
|
||||||
|
|
||||||
## Configuration
|
|
||||||
|
|
||||||
This integration is by default enabled, unless you've disabled or removed the [`default_config:`](https://www.home-assistant.io/integrations/default_config/) line from your configuration. If that is the case, the following example shows you how to enable this integration manually:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
# Example configuration.yaml entry
|
|
||||||
automation:
|
|
||||||
```
|
|
||||||
|
|
||||||
### Automation initial state
|
|
||||||
|
|
||||||
When you create a new automation, it will be enabled unless you explicitly add `initial_state: false` to it or turn it off manually via UI/another automation/developer tools. In case automations need to be always enabled or disabled when Home Assistant starts, then you can set the `initial_state` in your automations. Otherwise, the previous state will be restored.
|
|
||||||
|
|
||||||
Please note that if for some reason Home Assistant cannot restore the previous state, it will result in the automation being enabled.
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
automation:
|
|
||||||
- alias: Automation Name
|
|
||||||
initial_state: false
|
|
||||||
trigger:
|
|
||||||
...
|
|
||||||
```
|
|
||||||
|
|
||||||
### Automation Modes
|
|
||||||
|
|
||||||
The automation's `mode` configuration option controls what happens when the automation is triggered while the actions are still running from a previous trigger.
|
|
||||||
|
|
||||||
Mode | Description
|
|
||||||
-|-
|
|
||||||
`single` | (Default) 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>
|
|
||||||
|
|
||||||
For both `queued` and `parallel` modes, configuration option `max` controls the maximum
|
|
||||||
number of runs that can be executing and/or queued up at a time. The default is 10.
|
|
||||||
|
|
||||||
When `max` is exceeded (which is effectively 1 for `single` mode) a log message will be emitted to indicate this has happened. Configuration option `max_exceeded` 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. The default is `warning`.
|
|
||||||
|
|
||||||
#### Example Setting Automation Mode
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
automation:
|
|
||||||
- trigger:
|
|
||||||
- ...
|
|
||||||
mode: queued
|
|
||||||
max: 25
|
|
||||||
action:
|
|
||||||
- ...
|
|
||||||
```
|
|
||||||
|
|
||||||
### 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 **Configuration** -> **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'.
|
|
||||||
|
|
||||||
## Services
|
|
||||||
|
|
||||||
### `automation.turn_on`
|
|
||||||
|
|
||||||
This service enables the automation's triggers.
|
|
||||||
|
|
||||||
Service data attribute | Optional | Description
|
|
||||||
-|-|-
|
|
||||||
`entity_id` | no | Entity ID of automation to turn on. Can be a list. `none` or `all` are also accepted.
|
|
||||||
|
|
||||||
### `automation.turn_off`
|
|
||||||
|
|
||||||
This service disables the automation's triggers, and optionally stops any currently active actions.
|
|
||||||
|
|
||||||
Service data attribute | Optional | Description
|
|
||||||
-|-|-
|
|
||||||
`entity_id` | no | Entity ID of automation to turn on. Can be a list. `none` or `all` are also accepted.
|
|
||||||
`stop_actions` | yes | Stop any currently active actions (defaults to true).
|
|
||||||
|
|
||||||
### `automation.toggle`
|
|
||||||
|
|
||||||
This service enables the automation's triggers if they were disabled, or disables the automation's triggers, and stops any currently active actions, if the triggers were enabled.
|
|
||||||
|
|
||||||
Service data attribute | Optional | Description
|
|
||||||
-|-|-
|
|
||||||
`entity_id` | no | Entity ID of automation to turn on. Can be a list. `none` or `all` are also accepted.
|
|
||||||
|
|
||||||
### `automation.reload`
|
|
||||||
|
|
||||||
This service reloads all automations, stopping any currently active actions in all of them.
|
|
||||||
|
|
||||||
### `automation.trigger`
|
|
||||||
|
|
||||||
This service will trigger the action of an automation. By default it bypasses any conditions, though that can be changed via the `skip_condition` attribute.
|
|
||||||
|
|
||||||
Service data attribute | Optional | Description
|
|
||||||
-|-|-
|
|
||||||
`entity_id` | no | Entity ID of automation to trigger. Can be a list. `none` or `all` are also accepted.
|
|
||||||
`skip_condition` | yes | Whether or not the condition will be skipped (defaults to true).
|
|
||||||
|
|||||||
@ -2050,6 +2050,7 @@
|
|||||||
/ecosystem/notebooks/stats https://data.home-assistant.io
|
/ecosystem/notebooks/stats https://data.home-assistant.io
|
||||||
/ios/whats-new https://companion.home-assistant.io/docs/getting_started/getting-started
|
/ios/whats-new https://companion.home-assistant.io/docs/getting_started/getting-started
|
||||||
/integrations/auth /docs/authentication
|
/integrations/auth /docs/authentication
|
||||||
|
/integrations/automation /docs/automation
|
||||||
/integrations/binary_sensor.knx /integrations/knx#binary-sensor
|
/integrations/binary_sensor.knx /integrations/knx#binary-sensor
|
||||||
/integrations/climate.knx /integrations/knx#climate
|
/integrations/climate.knx /integrations/knx#climate
|
||||||
/integrations/cover.knx /integrations/knx#cover
|
/integrations/cover.knx /integrations/knx#cover
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user