From cbb417934d15105dac889845e852da8f34243ce4 Mon Sep 17 00:00:00 2001 From: Paulus Schoutsen Date: Mon, 22 Mar 2021 04:23:43 +0000 Subject: [PATCH 1/7] Document trigger entity --- source/_docs/automation/templating.markdown | 34 ++++--- source/_integrations/trigger_entity.markdown | 96 ++++++++++++++++++++ 2 files changed, 112 insertions(+), 18 deletions(-) create mode 100644 source/_integrations/trigger_entity.markdown diff --git a/source/_docs/automation/templating.markdown b/source/_docs/automation/templating.markdown index 38da81fa0bfd..b35b9b4fc6ab 100644 --- a/source/_docs/automation/templating.markdown +++ b/source/_docs/automation/templating.markdown @@ -1,26 +1,10 @@ --- -title: "Automation Templating" -description: "Advanced automation documentation using templating." +title: "Automation Trigger Variables" +description: "List all available variables made available by triggers." --- Automations support [templating](/docs/configuration/templating/) in the same way as scripts do. In addition to the [Home Assistant template extensions](/docs/configuration/templating/#home-assistant-template-extensions) available to scripts, the `trigger` template variable is available. -
- - Be aware that if you reference a `trigger` state object in templates of an automation' `action` or `condition` sections, attempting to test that automation by calling the `automation.trigger` service or by clicking EXECUTE in the More Info box for the automation will not work. This is because the trigger state object doesn't exist in those contexts. One way to test automations like these is to manually check that the templates work as expected by pasting them in {% my developer_template title="Developer Tools > Template" %} together with your trigger's definition like: - -{%raw%} - -```yaml -{% set trigger={'to_state':{'state': 'heat'}} %} -{% set option = trigger.to_state.state %} -{{ 'on' if option == 'heat' else 'off' }} -``` - -{%endraw%} - -
- ## Available Trigger Data The following tables show the available trigger data per platform. @@ -167,3 +151,17 @@ automation 3: {% endraw %} [state object]: /docs/configuration/state_object/ + +## Troubleshooting + +Be aware that if you reference a `trigger` state object in templates of an automation' `action` or `condition` sections, attempting to test that automation by calling the `automation.trigger` service or by clicking EXECUTE in the More Info box for the automation will not work. This is because the trigger state object doesn't exist in those contexts. One way to test automations like these is to manually check that the templates work as expected by pasting them in {% my developer_template title="Developer Tools > Template" %} together with your trigger's definition like: + +{%raw%} + +```yaml +{% set trigger={'to_state':{'state': 'heat'}} %} +{% set option = trigger.to_state.state %} +{{ 'on' if option == 'heat' else 'off' }} +``` + +{%endraw%} diff --git a/source/_integrations/trigger_entity.markdown b/source/_integrations/trigger_entity.markdown new file mode 100644 index 000000000000..23c37de3d400 --- /dev/null +++ b/source/_integrations/trigger_entity.markdown @@ -0,0 +1,96 @@ +--- +title: Trigger Entities +description: Instructions on how to render entities using triggers. +ha_category: + - Automation +ha_release: 2021.4.0 +ha_quality_scale: internal +ha_codeowners: + - '@home-assistant/core' +ha_iot_class: +ha_domain: trigger_entity +ha_platforms: + - sensor +--- + +Trigger Entities allow you to define entities using templates which are updated based on [automation triggers][trigger-docs]. The entity templates will have access to the [trigger variables](/docs/automation/templating/#available-trigger-data). + +```yaml +trigger_entity: + trigger: + - platform: webhook + webhook_id: my-super-secret-webhook-id + sensor: + - name: "Webhook Temperature" + value_template: "{{ trigger.json.temperature }}" +``` + +_(see [below](#example-adding-webhook-data-to-home-assistant) how to test this webhook example)_ + +{% configuration %} +trigger: + description: The trigger configuration for this entity. [See trigger docs][trigger-docs] + required: true + type: list +unique_id: + description: The unique ID for this trigger. This will be prefixed to all unique IDs of all entities. + required: false + type: string +sensor: + description: A list of sensors to create from the trigger data. + required: true + type: list + keys: + name: + description: Name to use in the frontend. + required: false + type: string + unique_id: + description: An ID that uniquely identifies this sensor for this trigger. + required: false + type: string + unit_of_measurement: + description: "Defines the units of measurement of the sensor, if any. Sensors without are assumed to be discrete values." + required: false + type: string + default: None + value_template: + description: Defines a template to get the state of the sensor. + required: true + type: template + device_class: + description: Sets the class of the device, changing the device state and icon that is displayed on the UI (see below). It does not set the `unit_of_measurement`. + required: false + type: device_class + default: None +{% endconfiguration %} + + +## Example: adding webhook data to Home Assistant + +Sometimes the easiest way to get data into Home Assistant is by having the source system send it to Home Assistant. The easiest way to do this in Home Assistant is to use a Trigger Entity configured with a webhook trigger. In our templates we will be able to access the [webhook trigger variables](/docs/automation/templating/#webhook). + +```yaml +trigger_entity: + unique_id: "webhook-environment-info" + trigger: + - platform: webhook + webhook_id: my-super-secret-webhook-id + sensor: + - name: "Webhook Temperature" + unique_id: "temperature" + value_template: "{{ trigger.json.temperature }}" +``` + +You can test this trigger entity with the following CURL command: + +```bash +curl --header "Content-Type: application/json" \ + --request POST \ + --data '{"temperature": 5}' \ + http://homeassistant.local:8123/api/webhook/my-super-secret-webhook-id +``` + +

webhook URL endpoints do not require authentication so pick a randomized webhook ID.

+ +[trigger-docs]: /docs/automatin/trigger From 2b5ec372a44bdc555dfa36795fb9cf6abb13705a Mon Sep 17 00:00:00 2001 From: Paulus Schoutsen Date: Mon, 22 Mar 2021 04:34:40 +0000 Subject: [PATCH 2/7] Spelling --- source/_integrations/trigger_entity.markdown | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/source/_integrations/trigger_entity.markdown b/source/_integrations/trigger_entity.markdown index 23c37de3d400..6ae7fcd9a4ce 100644 --- a/source/_integrations/trigger_entity.markdown +++ b/source/_integrations/trigger_entity.markdown @@ -13,7 +13,7 @@ ha_platforms: - sensor --- -Trigger Entities allow you to define entities using templates which are updated based on [automation triggers][trigger-docs]. The entity templates will have access to the [trigger variables](/docs/automation/templating/#available-trigger-data). +Trigger Entities allow you to define entities using templates which are updated based on [automation triggers][trigger-doc]. The entity templates will have access to the [trigger variables](/docs/automation/templating/#available-trigger-data). ```yaml trigger_entity: @@ -29,7 +29,7 @@ _(see [below](#example-adding-webhook-data-to-home-assistant) how to test this w {% configuration %} trigger: - description: The trigger configuration for this entity. [See trigger docs][trigger-docs] + description: The trigger configuration for this entity. [See trigger documentation][trigger-doc] required: true type: list unique_id: @@ -93,4 +93,4 @@ curl --header "Content-Type: application/json" \

webhook URL endpoints do not require authentication so pick a randomized webhook ID.

-[trigger-docs]: /docs/automatin/trigger +[trigger-doc]: /docs/automatin/trigger From fcbc22dac428a61fe6cd8dbeb763519550edcba3 Mon Sep 17 00:00:00 2001 From: Paulus Schoutsen Date: Mon, 22 Mar 2021 04:35:25 +0000 Subject: [PATCH 3/7] Remove troubleshooting --- source/_docs/automation/templating.markdown | 14 -------------- 1 file changed, 14 deletions(-) diff --git a/source/_docs/automation/templating.markdown b/source/_docs/automation/templating.markdown index b35b9b4fc6ab..937aa423b91a 100644 --- a/source/_docs/automation/templating.markdown +++ b/source/_docs/automation/templating.markdown @@ -151,17 +151,3 @@ automation 3: {% endraw %} [state object]: /docs/configuration/state_object/ - -## Troubleshooting - -Be aware that if you reference a `trigger` state object in templates of an automation' `action` or `condition` sections, attempting to test that automation by calling the `automation.trigger` service or by clicking EXECUTE in the More Info box for the automation will not work. This is because the trigger state object doesn't exist in those contexts. One way to test automations like these is to manually check that the templates work as expected by pasting them in {% my developer_template title="Developer Tools > Template" %} together with your trigger's definition like: - -{%raw%} - -```yaml -{% set trigger={'to_state':{'state': 'heat'}} %} -{% set option = trigger.to_state.state %} -{{ 'on' if option == 'heat' else 'off' }} -``` - -{%endraw%} From 9b896d5e613353d07d3c174f6cd26dca5fd3472e Mon Sep 17 00:00:00 2001 From: Paulus Schoutsen Date: Mon, 22 Mar 2021 09:57:57 -0700 Subject: [PATCH 4/7] Update source/_integrations/trigger_entity.markdown Co-authored-by: Hmmbob <33529490+hmmbob@users.noreply.github.com> --- source/_integrations/trigger_entity.markdown | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/_integrations/trigger_entity.markdown b/source/_integrations/trigger_entity.markdown index 6ae7fcd9a4ce..d97c9a8c4c26 100644 --- a/source/_integrations/trigger_entity.markdown +++ b/source/_integrations/trigger_entity.markdown @@ -93,4 +93,4 @@ curl --header "Content-Type: application/json" \

webhook URL endpoints do not require authentication so pick a randomized webhook ID.

-[trigger-doc]: /docs/automatin/trigger +[trigger-doc]: /docs/automation/trigger From 0ff284ac6dbc5aad71cd9782559c5fee7c50883c Mon Sep 17 00:00:00 2001 From: Paulus Schoutsen Date: Mon, 22 Mar 2021 18:03:35 +0000 Subject: [PATCH 5/7] Use `state` instead of `value_template` --- source/_integrations/trigger_entity.markdown | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/source/_integrations/trigger_entity.markdown b/source/_integrations/trigger_entity.markdown index d97c9a8c4c26..1a2ee73f2622 100644 --- a/source/_integrations/trigger_entity.markdown +++ b/source/_integrations/trigger_entity.markdown @@ -22,7 +22,7 @@ trigger_entity: webhook_id: my-super-secret-webhook-id sensor: - name: "Webhook Temperature" - value_template: "{{ trigger.json.temperature }}" + state: "{{ trigger.json.temperature }}" ``` _(see [below](#example-adding-webhook-data-to-home-assistant) how to test this webhook example)_ @@ -54,7 +54,7 @@ sensor: required: false type: string default: None - value_template: + state: description: Defines a template to get the state of the sensor. required: true type: template @@ -79,7 +79,7 @@ trigger_entity: sensor: - name: "Webhook Temperature" unique_id: "temperature" - value_template: "{{ trigger.json.temperature }}" + state: "{{ trigger.json.temperature }}" ``` You can test this trigger entity with the following CURL command: From 92a520dd90be229019c503cf04128cfb558f40e0 Mon Sep 17 00:00:00 2001 From: Paulus Schoutsen Date: Tue, 30 Mar 2021 16:58:04 +0000 Subject: [PATCH 6/7] Add trigger-based template sensor documentation --- source/_docs/automation/trigger.markdown | 17 +++- source/_integrations/template.markdown | 74 ++++++++++++++- source/_integrations/trigger_entity.markdown | 96 -------------------- 3 files changed, 85 insertions(+), 102 deletions(-) delete mode 100644 source/_integrations/trigger_entity.markdown diff --git a/source/_docs/automation/trigger.markdown b/source/_docs/automation/trigger.markdown index aca3c69e3c62..bb29ef57a97e 100644 --- a/source/_docs/automation/trigger.markdown +++ b/source/_docs/automation/trigger.markdown @@ -3,13 +3,24 @@ title: "Automation Trigger" description: "All the different ways how automations can be triggered." --- -## What are triggers - Triggers are what starts the processing of an automation rule. When _any_ of the automation's triggers becomes true (trigger _fires_), Home Assistant will validate the [conditions](/docs/automation/condition/), if any, and call the [action](/docs/automation/action/). An automation can be triggered by an event, with a certain entity state, at a given time, and more. These can be specified directly or more flexible via templates. It is also possible to specify multiple triggers for one automation. -The following sections introduce all trigger types and further details to get started. +- [Event trigger](#event-trigger) +- [Home Assistant trigger](#home-assistant-trigger) +- [MQTT trigger](#mqtt-trigger) +- [Numeric state trigger](#numeric-state-trigger) +- [State trigger](#state-trigger) +- [Sun trigger](#sun-trigger) +- [Tag trigger](#tag-trigger) +- [Template trigger](#template-trigger) +- [Time trigger](#time-trigger) +- [Time pattern trigger](#time-pattern-trigger) +- [Webhook trigger](#webhook-trigger) +- [Zone trigger](#zone-trigger) +- [Geolocation trigger](#geolocation-trigger) +- [Device triggers](#device-triggers) ## Trigger variables diff --git a/source/_integrations/template.markdown b/source/_integrations/template.markdown index 62337f62370d..0b03e17581e2 100644 --- a/source/_integrations/template.markdown +++ b/source/_integrations/template.markdown @@ -23,7 +23,22 @@ ha_platforms: - weather --- -The `template` platform supports sensors which get their values from other entities. +The `template` integration allows creating entities which derive their values from other entities. This is done by defining [templates](/docs/configuration/templating/) for each property of an entity, like the name or the state. Entities are updated automatically whenever a value that a template relies on changes. + +For sensors it's also possible to derive the state from [automation triggers](#configuration-for-trigger-based-template-sensors). + +Available template platforms: + +- [Alarm_control_panel](/integrations/alarm_control_panel.template/) +- [Binary_sensor](/integrations/binary_sensor.template/) +- [Cover](/integrations/cover.template/) +- [Fan](/integrations/fan.template/) +- [Light](/integrations/light.template/) +- [Lock](/integrations/lock.template/) +- Sensor (this page) +- [Switch](/integrations/switch.template/) +- [Vacuum](/integrations/vacuum.template/) +- [Weather](/integrations/weather.template/) ## Configuration @@ -49,7 +64,7 @@ sensor: {% configuration %} sensors: - description: List of your sensors. + description: Map of your sensors. required: true type: map keys: @@ -90,7 +105,7 @@ sensor: "attribute: template": description: The attribute and corresponding template. required: true - type: template + type: template availability_template: description: Defines a template to get the `available` state of the component. If the template returns `true`, the device is `available`. If the template returns any other value, the device will be `unavailable`. If `availability_template` is not configured, the component will always be `available`. required: false @@ -103,6 +118,59 @@ sensor: default: None {% endconfiguration %} +## Configuration for trigger-based template sensors + +Trigger-based template sensors allow the user to define [an automation trigger][trigger-doc] for a group of template sensors. Whenever the trigger fires, the template sensor will re-render and it will have access to [the trigger data](https://www.home-assistant.io/docs/automation/templating/) in the templates. This feature is a great way to create data based on webhook data, or have sensors be updated based on a time-schedule. + +Trigger-based template entities are defined in YAML directly under the `template:` key. You can define multiple configuration blocks as a list. Each block defines one or more triggers and the sensors that should be updated when the trigger fires. + +Trigger-based entities do not automatically update when states referenced in the templates change. This functionality can be added by defining a [state trigger](/docs/automation/trigger/#state-trigger) for each entity that you want to trigger updates. + +{% raw %} + +```yaml +# Example configuration entry +template: + - trigger: + - platform: webhook + webhook_id: my-super-secret-webhook-id + sensor: + - name: "Webhook Temperature" + state: "{{ trigger.json.temperature }}" + - name: "Webhook Humidity" + state: "{{ trigger.json.humidity }}" +``` + +{% endraw %} + +You can test this trigger entity with the following CURL command: + +```bash +curl --header "Content-Type: application/json" \ + --request POST \ + --data '{"temperature": 5, "humidity": 34}' \ + http://homeassistant.local:8123/api/webhook/my-super-secret-webhook-id +``` + +{% configuration %} +trigger: + description: The trigger configuration for this entity. [See trigger documentation](/docs/automation/trigger) + required: true + type: list +unique_id: + description: The unique ID for this trigger. This will be prefixed to all unique IDs of all entities in this block. + required: false + type: string +sensor: + description: Map of your sensors to create from the trigger data. For available keys, see [configuration variables](#configuration-variables) above. + required: true + type: map +{% endconfiguration %} + +

It's currently only possible to define trigger-based entities via the top-level configuration. These entities are not yet included when reloading template entities.

+ +[trigger-doc]: /docs/automation/trigger + ## Considerations ### Startup diff --git a/source/_integrations/trigger_entity.markdown b/source/_integrations/trigger_entity.markdown deleted file mode 100644 index 1a2ee73f2622..000000000000 --- a/source/_integrations/trigger_entity.markdown +++ /dev/null @@ -1,96 +0,0 @@ ---- -title: Trigger Entities -description: Instructions on how to render entities using triggers. -ha_category: - - Automation -ha_release: 2021.4.0 -ha_quality_scale: internal -ha_codeowners: - - '@home-assistant/core' -ha_iot_class: -ha_domain: trigger_entity -ha_platforms: - - sensor ---- - -Trigger Entities allow you to define entities using templates which are updated based on [automation triggers][trigger-doc]. The entity templates will have access to the [trigger variables](/docs/automation/templating/#available-trigger-data). - -```yaml -trigger_entity: - trigger: - - platform: webhook - webhook_id: my-super-secret-webhook-id - sensor: - - name: "Webhook Temperature" - state: "{{ trigger.json.temperature }}" -``` - -_(see [below](#example-adding-webhook-data-to-home-assistant) how to test this webhook example)_ - -{% configuration %} -trigger: - description: The trigger configuration for this entity. [See trigger documentation][trigger-doc] - required: true - type: list -unique_id: - description: The unique ID for this trigger. This will be prefixed to all unique IDs of all entities. - required: false - type: string -sensor: - description: A list of sensors to create from the trigger data. - required: true - type: list - keys: - name: - description: Name to use in the frontend. - required: false - type: string - unique_id: - description: An ID that uniquely identifies this sensor for this trigger. - required: false - type: string - unit_of_measurement: - description: "Defines the units of measurement of the sensor, if any. Sensors without are assumed to be discrete values." - required: false - type: string - default: None - state: - description: Defines a template to get the state of the sensor. - required: true - type: template - device_class: - description: Sets the class of the device, changing the device state and icon that is displayed on the UI (see below). It does not set the `unit_of_measurement`. - required: false - type: device_class - default: None -{% endconfiguration %} - - -## Example: adding webhook data to Home Assistant - -Sometimes the easiest way to get data into Home Assistant is by having the source system send it to Home Assistant. The easiest way to do this in Home Assistant is to use a Trigger Entity configured with a webhook trigger. In our templates we will be able to access the [webhook trigger variables](/docs/automation/templating/#webhook). - -```yaml -trigger_entity: - unique_id: "webhook-environment-info" - trigger: - - platform: webhook - webhook_id: my-super-secret-webhook-id - sensor: - - name: "Webhook Temperature" - unique_id: "temperature" - state: "{{ trigger.json.temperature }}" -``` - -You can test this trigger entity with the following CURL command: - -```bash -curl --header "Content-Type: application/json" \ - --request POST \ - --data '{"temperature": 5}' \ - http://homeassistant.local:8123/api/webhook/my-super-secret-webhook-id -``` - -

webhook URL endpoints do not require authentication so pick a randomized webhook ID.

- -[trigger-doc]: /docs/automation/trigger From e0c8635694c190c509b615cf8be8c46950599525 Mon Sep 17 00:00:00 2001 From: Franck Nijhof Date: Tue, 30 Mar 2021 19:10:32 +0200 Subject: [PATCH 7/7] Fix link --- source/_integrations/template.markdown | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/_integrations/template.markdown b/source/_integrations/template.markdown index 0b03e17581e2..369304943dab 100644 --- a/source/_integrations/template.markdown +++ b/source/_integrations/template.markdown @@ -120,7 +120,7 @@ sensor: ## Configuration for trigger-based template sensors -Trigger-based template sensors allow the user to define [an automation trigger][trigger-doc] for a group of template sensors. Whenever the trigger fires, the template sensor will re-render and it will have access to [the trigger data](https://www.home-assistant.io/docs/automation/templating/) in the templates. This feature is a great way to create data based on webhook data, or have sensors be updated based on a time-schedule. +Trigger-based template sensors allow the user to define [an automation trigger][trigger-doc] for a group of template sensors. Whenever the trigger fires, the template sensor will re-render and it will have access to [the trigger data](/docs/automation/templating/) in the templates. This feature is a great way to create data based on webhook data, or have sensors be updated based on a time-schedule. Trigger-based template entities are defined in YAML directly under the `template:` key. You can define multiple configuration blocks as a list. Each block defines one or more triggers and the sensors that should be updated when the trigger fires.