Add new script configuration options (#13859)

Co-authored-by: Franck Nijhof <git@frenck.dev>
This commit is contained in:
Phil Bruckner 2020-07-06 05:02:26 -05:00 committed by GitHub
parent 2e0b7edc82
commit d81685a379
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 74 additions and 2 deletions

View File

@ -16,6 +16,8 @@ The `script` integration allows users to specify a sequence of actions to be exe
The sequence of actions is specified using the [Home Assistant Script Syntax](/getting-started/scripts/).
{% raw %}
```yaml
# Example configuration.yaml entry
script:
@ -24,9 +26,11 @@ script:
# This is Home Assistant Script Syntax
- service: notify.notify
data_template:
         message: Current temperature is {% raw %}{{ states('sensor.temperature') }}{% endraw %}
message: "Current temperature is {{ states('sensor.temperature') }}"
```
{% endraw %}
<div class='note'>
Script names (e.g., `message_temperature` in the example above) are not allowed to contain capital letters, or dash (minus) characters, i.e., `-`. The preferred way to separate words for better readability is to use underscore (`_`) characters.
@ -63,12 +67,47 @@ fields:
example:
description: An example value for PARAMETER_NAME.
type: string
mode:
description: "Controls what happens when script is run while it is still running from one or more previous invocations. See [Script Modes](#script-modes)."
required: false
type: string
default: legacy
queue_size:
description: "Controls maximum number of queued runs waiting for previous run to complete. Only valid with `mode: queue`."
required: false
type: integer
default: 10
sequence:
description: The sequence of actions to be performed in the script.
required: true
type: list
{% endconfiguration %}
### Script Modes
Mode | Description
-|-
`legacy` | See [below](#legacy-mode).
`error` | Raise an error. Previous run continues normally.
`ignore` | Do not start a new run. Previous run continues normally.
`parallel` | Start a new, independent run in parallel with previous runs which continue normally.
`restart` | Start a new run after first stopping previous run.
`queue` | Start a new run after all previous runs complete. Runs are guaranteed to execute in the order they were queued.
<p class='img'>
<img src='/images/integrations/script/script_modes.jpg'>
</p>
#### Legacy Mode
<div class='note'>
This mode is deprecated, and a warning to that effect will be issued at startup unless `mode: legacy` is specified.
</div>
This mode maintains the legacy script behavior. That is, the script will run until it executes a `delay` step, or a `wait_template` step (that actually waits), at which point the script will suspend. If the script is run while suspended, it will abort the delay/wait_template and continue immediately to the next step, or finish if there are no more steps. Also, calling a legacy script that is still running (and not suspended) will result in an error.
### Full Configuration
{% raw %}
@ -83,6 +122,8 @@ script: 
minutes:
description: 'The amount of time to wait before turning on the living room lights'
example: 1
# If called again while still running (probably in delay step), start over.
mode: restart
sequence:
# This is Home Assistant Script Syntax
- event: LOGBOOK_ENTRY
@ -171,8 +212,39 @@ script:
message: "{% raw %}{{ message }}{% endraw %}"
```
### Waiting for Script to Complete
When calling a script "directly" (e.g., `script.NAME`) the calling script will wait for the called script to finish.
When calling a script (or multiple scripts) via the `script.turn_on` service the calling script does _not_ wait. It starts the scripts, in the order listed, and continues as soon as the last script is started.
<p class='img'>
<img src='/images/integrations/script/script_wait.jpg'>
</p>
Following is an example of the calling script not waiting. It performs some other operations while the called script runs "in the background." Then it later waits for the called script to complete via a `wait_template`.
{% raw %}
```yaml
script:
script_1:
sequence:
- service: script.turn_on
entity_id: script.script_2
# Perform some other steps here while second script runs...
# Now wait for called script to complete.
- wait_template: "{{ is_state('script.script_2', 'off') }}"
# Now do some other things...
script_2:
sequence:
# Do some things at the same time as the first script...
```
{% endraw %}
Note that this is only guaranteed to work if the called script uses a non-legacy mode.
### In the Overview
Scripts in the Overview panel will be displayed with an **EXECUTE** button if the device has no `delay:` or `wait:` statement, and as a toggle switch if it has either of those.
Legacy scripts in the Overview panel will be displayed with an **EXECUTE** button if the script has no `delay:` or `wait_template:` statement, and as a toggle switch if it has either of those. Scripts configured for any other mode than `legacy` will also be displayed with a toggle switch.
This is to enable you to stop a running script.

Binary file not shown.

Binary file not shown.

After

Width:  |  Height:  |  Size: 58 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 51 KiB