Update template entity docs for entity_id removal and guidance on working without entities (#14343)

Co-authored-by: Anders Melchiorsen <amelchio@nogoto.net>
Co-authored-by: Swamp-Ig <github@ninjateaparty.com>
This commit is contained in:
J. Nick Koston 2020-09-03 11:51:07 -05:00 committed by GitHub
parent 0ac2e4928c
commit b908b87c7d
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
12 changed files with 94 additions and 34 deletions

View File

@ -114,6 +114,8 @@ When used within an automation the `trigger` variable is available. See [Availab
This action evaluates the template, and if true, the script will continue. If not, then it will wait until it is true.
The template is re-evaluated whenever an entity ID that it references changes state. If you use non-deterministic functions like `now()` in the template it will not be continuously re-evaluated, but only when an entity ID that is referenced is changed. If you need to periodically re-evaluate the template, reference a sensor from the (Time and Date)[/integrations/time_date/] component that will update minutely or daily.
{% raw %}
```yaml
# Wait until media player have stop the playing

View File

@ -106,3 +106,7 @@ panels:
If you are using the state of a integration that takes extra time to load, the Template Alarm Control Panel may get an `unknown` state during startup. This results in error messages in your log file until that integration has completed loading. If you use `is_state()` function in your template, you can avoid this situation.
For example, you would replace {% raw %}`{{ states.switch.source.state == 'on' }}`{% endraw %} with this equivalent that returns `true`/`false` and never gives an unknown result: {% raw %}`{{ is_state('switch.source', 'on') }}`{% endraw %}
### Working without entities
If you use a template that depends on the current time or some other non-deterministic result not sourced from entities, the template won't repeatedly update but will only update when the state of a referenced entity updates. For ways to deal with this issue, see [Working without entities](/integrations/binary_sensor.template/#working-without-entities) in the Template Binary Sensor integration.

View File

@ -132,8 +132,7 @@ binary_sensor:
below: 50
```
Finally, here's an example for `template` observation platform,
as seen in the configuration it requires `value_template` and does not use `entity_id`.
Finally, here's an example for `template` observation platform, as seen in the configuration it requires `value_template`.
{% raw %}
```yaml
@ -150,3 +149,7 @@ binary_sensor:
prob_given_true: 0.95
```
{% endraw %}
The template is re-evaluated whenever an entity ID that it references changes state. If you use non-deterministic functions like `now()` in the template it will not be continuously re-evaluated, but only when an entity ID that is referenced is updated.
In this example, since the template is only evaluated on state change of `device_tracker.paulus` the template won't change state after 5 mins like intended. The ways to force template reevaluation are documented in the [template binary_sensor](/integrations/binary_sensor.template/#working-without-entities).

View File

@ -110,13 +110,12 @@ with this equivalent that returns `true`/`false` and never gives an unknown
result:
{% raw %}`{{ is_state('switch.source', 'on') }}`{% endraw %}
### Entity IDs
### Sensor state updates
The template engine will attempt to work out what entities should trigger an
update of the sensor. This can fail, for example if your template loops over
the contents of a group. In this case you can use `entity_id` to provide a
list of entity IDs that will cause the sensor to update or you can run the
service `homeassistant.update_entity` to update the sensor at will.
The template engine works out what entities are used to trigger an update of the sensor and recalculates the result when one of those entities change.
If you use a template that depends on the current time or some other non-deterministic result not sourced from entities, create an interval-based
automation that calls the service `homeassistant.update_entity` for the sensor requiring updates. See the [example below](#working-without-entities).
## Examples
@ -294,3 +293,44 @@ binary_sensor:
```
{% endraw %}
### Working without entities
The `template` sensors are not limited to use attributes from other entities but can also work with [Home Assistant's template extensions](/docs/configuration/templating/#home-assistant-template-extensions). If the template includes some non-deterministic property such as time in its calculation, the result will not continually update, but will only update when some entity referenced by the template updates.
There's a couple of options to manage this issue. This first example creates a `sensor.time` from the [Time & Date](/integrations/time_date/) component which updates every minute, and the binary sensor is triggered by this updating. The binary sensor returns true if in the first half of the hour:
{% raw %}
```yaml
sensor:
- platform: time_date
display_options:
- 'time'
binary_sensor:
- platform: template
sensors:
half_hour:
value_template: '{{ (states.sensor.time.state[3:]|int) < 30 }}'
```
{% endraw %}
An alternative to this is to create an interval-based automation that calls the service `homeassistant.update_entity` for the entities requiring updates. This modified example updates every 2 minutes:
{% raw %}
```yaml
binary_sensor:
- platform: template
sensors:
minute_is_odd:
value_template: '{{ now().minute % 2 }}'
automation:
- alias: 'Update minute_is_odd'
trigger:
- platform: time_pattern
minutes: '*'
action:
- service: homeassistant.update_entity
entity_id: binary_sensor.minute_is_odd
{% endraw %}

View File

@ -49,10 +49,6 @@ cover:
description: Name to use in the frontend.
required: false
type: string
entity_id:
description: A list of entity IDs so the cover only reacts to state changes of these entities. This can be used if the automatic analysis fails to find all relevant entities.
required: false
type: [string, list]
unique_id:
description: An ID that uniquely identifies this cover. Set this to an unique value to allow customisation trough the UI.
required: false
@ -126,6 +122,10 @@ with this equivalent that returns `true`/`false` and never gives an unknown
result:
{% raw %}`{{ is_state('cover.source', 'open') }}`{% endraw %}
### Working without entities
If you use a template that depends on the current time or some other non-deterministic result not sourced from entities, the template won't repeatedly update but will only update when the state of a referenced entity updates. For ways to deal with this issue, see [Working without entities](/integrations/binary_sensor.template/#working-without-entities) in the Template Binary Sensor integration.
## Optimistic Mode
In optimistic mode, the cover position state is maintained internally. This mode
@ -219,9 +219,6 @@ cover:
{% else %}
mdi:window-closed
{% endif %}
entity_id:
- cover.bedroom
- cover.livingroom
sensor:
- platform: template

View File

@ -114,3 +114,7 @@ fan:
type: [string, list]
default: ['low', 'medium', 'high']
{% endconfiguration %}
### Working without entities
If you use a template that depends on the current time or some other non-deterministic result not sourced from entities, the template won't repeatedly update but will only update when the state of a referenced entity updates. For ways to deal with this issue, see [Working without entities](/integrations/binary_sensor.template/#working-without-entities) in the Template Binary Sensor integration.

View File

@ -70,10 +70,6 @@ light:
description: Name to use in the frontend.
required: false
type: string
entity_id:
description: A list of entity IDs so the light only reacts to state changes of these entities. This can be used if the automatic analysis fails to find all relevant entities.
required: false
type: [string, list]
unique_id:
description: An ID that uniquely identifies this light. Set this to an unique value to allow customisation trough the UI.
required: false
@ -150,6 +146,10 @@ with this equivalent that returns `true`/`false` and never gives an unknown
result:
{% raw %}`{{ is_state('switch.source', 'on') }}`{% endraw %}
### Working without entities
If you use a template that depends on the current time or some other non-deterministic result not sourced from entities, the template won't repeatedly update but will only update when the state of a referenced entity updates. For ways to deal with this issue, see [Working without entities](/integrations/binary_sensor.template/#working-without-entities) in the Template Binary Sensor integration.
## Examples
In this section you will find some real-life examples of how to use this light.

View File

@ -79,6 +79,10 @@ lock:
If you are using the state of a platform that takes extra time to load, the Template Lock may get an `unknown` state during startup. This results in error messages in your log file until that platform has completed loading. If you use `is_state()` function in your template, you can avoid this situation. For example, you would replace {% raw %}`{{ is_state('switch.source', 'on') }}`{% endraw %} with this equivalent that returns `true`/`false` and never gives an unknown result: {% raw %}`{{ is_state('switch.source', 'on') }}`{% endraw %}
### Working without entities
If you use a template that depends on the current time or some other non-deterministic result not sourced from entities, the template won't repeatedly update but will only update when the state of a referenced entity updates. For ways to deal with this issue, see [Working without entities](/integrations/binary_sensor.template/#working-without-entities) in the Template Binary Sensor integration.
## Examples
In this section, you find some real-life examples of how to use this lock.

View File

@ -50,10 +50,6 @@ switch:
description: Name to use in the frontend.
required: false
type: string
entity_id:
description: A list of entity IDs so the switch only reacts to state changes of these entities. This can be used if the automatic analysis fails to find all relevant entities.
required: false
type: [string, list]
unique_id:
description: An ID that uniquely identifies this switch. Set this to an unique value to allow customisation trough the UI.
required: false
@ -90,6 +86,10 @@ switch:
If you are using the state of a platform that takes extra time to load, the Template Switch may get an `unknown` state during startup. This results in error messages in your log file until that platform has completed loading. If you use `is_state()` function in your template, you can avoid this situation. For example, you would replace {% raw %}`{{ states.switch.source.state == 'on') }}`{% endraw %} with this equivalent that returns `true`/`false` and never gives an unknown result: {% raw %}`{{ is_state('switch.source', 'on') }}`{% endraw %}
### Working without entities
If you use a template that depends on the current time or some other non-deterministic result not sourced from entities, the template won't repeatedly update but will only update when the state of a referenced entity updates. For ways to deal with this issue, see [Working without entities](/integrations/binary_sensor.template/#working-without-entities) in the Template Binary Sensor integration.
## Examples
In this section you find some real-life examples of how to use this switch.

View File

@ -50,10 +50,6 @@ sensor:
description: Defines a template for the name to be used in the frontend (this overrides friendly_name).
required: false
type: template
entity_id:
description: A list of entity IDs so the sensor only reacts to state changes of these entities. This can be used if the automatic analysis fails to find all relevant entities.
required: false
type: [string, list]
unique_id:
description: An ID that uniquely identifies this sensor. Set this to an unique value to allow customisation trough the UI.
required: false
@ -104,9 +100,12 @@ If you are using the state of a platform that takes extra time to load, the Temp
{% raw %}`{{ is_state('switch.source', 'on') }}`{% endraw %}
### Entity IDs
### Sensor state updates
The template engine will attempt to work out what entities should trigger an update of the sensor. This can fail, for example, if your template loops over the contents of a group. In this case, you can use `entity_id` to provide a list of entity IDs that will cause the sensor to update or you can run the service `homeassistant.update_entity` to update the sensor at will.
The template engine works out what entities are used to trigger an update of the sensor and recalculates the result when one of those entities change.
If you use a template that depends on the current time or some other non-deterministic result not sourced from entities, create an interval-based
automation that calls the service `homeassistant.update_entity` for the sensor requiring updates. See the [example below](#working-without-entities).
### Unique ID
@ -322,17 +321,19 @@ sensor:
The `template` sensors are not limited to use attributes from other entities but can also work with [Home Assistant's template extensions](/docs/configuration/templating/#home-assistant-template-extensions).
This template contains no entities that will trigger an update (as `now()` is a function), so we add an `entity_id:` line with an entity that will force an update - here we're using a [date sensor](/integrations/time_date) to get a daily update:
This template contains no entities that will trigger an update, so we add in a reference to the `sensor.date` sensor from the [Time & Date](/integrations/time_date/), which will update once a day.
{% raw %}
```yaml
sensor:
- platform: time_date
display_options:
- 'date'
- platform: template
sensors:
nonsmoker:
value_template: "{{ (( as_timestamp(now()) - as_timestamp(strptime('06.07.2018', '%d.%m.%Y')) ) / 86400 ) | round(2) }}"
entity_id: sensor.date
value_template: '{{ states('sensor.date') and (( as_timestamp(now()) - as_timestamp(strptime("06.07.2018", "%d.%m.%Y")) ) / 86400 ) | round(2) }}'
friendly_name: 'Not smoking'
unit_of_measurement: "Days"
```
@ -367,8 +368,7 @@ sensor:
- platform: template
sensors:
nonsmoker:
value_template: "{{ (( as_timestamp(now()) - as_timestamp(strptime('06.07.2018', '%d.%m.%Y')) ) / 86400 ) | round(2) }}"
entity_id: []
value_template: '{{ (( as_timestamp(now()) - as_timestamp(strptime("06.07.2018", "%d.%m.%Y")) ) / 86400 ) | round(2) }}'
friendly_name: 'Not smoking'
unit_of_measurement: "Days"

View File

@ -74,6 +74,8 @@ It is also recommended that the command `volume_up`, the command `volume_down`,
When providing `select_source` as a command, it is recommended to also provide the attributes `source`, and `source_list`. The `source` attribute is the currently select source, while the `source_list` attribute is a list of all available sources.
When using `state_template`, if you use a template that depends on the current time or some other non-deterministic result not sourced from entities, the template won't repeatedly update but will only update when the state of a referenced entity updates. For ways to deal with this issue, see the [example](/integrations/binary_sensor.template/#working-without-entities) in the template binary_sensor.
## Usage examples
### Chromecast & Kodi control with switches

View File

@ -103,6 +103,10 @@ vacuum:
type: [string, list]
{% endconfiguration %}
### Working without entities
If you use a template that depends on the current time or some other non-deterministic result not sourced from entities, the template won't repeatedly update but will only update when the state of a referenced entity updates. For ways to deal with this issue, see [Working without entities](/integrations/template/#working-without-entities) in the Template Sensor integration.
## Examples
### Control vacuum with Harmony Hub