From edb95ccf92cb2f4cba6ef84fe356198d019892fd Mon Sep 17 00:00:00 2001 From: Erik Montnemery Date: Mon, 22 Feb 2021 20:06:49 +0100 Subject: [PATCH 1/3] Add alias to script syntax examples --- source/_docs/scripts.markdown | 52 +++++++++++++++++++++++------------ 1 file changed, 35 insertions(+), 17 deletions(-) diff --git a/source/_docs/scripts.markdown b/source/_docs/scripts.markdown index 508e9341b1c8..006851810097 100644 --- a/source/_docs/scripts.markdown +++ b/source/_docs/scripts.markdown @@ -9,16 +9,20 @@ When the script is executed within an automation the `trigger` variable is avail The script syntax basic structure is a list of key/value maps that contain actions. If a script contains only 1 action, the wrapping list can be omitted. +All actions support an optional `alias`. + ```yaml # Example script integration containing script syntax script: example_script: sequence: # This is written using the Script Syntax - - service: light.turn_on + - alias: "Turn on ceiling light" + service: light.turn_on target: entity_id: light.ceiling - - service: notify.notify + - alias: "Notify that ceiling light is turned on" + service: notify.notify data: message: "Turned on the ceiling light!" ``` @@ -70,7 +74,8 @@ The variables action allows you to set/override variables that will be accessibl {% raw %} ```yaml -- variables: +- alias: "Set variables" + variables: entities: - light.kitchen - light.living_room @@ -91,6 +96,7 @@ While executing a script you can add a condition to stop further execution. When ```yaml # If paulus is home, continue to execute the script below these lines + alias: "Check if Paulus is home" - condition: state entity_id: device_tracker.paulus state: "home" @@ -105,7 +111,8 @@ Delays are useful for temporarily suspending your script and start it at a later ```yaml # Seconds # Waits 5 seconds -- delay: 5 +- alias: "Wait 5s" + delay: 5 ``` ```yaml @@ -154,8 +161,9 @@ The template is re-evaluated whenever an entity ID that it references changes st {% raw %} ```yaml -# Wait until media player have stop the playing -- wait_template: "{{ is_state('media_player.floor', 'stop') }}" +# Wait until media player is stopped +- alias: "Wait until media player is stopped" + wait_template: "{{ is_state('media_player.floor', 'stop') }}" ``` {% endraw %} @@ -167,7 +175,8 @@ This action can use the same triggers that are available in an automation's `tri ```yaml # Wait for a custom event or light to turn on and stay on for 10 sec -- wait_for_trigger: +- alias: "Wait for MY_EVENT or light on" + wait_for_trigger: - platform: event event_type: MY_EVENT - platform: state @@ -186,7 +195,8 @@ With both types of waits it is possible to set a timeout after which the script ```yaml # Wait for sensor to change to 'on' up to 1 minute before continuing to execute. -- wait_template: "{{ is_state('binary_sensor.entrance', 'on') }}" +- alias: "Wait for sensor 'on' for 1 minute" + wait_template: "{{ is_state('binary_sensor.entrance', 'on') }}" timeout: "00:01:00" ``` @@ -198,7 +208,8 @@ You can also get the script to abort after the timeout by using optional `contin ```yaml # Wait for IFTTT event or abort after specified timeout. -- wait_for_trigger: +- alias: "Wait for IFTTT, or abort" + wait_for_trigger: - platform: event event_type: ifttt_webhook_received event_data: @@ -228,7 +239,8 @@ This can be used to take different actions based on whether or not the condition ```yaml # Take different actions depending on if condition was met. -- wait_template: "{{ is_state('binary_sensor.door', 'on') }}" +- alias: "Wait for door on" + wait_template: "{{ is_state('binary_sensor.door', 'on') }}" timeout: 10 - choose: - conditions: "{{ not wait.completed }}" @@ -266,7 +278,8 @@ This can be used to take different actions based on whether or not the condition This action allows you to fire an event. Events can be used for many things. It could trigger an automation or indicate to another integration that something is happening. For instance, in the below example it is used to create an entry in the logbook. ```yaml -- event: LOGBOOK_ENTRY +- alias: "Fire LOGBOOK_ENTRY event" + event: LOGBOOK_ENTRY event_data: name: Paulus message: is waking up @@ -340,10 +353,12 @@ script: flash_light: mode: restart sequence: - - service: light.turn_on + - alias: "Turn light on" + service: light.turn_on target: entity_id: "light.{{ light }}" - - repeat: + - alias: "Cycle light count times" + repeat: count: "{{ count|int * 2 - 1 }}" sequence: - delay: 2 @@ -352,7 +367,8 @@ script: entity_id: "light.{{ light }}" flash_hallway_light: sequence: - - service: script.flash_light + - alias: "Flash hallway light 3 times" + service: script.flash_light data: light: hallway count: 3 @@ -480,8 +496,8 @@ automation: entity_id: binary_sensor.motion to: "on" action: + - alias: "IF nobody home, sound the alarm! - choose: - # IF nobody home, sound the alarm! - conditions: - condition: state entity_id: group.family @@ -503,7 +519,8 @@ automation: entity_id: binary_sensor.motion mode: queued action: - - choose: + - alias: "Turn on front lights if motion detected, else turn off" + choose: # IF motion detected - conditions: - condition: template @@ -530,7 +547,8 @@ automation: to: "on" mode: restart action: - - choose: + - alias: "Choose time of day" + choose: # IF morning - conditions: - condition: template From 7726ee4c92d864d9ed5a4ac4cf4d1e8116c9c9b7 Mon Sep 17 00:00:00 2001 From: Erik Montnemery Date: Mon, 22 Feb 2021 20:30:27 +0100 Subject: [PATCH 2/3] Update scripts.markdown --- source/_docs/scripts.markdown | 26 ++++++++++++-------------- 1 file changed, 12 insertions(+), 14 deletions(-) diff --git a/source/_docs/scripts.markdown b/source/_docs/scripts.markdown index 006851810097..3299c8f0d845 100644 --- a/source/_docs/scripts.markdown +++ b/source/_docs/scripts.markdown @@ -195,8 +195,7 @@ With both types of waits it is possible to set a timeout after which the script ```yaml # Wait for sensor to change to 'on' up to 1 minute before continuing to execute. -- alias: "Wait for sensor 'on' for 1 minute" - wait_template: "{{ is_state('binary_sensor.entrance', 'on') }}" +- wait_template: "{{ is_state('binary_sensor.entrance', 'on') }}" timeout: "00:01:00" ``` @@ -208,8 +207,7 @@ You can also get the script to abort after the timeout by using optional `contin ```yaml # Wait for IFTTT event or abort after specified timeout. -- alias: "Wait for IFTTT, or abort" - wait_for_trigger: +- wait_for_trigger: - platform: event event_type: ifttt_webhook_received event_data: @@ -239,8 +237,7 @@ This can be used to take different actions based on whether or not the condition ```yaml # Take different actions depending on if condition was met. -- alias: "Wait for door on" - wait_template: "{{ is_state('binary_sensor.door', 'on') }}" +- wait_template: "{{ is_state('binary_sensor.door', 'on') }}" timeout: 10 - choose: - conditions: "{{ not wait.completed }}" @@ -353,11 +350,10 @@ script: flash_light: mode: restart sequence: - - alias: "Turn light on" - service: light.turn_on + - service: light.turn_on target: entity_id: "light.{{ light }}" - - alias: "Cycle light count times" + - alias: "Cycle light 'count' times" repeat: count: "{{ count|int * 2 - 1 }}" sequence: @@ -484,6 +480,8 @@ Nesting is fully supported. Each sequence is paired with a list of conditions. (See the [conditions page] for available options and how multiple conditions are handled.) The first sequence whose conditions are all true will be run. An _optional_ `default` sequence can be included which will be run only if none of the sequences from the list are run. +An _optionl_ `alias` can be added to each of the sequences, excluding the `default` sequence. + The `choose` action can be used like an "if" statement. The first `conditions`/`sequence` pair is like the "if/then", and can be used just by itself. Or additional pairs can be added, each of which is like an "elif/then". And lastly, a `default` can be added, which would be like the "else." {% raw %} @@ -496,9 +494,9 @@ automation: entity_id: binary_sensor.motion to: "on" action: - - alias: "IF nobody home, sound the alarm! - choose: - - conditions: + - alias: "IF nobody home, sound the alarm! + conditions: - condition: state entity_id: group.family state: not_home @@ -522,7 +520,8 @@ automation: - alias: "Turn on front lights if motion detected, else turn off" choose: # IF motion detected - - conditions: + - alias: "Motion detected" + conditions: - condition: template value_template: "{{ trigger.to_state.state == 'on' }}" sequence: @@ -547,8 +546,7 @@ automation: to: "on" mode: restart action: - - alias: "Choose time of day" - choose: + - choose: # IF morning - conditions: - condition: template From e32a028ad0e2e8468c5834b4c708f4ce40e4aae4 Mon Sep 17 00:00:00 2001 From: Erik Montnemery Date: Mon, 22 Feb 2021 20:43:09 +0100 Subject: [PATCH 3/3] Apply suggestions from code review Co-authored-by: Franck Nijhof --- source/_docs/scripts.markdown | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/source/_docs/scripts.markdown b/source/_docs/scripts.markdown index 3299c8f0d845..56e3e324b3d7 100644 --- a/source/_docs/scripts.markdown +++ b/source/_docs/scripts.markdown @@ -480,7 +480,7 @@ Nesting is fully supported. Each sequence is paired with a list of conditions. (See the [conditions page] for available options and how multiple conditions are handled.) The first sequence whose conditions are all true will be run. An _optional_ `default` sequence can be included which will be run only if none of the sequences from the list are run. -An _optionl_ `alias` can be added to each of the sequences, excluding the `default` sequence. +An _optional_ `alias` can be added to each of the sequences, excluding the `default` sequence. The `choose` action can be used like an "if" statement. The first `conditions`/`sequence` pair is like the "if/then", and can be used just by itself. Or additional pairs can be added, each of which is like an "elif/then". And lastly, a `default` can be added, which would be like the "else." @@ -521,9 +521,7 @@ automation: choose: # IF motion detected - alias: "Motion detected" - conditions: - - condition: template - value_template: "{{ trigger.to_state.state == 'on' }}" + conditions: "{{ trigger.to_state.state == 'on' }}" sequence: - service: script.turn_on target: