diff --git a/source/_docs/automation/condition.markdown b/source/_docs/automation/condition.markdown index 931b26c19c5..7811294340a 100644 --- a/source/_docs/automation/condition.markdown +++ b/source/_docs/automation/condition.markdown @@ -10,22 +10,44 @@ The available conditions for an automation are the same as for the script syntax Example of using condition: +{% raw %} + ```yaml automation: -- alias: 'Enciende Despacho' - trigger: - platform: state - entity_id: sensor.mini_despacho - to: 'on' - condition: - condition: or - conditions: - - condition: template - value_template: "{% raw %}{{ state_attr('sun.sun', 'elevation') < 4 }}{% endraw %}" - - condition: template - value_template: "{% raw %}{{ states('sensor.sensorluz_7_0') < 10 }}{% endraw %}" - action: - - service: scene.turn_on - entity_id: scene.DespiertaDespacho + - alias: 'Enciende Despacho' + trigger: + platform: state + entity_id: sensor.mini_despacho + to: 'on' + condition: + condition: or + conditions: + - condition: template + value_template: "{{ state_attr('sun.sun', 'elevation') < 4 }}" + - condition: template + value_template: "{{ states('sensor.sensorluz_7_0') < 10 }}" + action: + - service: scene.turn_on + entity_id: scene.DespiertaDespacho ``` +{% endraw %} + +The `condition` option of an automation, also accepts a single condition template directly. For example: + +{% raw %} + +```yaml +automation: + - alias: 'Enciende Despacho' + trigger: + platform: state + entity_id: sensor.mini_despacho + to: 'on' + condition: "{{ state_attr('sun.sun', 'elevation') < 4 }}" + action: + - service: scene.turn_on + entity_id: scene.DespiertaDespacho +``` + +{% endraw %} diff --git a/source/_docs/scripts.markdown b/source/_docs/scripts.markdown index d50c2fab103..f13d2657fff 100644 --- a/source/_docs/scripts.markdown +++ b/source/_docs/scripts.markdown @@ -315,6 +315,7 @@ This form accepts a list of conditions (see [conditions page] for available opti is run. The sequence will be run _as long as_ the condition(s) evaluate to true. {% raw %} + ```yaml script: do_something: @@ -332,6 +333,20 @@ script: sequence: - service: script.something ``` + +{% endraw %} + +The `while` also accepts a [shorthand notation of a template condition][shorthand-template]. +For example: + +{% raw %} + +```yaml +- while: "{{ is_state('sensor.mode', 'Home') and repeat.index < 10 }}" + sequence: + - ... +``` + {% endraw %} #### Repeat Until @@ -341,6 +356,7 @@ is run. Therefore the sequence will always run at least once. The sequence will _until_ the condition(s) evaluate to true. {% raw %} + ```yaml automation: - trigger: @@ -367,8 +383,20 @@ automation: entity_id: binary_sensor.something state: 'on' ``` + {% endraw %} +`until` also accepts a [shorthand notation of a template condition][shorthand-template]. +For example: + +{% raw %} + +```yaml +- until: "{{ is_state('device_tracker.iphone', 'home') }}" + sequence: + - ... +``` + #### Repeat Loop Variable A variable named `repeat` is defined within the repeat action (i.e., it is available inside `sequence`, `while` & `until`.) @@ -391,6 +419,7 @@ An _optional_ `default` sequence can be included which will be run only if none 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 %} + ```yaml # Example with just an "if" automation: @@ -412,6 +441,7 @@ automation: - service: light.turn_on entity_id: all ``` + ```yaml # Example with "if" and "else" automation: @@ -435,6 +465,7 @@ automation: - service: light.turn_off entity_id: light.front_lights ``` + ```yaml # Example with "if", "elif" and "else" automation: @@ -468,6 +499,42 @@ automation: - service: light.turn_off entity_id: all ``` + +{% endraw %} + +`conditions` also accepts a [shorthand notation of a template condition][shorthand-template]. +For example: + +{% raw %} + +```yaml +automation: + - trigger: + - platform: state + entity_id: input_select.home_mode + action: + - choose: + - conditions: > + {{ trigger.to_state.state == 'Home' and + is_state('binary_sensor.all_clear', 'on') }} + sequence: + - service: script.arrive_home + data: + ok: true + - conditions: > + {{ trigger.to_state.state == 'Home' and + is_state('binary_sensor.all_clear', 'off') }} + sequence: + - service: script.turn_on + entity_id: script.flash_lights + - service: script.arrive_home + data: + ok: false + - conditions: "{{ trigger.to_state.state == 'Away' }}" + sequence: + - service: script.left_home +``` + {% endraw %} [Script component]: /integrations/script/ @@ -475,3 +542,4 @@ automation: [Alexa/Amazon Echo]: /integrations/alexa/ [service calls page]: /getting-started/scripts-service-calls/ [conditions page]: /getting-started/scripts-conditions/ +[shorthand-template]: /docs/scripts/conditions/#template-condition-shorthand-notation diff --git a/source/_docs/scripts/conditions.markdown b/source/_docs/scripts/conditions.markdown index f25329c73a0..060ed8292d8 100644 --- a/source/_docs/scripts/conditions.markdown +++ b/source/_docs/scripts/conditions.markdown @@ -8,7 +8,7 @@ Conditions can be used within a script or automation to prevent further executio Unlike a trigger, which is always `or`, conditions are `and` by default - all conditions have to be true. -### AND condition +## AND condition Test multiple conditions in one condition statement. Passes if all embedded conditions are valid. @@ -40,7 +40,7 @@ condition: Currently you need to format your conditions like this to be able to edit them using the [automations editor](/docs/automation/editor/). -### OR condition +## OR condition Test multiple conditions in one condition statement. Passes if any embedded condition is valid. @@ -56,7 +56,7 @@ condition: below: 20 ``` -### MIXED AND and OR conditions +## MIXED AND and OR conditions Test multiple AND and OR conditions in one condition statement. Passes if any embedded condition is valid. This allows you to mix several AND and OR conditions together. @@ -78,7 +78,7 @@ condition: below: 20 ``` -### NOT condition +## NOT condition Test multiple conditions in one condition statement. Passes if all embedded conditions are **not** valid. @@ -94,7 +94,7 @@ condition: state: disarmed ``` -### Numeric state condition +## Numeric state condition This type of condition attempts to parse the state of the specified entity or the attribute of an entity as a number, and triggers if the value matches the thresholds. @@ -111,6 +111,7 @@ condition: You can optionally use a `value_template` to process the value of the state before testing it. {% raw %} + ```yaml condition: condition: numeric_state @@ -118,8 +119,9 @@ condition: above: 17 below: 25 # If your sensor value needs to be adjusted - value_template: '{{ float(state.state) + 2 }}' + value_template: "{{ float(state.state) + 2 }}" ``` + {% endraw %} It is also possible to test the condition against multiple entities at once. @@ -146,7 +148,7 @@ condition: below: 25 ``` -### State condition +## State condition Tests if an entity is a specified state. @@ -231,7 +233,7 @@ condition: state: 'below_horizon' ``` -#### Sun elevation condition +### Sun elevation condition The sun elevation can be used to test if the sun has set or risen, it is dusk, it is night, etc. when a trigger occurs. For an in-depth explanation of sun elevation, see [sun elevation trigger][sun_elevation_trigger]. @@ -239,6 +241,7 @@ For an in-depth explanation of sun elevation, see [sun elevation trigger][sun_el [sun_elevation_trigger]: /docs/automation/trigger/#sun-elevation-trigger {% raw %} + ```yaml condition: condition: and # 'twilight' condition: dusk and dawn, in typical locations @@ -248,17 +251,20 @@ condition: - condition: template value_template: "{{ state_attr('sun.sun', 'elevation') > -6 }}" ``` + {% endraw %} {% raw %} + ```yaml condition: condition: template # 'night' condition: from dusk to dawn, in typical locations value_template: "{{ state_attr('sun.sun', 'elevation') < -6 }}" ``` + {% endraw %} -#### Sunset/sunrise condition +### Sunset/sunrise condition The sun condition can also test if the sun has already set or risen when a trigger occurs. The `before` and `after` keys can only be set to `sunset` or `sunrise`. They have a corresponding optional offset value (`before_offset`, `after_offset`) that can be added, similar to the [sun trigger][sun_trigger]. When both keys are used, the result is a logical `and` of separate conditions. @@ -306,24 +312,97 @@ A visual timeline is provided below showing an example of when these conditions Graphic showing an example of sun conditions -### Template condition +## Template condition The template condition tests if the [given template][template] renders a value equal to true. This is achieved by having the template result in a true boolean expression or by having the template render 'true'. {% raw %} + ```yaml condition: condition: template value_template: "{{ (state_attr('device_tracker.iphone', 'battery_level')|int) > 50 }}" ``` + {% endraw %} Within an automation, template conditions also have access to the `trigger` variable as [described here][automation-templating]. +### Template condition shorthand notation + +The template condition has a shorthand notation that can be used to make your scripts and automations shorter. + +For example: + +{% raw %} + +```yaml +conditions: "{{ (state_attr('device_tracker.iphone', 'battery_level')|int) > 50 }}" +``` + +{% endraw %} + +Or in a list of conditions, allowing to use existing conditions as described in this +chapter and one or more shorthand template conditions + +{% raw %} + +```yaml +conditions: + - "{{ (state_attr('device_tracker.iphone', 'battery_level')|int) > 50 }}" + - condition: state + entity_id: alarm_control_panel.home + state: armed_away + - "{{ is_state('device_tracker.iphone', 'away') }}" +``` + +{% endraw %} + +This shorthand notation can be used everywhere in Home Assistant where +conditions are accepted. For example, in [`and`](#and-condition), [`or`](#or-condition) +and [`not`](#not-condition) conditions: + +{% raw %} + +```yaml +condition: + condition: or + conditions: + - "{{ is_state('device_tracker.iphone', 'away') }}" + - condition: numeric_state + entity_id: 'sensor.temperature' + below: 20 +``` + +{% endraw %} + +But also in the `repeat` action's `while` or `until` option, or in a `choose` action's `conditions` option: + +{% raw %} + +```yaml +- while: "{{ is_state('sensor.mode', 'Home') and repeat.index < 10 }}" + sequence: + - ... +``` + +{% endraw %} + +{% raw %} + +```yaml +- choose: + - conditions: "{{ is_state('sensor.mode', 'Home') and repeat.index < 10 }}" + sequence: + - ... +``` + +{% endraw %} + [template]: /topics/templating/ [automation-templating]: /getting-started/automation-templating/ -### Time condition +## Time condition The time condition can test if it is after a specified time, before a specified time or if it is a certain day of the week. @@ -359,7 +438,7 @@ condition: before: input_datetime.house_silent_hours_end ``` -### Zone condition +## Zone condition Zone conditions test if an entity is in a certain zone. For zone automation to work, you need to have set up a device tracker platform that supports reporting GPS coordinates. @@ -409,14 +488,15 @@ condition: - zone.work ``` -### Examples +## Examples {% raw %} + ```yaml condition: - condition: numeric_state entity_id: sun.sun - value_template: '{{ state.attributes.elevation }}' + value_template: "{{ state.attributes.elevation }}" below: 1 - condition: state entity_id: light.living_room @@ -428,4 +508,5 @@ condition: entity_id: script.light_turned_off_5min state: 'off' ``` + {% endraw %}