mirror of
https://github.com/home-assistant/home-assistant.io.git
synced 2025-07-23 09:17:06 +00:00
Add shorthand notation for Template conditions (#14413)
This commit is contained in:
Franck Nijhof
GitHub
parent
2ecb085eff
commit
056cdf967a
@ -10,9 +10,11 @@ The available conditions for an automation are the same as for the script syntax
|
||||
|
||||
Example of using condition:
|
||||
|
||||
{% raw %}
|
||||
|
||||
```yaml
|
||||
automation:
|
||||
- alias: 'Enciende Despacho'
|
||||
- alias: 'Enciende Despacho'
|
||||
trigger:
|
||||
platform: state
|
||||
entity_id: sensor.mini_despacho
|
||||
@ -21,11 +23,31 @@ automation:
|
||||
condition: or
|
||||
conditions:
|
||||
- condition: template
|
||||
value_template: "{% raw %}{{ state_attr('sun.sun', 'elevation') < 4 }}{% endraw %}"
|
||||
value_template: "{{ state_attr('sun.sun', 'elevation') < 4 }}"
|
||||
- condition: template
|
||||
value_template: "{% raw %}{{ states('sensor.sensorluz_7_0') < 10 }}{% endraw %}"
|
||||
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 %}
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
<img src='/images/docs/scripts/sun-conditions.svg' alt='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 %}
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user