State trigger: rephrase (#34571)

* State trigger: rephrase

* Add intro text to example
This commit is contained in:
c0ffeeca7 2024-09-04 14:36:33 +02:00 committed by GitHub
parent 2bcd9ecfbb
commit ed0c871f4e
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194

View File

@ -85,7 +85,7 @@ automation:
## Event trigger
Fires when an event is being received. Events are the raw building blocks of Home Assistant. You can match events on just the event name or also require specific event data or context to be present.
Fires when an {% term event %} is being received. Events are the raw building blocks of Home Assistant. You can match events on just the event name or also require specific event data or context to be present.
Events can be fired by integrations or via the API. There is no limitation to the types. A list of built-in events can be found [here](/docs/configuration/events/).
@ -357,12 +357,22 @@ If for your use case this is undesired, you could consider using the automation
## State trigger
Fires when the state of any of given entities changes. If only `entity_id` is given, the trigger will fire for all state changes, even if only state attributes change.
If at least one of `from`, `to`, `not_from`, or `not_to` are given, the trigger will fire on any matching state change, but not if only attributes change. To trigger on all state changes, but not on changed attributes, set at least one of `from`, `to`, `not_from`, or `not_to` to `null`.
In general, the state trigger fires when the state of any of given entities **changes**. The behavior is as follows:
{% note %}
The values you see in your overview will often not be the same as the actual state of the entity. For instance, the overview may show `Connected` when the underlying entity is actually `on`. You should check the state of the entity by looking in the _States_ menu under _Developer tools_.
{% endnote %}
- If only the `entity_id` is given, the trigger fires for **all** state changes, even if only a state attribute changed.
- If at least one of `from`, `to`, `not_from`, or `not_to` are given, the trigger fires on any matching state change, but not if only an attribute changed.
- To trigger on all state changes, but not on changed attributes, set at least one of `from`, `to`, `not_from`, or `not_to` to `null`.
- Use of the `for` option doesn't survive a Home Assistant restart or the reload of automations.
- During restart or reload, automations that were awaiting `for` the trigger to pass, are reset.
- If for your use case this is undesired, you could consider using the automation to set an [`input_datetime`](/integrations/input_datetime) to the desired time and then use that [`input_datetime`](/integrations/input_datetime) as an automation trigger to perform the desired actions at the set time.
{% tip %}
The values you see in your overview will often not be the same as the actual state of the entity. For instance, the overview may show `Connected` when the underlying entity is actually `on`. You should check the state of the entity by checking the states in the developer tool, under {% my developer_states title="**Developer Tools** > **States**" %}.
{% endtip %}
### Examples
This automation triggers if either Paulus or Anne-Therese are home for one minute.
```yaml
automation:
@ -395,7 +405,7 @@ automation:
to: "error"
```
Trigger on all state changes, but not attributes by setting `to` to `null`:
If you want to trigger on all state changes, but not on attribute changes, you can `to` to `null` (this would also work by setting `from`, `not_from`, or `not_to` to `null`):
```yaml
automation:
@ -405,7 +415,7 @@ automation:
to:
```
The `not_from` and `not_to` options are the counter parts of `from` and `to`. They can be used to trigger on state changes that are **not** the specified state. This can be useful to trigger on all state changes, except specific ones.
If you want to trigger on all state changes *except* specific ones, use `not_from` or `not_to` The `not_from` and `not_to` options are the counter parts of `from` and `to`. They can be used to trigger on state changes that are **not** the specified state.
```yaml
automation:
@ -423,8 +433,8 @@ You cannot use `from` and `not_from` at the same time. The same applies to `to`
### Triggering on attribute changes
When the `attribute` option is specified, the trigger only fires
when the specified attribute changes. Changes to other attributes or the
state are ignored.
when the specified attribute **changes**. Changes to other attributes or
state changes are ignored.
For example, this trigger only fires when the boiler has been heating for 10 minutes:
@ -465,8 +475,8 @@ automation:
for: "00:00:30"
```
Please note, that when holding a state, changes to attributes are ignored and
do not cancel the hold time.
When holding a state, changes to attributes are ignored. Changes to attributes
don't cancel the hold time.
You can also fire the trigger when the state value changed from a specific
state, but hasn't returned to that state value for the specified time.
@ -528,12 +538,6 @@ The `for` template(s) will be evaluated when an entity changes as specified.
Use quotes around your values for `from` and `to` to avoid the YAML parser from interpreting values as booleans.
{% endtip %}
{% important %}
Use of the `for` option will not survive Home Assistant restart or the reload of automations. During restart or reload, automations that were awaiting `for` the trigger to pass, are reset.
If for your use case this is undesired, you could consider using the automation to set an [`input_datetime`](/integrations/input_datetime) to the desired time and then use that [`input_datetime`](/integrations/input_datetime) as an automation trigger to perform the desired actions at the set time.
{% endimportant %}
## Sun trigger
### Sunset / Sunrise trigger