diff --git a/source/_integrations/alarm_control_panel.template.markdown b/source/_integrations/alarm_control_panel.template.markdown deleted file mode 100644 index 47bc9d9b3f6..00000000000 --- a/source/_integrations/alarm_control_panel.template.markdown +++ /dev/null @@ -1,147 +0,0 @@ ---- -title: "Template Alarm control panel" -description: "Instructions on how to integrate template alarm control panels into Home Assistant." -ha_category: - - Alarm - - Helper -ha_release: 0.105 -ha_iot_class: "Local Push" -ha_quality_scale: internal -ha_codeowners: - - '@home-assistant/core' -ha_domain: template -ha_config_flow: true -ha_platforms: - - alarm_control_panel -ha_integration_type: helper -related: - - docs: /docs/configuration/ - title: Configuration file ---- - -The `template` {% term integration %} creates alarm control panels that combine integrations or adds preprocessing logic to actions. - -There are several powerful ways to use this {% term integration %}, including grouping existing integrations into a simpler integrations, or adding logic that Home Assistant will execute when accessed. - -For example, if you want to expose a true alarm panel to Google Home, Alexa, or HomeKit - but limit its ability to disarm when there's no one home, you can do that using a template. - -Another use case could be grouping a series of sensors and services together to represent various "armed" and "disarmed" states and actions. - -This can simplify the GUI and make it easier to write automations. - -In optimistic mode, the alarm control panel will immediately change state after every command. Otherwise, the alarm control panel will wait for state confirmation from the template. Try to enable it, if experiencing incorrect operation. - -{% include integrations/config_flow.md %} - -## YAML Configuration - -To enable a template alarm control panel in your installation, add the following to your {% term "`configuration.yaml`" %} file. -{% include integrations/restart_ha_after_config_inclusion.md %} - -{% raw %} - -```yaml -# Example configuration.yaml entry -alarm_control_panel: - - platform: template - panels: - safe_alarm_panel: - value_template: "{{ states('alarm_control_panel.real_alarm') }}" - arm_away: - action: alarm_control_panel.alarm_arm_away - target: - entity_id: alarm_control_panel.real_alarm - data: - code: !secret alarm_code - arm_home: - action: alarm_control_panel.alarm_arm_home - target: - entity_id: alarm_control_panel.real_alarm - data: - code: !secret alarm_code - disarm: - - condition: state - entity_id: device_tracker.paulus - state: "home" - - action: alarm_control_panel.alarm_disarm - target: - entity_id: alarm_control_panel.real_alarm - data: - code: !secret alarm_code -``` - -{% endraw %} - -{% configuration %} -panels: - description: List of your panels. - required: true - type: map - keys: - alarm_control_panel_name: - description: The slug of the panel. - required: true - type: map - keys: - name: - description: Name to use in the frontend. - required: false - type: string - default: Template Alarm Control Panel - unique_id: - description: An ID that uniquely identifies this alarm control panel. Set this to a unique value to allow customization through the UI. - required: false - type: string - value_template: - description: "Defines a template to set the state of the alarm panel. Only the states `armed_away`, `armed_home`, `armed_night`, `armed_vacation`, `arming`, `disarmed`, `pending`, `triggered` and `unavailable` are used." - required: false - type: template - disarm: - description: Defines an action to run when the alarm is disarmed. - required: false - type: action - arm_away: - description: Defines an action to run when the alarm is armed to away mode. - required: false - type: action - arm_home: - description: Defines an action to run when the alarm is armed to home mode. - required: false - type: action - arm_night: - description: Defines an action to run when the alarm is armed to night mode. - required: false - type: action - arm_vacation: - description: Defines an action to run when the alarm is armed to vacation mode. - required: false - type: action - arm_custom_bypass: - description: Defines an action to run when the alarm is armed to custom bypass mode. - required: false - type: action - trigger: - description: Defines an action to run when the alarm is triggered. - required: false - type: action - code_arm_required: - description: If true, the code is required to arm the alarm. - required: false - type: boolean - default: true - code_format: - description: One of `number`, `text` or `no_code`. Format for the code used to arm/disarm the alarm. - required: false - type: string - default: number -{% endconfiguration %} - -### Template and action variables - -State-based template entities have the special template variable `this` available in their templates and actions. The `this` variable aids [self-referencing](/integrations/template#self-referencing) of an entity's state and attribute in templates and actions. - -## Considerations - -If you are using the state of an 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 %} diff --git a/source/_integrations/cover.template.markdown b/source/_integrations/cover.template.markdown deleted file mode 100644 index c24773e2854..00000000000 --- a/source/_integrations/cover.template.markdown +++ /dev/null @@ -1,376 +0,0 @@ ---- -title: "Template cover" -description: "Instructions on how to integrate template covers into Home Assistant." -ha_category: - - Cover - - Helper -ha_release: 0.48 -ha_iot_class: Local Push -ha_quality_scale: internal -ha_codeowners: - - '@home-assistant/core' -ha_domain: template -ha_platforms: - - cover -ha_integration_type: helper -related: - - docs: /docs/configuration/ - title: Configuration file ---- - -The `template` platform can create covers that combine integrations and provides -the ability to run scripts or invoke actions for each of the open, -close, stop, position and tilt commands of a cover. - -## Configuration - -To enable Template Covers in your installation, -add the following to your {% term "`configuration.yaml`" %} file: - -{% raw %} - -```yaml -# Example configuration.yaml entry -cover: - - platform: template - covers: - garage_door: - device_class: garage - friendly_name: "Garage Door" - value_template: "{{ states('sensor.garage_door')|float > 0 }}" - open_cover: - action: script.open_garage_door - close_cover: - action: script.close_garage_door - stop_cover: - action: script.stop_garage_door -``` - -{% endraw %} - -{% configuration %} - covers: - description: List of your covers. - required: true - type: map - keys: - friendly_name: - description: Name to use in the frontend. - required: false - type: string - unique_id: - description: An ID that uniquely identifies this cover. Set this to a unique value to allow customization through the UI. - required: false - type: string - value_template: - description: Defines a template to get the state of the cover. Valid output values from the template are `open`, `opening`, `closing` and `closed` which are directly mapped to the corresponding states. In addition, `true` is valid as a synonym to `open` and `false` as a synonym to `closed`. If [both a `value_template` and a `position_template`](#combining-value_template-and-position_template) are specified, only `opening` and `closing` are set from the `value_template`. If the template produces a `None` value the state will be set to `unknown`. - required: false - type: template - position_template: - description: Defines a template to get the position of the cover. Legal values are numbers between `0` (closed) and `100` (open). If the template produces a `None` value the current position will be set to `unknown`. - required: false - type: template - icon_template: - description: Defines a template to specify which icon to use. - required: false - type: template - entity_picture_template: - description: Defines a template for the entity picture of the cover. - required: false - type: template - availability_template: - description: Defines a template to get the `available` state of the entity. If the template either fails to render or returns `True`, `"1"`, `"true"`, `"yes"`, `"on"`, `"enable"`, or a non-zero number, the entity will be `available`. If the template returns any other value, the entity will be `unavailable`. If not configured, the entity will always be `available`. Note that the string comparison is not case sensitive; `"TrUe"` and `"yEs"` are allowed. - required: false - type: template - default: true - device_class: - description: Sets the [class of the device](/integrations/cover/), changing the device state and icon that is displayed on the frontend. - required: false - type: string - open_cover: - description: Defines an action to open the cover. If [`open_cover`](#open_cover) is specified, [`close_cover`](#close_cover) must also be specified. At least one of [`open_cover`](#open_cover) and [`set_cover_position`](#set_cover_position) must be specified. - required: inclusive - type: action - close_cover: - description: Defines an action to close the cover. - required: inclusive - type: action - stop_cover: - description: Defines an action to stop the cover. - required: false - type: action - set_cover_position: - description: Defines an action to set to a cover position (between `0` and `100`). The variable `position` will contain the entity's set position. - required: false - type: action - set_cover_tilt_position: - description: Defines an action to set the tilt of a cover (between `0` and `100`). The variable `tilt` will contain the entity's set tilt position. - required: false - type: action - optimistic: - description: Force cover position to use [optimistic mode](#optimistic-mode). - required: false - type: boolean - default: false - tilt_optimistic: - description: Force cover tilt position to use [optimistic mode](#optimistic-mode). - required: false - type: boolean - default: false - tilt_template: - description: Defines a template to get the tilt state of the cover. Legal values are numbers between `0` (closed) and `100` (open). If the template produces a `None` value the current tilt state will be set to `unknown`. - required: false - type: template -{% endconfiguration %} - -### Template and action variables - -State-based template entities have the special template variable `this` available in their templates and actions. The `this` variable aids [self-referencing](/integrations/template#self-referencing) of an entity's state and attribute in templates and actions. - -## Considerations - -If you are using the state of a platform that takes extra time to load, the -Template Cover 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.cover.source.state == 'open' }}`{% endraw %} -with this equivalent that returns `true`/`false` and never gives an unknown -result: -{% raw %}`{{ is_state('cover.source', 'open') }}`{% endraw %} - -## Optimistic mode - -In optimistic mode, the cover position state is maintained internally. This mode -is automatically enabled if neither [`value_template`](#value_template) or -[`position_template`](#position_template) are specified. Note that this is -unlikely to be very reliable without some feedback mechanism, since there is -otherwise no way to know if the cover is moving properly. The cover can be -forced into optimistic mode by using the [`optimistic`](#optimistic) attribute. -There is an equivalent mode for `tilt_position` that is enabled when -[`tilt_template`](#tilt_template) is not specified or when the -[`tilt_optimistic`](#tilt_optimistic) attribute is used. - -## Combining `value_template` and `position_template` - -If both a [`value_template`](#value_template) and a [`position_template`](#position_template) are specified only `opening` and `closing` states are set directly from the `value_template`, the `open` and `closed` states will instead be derived from the cover position. - -| value_template output | result | -| --------------------- | ------------------------------------ | -| open | state defined by `position_template` | -| closed | state defined by `position_template` | -| true | state defined by `position_template` | -| false | state defined by `position_template` | -| opening | state set to `opening` | -| closing | state set to `closing` | -| | No change of state or position | - -## Examples - -In this section you will find some real-life examples of how to use this cover. - -### Garage door - -This example converts a garage door with a controllable switch and position -sensor into a cover. The condition check is optional, but suggested if you -use the same switch to open and close the garage. - -{% raw %} - -```yaml -cover: - - platform: template - covers: - garage_door: - device_class: garage - friendly_name: "Garage Door" - position_template: "{{ states('sensor.garage_door') }}" - open_cover: - - condition: state - entity_id: sensor.garage_door - state: "off" - - action: switch.turn_on - target: - entity_id: switch.garage_door - close_cover: - - condition: state - entity_id: sensor.garage_door - state: "on" - - action: switch.turn_off - target: - entity_id: switch.garage_door - stop_cover: - action: switch.turn_on - target: - entity_id: switch.garage_door - icon_template: >- - {% if states('sensor.garage_door')|float > 0 %} - mdi:garage-open - {% else %} - mdi:garage - {% endif %} -``` - -{% endraw %} - -### Multiple covers - -This example allows you to control two or more covers at once. - -{% raw %} - -```yaml -homeassistant: - customize: - cover_group: - assumed_state: true - -cover: - - platform: template - covers: - cover_group: - friendly_name: "Cover Group" - open_cover: - action: script.cover_group - data: - modus: "open" - close_cover: - action: script.cover_group - data: - modus: "close" - stop_cover: - action: script.cover_group - data: - modus: "stop" - set_cover_position: - action: script.cover_group_position - data: - position: "{{position}}" - set_cover_tilt_position: - action: script.cover_group_tilt_position - data: - tilt: "{{tilt}}" - value_template: "{{is_state('sensor.cover_group', 'open')}}" - icon_template: >- - {% if is_state('sensor.cover_group', 'open') %} - mdi:window-open - {% else %} - mdi:window-closed - {% endif %} - -sensor: - - platform: template - sensors: - cover_group: - value_template: >- - {% if is_state('cover.bedroom', 'open') %} - open - {% elif is_state('cover.livingroom', 'open') %} - open - {% else %} - closed - {% endif %} - -script: - cover_group: - sequence: - - action: "cover.{{modus}}_cover" - target: - entity_id: - - cover.bedroom - - cover.livingroom - cover_group_position: - sequence: - - action: cover.set_cover_position - target: - entity_id: - - cover.bedroom - - cover.livingroom - data: - position: "{{position}}" - -automation: - - alias: "Close covers at night" - triggers: - - trigger: sun - event: sunset - offset: "+00:30:00" - actions: - - action: cover.set_cover_position - target: - entity_id: cover.cover_group - data: - position: 25 -``` - -{% endraw %} - -### Change the icon - -This example shows how to change the icon based on the cover state. - -{% raw %} - -```yaml -cover: - - platform: template - covers: - cover_group: - friendly_name: "Cover Group" - open_cover: - action: script.cover_group - data: - modus: "open" - close_cover: - action: script.cover_group - data: - modus: "close" - stop_cover: - action: script.cover_group - data: - modus: "stop" - value_template: "{{is_state('sensor.cover_group', 'open')}}" - icon_template: >- - {% if is_state('sensor.cover_group', 'open') %} - mdi:window-open - {% else %} - mdi:window-closed - {% endif %} -``` - -{% endraw %} - -### Change the entity picture - -This example shows how to change the entity picture based on the cover state. - -{% raw %} - -```yaml -cover: - - platform: template - covers: - cover_group: - friendly_name: "Cover Group" - open_cover: - action: script.cover_group - data: - modus: "open" - close_cover: - action: script.cover_group - data: - modus: "close" - stop_cover: - action: script.cover_group - data: - modus: "stop" - value_template: "{{is_state('sensor.cover_group', 'open')}}" - entity_picture_template: >- - {% if is_state('sensor.cover_group', 'open') %} - /local/cover-open.png - {% else %} - /local/cover-closed.png - {% endif %} -``` - -{% endraw %} diff --git a/source/_integrations/fan.template.markdown b/source/_integrations/fan.template.markdown deleted file mode 100644 index b2d4caa0871..00000000000 --- a/source/_integrations/fan.template.markdown +++ /dev/null @@ -1,266 +0,0 @@ ---- -title: "Template fan" -description: "Instructions how to setup the template fans within Home Assistant." -ha_category: - - Fan - - Helper -ha_release: 0.69 -ha_iot_class: Local Push -ha_quality_scale: internal -ha_codeowners: - - '@home-assistant/core' -ha_domain: template -ha_platforms: - - fan -ha_integration_type: helper -related: - - docs: /docs/configuration/ - title: Configuration file ---- - -The **Template** {% term integration %} creates fans that combine integrations and provides the -ability to run scripts or invoke actions for each of the `turn_on`, `turn_off`, `set_percentage`, -`set_preset_mode`, `set_oscillating`, and `set_direction` commands of a fan. - -## Configuration - -To enable template fans in your installation, add the following to your -{% term "`configuration.yaml`" %} file: - -{% raw %} - -```yaml -# Example configuration.yaml entry -fan: - - platform: template - fans: - bedroom_fan: - friendly_name: "Bedroom fan" - value_template: "{{ states('input_boolean.state') }}" - percentage_template: "{{ states('input_number.percentage') }}" - preset_mode_template: "{{ states('input_select.preset_mode') }}" - oscillating_template: "{{ states('input_select.osc') }}" - direction_template: "{{ states('input_select.direction') }}" - turn_on: - action: script.fan_on - turn_off: - action: script.fan_off - set_percentage: - action: script.fans_set_speed - data: - percentage: "{{ percentage }}" - set_preset_mode: - action: script.fans_set_preset_mode - data: - preset_mode: "{{ preset_mode }}" - set_oscillating: - action: script.fan_oscillating - data: - oscillating: "{{ oscillating }}" - set_direction: - action: script.fan_direction - data: - direction: "{{ direction }}" - speed_count: 6 - preset_modes: - - 'auto' - - 'smart' - - 'whoosh' -``` - -{% endraw %} - -{% configuration %} - fans: - description: List of your fans. - required: true - type: map - keys: - friendly_name: - description: Name to use in the frontend. - required: false - type: string - unique_id: - description: An ID that uniquely identifies this fan. Set this to a unique value to allow customization through the UI. - required: false - type: string - value_template: - description: "Defines a template to get the state of the fan. Valid values: `on`, `off`" - required: true - type: template - percentage_template: - description: Defines a template to get the speed percentage of the fan. - required: false - type: template - preset_mode_template: - description: Defines a template to get the preset mode of the fan. - required: false - type: template - oscillating_template: - description: "Defines a template to get the osc state of the fan. Valid values: `true`, `false`" - required: false - type: template - direction_template: - description: "Defines a template to get the direction of the fan. Valid values: `forward`, `reverse`" - required: false - type: template - availability_template: - description: Defines a template to get the `available` state of the entity. If the template either fails to render or returns `True`, `"1"`, `"true"`, `"yes"`, `"on"`, `"enable"`, or a non-zero number, the entity will be `available`. If the template returns any other value, the entity will be `unavailable`. If not configured, the entity will always be `available`. Note that the string comparison not case sensitive; `"TrUe"` and `"yEs"` are allowed. - required: false - type: template - default: true - turn_on: - description: Defines an action to run when the fan is turned on. - required: true - type: action - turn_off: - description: Defines an action to run when the fan is turned off. - required: true - type: action - set_percentage: - description: Defines an action to run when the fan is given a speed percentage command. - required: false - type: action - set_preset_mode: - description: Defines an action to run when the fan is given a preset command. - required: false - type: action - set_oscillating: - description: Defines an action to run when the fan is given an osc state command. - required: false - type: action - set_direction: - description: Defines an action to run when the fan is given a direction command. - required: false - type: action - preset_modes: - description: List of preset modes the fan is capable of. This is an arbitrary list of strings and must not contain any speeds. - required: false - type: [string, list] - default: [] - speed_count: - description: The number of speeds the fan supports. Used to calculate the percentage step for the `fan.increase_speed` and `fan.decrease_speed` actions. - required: false - type: integer - default: 100 -{% endconfiguration %} - -### Template and action variables - -State-based template entities have the special template variable `this` available in their templates and actions. The `this` variable aids [self-referencing](/integrations/template#self-referencing) of an entity's state and attribute in templates and actions. - -## Converting from speeds to percentage - -When converting a fan with 3 speeds from the old fan entity model, the following percentages can be used: - -0 - `off` -33 - `low` -66 - `medium` -100 - `high` - -## Examples - -### Helper fan - -This example uses an input_boolean and an input_number to mimic a fan, and -the example shows multiple actions for `set_percentage`. - -{% raw %} - -```yaml -fan: - - platform: template - fans: - helper_fan: - friendly_name: "Helper Fan" - value_template: "{{ states('input_boolean.state') }}" - turn_on: - - action: input_boolean.turn_on - target: - entity_id: input_boolean.state - turn_off: - - action: input_boolean.turn_off - target: - entity_id: input_boolean.state - percentage_template: > - {{ states('input_number.percentage') if is_state('input_boolean.state', 'on') else 0 }} - speed_count: 6 - set_percentage: - - action: input_boolean.turn_{{ 'on' if percentage > 0 else 'off' }} - target: - entity_id: input_boolean.state - - action: input_number.set_value - target: - entity_id: input_number.percentage - data: - value: "{{ percentage }}" -``` - -{% endraw %} - -### Preset modes fan - -This example uses an existing fan with only a percentage. It extends the -percentage value into useable preset modes without a helper entity. - -{% raw %} - -```yaml -fan: - - platform: template - fans: - preset_mode_fan: - friendly_name: "Preset Mode Fan Example" - value_template: "{{ states('fan.percentage_fan') }}" - turn_on: - - action: fan.turn_on - target: - entity_id: fan.percentage_fan - turn_off: - - action: fan.turn_off - target: - entity_id: fan.percentage_fan - percentage_template: > - {{ state_attr('fan.percentage_fan', 'percentage') }} - speed_count: 3 - set_percentage: - - action: fan.set_percentage - target: - entity_id: fan.percentage_fan - data: - percentage: "{{ percentage }}" - preset_modes: - - "off" - - "low" - - "medium" - - "high" - preset_mode_template: > - {% if is_state('fan.percentage_fan', 'on') %} - {% if state_attr('fan.percentage_fan', 'percentage') == 100 %} - high - {% elif state_attr('fan.percentage_fan', 'percentage') == 66 %} - medium - {% else %} - low - {% endif %} - {% else %} - off - {% endif %} - set_preset_mode: - - action: fan.set_percentage - target: - entity_id: fan.percentage_fan - data: - percentage: >- - {% if preset_mode == 'high' %} - 100 - {% elif preset_mode == 'medium' %} - 66 - {% elif preset_mode == 'low' %} - 33 - {% else %} - 0 - {% endif %} -``` - -{% endraw %} diff --git a/source/_integrations/light.template.markdown b/source/_integrations/light.template.markdown deleted file mode 100644 index d19dfc5228f..00000000000 --- a/source/_integrations/light.template.markdown +++ /dev/null @@ -1,430 +0,0 @@ ---- -title: "Template Light" -description: "Instructions on how to integrate Template Lights into Home Assistant." -ha_category: - - Light - - Helper -ha_release: 0.46 -ha_iot_class: Local Push -ha_quality_scale: internal -ha_codeowners: - - '@home-assistant/core' -ha_domain: template -ha_platforms: - - light -ha_integration_type: helper -related: - - docs: /docs/configuration/ - title: Configuration file ---- - -The `template` platform creates lights that combine integrations and provides the -ability to run scripts or invoke actions for each of the on, off, and -brightness commands of a light. - -To enable Template Lights in your installation, add the following to your -{% term "`configuration.yaml`" %} file: - -{% raw %} - -```yaml -# Example configuration.yaml entry -light: - - platform: template - lights: - theater_lights: - friendly_name: "Theater Lights" - level_template: "{{ state_attr('sensor.theater_brightness', 'lux')|int }}" - value_template: "{{ state_attr('sensor.theater_brightness', 'lux')|int > 0 }}" - temperature_template: "{{states('input_number.temperature_input') | int}}" - hs_template: "({{states('input_number.h_input') | int}}, {{states('input_number.s_input') | int}})" - effect_list_template: "{{ state_attr('light.led_strip', 'effect_list') }}" - turn_on: - action: script.theater_lights_on - turn_off: - action: script.theater_lights_off - set_level: - action: script.theater_lights_level - data: - brightness: "{{ brightness }}" - set_temperature: - action: input_number.set_value - data: - value: "{{ color_temp }}" - entity_id: input_number.temperature_input - set_hs: - - action: input_number.set_value - data: - value: "{{ h }}" - entity_id: input_number.h_input - - action: input_number.set_value - data: - value: "{{ s }}" - entity_id: input_number.s_input - - action: light.turn_on - data: - entity_id: - - light.led_strip - transition: "{{ transition | float }}" - hs_color: - - "{{ hs[0] }}" - - "{{ hs[1] }}" - set_effect: - - action: light.turn_on - data: - entity_id: - - light.led_strip - effect: "{{ effect }}" - supports_transition_template: "{{ true }}" -``` - -{% endraw %} - -{% configuration %} - lights: - description: List of your lights. - required: true - type: map - keys: - friendly_name: - description: Name to use in the frontend. - required: false - type: string - unique_id: - description: An ID that uniquely identifies this light. Set this to a unique value to allow customization through the UI. - required: false - type: string - value_template: - description: Defines a template to get the state of the light. - required: false - type: template - default: optimistic - level_template: - description: Defines a template to get the brightness of the light. - required: false - type: template - default: optimistic - temperature_template: - description: Defines a template to get the color temperature of the light. - required: false - type: template - default: optimistic - hs_template: - description: Defines a template to get the HS color of the light. Must render a tuple (hue, saturation). - required: false - type: template - default: optimistic - rgb_template: - description: Defines a template to get the RGB color of the light. Must render a tuple or a list (red, green, blue). - required: false - type: template - default: optimistic - rgbw_template: - description: Defines a template to get the RGBW color of the light. Must render a tuple or a list (red, green, blue, white). - required: false - type: template - default: optimistic - rgbww_template: - description: Defines a template to get the RGBWW color of the light. Must render a tuple or a list (red, green, blue, cold white, warm white). - required: false - type: template - default: optimistic - supports_transition_template: - description: Defines a template to get if light supports transition. Should return boolean value (True/False). If this value is `True` transition parameter in a turn on or turn off call will be passed as a named parameter `transition` to either of the scripts. - required: false - type: template - default: false - effect_list_template: - description: Defines a template to get the list of supported effects. Must render a list - required: inclusive - type: template - default: optimistic - effect_template: - description: Defines a template to get the effect of the light. - required: inclusive - type: template - default: optimistic - min_mireds_template: - description: Defines a template to get the min mireds value of the light. - required: false - type: template - default: optimistic - max_mireds_template: - description: Defines a template to get the max mireds value of the light. - required: false - type: template - default: optimistic - icon_template: - description: Defines a template for an icon or picture, e.g., showing a different icon for different states. - required: false - type: template - availability_template: - description: Defines a template to get the `available` state of the entity. If the template either fails to render or returns `True`, `"1"`, `"true"`, `"yes"`, `"on"`, `"enable"`, or a non-zero number, the entity will be `available`. If the template returns any other value, the entity will be `unavailable`. If not configured, the entity will always be `available`. Note that the string comparison not case sensitive; `"TrUe"` and `"yEs"` are allowed. - required: false - type: template - default: true - turn_on: - description: Defines an action to run when the light is turned on. May receive variables `brightness` and/or `transition`. - required: true - type: action - turn_off: - description: Defines an action to run when the light is turned off. May receive variable `transition`. - required: true - type: action - set_level: - description: Defines an action to run when the light is given a brightness command. The script will only be called if the `turn_on` call only has brightness, and optionally transition. Receives variables `brightness` and optionally `transition`. - required: false - type: action - set_temperature: - description: Defines an action to run when the light is given a color temperature command. Receives variable `color_temp`. May also receive variables `brightness` and/or `transition`. - required: false - type: action - set_hs: - description: "Defines an action to run when the light is given a hs color command. Available variables: `hs` as a tuple, `h` and `s`" - required: false - type: action - set_rgb: - description: "Defines an action to run when the light is given an RGB color command. Available variables: `rgb` as a tuple, `r`, `g` and `b`." - required: false - type: action - set_rgbw: - description: "Defines an action to run when the light is given an RGBW color command. Available variables: `rgbw` as a tuple, `rgb` as a tuple, `r`, `g`, `b` and `w`." - required: false - type: action - set_rgbww: - description: "Defines an action to run when the light is given an RGBWW color command. Available variables: `rgbww` as a tuple, `rgb` as a tuple, `r`, `g`, `b`, `cw` and `ww`." - required: false - type: action - set_effect: - description: Defines an action to run when the light is given an effect command. Receives variable `effect`. May also receive variables `brightness` and/or `transition`. - required: inclusive - type: action -{% endconfiguration %} - -### Template and action variables - -State-based template entities have the special template variable `this` available in their templates and actions. The `this` variable aids [self-referencing](/integrations/template#self-referencing) of an entity's state and attribute in templates and actions. - -## Considerations - -If you are using the state of a platform that takes extra time to load, the -Template Light 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 %} -Transition doesn't have its own script, it will instead be passed as a named parameter `transition` to the `turn_on`, `turn_off`, `brightness`, `color_temp`, `effect`, `hs_color`, `rgb_color`, `rgbw_color` or `rgbww_color` scripts. -Brightness will be passed as a named parameter `brightness` to either of `turn_on`, `color_temp`, `effect`, `hs_color`, `rgb_color`, `rgbw_color` or `rgbww_color` scripts if the corresponding parameter is also in the call. In this case, the brightness script (`set_level`) will not be called. -If only brightness is passed to `light.turn_on` action, then `set_level` script is called. - -## Examples - -In this section you will find some real-life examples of how to use this light. - -### Theater Volume Control - -This example shows a light that is actually a home theater's volume. This -integration gives you the flexibility to provide whatever you'd like to send as -the payload to the consumer including any scale conversions you may need to -make; the [media player integration](/integrations/media_player/) needs a floating -point percentage value from `0.0` to `1.0`. - -{% raw %} - -```yaml -light: - - platform: template - lights: - theater_volume: - friendly_name: "Receiver Volume" - value_template: >- - {% if is_state('media_player.receiver', 'on') %} - {% if state_attr('media_player.receiver', 'is_volume_muted') %} - off - {% else %} - on - {% endif %} - {% else %} - off - {% endif %} - turn_on: - action: media_player.volume_mute - target: - entity_id: media_player.receiver - data: - is_volume_muted: false - turn_off: - action: media_player.volume_mute - target: - entity_id: media_player.receiver - data: - is_volume_muted: true - set_level: - action: media_player.volume_set - target: - entity_id: media_player.receiver - data: - volume_level: "{{ (brightness / 255 * 100)|int / 100 }}" - level_template: >- - {% if is_state('media_player.receiver', 'on') %} - {{ (state_attr('media_player.receiver', 'volume_level')|float * 255)|int }} - {% else %} - 0 - {% endif %} -``` - -{% endraw %} - -### Change The Icon - -This example shows how to change the icon based on the light state. - -{% raw %} - -```yaml -light: - - platform: template - lights: - theater_volume: - friendly_name: "Receiver Volume" - value_template: >- - {% if is_state('media_player.receiver', 'on') %} - {% if state_attr('media_player.receiver', 'is_volume_muted') %} - off - {% else %} - on - {% endif %} - {% else %} - off - {% endif %} - icon_template: >- - {% if is_state('media_player.receiver', 'on') %} - {% if state_attr('media_player.receiver', 'is_volume_muted') %} - mdi:lightbulb-off - {% else %} - mdi:lightbulb-on - {% endif %} - {% else %} - mdi:lightbulb-off - {% endif %} - turn_on: - action: media_player.volume_mute - target: - entity_id: media_player.receiver - data: - is_volume_muted: false - turn_off: - action: media_player.volume_mute - target: - entity_id: media_player.receiver - data: - is_volume_muted: true -``` - -{% endraw %} - -### Change The Entity Picture - -This example shows how to change the entity picture based on the light state. - -{% raw %} - -```yaml -light: - - platform: template - lights: - theater_volume: - friendly_name: "Receiver Volume" - value_template: >- - {% if is_state('media_player.receiver', 'on') %} - {% if state_attr('media_player.receiver', 'is_volume_muted') %} - off - {% else %} - on - {% endif %} - {% else %} - off - {% endif %} - icon_template: >- - {% if is_state('media_player.receiver', 'on') %} - {% if state_attr('media_player.receiver', 'is_volume_muted') %} - /local/lightbulb-off.png - {% else %} - /local/lightbulb-on.png - {% endif %} - {% else %} - /local/lightbulb-off.png - {% endif %} - turn_on: - action: media_player.volume_mute - target: - entity_id: media_player.receiver - data: - is_volume_muted: false - turn_off: - action: media_player.volume_mute - target: - entity_id: media_player.receiver - data: - is_volume_muted: true -``` - -{% endraw %} - -### Make a global light entity for a multi-segment WLED light - -This example shows how to group together 2 RGBW segments from the same WLED controller into a single usable light - -{% raw %} - -```yaml -light: - - platform: template - lights: - wled_global: - unique_id: 28208f257b54c44e50deb2d618d44710 - friendly_name: "Multi-segment Wled control" - value_template: "{{ states('light.wled_master') }}" - level_template: "{{ state_attr('light.wled_master', 'brightness')|d(0,true)|int }}" - rgbw_template: ( - {{ (state_attr('light.wled_segment_0', 'rgbw_color')[0]|d(0) + state_attr('light.wled_segment_1', 'rgbw_color')[0]|d(0))/2 }}, - {{ (state_attr('light.wled_segment_0', 'rgbw_color')[1]|d(0) + state_attr('light.wled_segment_1', 'rgbw_color')[1]|d(0))/2 }}, - {{ (state_attr('light.wled_segment_0', 'rgbw_color')[2]|d(0) + state_attr('light.wled_segment_1', 'rgbw_color')[2]|d(0))/2 }}, - {{ (state_attr('light.wled_segment_0', 'rgbw_color')[3]|d(0) + state_attr('light.wled_segment_1', 'rgbw_color')[3]|d(0))/2 }} - ) - effect_list_template: "{{ state_attr('light.wled_segment_0', 'effect_list') }}" - effect_template: "{{ state_attr('light.wled_segment_0', 'effect') if state_attr('light.wled_segment_0', 'effect') == state_attr('light.wled_segment_1', 'effect') else none }}" - availability_template: "{{ not is_state('light.wled_master', 'unknown') }}" - - turn_on: - action: light.turn_on - entity_id: light.wled_segment_0, light.wled_segment_1, light.wled_master - turn_off: - action: light.turn_off - entity_id: light.wled_master - set_level: - action: light.turn_on - entity_id: light.wled_master - data: - brightness: "{{ brightness }}" - set_rgbw: - action: light.turn_on - entity_id: light.wled_segment_0, light.wled_segment_1 - data: - rgbw_color: - - "{{ r }}" - - "{{ g }}" - - "{{ b }}" - - "{{ w }}" - effect: "Solid" - set_effect: - action: light.turn_on - entity_id: light.wled_segment_0, light.wled_segment_1 - data: - effect: "{{ effect }}" -``` - -{% endraw %} diff --git a/source/_integrations/lock.template.markdown b/source/_integrations/lock.template.markdown deleted file mode 100644 index ddfeaf7f367..00000000000 --- a/source/_integrations/lock.template.markdown +++ /dev/null @@ -1,213 +0,0 @@ ---- -title: "Template Lock" -description: "Instructions on how to integrate Template Locks into Home Assistant." -ha_category: - - Lock - - Helper -ha_release: 0.81 -ha_iot_class: Local Push -ha_quality_scale: internal -ha_codeowners: - - '@home-assistant/core' -ha_domain: template -ha_platforms: - - lock -ha_integration_type: helper -related: - - docs: /docs/configuration/ - title: Configuration file ---- - -The `template` platform creates locks that combines components. - -For example, if you have a garage door with a toggle switch that operates the motor and a sensor that allows you know whether the door is open or closed, you can combine these into a lock that knows whether the garage door is open or closed. - -This can simplify the GUI and make it easier to write automations. - -In optimistic mode, the lock will immediately change state after every command. Otherwise, the lock will wait for state confirmation from the template. Try to enable it, if experiencing incorrect lock operation. - -## Configuration - -To enable Template Locks in your installation, add the following to your {% term "`configuration.yaml`" %} file: - -{% raw %} - -```yaml -# Example configuration.yaml entry -lock: - - platform: template - name: Garage door - value_template: "{{ is_state('sensor.door', 'on') }}" - lock: - action: switch.turn_on - target: - entity_id: switch.door - unlock: - action: switch.turn_off - target: - entity_id: switch.door -``` - -{% endraw %} - -{% configuration %} - name: - description: Name to use in the frontend. - required: false - type: string - default: Template Lock - unique_id: - description: An ID that uniquely identifies this lock. Set this to a unique value to allow customization through the UI. - required: false - type: string - value_template: - description: Defines a template to set the state of the lock. - required: true - type: template - availability_template: - description: Defines a template to get the `available` state of the entity. If the template either fails to render or returns `True`, `"1"`, `"true"`, `"yes"`, `"on"`, `"enable"`, or a non-zero number, the entity will be `available`. If the template returns any other value, the entity will be `unavailable`. If not configured, the entity will always be `available`. Note that the string comparison not case sensitive; `"TrUe"` and `"yEs"` are allowed. - required: false - type: template - default: true - code_format_template: - description: Defines a template to get the `code_format` attribute of the entity. This template must evaluate to a valid [Python regular expression](https://docs.python.org/3/library/re.html#regular-expression-syntax) or `None`. If it evaluates to a not-`None` value, the user is prompted to enter a code when interacting with the lock. The code will be matched against the regular expression, and only if it matches, the lock/unlock actions will be executed. The actual _validity_ of the entered code must be verified within these actions. If there's a syntax error in the template, the entity will be unavailable. If the template fails to render for other reasons or if the regular expression is invalid, no code will be accepted and the lock/unlock actions will never be invoked. - required: false - type: template - default: None - lock: - description: Defines an action to run when the lock is locked. - required: true - type: action - unlock: - description: Defines an action to run when the lock is unlocked. - required: true - type: action - open: - description: Defines an action to run when the lock is opened. - required: false - type: action - optimistic: - description: Flag that defines if lock works in optimistic mode. - required: false - type: boolean - default: false -{% endconfiguration %} - -### Template and action variables - -State-based template entities have the special template variable `this` available in their templates and actions. The `this` variable aids [self-referencing](/integrations/template#self-referencing) of an entity's state and attribute in templates and actions. - -## Considerations - -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 %}`{{ 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 %} - -## Examples - -In this section, you find some real-life examples of how to use this lock. - -### Lock from Switch - -This example shows a lock that copies data from a switch. - -{% raw %} - -```yaml -lock: - - platform: template - name: Garage Door - value_template: "{{ is_state('switch.source', 'on') }}" - lock: - action: switch.turn_on - target: - entity_id: switch.source - unlock: - action: switch.turn_off - target: - entity_id: switch.source -``` - -{% endraw %} - -### Optimistic mode - -This example shows a lock in optimistic mode. This lock will immediately change state after command and will not wait for state update from the sensor. - -{% raw %} - -```yaml -lock: - - platform: template - name: Garage Door - value_template: "{{ is_state('sensor.skylight.state', 'on') }}" - optimistic: true - lock: - action: switch.turn_on - target: - entity_id: switch.source - unlock: - action: switch.turn_off - target: - entity_id: switch.source -``` - -{% endraw %} - -### Sensor and Two Switches - -This example shows a lock that takes its state from a sensor, and uses two momentary switches to control a device. - -{% raw %} - -```yaml -lock: - - platform: template - name: Garage Door - value_template: "{{ is_state('sensor.skylight.state', 'on') }}" - lock: - action: switch.turn_on - target: - entity_id: switch.skylight_open - unlock: - action: switch.turn_on - target: - entity_id: switch.skylight_close -``` - -{% endraw %} - -### Lock from switch with dynamic code - -This example shows a lock that copies data from a switch. It needs a PIN code defined as a [secret](/docs/configuration/secrets) to unlock and no code to lock. Note that the actual validity check of the code is part of the `unlock` action and should always happen there or in scripts called from these actions. In this way, you can not only perform code checks against static values, but also dynamic ones (for instance, TOTPs). - -{% raw %} - -```yaml -lock: - - platform: template - name: Garage Door - value_template: "{{ is_state('switch.source', 'on') }}" - code_format_template: "{{ '\\d{4}' if is_state('switch.source', 'on') else None }}" - lock: - - action: switch.turn_on - target: - entity_id: switch.source - unlock: - - variables: - pin: !secret garage_door_pin - - condition: "{{ code == pin }}" - - action: switch.turn_off - target: - entity_id: switch.source -``` - -{% endraw %} - -In `secrets.yaml`: - -{% raw %} - -```yaml -garage_door_pin: "1234" -``` - -{% endraw %} diff --git a/source/_integrations/switch.template.markdown b/source/_integrations/switch.template.markdown deleted file mode 100644 index a986dbde679..00000000000 --- a/source/_integrations/switch.template.markdown +++ /dev/null @@ -1,285 +0,0 @@ ---- -title: "Template Switch" -description: "Instructions on how to integrate Template Switches into Home Assistant." -ha_category: - - Switch - - Helper -ha_release: 0.13 -ha_iot_class: Local Push -ha_quality_scale: internal -ha_codeowners: - - '@home-assistant/core' -ha_domain: template -ha_config_flow: true -ha_platforms: - - switch -ha_integration_type: helper -related: - - docs: /docs/configuration/ - title: Configuration file ---- - -The `template` platform creates switches that combines components. - -For example, if you have a garage door with a toggle switch that operates the motor and a sensor that allows you know whether the door is open or closed, you can combine these into a switch that knows whether the garage door is open or closed. - -This can simplify the GUI and make it easier to write automations. - -{% include integrations/config_flow.md %} - -{% important %} -To be able to add **{% my helpers title="Helpers" %}** via the user interface, you should have `default_config:` in your {% term "`configuration.yaml`" %}. It should already be there by default unless you removed it. -{% endimportant %} - -{% note %} -Configuration using our user interface provides a more limited subset of options, making this integration more accessible while covering most use cases. - -If you need more specific features for your use case, the manual [YAML-configuration section](#yaml-configuration) of this integration might provide them. -{% endnote %} - -## YAML Configuration - -To enable Template Switches in your installation, add the following to your {% term "`configuration.yaml`" %} file: - -{% raw %} - -```yaml -# Example configuration.yaml entry -switch: - - platform: template - switches: - skylight: - value_template: "{{ is_state('sensor.skylight', 'on') }}" - turn_on: - action: switch.turn_on - target: - entity_id: switch.skylight_open - turn_off: - action: switch.turn_off - target: - entity_id: switch.skylight_close -``` - -{% endraw %} - -{% configuration %} - switches: - description: List of your switches. - required: true - type: map - keys: - friendly_name: - description: Name to use in the frontend. - required: false - type: string - unique_id: - description: An ID that uniquely identifies this switch. Set this to a unique value to allow customization through the UI. - required: false - type: string - value_template: - description: Defines a template to set the state of the switch. If not defined, the switch will optimistically assume all commands are successful. - required: false - type: template - default: optimistic - availability_template: - description: Defines a template to get the `available` state of the entity. If the template either fails to render or returns `True`, `"1"`, `"true"`, `"yes"`, `"on"`, `"enable"`, or a non-zero number, the entity will be `available`. If the template returns any other value, the entity will be `unavailable`. If not configured, the entity will always be `available`. Note that the string comparison not case sensitive; `"TrUe"` and `"yEs"` are allowed. - required: false - type: template - default: true - turn_on: - description: Defines an action or list of actions to run when the switch is turned on. - required: true - type: action - turn_off: - description: Defines an action or list of actions to run when the switch is turned off. - required: true - type: action - icon_template: - description: Defines a template for the icon of the switch. - required: false - type: template - entity_picture_template: - description: Defines a template for the picture of the switch. - required: false - type: template -{% endconfiguration %} - -### Template and action variables - -State-based template entities have the special template variable `this` available in their templates and actions. The `this` variable aids [self-referencing](/integrations/template#self-referencing) of an entity's state and attribute in templates and actions. - -## Considerations - -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 %} - -## Examples - -In this section you find some real-life examples of how to use this switch. - -### Invert a Switch - -This example shows a switch that is the inverse of another switch. - -{% raw %} - -```yaml -switch: - - platform: template - switches: - invert: - value_template: "{{ not is_state('switch.target', 'on') }}" - availability_template: "{{ has_value('switch.target') }}" - turn_on: - action: switch.turn_off - target: - entity_id: switch.target - turn_off: - action: switch.turn_on - target: - entity_id: switch.target -``` - -{% endraw %} - -### Toggle Switch - -This example shows a switch that takes its state from a sensor and toggles a switch. - -{% raw %} - -```yaml -switch: - - platform: template - switches: - blind: - friendly_name: "Blind" - value_template: "{{ is_state_attr('switch.blind_toggle', 'sensor_state', 'on') }}" - turn_on: - action: switch.toggle - target: - entity_id: switch.blind_toggle - turn_off: - action: switch.toggle - target: - entity_id: switch.blind_toggle -``` - -{% endraw %} - -### Multiple actions for turn_on or turn_off - -This example shows multiple actions for turn_on and turn_off. - -{% raw %} - -```yaml -switch: - - platform: template - switches: - copy: - value_template: "{{ is_state('switch.source', 'on') }}" - turn_on: - - action: switch.turn_on - target: - entity_id: switch.target - - action: light.turn_on - target: - entity_id: light.target - data: - brightness_pct: 40 - turn_off: - - action: switch.turn_off - target: - entity_id: switch.target - - action: light.turn_off - target: - entity_id: light.target -``` - -{% endraw %} - -### Sensor and Two Switches - -This example shows a switch that takes its state from a sensor, and uses two -momentary switches to control a device. - -{% raw %} - -```yaml -switch: - - platform: template - switches: - skylight: - friendly_name: "Skylight" - value_template: "{{ is_state('sensor.skylight', 'on') }}" - turn_on: - action: switch.turn_on - target: - entity_id: switch.skylight_open - turn_off: - action: switch.turn_on - target: - entity_id: switch.skylight_close -``` - -{% endraw %} - -### Change The Icon - -This example shows how to change the icon based on the state of the garage door. - -{% raw %} - -```yaml -switch: - - platform: template - switches: - garage: - value_template: "{{ is_state('cover.garage_door', 'open') }}" - turn_on: - action: cover.open_cover - target: - entity_id: cover.garage_door - turn_off: - action: cover.close_cover - target: - entity_id: cover.garage_door - icon_template: >- - {% if is_state('cover.garage_door', 'open') %} - mdi:garage-open - {% else %} - mdi:garage - {% endif %} -``` - -{% endraw %} - -### Change The Entity Picture - -This example shows how to change the entity picture based on the state of the garage door. - -{% raw %} - -```yaml -switch: - - platform: template - switches: - garage: - value_template: "{{ is_state('cover.garage_door', 'open') }}" - turn_on: - action: cover.open_cover - target: - entity_id: cover.garage_door - turn_off: - action: cover.close_cover - target: - entity_id: cover.garage_door - entity_picture_template: >- - {% if is_state('cover.garage_door', 'open') %} - /local/garage-open.png - {% else %} - /local/garage-closed.png - {% endif %} -``` - -{% endraw %} diff --git a/source/_integrations/template.markdown b/source/_integrations/template.markdown index fcc432d01ae..f676873047d 100644 --- a/source/_integrations/template.markdown +++ b/source/_integrations/template.markdown @@ -50,18 +50,22 @@ related: The `template` integration allows creating entities which derive their values from other data. This is done by specifying [templates](/docs/configuration/templating/) for properties of an entity, like the name or the state. -Alarm control panels, binary sensors, buttons, covers, fans, images, lights, locks, numbers, selects, sensors, switches, vacuums, and weathers are covered on this page. They can be configured using [UI](#configuration) or [YAML](#yaml-configuration) file. +There is currently support for the following device types within Home Assistant: -For Legacy types, please see the specific pages: - -- [Alarm control panel](/integrations/alarm_control_panel.template/) -- [Cover](/integrations/cover.template/) -- [Fan](/integrations/fan.template/) -- [Light](/integrations/light.template/) -- [Lock](/integrations/lock.template/) -- [Switch](/integrations/switch.template/) -- [Vacuum](/integrations/vacuum.template/) -- [Weather](/integrations/weather.template/) +- [Alarm control panel](#alarm-control-panel) +- [Binary sensor](#binary-sensor) +- [Button](#button) +- [Cover](#cover) +- [Fan](#fan) +- [Image](#image) +- [Light](#light) +- [Lock](#lock) +- [Number](#number) +- [Select](#select) +- [Sensor](#sensor) +- [Switch](#switch) +- [Vacuum](#vacuum) +- [Weather](#weather) {% include integrations/config_flow.md %} @@ -77,11 +81,9 @@ If you need more specific features for your use case, the manual [YAML-configura ## YAML configuration -Entities (alarm control panels, binary sensors, buttons, covers, fans, images, lights, locks, numbers, selects, sensors, switches, vacuums, and weathers) are defined in your YAML configuration files under the `template:` key. You can define multiple configuration blocks as a list. Each block defines sensor/binary sensor/number/select entities and can contain optional update triggers. +Entities are defined in your YAML configuration files under the `template:` key. You can define multiple configuration blocks as a list. Each block defines sensor/binary sensor/number/select entities and can contain optional update triggers. -_For old sensor/binary sensor configuration format, [see below](#legacy-binary-sensor-configuration-format)._ - -### State-based template (all platforms / domains) +### State-based template entities Template entities will by default update as soon as any of the referenced data in the template updates. @@ -156,7 +158,7 @@ unique_id: required: false type: string variables: - description: Key-value pairs of variable definitions which can be referenced and used in the templates below (for trigger-based entities only). Mostly used by blueprints. With State-based template entities, variables are only resolved when the configuration is loaded or reloaded. Trigger based template entities resolve variables between triggers and actions. + description: Key-value pairs of variable definitions which can be referenced and used in the templates below (for trigger-based entities only). Mostly used by blueprints. With State-based template entities, variables are only resolved when the configuration is loaded or reloaded. Trigger based template entities resolve variables between triggers and actions. required: false type: map keys: @@ -164,46 +166,98 @@ variables: description: The variable name and corresponding value. required: true type: string -"[all sensor, binary sensor, button, image, light, number, select, switch, weather entities]": - description: Fields that can be used above for sensors, binary sensors, buttons, numbers, and selects. - required: false - type: map - keys: - availability: - description: Defines a template to get the `available` state of the entity. If the template either fails to render or returns `True`, `"1"`, `"true"`, `"yes"`, `"on"`, `"enable"`, or a non-zero number, the entity will be `available`. If the template returns any other value, the entity will be `unavailable`. If not configured, the entity will always be `available`. Note that the string comparison is not case sensitive; `"TrUe"` and `"yEs"` are allowed. - required: false - type: template - default: true - icon: - description: Defines a template for the icon of the entity. - required: false - type: template - picture: - description: Defines a template for the entity picture of the sensor. - required: false - type: template - name: - description: Defines a template to get the name of the entity. - required: false - type: template - unique_id: - description: An ID that uniquely identifies this entity. Will be combined with the unique ID of the configuration block if available. This allows changing the `name`, `icon` and `entity_id` from the web interface. - required: false - type: string -"[all binary_sensor, sensor, vacuum entities]": - description: Fields that can be used above for binary sensors, sensors, and vacuums. - required: false - type: map - keys: - attributes: - description: Defines templates for attributes of the entity. - required: false - type: map - keys: - "attribute: template": - description: The attribute and corresponding template. - required: true - type: template + +{% endconfiguration %} + +## Common Device Configuration Options + +Each entity platform has its own set of configuration options, but there are some common options that can be used across all entity platforms. + +{% raw %} + +```yaml +# Example configuration.yaml entry +template: + binary_sensor: + # Common configuration options + - unique_id: my_unique_sensor_id + availability: "{{ 'sensor.watts' | has_value }}" + icon: "{{ 'mdi:flash-alert' if states('sensor.watts') | float > 100 else 'mdi:flash' }}" + name: "{{ states('sensor.watts') }} Alert" + # Entity specific configuration options + state: "{{ states('sensor.watts') | float > 100}}" + device_class: problem +``` + +{% endraw %} + +{% configuration %} + availability: + description: Defines a template to get the `available` state of the entity. If the template either fails to render or returns `True`, `"1"`, `"true"`, `"yes"`, `"on"`, `"enable"`, or a non-zero number, the entity will be `available`. If the template returns any other value, the entity will be `unavailable`. If not configured, the entity will always be `available`. Note that the string comparison is not case sensitive; `"TrUe"` and `"yEs"` are allowed. + required: false + type: template + default: true + icon: + description: Defines a template for the icon of the entity. + required: false + type: template + picture: + description: Defines a template for the entity picture of the sensor. + required: false + type: template + name: + description: Defines a template to get the name of the entity. + required: false + type: template + unique_id: + description: An ID that uniquely identifies this entity. Will be combined with the unique ID of the configuration block if available. This allows changing the `name`, `icon` and `entity_id` from the web interface. + required: false + type: string + +{% endconfiguration %} + +## Alarm Control Panel + +The template alarm control panel platform allows you to create a alarm control panels with templates to define the state and scripts to define each actions. + +Alarm control panel entities can be created from the frontend in the Helpers section or via YAML. Alarm control panel entities do not support trigger-based configurations. + +{% raw %} + +```yaml +# Example state-based configuration.yaml entry +template: + - alarm_control_panel: + - name: "Alarm Control Panel 1" + state: "{{ states('input_select.panel_1_state') }}" + arm_away: + action: script.arm_panel_away + arm_home: + action: script.arm_panel_home + disarm: + action: script.disarm_panel +``` + +```yaml +# Example trigger-based configuration.yaml entry +template: + - triggers: + - trigger: state + entity_id: input_select.panel_1_state + alarm_control_panel: + - name: "Alarm Control Panel 1" + state: "{{ states('input_select.panel_1_state') }}" + arm_away: + action: script.arm_panel_away + arm_home: + action: script.arm_panel_home + disarm: + action: script.disarm_panel +``` + +{% endraw %} + +{% configuration %} alarm_control_panel: description: List of alarm control panels required: true @@ -251,11 +305,54 @@ alarm_control_panel: description: Defines an action to run when the alarm is triggered. required: false type: action +{% endconfiguration %} + +## Binary Sensor + +The template binary sensor platform allows you to create binary sensors with templates to define the state and attributes. + +Binary sensor entities can be created from the frontend in the Helpers section or via YAML. + +{% raw %} + +```yaml +# Example state-based configuration.yaml entry +template: + - binary_sensor: + - name: Sun Up + state: > + {{ is_state("sun.sun", "above_horizon") }} +``` + +```yaml +# Example trigger-based configuration.yaml entry +template: + - triggers: + - trigger: state + entity_id: sun.sun + binary_sensor: + - name: Sun Up + state: > + {{ is_state("sun.sun", "above_horizon") }} +``` + +{% endraw %} + +{% configuration %} binary_sensor: description: List of binary sensors required: true type: list keys: + attributes: + description: Defines templates for attributes of the entity. + required: false + type: map + keys: + "attribute: template": + description: The attribute and corresponding template. + required: true + type: template auto_off: description: "**Requires a trigger.** After how much time the entity should turn off after it rendered 'on'." required: false @@ -277,6 +374,158 @@ binary_sensor: description: The sensor is `on` if the template evaluates as `True`, `yes`, `on`, `enable` or a positive number. Any other value will render it as `off`. The actual appearance in the frontend (`Open`/`Closed`, `Detected`/`Clear` etc) depends on the sensor's device_class value required: true type: template + +{% endconfiguration %} + +### State based binary sensor - Washing Machine Running + +This example creates a washing machine "load running" sensor by monitoring an +energy meter connected to the washer. During the washer's operation, the energy meter will fluctuate wildly, hitting zero frequently even before the load is finished. By utilizing `delay_off`, we can have this sensor only turn off if there has been no washer activity for 5 minutes. + +{% raw %} + +```yaml +# Example configuration.yaml entry +# Determine when the washing machine has a load running. +template: + - binary_sensor: + - name: "Washing Machine" + delay_off: + minutes: 5 + state: > + {{ states('sensor.washing_machine_power')|float > 0 }} +``` + +{% endraw %} + +### State based binary sensor - Is Anyone Home + +This example is determining if anyone is home based on the combination of device tracking and motion sensors. It's extremely useful if you have kids/baby sitter/grand parents who might still be in your house that aren't represented by a trackable device in Home Assistant. This is providing a composite of Wi-Fi based device tracking and Z-Wave multisensor presence sensors. + +{% raw %} + +```yaml +# Example configuration.yaml entry +template: + - binary_sensor: + - name: People home + state: > + {{ is_state('device_tracker.sean', 'home') + or is_state('device_tracker.susan', 'home') + or is_state('binary_sensor.office_124', 'on') + or is_state('binary_sensor.hallway_134', 'on') + or is_state('binary_sensor.living_room_139', 'on') + or is_state('binary_sensor.porch_ms6_1_129', 'on') + or is_state('binary_sensor.family_room_144', 'on') }} +``` + +{% endraw %} + +### State based binary sensor - device tracker sensor with latitude and longitude attributes + +This example shows how to combine a non-GPS (e.g., NMAP) and GPS device tracker while still including latitude and longitude attributes + +{% raw %} + +```yaml +# Example configuration.yaml entry +template: + - binary_sensor: + - name: My Device + state: > + {{ is_state('device_tracker.my_device_nmap', 'home') or is_state('device_tracker.my_device_gps', 'home') }} + device_class: "presence" + attributes: + latitude: > + {% if is_state('device_tracker.my_device_nmap', 'home') %} + {{ state_attr('zone.home', 'latitude') }} + {% else %} + {{ state_attr('device_tracker.my_device_gps', 'latitude') }} + {% endif %} + longitude: > + {% if is_state('device_tracker.my_device_nmap', 'home') %} + {{ state_attr('zone.home', 'longitude') }} + {% else %} + {{ state_attr('device_tracker.my_device_gps', 'longitude') }} + {% endif %} +``` + +{% endraw %} + +### State based binary sensor - Change the icon when a state changes + +This example demonstrates how to use template to change the icon as its state changes. This icon is referencing its own state. + +{% raw %} + +```yaml +# Example configuration.yaml entry +template: + - binary_sensor: + - name: Sun Up + state: > + {{ is_state("sun.sun", "above_horizon") }} + icon: > + {% if is_state("binary_sensor.sun_up", "on") %} + mdi:weather-sunset-up + {% else %} + mdi:weather-sunset-down + {% endif %} +``` + +{% endraw %} + +### Trigger based binary sensor - Change state and icon when a custom event is received + +A more advanced use case could be to set the icon based on the sensor's own state like above, but when triggered by an event. This example demonstrates a binary sensor that turns on momentarily, such as when a doorbell button is pressed. + +The binary sensor turns on and sets the matching icon when the appropriate event is received. After 5 seconds, the binary sensor turns off automatically. To ensure the icon gets updated, there must be a trigger for when the state changes to off. + +{% raw %} + +```yaml +# Example configuration.yaml entry +template: + - triggers: + - trigger: event + event_type: YOUR_EVENT + - trigger: state + entity_id: binary_sensor.doorbell_rang + to: "off" + binary_sensor: + name: doorbell_rang + icon: "{{ (trigger.platform == 'event') | iif('mdi:bell-ring-outline', 'mdi:bell-outline') }}" + state: "{{ trigger.platform == 'event' }}" + auto_off: + seconds: 5 +``` + +{% endraw %} + +## Button + +The template button platform allows you to create button entities with scripts to define each action. + +Button entities can be created from the frontend in the Helpers section or via YAML. + +{% raw %} + +```yaml +# Example configuration.yaml entry +template: + - button: + - name: Fast Forward + press: + action: remote.send_command + target: + entity_id: remote.living_room + data: + command: fast_forward +``` + +{% endraw %} + +{% configuration %} button: description: List of buttons required: true @@ -286,6 +535,52 @@ button: description: Defines actions to run to press the button. required: true type: action +{% endconfiguration %} + +## Cover + +The template cover platform allows you to create covers with templates to define the state and scripts to define each action. + +Cover entities can only be created from YAML. + +{% raw %} + +```yaml +# Example state-based configuration.yaml entry +template: + - cover: + - name: Garage Door + state: "{{ states('sensor.garage_door')|float > 0 }}" + device_class: garage + open_cover: + action: script.open_garage_door + close_cover: + action: script.close_garage_door + stop_cover: + action: script.stop_garage_door +``` + +```yaml +# Example trigger-based configuration.yaml entry +template: + - triggers: + - trigger: state + entity_id: sensor.garage_door + cover: + - name: Garage Door + state: "{{ trigger.to_state.state|float(0) > 0 }}" + device_class: garage + open_cover: + action: script.open_garage_door + close_cover: + action: script.close_garage_door + stop_cover: + action: script.stop_garage_door +``` + +{% endraw %} + +{% configuration %} cover: description: Characteristics of a cover type: map @@ -299,11 +594,11 @@ cover: required: false type: string open_cover: - description: Defines an action to open the cover. If [`open_cover`](#open_cover) is specified, [`close_cover`](#close_cover) must also be specified. At least one of [`open_cover`](#open_cover) and [`set_cover_position`](#set_cover_position) must be specified. + description: Defines an action to open the cover. If `open_cover` is specified, `close_cover` must also be specified. At least one of `open_cover` and `set_cover_position` must be specified. required: inclusive type: action optimistic: - description: Force cover position to use [optimistic mode](#optimistic-mode). + description: Force cover position to use [optimistic mode](#cover-optimistic-mode). required: false type: boolean default: false @@ -320,7 +615,7 @@ cover: required: false type: action state: - description: Defines a template to get the state of the cover. Valid output values from the template are `open`, `opening`, `closing` and `closed` which are directly mapped to the corresponding states. In addition, `true` is valid as a synonym to `open` and `false` as a synonym to `closed`. If [both a `state` and a `position` template](/integrations/cover.template/#combining-value_template-and-position_template) are specified, only `opening` and `closing` are set from the `state` template. If the template produces a `None` value the state will be set to `unknown`. + description: Defines a template to get the state of the cover. Valid output values from the template are `open`, `opening`, `closing` and `closed` which are directly mapped to the corresponding states. In addition, `true` is valid as a synonym to `open` and `false` as a synonym to `closed`. If [both a `state` and a `position` template](#combining-state-and-position-templates) are specified, only `opening` and `closing` are set from the `state` template. If the template produces a `None` value the state will be set to `unknown`. required: false type: template stop_cover: @@ -328,14 +623,150 @@ cover: required: false type: action tilt: - description: Defines a template to get the tilt state of the cover. Legal values are numbers between `0` (closed) and `100` (open). If the template produces a `None` value, the current tilt state will be set to `unknown`. + description: Defines a template to get the tilt state of the cover. Legal values are numbers between `0` (closed) and `100` (open). If the template produces a `None` value, the current tilt state will be set to `unknown`. required: false type: template tilt_optimistic: - description: Force cover tilt position to use [optimistic mode](#optimistic-mode). + description: Force cover tilt position to use [optimistic mode](#cover-optimistic-mode). required: false type: boolean default: false + +{% endconfiguration %} + +### Cover Optimistic Mode + +In optimistic mode, the cover position state is maintained internally. This mode is automatically enabled if neither `state` or `position` are specified. Note that this is unlikely to be very reliable without some feedback mechanism, since there is otherwise no way to know if the cover is moving properly. The cover can be forced into optimistic mode by using the `optimistic` attribute. There is an equivalent mode for `tilt_position` that is enabled when `tilt` is not specified or when the `tilt_optimistic` attribute is used. + +### Combining `state` and `position` templates + +If both a `state` and a `position` are specified only `opening` and `closing` states are set directly from the `state`, the `open` and `closed` states will instead be derived from the cover position. + +| value_template output | result | +| --------------------- | ------------------------------------ | +| open | state defined by `position_template` | +| closed | state defined by `position_template` | +| true | state defined by `position_template` | +| false | state defined by `position_template` | +| opening | state set to `opening` | +| closing | state set to `closing` | +| | No change of state or position | + +### State based cover - Garage Door + +This example converts a garage door with a controllable switch and position sensor into a cover. The condition check is optional, but suggested if you use the same switch to open and close the garage. + +{% raw %} + +```yaml +template: + - cover: + - name: Garage Door + device_class: garage + position: "{{ states('sensor.garage_door') }}" + open_cover: + - condition: state + entity_id: sensor.garage_door + state: "off" + - action: switch.turn_on + target: + entity_id: switch.garage_door + close_cover: + - condition: state + entity_id: sensor.garage_door + state: "on" + - action: switch.turn_off + target: + entity_id: switch.garage_door + stop_cover: + action: switch.turn_on + target: + entity_id: switch.garage_door + icon: >- + {% if states('sensor.garage_door')|float > 0 %} + mdi:garage-open + {% else %} + mdi:garage + {% endif %} +``` + +{% endraw %} + +### State based cover - Optimistic Garage Door with Momentary Switch + +This example converts a garage door with a momentary switch. + +{% raw %} + +```yaml +template: + - cover: + - name: Garage Door + device_class: garage + open_cover: + - action: switch.turn_on + target: + entity_id: switch.garage_door + close_cover: + - action: switch.turn_on + target: + entity_id: switch.garage_door + stop_cover: + - action: switch.turn_on + target: + entity_id: switch.garage_door +``` + +{% endraw %} + +## Fan + +The template fan platform allows you to create fans with templates to define the state and scripts to define each action. + +Fan entities can only be created from YAML. Fan entities do not support trigger-based configurations. + +{% raw %} + +```yaml +# Example state-based configuration.yaml entry +template: + - fan: + - name: "Bedroom fan" + state: "{{ states('input_boolean.state') }}" + percentage: "{{ states('input_number.percentage') }}" + preset_mode: "{{ states('input_select.preset_mode') }}" + oscillating: "{{ states('input_select.osc') }}" + direction: "{{ states('input_select.direction') }}" + turn_on: + action: script.fan_on + turn_off: + action: script.fan_off + set_percentage: + action: script.fans_set_speed + data: + percentage: "{{ percentage }}" + set_preset_mode: + action: script.fans_set_preset_mode + data: + preset_mode: "{{ preset_mode }}" + set_oscillating: + action: script.fan_oscillating + data: + oscillating: "{{ oscillating }}" + set_direction: + action: script.fan_direction + data: + direction: "{{ direction }}" + speed_count: 6 + preset_modes: + - 'auto' + - 'smart' + - 'whoosh' +``` + +{% endraw %} + +{% configuration %} fan: description: List of fans required: true @@ -395,6 +826,153 @@ fan: description: Defines an action to run when the fan is turned off. required: true type: action + +{% endconfiguration %} + +### Converting from speeds to percentage + +When converting a fan with 3 speeds from the old fan entity model, the following percentages can be used: + +0 - `off` +33 - `low` +66 - `medium` +100 - `high` + +### State based fan - Helper fan + +This example uses an input_boolean and an input_number to mimic a fan, and the example shows multiple actions for `set_percentage`. + +{% raw %} + +```yaml +template: + - fan: + - name: "Helper Fan" + state: "{{ states('input_boolean.state') }}" + turn_on: + - action: input_boolean.turn_on + target: + entity_id: input_boolean.state + turn_off: + - action: input_boolean.turn_off + target: + entity_id: input_boolean.state + speed_count: 6 + percentage: > + {{ states('input_number.percentage') if is_state('input_boolean.state', 'on') else 0 }} + set_percentage: + - action: input_boolean.turn_{{ 'on' if percentage > 0 else 'off' }} + target: + entity_id: input_boolean.state + - action: input_number.set_value + target: + entity_id: input_number.percentage + data: + value: "{{ percentage }}" +``` + +{% endraw %} + +### State based fan - Fan with preset modes + +This example uses an existing fan with only a percentage. It extends the percentage value into useable preset modes without a helper entity. + +{% raw %} + +```yaml +template: + - fan: + - name: "Preset Mode Fan Example" + state: "{{ states('fan.percentage_fan') }}" + turn_on: + - action: fan.turn_on + target: + entity_id: fan.percentage_fan + turn_off: + - action: fan.turn_off + target: + entity_id: fan.percentage_fan + percentage: > + {{ state_attr('fan.percentage_fan', 'percentage') }} + speed_count: 3 + set_percentage: + - action: fan.set_percentage + target: + entity_id: fan.percentage_fan + data: + percentage: "{{ percentage }}" + preset_modes: + - "off" + - "low" + - "medium" + - "high" + preset_mode: > + {% if is_state('fan.percentage_fan', 'on') %} + {% if state_attr('fan.percentage_fan', 'percentage') == 100 %} + high + {% elif state_attr('fan.percentage_fan', 'percentage') == 66 %} + medium + {% else %} + low + {% endif %} + {% else %} + off + {% endif %} + set_preset_mode: + - action: fan.set_percentage + target: + entity_id: fan.percentage_fan + data: + percentage: >- + {% if preset_mode == 'high' %} + 100 + {% elif preset_mode == 'medium' %} + 66 + {% elif preset_mode == 'low' %} + 33 + {% else %} + 0 + {% endif %} +``` + +{% endraw %} + +## Image + +The template image platform allows you to create image entities with templates to define the image URL. + +Image entities can be created from the frontend in the Helpers section or via YAML. + +{% raw %} + +```yaml +# Example state-based configuration.yaml entry +template: + - image: + - name: "My Image" + url: "http://example.com/image.jpg" +``` + +```yaml +# Example trigger-based configuration.yaml entry +template: + - triggers: + - trigger: state + entity_id: + - input_boolean.state + image: + - name: "My Image" + url: > + {% if is_state('input_boolean.state', 'on') %} + http://example.com/image_on.jpg + {% else %} + http://example.com/image_off.jpg + {% endif %} +``` + +{% endraw %} + +{% configuration %} image: description: List of images required: true @@ -409,6 +987,125 @@ image: required: false type: boolean default: true +{% endconfiguration %} + +## Light + +The template light platform allows you to create lights with templates to define the state and scripts to define each action. + +Light entities can only be created from YAML. + +{% raw %} + +```yaml +# Example state-based configuration.yaml entry +light: + - light: + - name: "Theater Lights" + level: "{{ state_attr('sensor.theater_brightness', 'lux')|int }}" + state: "{{ state_attr('sensor.theater_brightness', 'lux')|int > 0 }}" + temperature: "{{states('input_number.temperature_input') | int}}" + hs_template: "({{states('input_number.h_input') | int}}, {{states('input_number.s_input') | int}})" + effect_list: "{{ state_attr('light.led_strip', 'effect_list') }}" + turn_on: + action: script.theater_lights_on + turn_off: + action: script.theater_lights_off + set_level: + action: script.theater_lights_level + data: + brightness: "{{ brightness }}" + set_temperature: + action: input_number.set_value + data: + value: "{{ color_temp }}" + entity_id: input_number.temperature_input + set_hs: + - action: input_number.set_value + data: + value: "{{ h }}" + entity_id: input_number.h_input + - action: input_number.set_value + data: + value: "{{ s }}" + entity_id: input_number.s_input + - action: light.turn_on + data: + entity_id: + - light.led_strip + transition: "{{ transition | float }}" + hs_color: + - "{{ hs[0] }}" + - "{{ hs[1] }}" + set_effect: + - action: light.turn_on + data: + entity_id: + - light.led_strip + effect: "{{ effect }}" + supports_transition: "{{ true }}" +``` + +```yaml +# Example trigger-based configuration.yaml entry +template: + - triggers: + - trigger: state + entity_id: + - sensor.theater_brightness + - input_number.temperature_input + - input_number.h_input + - input_number.s_input + - light.led_strip + light: + - name: "Theater Lights" + level: "{{ state_attr('sensor.theater_brightness', 'lux')|int }}" + state: "{{ state_attr('sensor.theater_brightness', 'lux')|int > 0 }}" + temperature: "{{states('input_number.temperature_input') | int}}" + hs_template: "({{states('input_number.h_input') | int}}, {{states('input_number.s_input') | int}})" + effect_list: "{{ state_attr('light.led_strip', 'effect_list') }}" + turn_on: + action: script.theater_lights_on + turn_off: + action: script.theater_lights_off + set_level: + action: script.theater_lights_level + data: + brightness: "{{ brightness }}" + set_temperature: + action: input_number.set_value + data: + value: "{{ color_temp }}" + entity_id: input_number.temperature_input + set_hs: + - action: input_number.set_value + data: + value: "{{ h }}" + entity_id: input_number.h_input + - action: input_number.set_value + data: + value: "{{ s }}" + entity_id: input_number.s_input + - action: light.turn_on + data: + entity_id: + - light.led_strip + transition: "{{ transition | float }}" + hs_color: + - "{{ hs[0] }}" + - "{{ hs[1] }}" + set_effect: + - action: light.turn_on + data: + entity_id: + - light.led_strip + effect: "{{ effect }}" + supports_transition: "{{ true }}" +``` + +{% endraw %} + +{% configuration %} light: description: List of your lights. required: true @@ -510,6 +1207,146 @@ light: description: Defines an action to run when the light is turned off. May receive the variable `transition`. required: true type: action + +{% endconfiguration %} + +### Light Considerations + +Transition doesn't have its own script, it will instead be passed as a named parameter `transition` to the `turn_on`, `turn_off`, `brightness`, `color_temp`, `effect`, `hs_color`, `rgb_color`, `rgbw_color` or `rgbww_color` scripts. Brightness will be passed as a named parameter `brightness` to either of `turn_on`, `color_temp`, `effect`, `hs_color`, `rgb_color`, `rgbw_color` or `rgbww_color` scripts if the corresponding parameter is also in the call. In this case, the brightness script (`set_level`) will not be called. If only brightness is passed to `light.turn_on` action, then `set_level` script is called. + +### State based light - Theater Volume Control + +This example shows a light that is actually a home theater's volume. This +integration gives you the flexibility to provide whatever you'd like to send as +the payload to the consumer including any scale conversions you may need to +make; the [media player integration](/integrations/media_player/) needs a floating +point percentage value from `0.0` to `1.0`. + +{% raw %} + +```yaml +# Example configuration.yaml entry +template: + - light: + - name: Receiver Volume + state: >- + {% if is_state('media_player.receiver', 'on') %} + {% if state_attr('media_player.receiver', 'is_volume_muted') %} + off + {% else %} + on + {% endif %} + {% else %} + off + {% endif %} + turn_on: + action: media_player.volume_mute + target: + entity_id: media_player.receiver + data: + is_volume_muted: false + turn_off: + action: media_player.volume_mute + target: + entity_id: media_player.receiver + data: + is_volume_muted: true + set_level: + action: media_player.volume_set + target: + entity_id: media_player.receiver + data: + volume_level: "{{ (brightness / 255 * 100)|int / 100 }}" + level: >- + {% if is_state('media_player.receiver', 'on') %} + {{ (state_attr('media_player.receiver', 'volume_level')|float * 255)|int }} + {% else %} + 0 + {% endif %} +``` + +{% endraw %} + +### State based light - Make a global light entity for a multi-segment WLED light + +This example shows how to group together 2 RGBW segments from the same WLED controller into a single usable light. + +{% raw %} + +```yaml +template: + - light: + unique_id: 28208f257b54c44e50deb2d618d44710 + name: Multi-segment Wled control + state: "{{ states('light.wled_master') }}" + level: "{{ state_attr('light.wled_master', 'brightness')|d(0,true)|int }}" + rgbw: ( + {{ (state_attr('light.wled_segment_0', 'rgbw_color')[0]|d(0) + state_attr('light.wled_segment_1', 'rgbw_color')[0]|d(0))/2 }}, + {{ (state_attr('light.wled_segment_0', 'rgbw_color')[1]|d(0) + state_attr('light.wled_segment_1', 'rgbw_color')[1]|d(0))/2 }}, + {{ (state_attr('light.wled_segment_0', 'rgbw_color')[2]|d(0) + state_attr('light.wled_segment_1', 'rgbw_color')[2]|d(0))/2 }}, + {{ (state_attr('light.wled_segment_0', 'rgbw_color')[3]|d(0) + state_attr('light.wled_segment_1', 'rgbw_color')[3]|d(0))/2 }} + ) + effect_list: "{{ state_attr('light.wled_segment_0', 'effect_list') }}" + effect: "{{ state_attr('light.wled_segment_0', 'effect') if state_attr('light.wled_segment_0', 'effect') == state_attr('light.wled_segment_1', 'effect') else none }}" + availability: "{{ not is_state('light.wled_master', 'unknown') }}" + + turn_on: + action: light.turn_on + entity_id: light.wled_segment_0, light.wled_segment_1, light.wled_master + turn_off: + action: light.turn_off + entity_id: light.wled_master + set_level: + action: light.turn_on + entity_id: light.wled_master + data: + brightness: "{{ brightness }}" + set_rgbw: + action: light.turn_on + entity_id: light.wled_segment_0, light.wled_segment_1 + data: + rgbw_color: + - "{{ r }}" + - "{{ g }}" + - "{{ b }}" + - "{{ w }}" + effect: "Solid" + set_effect: + action: light.turn_on + entity_id: light.wled_segment_0, light.wled_segment_1 + data: + effect: "{{ effect }}" +``` + +{% endraw %} + +## Lock + +The template lock platform allows you to create locks with templates to define the state and scripts to define each action. + +Lock entities can only be created from YAML. Lock entities do not support trigger-based configurations. + +{% raw %} + +```yaml +# Example state-based configuration.yaml entry +template: + - lock: + - name: Garage door + state: "{{ is_state('sensor.door', 'on') }}" + lock: + action: switch.turn_on + target: + entity_id: switch.door + unlock: + action: switch.turn_off + target: + entity_id: switch.door +``` + +{% endraw %} + +{% configuration %} lock: description: List of locks required: true @@ -541,6 +1378,163 @@ lock: description: Defines an action to run when the lock is unlocked. required: true type: action +{% endconfiguration %} + +### State based lock - Lock from a switch + +This example shows a lock that copies data from a switch. + +{% raw %} + +```yaml +template: + - lock: + - name: Garage Door + state: "{{ is_state('switch.source', 'on') }}" + lock: + action: switch.turn_on + target: + entity_id: switch.source + unlock: + action: switch.turn_off + target: + entity_id: switch.source +``` + +{% endraw %} + +### State based lock - Optimistic mode + +This example shows a lock in optimistic mode. This lock will immediately change state after command and will not wait for state update from the sensor. + +{% raw %} + +```yaml +template: + - lock: + - name: Garage Door + state: "{{ is_state('sensor.skylight.state', 'on') }}" + optimistic: true + lock: + action: switch.turn_on + target: + entity_id: switch.source + unlock: + action: switch.turn_off + target: + entity_id: switch.source +``` + +{% endraw %} + +### State based lock - Sensor and Two Switches + +This example shows a lock that takes its state from a sensor, and uses two momentary switches to control a device. + +{% raw %} + +```yaml +template: + - lock: + - name: Garage Door + state: "{{ is_state('sensor.skylight.state', 'on') }}" + lock: + action: switch.turn_on + target: + entity_id: switch.skylight_open + unlock: + action: switch.turn_on + target: + entity_id: switch.skylight_close +``` + +{% endraw %} + +### State based lock - Secret code + +This example shows a lock that copies data from a switch. It needs a PIN code defined as a [secret](/docs/configuration/secrets) to unlock and no code to lock. Note that the actual validity check of the code is part of the `unlock` action and should always happen there or in scripts called from these actions. In this way, you can not only perform code checks against static values, but also dynamic ones (for instance, TOTPs). + +{% raw %} + +```yaml +template: + - lock: + - name: Garage Door + state: "{{ is_state('switch.source', 'on') }}" + code_format: "{{ '\\d{4}' if is_state('switch.source', 'on') else None }}" + lock: + - action: switch.turn_on + target: + entity_id: switch.source + unlock: + - variables: + pin: !secret garage_door_pin + - condition: "{{ code == pin }}" + - action: switch.turn_off + target: + entity_id: switch.source +``` + +{% endraw %} + +In `secrets.yaml`: + +{% raw %} + +```yaml +garage_door_pin: "1234" +``` + +{% endraw %} + +## Number + +The template number platform allows you to create number entities with templates to define the state and scripts to define each action. + +Number entities can be created from the frontend in the Helpers section or via YAML. + +{% raw %} + +```yaml +# Example state-based configuration.yaml entry +template: + - number: + - name: Desk Height + unit_of_measurement: "in" + state: "{{ states('sensor.desk_height') }}" + set_value: + - action: script.set_desk_height + data: + value: "{{ value }}" + step: 0.5 + min: 1 + max: 24 + icon: mdi:ruler +``` + +```yaml +# Example trigger-based configuration.yaml entry +template: + - triggers: + - trigger: state + entity_id: sensor.desk_height + - number: + - name: Desk Height + unit_of_measurement: "in" + state: "{{ states('sensor.desk_height') }}" + set_value: + - action: script.set_desk_height + data: + value: "{{ value }}" + step: 0.5 + min: 1 + max: 24 + icon: mdi:ruler +``` + +{% endraw %} + +{% configuration %} number: description: List of numbers required: true @@ -578,6 +1572,77 @@ number: description: Template for the number's increment/decrement step. required: true type: template + +{% endconfiguration %} + +### State based number - Changing the unit of measurement of another number + +This example demonstrates the usage of a template number with a unit of measurement set to change a unit-less value of another number entity. + +{% raw %} + +```yaml +template: + - number: + - name: "Cutting Height" + unit_of_measurement: "cm" + unique_id: automower_cutting_height + state: "{{ states('number.automower_cutting_height_raw')|int(0) * 0.5 + 1.5 }}" + set_value: + - service: number.set_value + target: + entity_id: number.automower_cutting_height_raw + data: + value: "{{ (value - 1.5) * 2 }}" + step: 0.5 + min: 2 + max: 6 + icon: mdi:ruler +``` + +{% endraw %} + +## Select + +The template select platform allows you to create select entities with templates to define the state and scripts to define each action. + +Select entities can be created from the frontend in the Helpers section or via YAML. + +{% raw %} + +```yaml +# Example state-based configuration.yaml entry +template: + - select: + - name: Camera Day-Night Mode + state: "{{ state_attr('camera.porch', 'day_night_mode') }}" + options: "{{ ['off', 'on', 'auto'] }}" + select_option: + - action: script.porch_camera_day_night_mode + data: + day_night_mode: "{{ option }}" +``` + +```yaml +# Example trigger-based configuration.yaml entry +template: + - triggers: + - trigger: state + entity_id: camera.porch + attribute: day_night_mode + select: + - name: Camera Day-Night Mode + state: "{{ state_attr('camera.porch', 'day_night_mode') }}" + options: "{{ ['off', 'on', 'auto'] }}" + select_option: + - action: script.porch_camera_day_night_mode + data: + day_night_mode: "{{ option }}" +``` + +{% endraw %} + +{% configuration %} select: description: List of selects required: true @@ -600,11 +1665,87 @@ select: description: Template for the select's current value. required: true type: template +{% endconfiguration %} + +### State based select - Control Day/Night mode of a camera + +This show how a state based template select can be used to perform an action. + +{% raw %} + +```yaml +template: + select: + - name: "Porch Camera Day-Night Mode" + unique_id: porch_camera_day_night_mode + state: "{{ state_attr('camera.porch_camera_sd', 'day_night_mode') }}" + options: "{{ ['off', 'on', 'auto'] }}" + select_option: + - action: tapo_control.set_day_night_mode + data: + day_night_mode: "{{ option }}" + target: + entity_id: camera.porch_camera_sd +``` + +{% endraw %} + +## Sensor + +The template sensor platform allows you to create sensors with templates to define the state and attributes. + +Sensor entities can be created from the frontend in the Helpers section or via YAML. + +{% raw %} + +```yaml +# Example state-based configuration.yaml entry +template: + - sensor: + - name: "Kettle" + state: > + {% if is_state('switch.kettle', 'off') %} + off + {% elif state_attr('switch.kettle', 'W')|float < 1000 %} + standby + {% elif is_state('switch.kettle', 'on') %} + on + {% else %} + failed + {% endif %} +``` + +```yaml +# Example trigger-based configuration.yaml entry +template: + - triggers: + - trigger: state + entity_id: sensor.outside_temperature + not_to: + - unknown + - unavailable + sensor: + - name: Outside Temperature + device_class: temperature + unit_of_measurement: °C + state: "{{ (states('sensor.outside_temperature') | float - 32) * 5/9 }}" +``` + +{% configuration %} sensor: description: List of sensors required: true type: list keys: + attributes: + description: Defines templates for attributes of the entity. + required: false + type: map + keys: + "attribute: template": + description: The attribute and corresponding template. + required: true + type: template last_reset: description: "Defines a template that describes when the state of the sensor was last reset. Must render to a valid `datetime`. Only available when `state_class` is set to `total`" required: false @@ -624,6 +1765,136 @@ sensor: required: false type: string default: None + +{% endconfiguration %} + +### State based sensor - Exposing sun angle + +This example shows the sun angle in the frontend. + +{% raw %} + +```yaml +template: + - sensor: + - name: Sun Angle + unit_of_measurement: "°" + state: "{{ '%+.1f'|format(state_attr('sun.sun', 'elevation')) }}" +``` + +{% endraw %} + +### State based sensor - Modifying another sensor's output + +If you don't like the wording of a sensor output, then the Template Sensor can help too. Let's rename the output of the [Sun integration](/integrations/sun/) as a simple example: + +{% raw %} + +```yaml +template: + - sensor: + - name: "Sun State" + state: > + {% if is_state('sun.sun', 'above_horizon') %} + up + {% else %} + down + {% endif %} +``` + +{% endraw %} + +### State based sensor - Changing the unit of measurement of another sensor + +With a Template Sensor, it's easy to convert given values into others if the unit of measurement doesn't fit your needs. +Because the sensors do math on the source sensor's state and need to render to a numeric value, an availability template is used +to suppress rendering of the state template if the source sensor does not have a valid numeric state. + +{% raw %} + +```yaml +template: + - sensor: + - name: "Transmission Down Speed" + unit_of_measurement: "kB/s" + state: "{{ states('sensor.transmission_down_speed')|float * 1024 }}" + availability: "{{ is_number(states('sensor.transmission_down_speed')) }}" + + - name: "Transmission Up Speed" + unit_of_measurement: "kB/s" + state: "{{ states('sensor.transmission_up_speed')|float * 1024 }}" + availability: "{{ is_number(states('sensor.transmission_up_speed')) }}" +``` + +{% endraw %} + +### Trigger based sensor - Using conditions to control updates + +This example shows how to store the last valid value of a temperature sensor. It will update as long as the source sensor has a valid (numeric) state. Otherwise, the template sensor's state will remain unchanged. + +{% raw %} + +```yaml +template: + - triggers: + trigger: state + entity_id: sensor.outside_temperature + conditions: + - condition: template + value_template: "{{ is_number(states('sensor.outside_temperature')) }}" + sensor: + - name: Outside Temperature last known value + state: "{{ states('sensor.outside_temperature') }}" +``` + +{% endraw %} + +## Switch + +The template switch platform allows you to create switches with templates to define the state and scripts to define each action. + +Switch entities can be created from the frontend in the Helpers section or via YAML. + +{% raw %} + +```yaml +# Example state-based configuration.yaml entry +template: + - switch: + - name: Skylight + state: "{{ is_state('binary_sensor.skylight', 'on') }}" + turn_on: + action: switch.turn_on + target: + entity_id: switch.skylight_open + turn_off: + action: switch.turn_off + target: + entity_id: switch.skylight_close +``` + +```yaml +# Example trigger-based configuration.yaml entry +template: + - triggers: + - trigger: state + entity_id: binary_sensor.skylight + switch: + - name: Skylight + state: "{{ is_state('binary_sensor.skylight', 'on') }}" + turn_on: + action: switch.turn_on + target: + entity_id: switch.skylight_open + turn_off: + action: switch.turn_off + target: + entity_id: switch.skylight_close +``` + +{% endraw %} + +{% configuration %} switch: description: List of switches required: true @@ -642,11 +1913,135 @@ switch: description: Defines an action or list of actions to run when the switch is turned on. required: true type: action + +{% endconfiguration %} + +### State based switch - Invert a Switch + +This example shows a switch that is the inverse of another switch. + +{% raw %} + +```yaml +template: + - switch: + - state: "{{ not is_state('switch.target', 'on') }}" + availability: "{{ has_value('switch.target') }}" + turn_on: + action: switch.turn_off + target: + entity_id: switch.target + turn_off: + action: switch.turn_on + target: + entity_id: switch.target +``` + +{% endraw %} + +### State based switch - Toggle Switch + +This example shows a switch that takes its state from a sensor and toggles a switch. + +{% raw %} + +```yaml +template: + - switch: + - name: "Blind" + state: "{{ is_state_attr('switch.blind_toggle', 'sensor_state', 'on') }}" + turn_on: + action: switch.toggle + target: + entity_id: switch.blind_toggle + turn_off: + action: switch.toggle + target: + entity_id: switch.blind_toggle +``` + +{% endraw %} + +### State based switch - Sensor and Two Switches + +This example shows a switch that takes its state from a sensor, and uses two +momentary switches to control a device. + +{% raw %} + +```yaml +template: + - switch: + - name: "Skylight" + value_template: "{{ is_state('sensor.skylight', 'on') }}" + turn_on: + action: switch.turn_on + target: + entity_id: switch.skylight_open + turn_off: + action: switch.turn_on + target: + entity_id: switch.skylight_close +``` + +{% endraw %} + +### State based switch - Optimistic Switch + +This example switch with an assumed state based on the actions performed. This switch will immediately change state after a `turn_on`/`turn_off` command. + +{% raw %} + +```yaml +template: + - switch: + - name: "Blind" + turn_on: + action: switch.toggle + target: + entity_id: switch.blind_toggle + turn_off: + action: switch.toggle + target: + entity_id: switch.blind_toggle +``` + +{% endraw %} + +## Vacuum + +The template vacuum platform allows you to create vacuum entities with templates to define the state and scripts to define each action. + +Vacuum entities can only be created via YAML. Vacuum entities do not support trigger-based configurations. + +{% raw %} + +```yaml +# Example state-based configuration.yaml entry +template: + - vacuum: + - name: Living Room Vacuum + start: + action: script.vacuum_start +``` + +{% endraw %} + +{% configuration %} vacuum: description: List of vacuum entities required: true type: map keys: + attributes: + description: Defines templates for attributes of the entity. + required: false + type: map + keys: + "attribute: template": + description: The attribute and corresponding template. + required: true + type: template battery_level: description: "Defines a template to get the battery level of the vacuum. Legal values are numbers between `0` and `100`." required: false @@ -691,6 +2086,108 @@ vacuum: description: Defines an action to run when the vacuum is stopped. required: false type: action +{% endconfiguration %} + +### State based vacuum - Control vacuum with Harmony Hub + +This example shows how you can use a Template Vacuum to control an IR vacuum cleaner using the [Harmony Hub Remote integration](/integrations/harmony). + +```yaml +vacuum: + - platform: template + vacuums: + living_room_vacuum: + start: + - action: remote.send_command + target: + entity_id: remote.harmony_hub + data: + command: Clean + device: 52840686 + return_to_base: + - action: remote.send_command + target: + entity_id: remote.harmony_hub + data: + command: Home + device: 52840686 + clean_spot: + - action: remote.send_command + target: + entity_id: remote.harmony_hub + data: + command: SpotCleaning + device: 52840686 +``` + +### State based vacuum - Custom attributes + +This example shows how to add custom attributes. + +{% raw %} + +```yaml +vacuum: + - platform: template + vacuums: + living_room_vacuum: + value_template: "{{ states('sensor.vacuum_state') }}" + battery_level_template: "{{ states('sensor.vacuum_battery_level')|int }}" + fan_speed_template: "{{ states('sensor.vacuum_fan_speed') }}" + attribute_templates: + status: >- + {% if (states('sensor.robot_vacuum_robot_cleaner_movement') == "after" and states('sensor.robot_vacuum_robot_cleaner_cleaning_mode') == "stop") %} + Charging to Resume + {% elif states('sensor.robot_vacuum_robot_cleaner_cleaning_mode') == "auto" %} + Cleaning + {% else %} + Charging + {% endif %} +``` + +{% endraw %} + +## Weather + +The template weather platform allows you to create weather entities with templates to define the state and attributes. + +Weather entities can only be created via YAML. + +{% raw %} + +```yaml +# Example state-based configuration.yaml entry +template: + - weather: + - name: "My Weather Station" + condition_template: "{{ states('weather.my_region') }}" + temperature_template: "{{ states('sensor.temperature') | float }}" + temperature_unit: "°C" + humidity_template: "{{ states('sensor.humidity') | float }}" + forecast_daily_template: "{{ state_attr('weather.my_region', 'forecast_data') }}" +``` + +```yaml +# Example trigger-based configuration.yaml entry +template: + - triggers: + - trigger: state + entity_id: + - weather.my_region + - sensor.temperature + - sensor.humidity + weather: + - name: "My Weather Station" + condition_template: "{{ states('weather.my_region') }}" + temperature_template: "{{ states('sensor.temperature') | float }}" + temperature_unit: "°C" + humidity_template: "{{ states('sensor.humidity') | float }}" + forecast_daily_template: "{{ state_attr('weather.my_region', 'forecast_data') }}" +``` + +{% endraw %} + +{% configuration %} weather: description: List of weather entities required: true @@ -779,7 +2276,44 @@ weather: {% endconfiguration %} -The above configuration variables describe a configuration section. The template integration allows defining multiple sections. +### Trigger based weather - Weather Forecast from response data + +This example demonstrates how to use an `action` to call a [action with response data](/docs/scripts/perform-actions/#use-templates-to-handle-response-data) +and use the response in a template. + +{% raw %} + +```yaml +template: + - triggers: + - trigger: time_pattern + hours: /1 + actions: + - action: weather.get_forecasts + data: + type: hourly + target: + entity_id: weather.home + response_variable: hourly + sensor: + - name: Weather Forecast Hourly + unique_id: weather_forecast_hourly + state: "{{ now().isoformat() }}" + attributes: + forecast: "{{ hourly['weather.home'].forecast }}" +``` + +{% endraw %} + +#### Video tutorial + +This video tutorial explains how to set up a trigger based template that makes use of an action to retrieve the weather forecast (precipitation). + + + +## Combining multiple template entities + +The template integration allows defining multiple sections. ```yaml # Example configuration.yaml entry with two sections @@ -801,13 +2335,44 @@ template: [trigger-doc]: /docs/automation/trigger -#### Video tutorial +### Trigger based sensor and binary sensor storing webhook information -This video tutorial explains how to set up a trigger based template that makes use of an action to retrieve the weather forecast (precipitation). +Template entities can be triggered using any automation trigger, including webhook triggers. Use a trigger-based template entity to store this information in template entities. - +{% raw %} -### Template and action variables +```yaml +template: + - triggers: + - trigger: webhook + webhook_id: my-super-secret-webhook-id + sensor: + - name: "Webhook Temperature" + state: "{{ trigger.json.temperature }}" + unit_of_measurement: °C + + - name: "Webhook Humidity" + state: "{{ trigger.json.humidity }}" + unit_of_measurement: % + + binary_sensor: + - name: "Motion" + state: "{{ trigger.json.motion }}" + device_class: motion +``` + +{% 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, "motion": true}' \ + http://homeassistant.local:8123/api/webhook/my-super-secret-webhook-id +``` + +## Template and action variables State-based and trigger-based template entities have the special template variable `this` available in their templates and actions. The `this` variable is the current [state object](/docs/configuration/state_object) of the entity and aids [self-referencing](#self-referencing) of an entity's state and attributes in templates and actions. Trigger-based entities also provide [the trigger data](/docs/automation/templating/). @@ -815,7 +2380,25 @@ State-based and trigger-based template entities have the special template variab Self-referencing using `this` provides the state and attributes for the entity before rendering the templates to calculate a new state. In other words, it contains the previous state. {% endnote %} -### Optimistic mode +### Self referencing + +This example demonstrates how the `this` variable can be used in templates for self-referencing. + +{% raw %} + +```yaml +template: + - sensor: + - name: test + state: "{{ this.attributes.test | default('Value when missing') }}" + # not: "{{ state_attr('sensor.test', 'test') }}" + attributes: + test: "{{ now() }}" +``` + +{% endraw %} + +## Optimistic mode For template entities that support interactivity (like `number` and `select`), you can enable optimistic mode by setting the `optimistic` parameter to `true`. This affects how the entity's state updates when you interact with it: @@ -831,7 +2414,7 @@ Optimistic mode is particularly useful when: When optimistic mode is disabled (default), you get more accuracy but potentially a less responsive UI, as the entity only updates after confirmation from the underlying system. -### Rate limiting updates +## Rate limiting updates When there are entities present in the template and no triggers are defined, the template will be re-rendered when one of the entities changes states. To avoid this taking up too many resources in Home Assistant, rate limiting will be automatically applied if too many states are observed. @@ -872,11 +2455,11 @@ template: If the template accesses every state on the system, a rate limit of one update per minute is applied. If the template accesses all states under a specific domain, a rate limit of one update per second is applied. If the template only accesses specific states, receives update events for specifically referenced entities, or the `homeassistant.update_entity` action is used, no rate limit is applied. -### Considerations +## Considerations -#### Startup +### Startup -If you are using the state of a platform that might not be available during startup, the Template Sensor may get an `unknown` state. To avoid this, use the `states()` function in your template. For example, you should replace {% raw %}`{{ states.sensor.moon.state }}`{% endraw %} with this equivalent that returns the state and never results in `unknown`: {% raw %}`{{ states('sensor.moon') }}` {% endraw %}. +If you are using the state of a platform that might not be available during startup, the Template Sensor may get an `unknown` state. To avoid this, use the `states()` function in your template. For example, you should replace {% raw %}`{{ states.sensor.moon.state }}`{% endraw %} with this equivalent that returns the state and never results in `unknown`: {% raw %}`{{ states('sensor.moon') }}` {% endraw %}. The same would apply to the `is_state()` function. You should replace {% raw %}`{{ states.switch.source.state == 'on' }}`{% endraw %} with this equivalent that returns `true`/`false` and never gives an `unknown` result: @@ -928,387 +2511,119 @@ The blueprint can now be used for creating template entities. [blueprint-forums]: /get-blueprints -## Examples +## Event `event_template_reloaded` -In this section, you find some real-life examples of how to use template sensors. +Event `event_template_reloaded` is fired when Template entities have been reloaded and entities thus might have changed. -### Trigger based sensor and binary sensor storing webhook information +This event has no additional data. -Template entities can be triggered using any automation trigger, including webhook triggers. Use a trigger-based template entity to store this information in template entities. +## Legacy Alarm Control Panel configuration format + +_These formats still work but are no longer recommended. [Use modern configuration](#alarm-control-panel)._ + +This format is configured as a platform for the `alarm_control_panel` integration and not directly under the `template` integration. {% raw %} ```yaml -template: - - triggers: - - trigger: webhook - webhook_id: my-super-secret-webhook-id - sensor: - - name: "Webhook Temperature" - state: "{{ trigger.json.temperature }}" - unit_of_measurement: °C - - - name: "Webhook Humidity" - state: "{{ trigger.json.humidity }}" - unit_of_measurement: % - - binary_sensor: - - name: "Motion" - state: "{{ trigger.json.motion }}" - device_class: motion -``` - -{% 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, "motion": true}' \ - http://homeassistant.local:8123/api/webhook/my-super-secret-webhook-id -``` - -### Turning an event into a trigger based binary sensor - -You can use a trigger-based template entity to convert any event or other automation trigger into a binary sensor. The below configuration will turn on a binary sensor for 5 seconds when the automation trigger triggers. - -```yaml -template: - - triggers: - trigger: event - event_type: my_event - binary_sensor: - - name: Event recently fired - auto_off: 5 - state: "true" -``` - -### Using conditions with triggers to control status updates - -This example shows how to store the last valid value of a temperature sensor. It will update as long as the source sensor has a valid (numeric) state. Otherwise, the template sensor's state will remain unchanged. - -{% raw %} - -```yaml -template: - - triggers: - trigger: state - entity_id: sensor.outside_temperature - conditions: - - condition: template - value_template: "{{ is_number(states('sensor.outside_temperature')) }}" - sensor: - - name: Outside Temperature last known value - state: "{{ states('sensor.outside_temperature') }}" -``` - -{% endraw %} - -### State based sensor exposing sun angle - -This example shows the sun angle in the frontend. - -{% raw %} - -```yaml -template: - - sensor: - - name: Sun Angle - unit_of_measurement: "°" - state: "{{ '%+.1f'|format(state_attr('sun.sun', 'elevation')) }}" -``` - -{% endraw %} - -### State based sensor modifying another sensor's output - -If you don't like the wording of a sensor output, then the Template Sensor can help too. Let's rename the output of the [Sun integration](/integrations/sun/) as a simple example: - -{% raw %} - -```yaml -template: - - sensor: - - name: "Sun State" - state: > - {% if is_state('sun.sun', 'above_horizon') %} - up - {% else %} - down - {% endif %} -``` - -{% endraw %} - -### State based sensor with multiline template with an `if` test - -This example shows a multiple line template with an `if` test. It looks at a sensing switch and shows `on`/`off` in the frontend, and shows 'standby' if the power use is less than 1000 watts. - -{% raw %} - -```yaml -template: - - sensor: - - name: "Kettle" - state: > - {% if is_state('switch.kettle', 'off') %} - off - {% elif state_attr('switch.kettle', 'W')|float < 1000 %} - standby - {% elif is_state('switch.kettle', 'on') %} - on - {% else %} - failed - {% endif %} -``` - -{% endraw %} - -### State based sensor changing the unit of measurement of another sensor - -With a Template Sensor, it's easy to convert given values into others if the unit of measurement doesn't fit your needs. -Because the sensors do math on the source sensor's state and need to render to a numeric value, an availability template is used -to suppress rendering of the state template if the source sensor does not have a valid numeric state. - -{% raw %} - -```yaml -template: - - sensor: - - name: "Transmission Down Speed" - unit_of_measurement: "kB/s" - state: "{{ states('sensor.transmission_down_speed')|float * 1024 }}" - availability: "{{ is_number(states('sensor.transmission_down_speed')) }}" - - - name: "Transmission Up Speed" - unit_of_measurement: "kB/s" - state: "{{ states('sensor.transmission_up_speed')|float * 1024 }}" - availability: "{{ is_number(states('sensor.transmission_up_speed')) }}" -``` - -{% endraw %} - -### State based binary sensor - Washing Machine Running - -This example creates a washing machine "load running" sensor by monitoring an -energy meter connected to the washer. During the washer's operation, the energy meter will fluctuate wildly, hitting zero frequently even before the load is finished. By utilizing `delay_off`, we can have this sensor only turn off if there has been no washer activity for 5 minutes. - -{% raw %} - -```yaml -# Determine when the washing machine has a load running. -template: - - binary_sensor: - - name: "Washing Machine" - delay_off: - minutes: 5 - state: > - {{ states('sensor.washing_machine_power')|float > 0 }} -``` - -{% endraw %} - -### State based binary sensor - Is Anyone Home - -This example is determining if anyone is home based on the combination of device tracking and motion sensors. It's extremely useful if you have kids/baby sitter/grand parents who might still be in your house that aren't represented by a trackable device in Home Assistant. This is providing a composite of Wi-Fi based device tracking and Z-Wave multisensor presence sensors. - -{% raw %} - -```yaml -template: - - binary_sensor: - - name: People home - state: > - {{ is_state('device_tracker.sean', 'home') - or is_state('device_tracker.susan', 'home') - or is_state('binary_sensor.office_124', 'on') - or is_state('binary_sensor.hallway_134', 'on') - or is_state('binary_sensor.living_room_139', 'on') - or is_state('binary_sensor.porch_ms6_1_129', 'on') - or is_state('binary_sensor.family_room_144', 'on') }} -``` - -{% endraw %} - -### State based binary sensor - device tracker sensor with latitude and longitude attributes - -This example shows how to combine a non-GPS (e.g., NMAP) and GPS device tracker while still including latitude and longitude attributes - -{% raw %} - -```yaml -template: - - binary_sensor: - - name: My Device - state: > - {{ is_state('device_tracker.my_device_nmap', 'home') or is_state('device_tracker.my_device_gps', 'home') }} - device_class: "presence" - attributes: - latitude: > - {% if is_state('device_tracker.my_device_nmap', 'home') %} - {{ state_attr('zone.home', 'latitude') }} - {% else %} - {{ state_attr('device_tracker.my_device_gps', 'latitude') }} - {% endif %} - longitude: > - {% if is_state('device_tracker.my_device_nmap', 'home') %} - {{ state_attr('zone.home', 'longitude') }} - {% else %} - {{ state_attr('device_tracker.my_device_gps', 'longitude') }} - {% endif %} -``` - -{% endraw %} - -### State based binary sensor - Change the icon when a state changes - -This example demonstrates how to use template to change the icon as its state changes. This icon is referencing its own state. - -{% raw %} - -```yaml -template: - - binary_sensor: - - name: Sun Up - state: > - {{ is_state("sun.sun", "above_horizon") }} - icon: > - {% if is_state("binary_sensor.sun_up", "on") %} - mdi:weather-sunset-up - {% else %} - mdi:weather-sunset-down - {% endif %} -``` - -{% endraw %} - -A more advanced use case could be to set the icon based on the sensor's own state like above, but when triggered by an event. This example demonstrates a binary sensor that turns on momentarily, such as when a doorbell button is pressed. - -The binary sensor turns on and sets the matching icon when the appropriate event is received. After 5 seconds, the binary sensor turns off automatically. To ensure the icon gets updated, there must be a trigger for when the state changes to off. - -{% raw %} - -```yaml -template: - - triggers: - - trigger: event - event_type: YOUR_EVENT - - trigger: state - entity_id: binary_sensor.doorbell_rang - to: "off" - binary_sensor: - name: doorbell_rang - icon: "{{ (trigger.platform == 'event') | iif('mdi:bell-ring-outline', 'mdi:bell-outline') }}" - state: "{{ trigger.platform == 'event' }}" - auto_off: - seconds: 5 -``` - -{% endraw %} - -### State based select - Control Day/Night mode of a camera - -This show how a state based template select can be used to perform an action. - -{% raw %} - - -```yaml -template: - select: - - name: "Porch Camera Day-Night Mode" - unique_id: porch_camera_day_night_mode - state: "{{ state_attr('camera.porch_camera_sd', 'day_night_mode') }}" - options: "{{ ['off', 'on', 'auto'] }}" - select_option: - - action: tapo_control.set_day_night_mode - data: - day_night_mode: "{{ option }}" +# Example configuration.yaml entry +alarm_control_panel: + - platform: template + panels: + safe_alarm_panel: + value_template: "{{ states('alarm_control_panel.real_alarm') }}" + arm_away: + action: alarm_control_panel.alarm_arm_away target: - entity_id: camera.porch_camera_sd -``` - -{% endraw %} - -### Self referencing - -This example demonstrates how the `this` variable can be used in templates for self-referencing. - -{% raw %} - -```yaml -template: - - sensor: - - name: test - state: "{{ this.attributes.test | default('Value when missing') }}" - # not: "{{ state_attr('sensor.test', 'test') }}" - attributes: - test: "{{ now() }}" -``` - -{% endraw %} - -### Trigger based handling of action response data - -This example demonstrates how to use an `action` to call a [action with response data](/docs/scripts/perform-actions/#use-templates-to-handle-response-data) -and use the response in a template. - -{% raw %} - -```yaml -template: - - triggers: - - trigger: time_pattern - hours: /1 - actions: - - action: weather.get_forecasts - data: - type: hourly - target: - entity_id: weather.home - response_variable: hourly - sensor: - - name: Weather Forecast Hourly - unique_id: weather_forecast_hourly - state: "{{ now().isoformat() }}" - attributes: - forecast: "{{ hourly['weather.home'].forecast }}" -``` - -{% endraw %} - -### Number entity changing the unit of measurement of another number - -This example demonstrates the usage of a template number with a unit of measurement set to change a unit-less value of another number entity. - -{% raw %} - -```yaml -template: - - number: - - name: "Cutting Height" - unit_of_measurement: "cm" - unique_id: automower_cutting_height - state: "{{ states('number.automower_cutting_height_raw')|int(0) * 0.5 + 1.5 }}" - set_value: - - service: number.set_value + entity_id: alarm_control_panel.real_alarm + data: + code: !secret alarm_code + arm_home: + action: alarm_control_panel.alarm_arm_home + target: + entity_id: alarm_control_panel.real_alarm + data: + code: !secret alarm_code + disarm: + - condition: state + entity_id: device_tracker.paulus + state: "home" + - action: alarm_control_panel.alarm_disarm target: - entity_id: number.automower_cutting_height_raw + entity_id: alarm_control_panel.real_alarm data: - value: "{{ (value - 1.5) * 2 }}" - step: 0.5 - min: 2 - max: 6 - icon: mdi:ruler + code: !secret alarm_code ``` {% endraw %} +{% configuration %} +panels: + description: List of your panels. + required: true + type: map + keys: + alarm_control_panel_name: + description: The slug of the panel. + required: true + type: map + keys: + name: + description: Name to use in the frontend. + required: false + type: string + default: Template Alarm Control Panel + unique_id: + description: An ID that uniquely identifies this alarm control panel. Set this to a unique value to allow customization through the UI. + required: false + type: string + value_template: + description: "Defines a template to set the state of the alarm panel. Only the states `armed_away`, `armed_home`, `armed_night`, `armed_vacation`, `arming`, `disarmed`, `pending`, `triggered` and `unavailable` are used." + required: false + type: template + disarm: + description: Defines an action to run when the alarm is disarmed. + required: false + type: action + arm_away: + description: Defines an action to run when the alarm is armed to away mode. + required: false + type: action + arm_home: + description: Defines an action to run when the alarm is armed to home mode. + required: false + type: action + arm_night: + description: Defines an action to run when the alarm is armed to night mode. + required: false + type: action + arm_vacation: + description: Defines an action to run when the alarm is armed to vacation mode. + required: false + type: action + arm_custom_bypass: + description: Defines an action to run when the alarm is armed to custom bypass mode. + required: false + type: action + trigger: + description: Defines an action to run when the alarm is triggered. + required: false + type: action + code_arm_required: + description: If true, the code is required to arm the alarm. + required: false + type: boolean + default: true + code_format: + description: One of `number`, `text` or `no_code`. Format for the code used to arm/disarm the alarm. + required: false + type: string + default: number +{% endconfiguration %} -## Legacy binary sensor configuration format +## Legacy Binary Sensor configuration format -_This format still works but is no longer recommended. [Use modern configuration](#configuration-variables)._ +_These formats still work but are no longer recommended. [Use modern configuration](#binary-sensor)._ This format is configured as a platform for the `binary_sensor` integration and not directly under the `template` integration. @@ -1386,9 +2701,486 @@ sensors: type: time {% endconfiguration %} +## Legacy Cover configuration format + +_This format still works but is no longer recommended. [Use modern configuration](#cover)._ + +This format is configured as a platform for the `cover` integration and not directly under the `template` integration. + +{% raw %} + +```yaml +# Example configuration.yaml entry +cover: + - platform: template + covers: + garage_door: + device_class: garage + friendly_name: "Garage Door" + value_template: "{{ states('sensor.garage_door')|float > 0 }}" + open_cover: + action: script.open_garage_door + close_cover: + action: script.close_garage_door + stop_cover: + action: script.stop_garage_door +``` + +{% endraw %} + +{% configuration %} + covers: + description: List of your covers. + required: true + type: map + keys: + friendly_name: + description: Name to use in the frontend. + required: false + type: string + unique_id: + description: An ID that uniquely identifies this cover. Set this to a unique value to allow customization through the UI. + required: false + type: string + value_template: + description: Defines a template to get the state of the cover. Valid output values from the template are `open`, `opening`, `closing` and `closed` which are directly mapped to the corresponding states. In addition, `true` is valid as a synonym to `open` and `false` as a synonym to `closed`. If [both a `value_template` and a `position_template`](#combining-state-and-position-templates) are specified, only `opening` and `closing` are set from the `value_template`. If the template produces a `None` value the state will be set to `unknown`. + required: false + type: template + position_template: + description: Defines a template to get the position of the cover. Legal values are numbers between `0` (closed) and `100` (open). If the template produces a `None` value the current position will be set to `unknown`. + required: false + type: template + icon_template: + description: Defines a template to specify which icon to use. + required: false + type: template + entity_picture_template: + description: Defines a template for the entity picture of the cover. + required: false + type: template + availability_template: + description: Defines a template to get the `available` state of the entity. If the template either fails to render or returns `True`, `"1"`, `"true"`, `"yes"`, `"on"`, `"enable"`, or a non-zero number, the entity will be `available`. If the template returns any other value, the entity will be `unavailable`. If not configured, the entity will always be `available`. Note that the string comparison is not case sensitive; `"TrUe"` and `"yEs"` are allowed. + required: false + type: template + default: true + device_class: + description: Sets the [class of the device](/integrations/cover/), changing the device state and icon that is displayed on the frontend. + required: false + type: string + open_cover: + description: Defines an action to open the cover. If `open_cover` is specified, `close_cover` must also be specified. At least one of `open_cover` and `set_cover_position` must be specified. + required: inclusive + type: action + close_cover: + description: Defines an action to close the cover. + required: inclusive + type: action + stop_cover: + description: Defines an action to stop the cover. + required: false + type: action + set_cover_position: + description: Defines an action to set to a cover position (between `0` and `100`). The variable `position` will contain the entity's set position. + required: false + type: action + set_cover_tilt_position: + description: Defines an action to set the tilt of a cover (between `0` and `100`). The variable `tilt` will contain the entity's set tilt position. + required: false + type: action + optimistic: + description: Force cover position to use [optimistic mode](#cover-optimistic-mode). + required: false + type: boolean + default: false + tilt_optimistic: + description: Force cover tilt position to use [optimistic mode](#cover-optimistic-mode). + required: false + type: boolean + default: false + tilt_template: + description: Defines a template to get the tilt state of the cover. Legal values are numbers between `0` (closed) and `100` (open). If the template produces a `None` value the current tilt state will be set to `unknown`. + required: false + type: template +{% endconfiguration %} + +## Legacy Fan configuration format + +_This format still works but is no longer recommended. [Use modern configuration](#fan)._ + +This format is configured as a platform for the `fan` integration and not directly under the `template` integration. + +{% raw %} + +```yaml +# Example configuration.yaml entry +fan: + - platform: template + fans: + bedroom_fan: + friendly_name: "Bedroom fan" + value_template: "{{ states('input_boolean.state') }}" + percentage_template: "{{ states('input_number.percentage') }}" + preset_mode_template: "{{ states('input_select.preset_mode') }}" + oscillating_template: "{{ states('input_select.osc') }}" + direction_template: "{{ states('input_select.direction') }}" + turn_on: + action: script.fan_on + turn_off: + action: script.fan_off + set_percentage: + action: script.fans_set_speed + data: + percentage: "{{ percentage }}" + set_preset_mode: + action: script.fans_set_preset_mode + data: + preset_mode: "{{ preset_mode }}" + set_oscillating: + action: script.fan_oscillating + data: + oscillating: "{{ oscillating }}" + set_direction: + action: script.fan_direction + data: + direction: "{{ direction }}" + speed_count: 6 + preset_modes: + - 'auto' + - 'smart' + - 'whoosh' +``` + +{% endraw %} + +{% configuration %} + fans: + description: List of your fans. + required: true + type: map + keys: + friendly_name: + description: Name to use in the frontend. + required: false + type: string + unique_id: + description: An ID that uniquely identifies this fan. Set this to a unique value to allow customization through the UI. + required: false + type: string + value_template: + description: "Defines a template to get the state of the fan. Valid values: `on`, `off`" + required: true + type: template + percentage_template: + description: Defines a template to get the speed percentage of the fan. + required: false + type: template + preset_mode_template: + description: Defines a template to get the preset mode of the fan. + required: false + type: template + oscillating_template: + description: "Defines a template to get the osc state of the fan. Valid values: `true`, `false`" + required: false + type: template + direction_template: + description: "Defines a template to get the direction of the fan. Valid values: `forward`, `reverse`" + required: false + type: template + availability_template: + description: Defines a template to get the `available` state of the entity. If the template either fails to render or returns `True`, `"1"`, `"true"`, `"yes"`, `"on"`, `"enable"`, or a non-zero number, the entity will be `available`. If the template returns any other value, the entity will be `unavailable`. If not configured, the entity will always be `available`. Note that the string comparison not case sensitive; `"TrUe"` and `"yEs"` are allowed. + required: false + type: template + default: true + turn_on: + description: Defines an action to run when the fan is turned on. + required: true + type: action + turn_off: + description: Defines an action to run when the fan is turned off. + required: true + type: action + set_percentage: + description: Defines an action to run when the fan is given a speed percentage command. + required: false + type: action + set_preset_mode: + description: Defines an action to run when the fan is given a preset command. + required: false + type: action + set_oscillating: + description: Defines an action to run when the fan is given an osc state command. + required: false + type: action + set_direction: + description: Defines an action to run when the fan is given a direction command. + required: false + type: action + preset_modes: + description: List of preset modes the fan is capable of. This is an arbitrary list of strings and must not contain any speeds. + required: false + type: [string, list] + default: [] + speed_count: + description: The number of speeds the fan supports. Used to calculate the percentage step for the `fan.increase_speed` and `fan.decrease_speed` actions. + required: false + type: integer + default: 100 +{% endconfiguration %} + +## Legacy Light configuration format + +_This format still works but is no longer recommended. [Use modern configuration](#light)._ + +This format is configured as a platform for the `light` integration and not directly under the `template` integration. + +{% raw %} + +```yaml +# Example configuration.yaml entry +light: + - platform: template + lights: + theater_lights: + friendly_name: "Theater Lights" + level_template: "{{ state_attr('sensor.theater_brightness', 'lux')|int }}" + value_template: "{{ state_attr('sensor.theater_brightness', 'lux')|int > 0 }}" + temperature_template: "{{states('input_number.temperature_input') | int}}" + hs_template: "({{states('input_number.h_input') | int}}, {{states('input_number.s_input') | int}})" + effect_list_template: "{{ state_attr('light.led_strip', 'effect_list') }}" + turn_on: + action: script.theater_lights_on + turn_off: + action: script.theater_lights_off + set_level: + action: script.theater_lights_level + data: + brightness: "{{ brightness }}" + set_temperature: + action: input_number.set_value + data: + value: "{{ color_temp }}" + entity_id: input_number.temperature_input + set_hs: + - action: input_number.set_value + data: + value: "{{ h }}" + entity_id: input_number.h_input + - action: input_number.set_value + data: + value: "{{ s }}" + entity_id: input_number.s_input + - action: light.turn_on + data: + entity_id: + - light.led_strip + transition: "{{ transition | float }}" + hs_color: + - "{{ hs[0] }}" + - "{{ hs[1] }}" + set_effect: + - action: light.turn_on + data: + entity_id: + - light.led_strip + effect: "{{ effect }}" + supports_transition_template: "{{ true }}" +``` + +{% endraw %} + +{% configuration %} + lights: + description: List of your lights. + required: true + type: map + keys: + friendly_name: + description: Name to use in the frontend. + required: false + type: string + unique_id: + description: An ID that uniquely identifies this light. Set this to a unique value to allow customization through the UI. + required: false + type: string + value_template: + description: Defines a template to get the state of the light. + required: false + type: template + default: optimistic + level_template: + description: Defines a template to get the brightness of the light. + required: false + type: template + default: optimistic + temperature_template: + description: Defines a template to get the color temperature of the light. + required: false + type: template + default: optimistic + hs_template: + description: Defines a template to get the HS color of the light. Must render a tuple (hue, saturation). + required: false + type: template + default: optimistic + rgb_template: + description: Defines a template to get the RGB color of the light. Must render a tuple or a list (red, green, blue). + required: false + type: template + default: optimistic + rgbw_template: + description: Defines a template to get the RGBW color of the light. Must render a tuple or a list (red, green, blue, white). + required: false + type: template + default: optimistic + rgbww_template: + description: Defines a template to get the RGBWW color of the light. Must render a tuple or a list (red, green, blue, cold white, warm white). + required: false + type: template + default: optimistic + supports_transition_template: + description: Defines a template to get if light supports transition. Should return boolean value (True/False). If this value is `True` transition parameter in a turn on or turn off call will be passed as a named parameter `transition` to either of the scripts. + required: false + type: template + default: false + effect_list_template: + description: Defines a template to get the list of supported effects. Must render a list + required: inclusive + type: template + default: optimistic + effect_template: + description: Defines a template to get the effect of the light. + required: inclusive + type: template + default: optimistic + min_mireds_template: + description: Defines a template to get the min mireds value of the light. + required: false + type: template + default: optimistic + max_mireds_template: + description: Defines a template to get the max mireds value of the light. + required: false + type: template + default: optimistic + icon_template: + description: Defines a template for an icon or picture, e.g., showing a different icon for different states. + required: false + type: template + availability_template: + description: Defines a template to get the `available` state of the entity. If the template either fails to render or returns `True`, `"1"`, `"true"`, `"yes"`, `"on"`, `"enable"`, or a non-zero number, the entity will be `available`. If the template returns any other value, the entity will be `unavailable`. If not configured, the entity will always be `available`. Note that the string comparison not case sensitive; `"TrUe"` and `"yEs"` are allowed. + required: false + type: template + default: true + turn_on: + description: Defines an action to run when the light is turned on. May receive variables `brightness` and/or `transition`. + required: true + type: action + turn_off: + description: Defines an action to run when the light is turned off. May receive variable `transition`. + required: true + type: action + set_level: + description: Defines an action to run when the light is given a brightness command. The script will only be called if the `turn_on` call only has brightness, and optionally transition. Receives variables `brightness` and optionally `transition`. + required: false + type: action + set_temperature: + description: Defines an action to run when the light is given a color temperature command. Receives variable `color_temp`. May also receive variables `brightness` and/or `transition`. + required: false + type: action + set_hs: + description: "Defines an action to run when the light is given a hs color command. Available variables: `hs` as a tuple, `h` and `s`" + required: false + type: action + set_rgb: + description: "Defines an action to run when the light is given an RGB color command. Available variables: `rgb` as a tuple, `r`, `g` and `b`." + required: false + type: action + set_rgbw: + description: "Defines an action to run when the light is given an RGBW color command. Available variables: `rgbw` as a tuple, `rgb` as a tuple, `r`, `g`, `b` and `w`." + required: false + type: action + set_rgbww: + description: "Defines an action to run when the light is given an RGBWW color command. Available variables: `rgbww` as a tuple, `rgb` as a tuple, `r`, `g`, `b`, `cw` and `ww`." + required: false + type: action + set_effect: + description: Defines an action to run when the light is given an effect command. Receives variable `effect`. May also receive variables `brightness` and/or `transition`. + required: inclusive + type: action +{% endconfiguration %} + +## Legacy Lock configuration format + +_This format still works but is no longer recommended. [Use modern configuration](#lock)._ + +This format is configured as a platform for the `lock` integration and not directly under the `template` integration. + +{% raw %} + +```yaml +# Example configuration.yaml entry +lock: + - platform: template + name: Garage door + value_template: "{{ is_state('sensor.door', 'on') }}" + lock: + action: switch.turn_on + target: + entity_id: switch.door + unlock: + action: switch.turn_off + target: + entity_id: switch.door +``` + +{% endraw %} + +{% configuration %} + name: + description: Name to use in the frontend. + required: false + type: string + default: Template Lock + unique_id: + description: An ID that uniquely identifies this lock. Set this to a unique value to allow customization through the UI. + required: false + type: string + value_template: + description: Defines a template to set the state of the lock. + required: true + type: template + availability_template: + description: Defines a template to get the `available` state of the entity. If the template either fails to render or returns `True`, `"1"`, `"true"`, `"yes"`, `"on"`, `"enable"`, or a non-zero number, the entity will be `available`. If the template returns any other value, the entity will be `unavailable`. If not configured, the entity will always be `available`. Note that the string comparison not case sensitive; `"TrUe"` and `"yEs"` are allowed. + required: false + type: template + default: true + code_format_template: + description: Defines a template to get the `code_format` attribute of the entity. This template must evaluate to a valid [Python regular expression](https://docs.python.org/3/library/re.html#regular-expression-syntax) or `None`. If it evaluates to a not-`None` value, the user is prompted to enter a code when interacting with the lock. The code will be matched against the regular expression, and only if it matches, the lock/unlock actions will be executed. The actual _validity_ of the entered code must be verified within these actions. If there's a syntax error in the template, the entity will be unavailable. If the template fails to render for other reasons or if the regular expression is invalid, no code will be accepted and the lock/unlock actions will never be invoked. + required: false + type: template + default: None + lock: + description: Defines an action to run when the lock is locked. + required: true + type: action + unlock: + description: Defines an action to run when the lock is unlocked. + required: true + type: action + open: + description: Defines an action to run when the lock is opened. + required: false + type: action + optimistic: + description: Flag that defines if lock works in optimistic mode. + required: false + type: boolean + default: false +{% endconfiguration %} + ## Legacy Sensor configuration format -_This format still works but is no longer recommended. [Use modern configuration](#configuration-variables)._ +_This format still works but is no longer recommended. [Use modern configuration](#sensor)._ This format is configured as a platform for the `sensor` integration and not directly under the `template` integration. @@ -1466,8 +3258,282 @@ sensor: default: None {% endconfiguration %} -## Event `event_template_reloaded` +## Legacy Switch configuration format -Event `event_template_reloaded` is fired when Template entities have been reloaded and entities thus might have changed. +_This format still works but is no longer recommended. [Use modern configuration](#switch)._ -This event has no additional data. +This format is configured as a platform for the `switch` integration and not directly under the `template` integration. + +{% raw %} + +```yaml +# Example configuration.yaml entry +switch: + - platform: template + switches: + skylight: + value_template: "{{ is_state('sensor.skylight', 'on') }}" + turn_on: + action: switch.turn_on + target: + entity_id: switch.skylight_open + turn_off: + action: switch.turn_off + target: + entity_id: switch.skylight_close +``` + +{% endraw %} + +{% configuration %} + switches: + description: List of your switches. + required: true + type: map + keys: + friendly_name: + description: Name to use in the frontend. + required: false + type: string + unique_id: + description: An ID that uniquely identifies this switch. Set this to a unique value to allow customization through the UI. + required: false + type: string + value_template: + description: Defines a template to set the state of the switch. If not defined, the switch will optimistically assume all commands are successful. + required: false + type: template + default: optimistic + availability_template: + description: Defines a template to get the `available` state of the entity. If the template either fails to render or returns `True`, `"1"`, `"true"`, `"yes"`, `"on"`, `"enable"`, or a non-zero number, the entity will be `available`. If the template returns any other value, the entity will be `unavailable`. If not configured, the entity will always be `available`. Note that the string comparison not case sensitive; `"TrUe"` and `"yEs"` are allowed. + required: false + type: template + default: true + turn_on: + description: Defines an action or list of actions to run when the switch is turned on. + required: true + type: action + turn_off: + description: Defines an action or list of actions to run when the switch is turned off. + required: true + type: action + icon_template: + description: Defines a template for the icon of the switch. + required: false + type: template + entity_picture_template: + description: Defines a template for the picture of the switch. + required: false + type: template +{% endconfiguration %} + +## Legacy Vacuum configuration format + +_This format still works but is no longer recommended. [Use modern configuration](#vacuum)._ + +This format is configured as a platform for the `vacuum` integration and not directly under the `template` integration. + +{% raw %} + +```yaml +# Example configuration.yaml entry +vacuum: + - platform: template + vacuums: + living_room_vacuum: + start: + action: script.vacuum_start +``` + +{% endraw %} + +{% configuration %} + vacuums: + description: List of your vacuums. + required: true + type: map + keys: + friendly_name: + description: Name to use in the frontend. + required: false + type: string + unique_id: + description: An ID that uniquely identifies this vacuum. Set this to a unique value to allow customization through the UI. + required: false + type: string + value_template: + description: "Defines a template to get the state of the vacuum. Valid value: `docked`/`cleaning`/`idle`/`paused`/`returning`/`error`" + required: false + type: template + battery_level_template: + description: "Defines a template to get the battery level of the vacuum. Legal values are numbers between `0` and `100`." + required: false + type: template + fan_speed_template: + description: Defines a template to get the fan speed of the vacuum. + required: false + type: template + attribute_templates: + description: Defines templates for attributes of the sensor. + required: false + type: map + keys: + "attribute: template": + description: The attribute and corresponding template. + required: true + type: template + availability_template: + description: Defines a template to get the `available` state of the entity. If the template either fails to render or returns `True`, `"1"`, `"true"`, `"yes"`, `"on"`, `"enable"`, or a non-zero number, the entity will be `available`. If the template returns any other value, the entity will be `unavailable`. If not configured, the entity will always be `available`. Note that the string comparison not case sensitive; `"TrUe"` and `"yEs"` are allowed. + required: false + type: template + default: true + start: + description: Defines an action to run when the vacuum is started. + required: true + type: action + pause: + description: Defines an action to run when the vacuum is paused. + required: false + type: action + stop: + description: Defines an action to run when the vacuum is stopped. + required: false + type: action + return_to_base: + description: Defines an action to run when the vacuum is given a return to base command. + required: false + type: action + clean_spot: + description: Defines an action to run when the vacuum is given a clean spot command. + required: false + type: action + locate: + description: Defines an action to run when the vacuum is given a locate command. + required: false + type: action + set_fan_speed: + description: Defines an action to run when the vacuum is given a command to set the fan speed. + required: false + type: action + fan_speeds: + description: List of fan speeds supported by the vacuum. + required: false + type: [string, list] +{% endconfiguration %} + +## Legacy Weather configuration format + +_This format still works but is no longer recommended. [Use modern configuration](#weather)._ + +This format is configured as a platform for the `weather` integration and not directly under the `template` integration. + +{% raw %} + +```yaml +# Example configuration.yaml entry +weather: + - platform: template + name: "My Weather Station" + condition_template: "{{ states('weather.my_region') }}" + temperature_template: "{{ states('sensor.temperature') | float }}" + temperature_unit: "°C" + humidity_template: "{{ states('sensor.humidity') | float }}" + forecast_daily_template: "{{ state_attr('weather.my_region', 'forecast_data') }}" +``` + +{% endraw %} + +{% configuration %} +name: + description: Name to use in the frontend. + required: true + type: template +unique_id: + description: An ID that uniquely identifies this weather entity. Set this to a unique value to allow customization through the UI. + required: false + type: string +condition_template: + description: The current weather condition. + required: true + type: template +temperature_template: + description: The current temperature. + required: true + type: template +dew_point_template: + description: The current dew point. + required: false + type: template +apparent_temperature_template: + description: The current apparent (feels-like) temperature. + required: false + type: template +temperature_unit: + description: Unit for temperature_template output. Valid options are °C, °F, and K. + required: false + type: string +humidity_template: + description: The current humidity. + required: true + type: template +attribution_template: + description: The attribution to be shown in the frontend. + required: false + type: string +pressure_template: + description: The current air pressure. + required: false + type: template +pressure_unit: + description: Unit for pressure_template output. Valid options are Pa, hPa, kPa, bar, cbar, mbar, mmHg, inHg, psi. + required: false + type: string +wind_speed_template: + description: The current wind speed. + required: false + type: template +wind_gust_speed_template: + description: The current wind gust speed. + required: false + type: template +wind_speed_unit: + description: Unit for wind_speed_template output. Valid options are m/s, km/h, mph, mm/d, in/d, and in/h. + required: false + type: string +wind_bearing_template: + description: The current wind bearing. + required: false + type: template +ozone_template: + description: The current ozone level. + required: false + type: template +cloud_coverage_template: + description: The current cloud coverage. + required: false + type: template +visibility_template: + description: The current visibility. + required: false + type: template +visibility_unit: + description: Unit for visibility_template output. Valid options are km, mi, ft, m, cm, mm, in, yd. + required: false + type: string +forecast_daily_template: + description: Daily forecast data. + required: false + type: template +forecast_hourly_template: + description: Hourly forecast data. + required: false + type: template +forecast_twice_daily_template: + description: Twice daily forecast data. + required: false + type: template +precipitation_unit: + description: Unit for precipitation output. Valid options are km, mi, ft, m, cm, mm, in, yd. + required: false + type: string +{% endconfiguration %} diff --git a/source/_integrations/vacuum.template.markdown b/source/_integrations/vacuum.template.markdown deleted file mode 100644 index 4fedbb92c83..00000000000 --- a/source/_integrations/vacuum.template.markdown +++ /dev/null @@ -1,217 +0,0 @@ ---- -title: "Template vacuum" -description: "Instructions how to setup template vacuums within Home Assistant." -ha_category: - - Vacuum - - Helper -ha_release: 0.96 -ha_iot_class: Local Push -ha_quality_scale: internal -ha_codeowners: - - '@home-assistant/core' -ha_domain: template -ha_platforms: - - vacuum -ha_integration_type: helper -related: - - docs: /docs/configuration/ - title: Configuration file ---- - -The `template` platform creates vacuums that combine integrations and provides the -ability to run scripts or invoke actions for each of the start, pause, stop, -return_to_base, clean_spot, locate and set_fan_speed commands of a vacuum. - -To enable Template Vacuums in your installation, add the following to your -`configuration.yaml` file: - -{% raw %} - -```yaml -# Example configuration.yaml entry -vacuum: - - platform: template - vacuums: - living_room_vacuum: - start: - action: script.vacuum_start -``` - -{% endraw %} - -{% configuration %} - vacuums: - description: List of your vacuums. - required: true - type: map - keys: - friendly_name: - description: Name to use in the frontend. - required: false - type: string - unique_id: - description: An ID that uniquely identifies this vacuum. Set this to a unique value to allow customization through the UI. - required: false - type: string - value_template: - description: "Defines a template to get the state of the vacuum. Valid value: `docked`/`cleaning`/`idle`/`paused`/`returning`/`error`" - required: false - type: template - battery_level_template: - description: "Defines a template to get the battery level of the vacuum. Legal values are numbers between `0` and `100`." - required: false - type: template - fan_speed_template: - description: Defines a template to get the fan speed of the vacuum. - required: false - type: template - attribute_templates: - description: Defines templates for attributes of the sensor. - required: false - type: map - keys: - "attribute: template": - description: The attribute and corresponding template. - required: true - type: template - availability_template: - description: Defines a template to get the `available` state of the entity. If the template either fails to render or returns `True`, `"1"`, `"true"`, `"yes"`, `"on"`, `"enable"`, or a non-zero number, the entity will be `available`. If the template returns any other value, the entity will be `unavailable`. If not configured, the entity will always be `available`. Note that the string comparison not case sensitive; `"TrUe"` and `"yEs"` are allowed. - required: false - type: template - default: true - start: - description: Defines an action to run when the vacuum is started. - required: true - type: action - pause: - description: Defines an action to run when the vacuum is paused. - required: false - type: action - stop: - description: Defines an action to run when the vacuum is stopped. - required: false - type: action - return_to_base: - description: Defines an action to run when the vacuum is given a return to base command. - required: false - type: action - clean_spot: - description: Defines an action to run when the vacuum is given a clean spot command. - required: false - type: action - locate: - description: Defines an action to run when the vacuum is given a locate command. - required: false - type: action - set_fan_speed: - description: Defines an action to run when the vacuum is given a command to set the fan speed. - required: false - type: action - fan_speeds: - description: List of fan speeds supported by the vacuum. - required: false - type: [string, list] -{% endconfiguration %} - -### Template and action variables - -State-based template entities have the special template variable `this` available in their templates and actions. The `this` variable aids [self-referencing](/integrations/template#self-referencing) of an {% term entity %}'s state and attribute in templates and actions. - -## Examples - -### Control vacuum with Harmony Hub - -This example shows how you can use a Template Vacuum to control an IR vacuum cleaner using the [Harmony Hub Remote integration](/integrations/harmony). - -```yaml -vacuum: - - platform: template - vacuums: - living_room_vacuum: - start: - - action: remote.send_command - target: - entity_id: remote.harmony_hub - data: - command: Clean - device: 52840686 - return_to_base: - - action: remote.send_command - target: - entity_id: remote.harmony_hub - data: - command: Home - device: 52840686 - clean_spot: - - action: remote.send_command - target: - entity_id: remote.harmony_hub - data: - command: SpotCleaning - device: 52840686 -``` - -### Vacuum with state - -This example shows how to use templates to specify the state of the vacuum. - -{% raw %} - -```yaml -vacuum: - - platform: template - vacuums: - living_room_vacuum: - value_template: "{{ states('sensor.vacuum_state') }}" - battery_level_template: "{{ states('sensor.vacuum_battery_level')|int }}" - fan_speed_template: "{{ states('sensor.vacuum_fan_speed') }}" - start: - action: script.vacuum_start - pause: - action: script.vacuum_pause - stop: - action: script.vacuum_stop - return_to_base: - action: script.vacuum_return_to_base - clean_spot: - action: script.vacuum_clean_spot - locate: - action: script.vacuum_locate_vacuum - set_fan_speed: - action: script.vacuum_set_fan_speed - data: - speed: "{{ fan_speed }}" - fan_speeds: - - Low - - Medium - - High -``` - -{% endraw %} - -### Add custom attributes - -This example shows how to add custom attributes. - -{% raw %} - -```yaml -vacuum: - - platform: template - vacuums: - living_room_vacuum: - value_template: "{{ states('sensor.vacuum_state') }}" - battery_level_template: "{{ states('sensor.vacuum_battery_level')|int }}" - fan_speed_template: "{{ states('sensor.vacuum_fan_speed') }}" - attribute_templates: - status: >- - {% if (states('sensor.robot_vacuum_robot_cleaner_movement') == "after" and states('sensor.robot_vacuum_robot_cleaner_cleaning_mode') == "stop") %} - Charging to Resume - {% elif states('sensor.robot_vacuum_robot_cleaner_cleaning_mode') == "auto" %} - Cleaning - {% else %} - Charging - {% endif %} -``` - -{% endraw %} diff --git a/source/_integrations/weather.template.markdown b/source/_integrations/weather.template.markdown deleted file mode 100644 index f5ded2771be..00000000000 --- a/source/_integrations/weather.template.markdown +++ /dev/null @@ -1,148 +0,0 @@ ---- -title: "Template Weather Provider" -description: "Instructions on how to integrate Template Weather provider into Home Assistant." -ha_category: - - Weather - - Helper -ha_release: 2021.3 -ha_iot_class: "Local Push" -ha_quality_scale: internal -ha_codeowners: - - '@home-assistant/core' -ha_domain: template -ha_platforms: - - weather -ha_integration_type: helper -related: - - docs: /docs/configuration/ - title: Configuration file ---- - -The `template` integrations creates weather provider that combines integrations and an existing weather provider into a fused weather provider. - -There are several powerful ways to use this {% term integration %}, including localizing your weather provider information with local information from temperature, humidity, pressure sensors that you own. - -Another use case could be using temperature and humidity from one weather platform, with forecasts from a different one. - -Output will be converted according to the user's unit system or {% term entity %} override, see [documentation](https://developers.home-assistant.io/docs/core/entity/weather/#unit-conversion). - -## Configuration - -To enable a Template Weather provider in your installation, add the following to your {% term "`configuration.yaml`" %} file: - -(Note, be sure to update my_region in the condition and forecast templates to an appropriate value for your setup). - -{% raw %} - -```yaml -# Example configuration.yaml entry -weather: - - platform: template - name: "My Weather Station" - condition_template: "{{ states('weather.my_region') }}" - temperature_template: "{{ states('sensor.temperature') | float }}" - temperature_unit: "°C" - humidity_template: "{{ states('sensor.humidity') | float }}" - forecast_daily_template: "{{ state_attr('weather.my_region', 'forecast_data') }}" -``` - -{% endraw %} - -{% configuration %} -name: - description: Name to use in the frontend. - required: true - type: template -unique_id: - description: An ID that uniquely identifies this weather entity. Set this to a unique value to allow customization through the UI. - required: false - type: string -condition_template: - description: The current weather condition. - required: true - type: template -temperature_template: - description: The current temperature. - required: true - type: template -dew_point_template: - description: The current dew point. - required: false - type: template -apparent_temperature_template: - description: The current apparent (feels-like) temperature. - required: false - type: template -temperature_unit: - description: Unit for temperature_template output. Valid options are °C, °F, and K. - required: false - type: string -humidity_template: - description: The current humidity. - required: true - type: template -attribution_template: - description: The attribution to be shown in the frontend. - required: false - type: string -pressure_template: - description: The current air pressure. - required: false - type: template -pressure_unit: - description: Unit for pressure_template output. Valid options are Pa, hPa, kPa, bar, cbar, mbar, mmHg, inHg, psi. - required: false - type: string -wind_speed_template: - description: The current wind speed. - required: false - type: template -wind_gust_speed_template: - description: The current wind gust speed. - required: false - type: template -wind_speed_unit: - description: Unit for wind_speed_template output. Valid options are m/s, km/h, mph, mm/d, in/d, and in/h. - required: false - type: string -wind_bearing_template: - description: The current wind bearing. - required: false - type: template -ozone_template: - description: The current ozone level. - required: false - type: template -cloud_coverage_template: - description: The current cloud coverage. - required: false - type: template -visibility_template: - description: The current visibility. - required: false - type: template -visibility_unit: - description: Unit for visibility_template output. Valid options are km, mi, ft, m, cm, mm, in, yd. - required: false - type: string -forecast_daily_template: - description: Daily forecast data. - required: false - type: template -forecast_hourly_template: - description: Hourly forecast data. - required: false - type: template -forecast_twice_daily_template: - description: Twice daily forecast data. - required: false - type: template -precipitation_unit: - description: Unit for precipitation output. Valid options are km, mi, ft, m, cm, mm, in, yd. - required: false - type: string -{% endconfiguration %} - -### Template variables - -State-based template entities have the special template variable `this` available in their templates. The `this` variable aids [self-referencing](/integrations/template#self-referencing) of an {% term entity %}'s state and attribute in templates.