Allow automation to be turned off without stopping actions (#14134)

Co-authored-by: Franck Nijhof <git@frenck.dev>
This commit is contained in:
Phil Bruckner 2020-08-03 09:16:08 -05:00 committed by GitHub
parent accbc276de
commit 10acbf0c24
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 86 additions and 65 deletions

View File

@ -5,6 +5,8 @@ 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).
Please see [Automation Integration](/integrations/automation/) for configuration options and services.
### Automation basics
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:
@ -40,55 +42,3 @@ Automation rules interact directly with the internal state of Home Assistant, so
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 <img src='/images/screenshots/developer-tool-services-icon.png' class='no-shadow' height='38' /> Services developer tool. 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.
### 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.
#### 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'.

View File

@ -10,25 +10,13 @@ ha_codeowners:
ha_domain: automation
---
Please see the [automation section](/docs/automation/) for in-depth
Please see [Automating Home Assistant](/docs/automation/) for in-depth
documentation on how to use the automation integration.
<p class='img'>
<img src='{{site_root}}/images/screenshots/automation-switches.png' />
</p>
You can also use `initial_state: 'false'` so that the automation
is not automatically turned on after a Home Assistant reboot.
```yaml
automation:
- alias: Door alarm
initial_state: true
trigger:
- platform: state
...
```
## 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:
@ -37,3 +25,86 @@ This integration is by default enabled, unless you've disabled or removed the [`
# 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.
#### 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.