mirror of
https://github.com/home-assistant/home-assistant.io.git
synced 2025-07-23 01:06:52 +00:00
Add Jekyll plugin for Configuration Variables (#3415)
* Add Jekyll plugin for configuration variables * Fix requested changes * Remove blank lines after configuration tag * Add component/platform to configuration tag
This commit is contained in:
parent
eb2e547237
commit
2676c87abe
114
plugins/configuration.rb
Normal file
114
plugins/configuration.rb
Normal file
@ -0,0 +1,114 @@
|
||||
module Jekyll
|
||||
class ConfigurationBlock < Liquid::Block
|
||||
TYPE_LINKS = {
|
||||
'action' => '/docs/scripts/',
|
||||
'device_class' => '/components/%{component}/#device_class',
|
||||
'template' => '/docs/configuration/templating/',
|
||||
}
|
||||
|
||||
def initialize(tag_name, text, tokens)
|
||||
super
|
||||
@component, @platform = text.strip.split('.', 2)
|
||||
end
|
||||
|
||||
def slug(key)
|
||||
key.downcase.strip.gsub(' ', '-').gsub(/[^\w\-]/, '')
|
||||
end
|
||||
|
||||
def type_class(type)
|
||||
((type.is_a? Array) ? type.join(' ') : type).downcase
|
||||
end
|
||||
|
||||
def type_link(type, component: nil)
|
||||
if type.include? ','
|
||||
type = type.split(',')
|
||||
end
|
||||
|
||||
if type.is_a? Array
|
||||
return (type.map { |t| type_link(t, component: component) }).join(' | ')
|
||||
end
|
||||
|
||||
type.strip!
|
||||
if TYPE_LINKS.include? type.downcase
|
||||
url = TYPE_LINKS[type.downcase] % {component: component}
|
||||
"[%s](%s)" % [type, url]
|
||||
else
|
||||
type
|
||||
end
|
||||
end
|
||||
|
||||
def required_value(value)
|
||||
if value === true
|
||||
"Required"
|
||||
elsif value === false
|
||||
"Optional"
|
||||
else
|
||||
value.strip.titlecase
|
||||
end
|
||||
end
|
||||
|
||||
def render_config_vars(vars:, component:, platform:, classes: nil)
|
||||
result = Array.new
|
||||
result << "<dl class='#{classes}'>"
|
||||
|
||||
result << vars.map do |key, attr|
|
||||
markup = Array.new
|
||||
markup << "<dt><a class='title-link' name='#{slug(key)}' href='\##{slug(key)}'></a> #{key}</dt>"
|
||||
markup << "<dd>"
|
||||
markup << "<p class='desc'>"
|
||||
if attr.key? 'type'
|
||||
markup << "<span class='type'>(<span class='#{type_class(attr['type'])}'>"
|
||||
markup << "#{type_link(attr['type'], component: component)}</span>)</span>"
|
||||
end
|
||||
if attr.key? 'required'
|
||||
markup << "<span class='required'>(#{required_value(attr['required'])})</span>"
|
||||
end
|
||||
if attr.key? 'description'
|
||||
markup << "<span class='description'>#{attr['description']}</span>"
|
||||
end
|
||||
markup << "</p>"
|
||||
if attr.key? 'default'
|
||||
markup << "<p class='default'>Default value: #{attr['default']}</p>"
|
||||
end
|
||||
markup << "</dd>"
|
||||
|
||||
# Check for nested configuration variables
|
||||
if attr.key? 'keys'
|
||||
markup << "<dd>"
|
||||
markup << render_config_vars(
|
||||
vars: attr['keys'], component: component,
|
||||
platform: platform, classes: 'nested')
|
||||
markup << "</dd>"
|
||||
end
|
||||
|
||||
markup
|
||||
end
|
||||
|
||||
result << "</dl>"
|
||||
result.join
|
||||
end
|
||||
|
||||
def render(context)
|
||||
if @component.nil? and @platform.nil?
|
||||
page = context.environments.first['page']
|
||||
@component, @platform = page['slug'].split('.', 2)
|
||||
end
|
||||
|
||||
contents = super(context)
|
||||
|
||||
component = Liquid::Template.parse(@component).render context
|
||||
platform = Liquid::Template.parse(@platform).render context
|
||||
|
||||
vars = SafeYAML.load(contents)
|
||||
|
||||
<<~MARKUP
|
||||
<div class="config-vars">
|
||||
<h3><a class="title-link" name="configuration-variables" href="#configuration-variables"></a> Configuration Variables</h3>
|
||||
#{render_config_vars(vars: vars, component: component, platform: platform)}
|
||||
</div>
|
||||
MARKUP
|
||||
end
|
||||
end
|
||||
end
|
||||
|
||||
Liquid::Template.register_tag('configuration', Jekyll::ConfigurationBlock)
|
@ -100,7 +100,6 @@ $primary-color: #049cdb;
|
||||
}
|
||||
|
||||
.frontpage {
|
||||
|
||||
.material-card {
|
||||
margin-bottom: 24px;
|
||||
}
|
||||
@ -109,7 +108,6 @@ $primary-color: #049cdb;
|
||||
.release-date {
|
||||
white-space: nowrap;
|
||||
}
|
||||
|
||||
}
|
||||
|
||||
.recent-posts {
|
||||
@ -202,7 +200,8 @@ h2:hover a.title-link,
|
||||
h3:hover a.title-link,
|
||||
h4:hover a.title-link,
|
||||
h5:hover a.title-link,
|
||||
h6:hover a.title-link {
|
||||
h6:hover a.title-link,
|
||||
dt:hover a.title-link {
|
||||
position: relative;
|
||||
|
||||
&::before {
|
||||
@ -237,7 +236,7 @@ h6:hover a.title-link {
|
||||
}
|
||||
|
||||
.icon i {
|
||||
border: none !important;
|
||||
border: none !important;
|
||||
}
|
||||
}
|
||||
|
||||
@ -310,6 +309,13 @@ article.post, article.page, article.listing {
|
||||
h2 {
|
||||
font-size: 1.5em;
|
||||
margin-top: 2em;
|
||||
|
||||
// Future re-design
|
||||
// margin: 1.5em 0 1rem;
|
||||
//
|
||||
// border: 0;
|
||||
// border-top: 1px solid $primary-color;
|
||||
// padding-top: 1.4rem;
|
||||
}
|
||||
|
||||
h3 {
|
||||
@ -317,11 +323,17 @@ article.post, article.page, article.listing {
|
||||
letter-spacing: 0.125rem;
|
||||
font-size: 1.2rem;
|
||||
margin-top: 2em;
|
||||
|
||||
// Future re-design
|
||||
// margin: 2em 0 1rem;
|
||||
}
|
||||
|
||||
h4 {
|
||||
font-size: 1.1rem;
|
||||
margin-top: 2em;
|
||||
|
||||
// Future re-design
|
||||
// margin: 1.5em 0 1rem;
|
||||
}
|
||||
}
|
||||
|
||||
@ -431,7 +443,7 @@ ul.sidebar-menu {
|
||||
}
|
||||
|
||||
a code {
|
||||
color: #049cdb;
|
||||
color: $primary-color;
|
||||
}
|
||||
|
||||
twitterwidget {
|
||||
@ -447,3 +459,48 @@ twitterwidget {
|
||||
max-width: 100%;
|
||||
overflow: hidden;
|
||||
}
|
||||
|
||||
// Configuration variables
|
||||
div.config-vars {
|
||||
// Future re-design
|
||||
// h3 {
|
||||
// border: 0;
|
||||
// border-top: 1px solid $primary-color;
|
||||
// padding-top: 1.4rem;
|
||||
// }
|
||||
|
||||
dl {
|
||||
margin-bottom: 1.5em;
|
||||
|
||||
&.nested {
|
||||
border-left: 1px dotted $primary-color;
|
||||
padding-left: 6px;
|
||||
}
|
||||
|
||||
dt {
|
||||
font-weight: bold;
|
||||
}
|
||||
|
||||
dd {
|
||||
margin: 0 0 0.5em 1em;
|
||||
|
||||
p.desc {
|
||||
margin: 0;
|
||||
|
||||
span.type,
|
||||
span.required {
|
||||
font-style: italic;
|
||||
|
||||
&::after {
|
||||
content: " "
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
p.default {
|
||||
font-style: italic;
|
||||
margin: 0;
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
@ -1,145 +1,191 @@
|
||||
---
|
||||
layout: page
|
||||
title: "Template Binary Sensor"
|
||||
description: "Instructions how to integrate Template binary sensors into Home Assistant."
|
||||
description: "Instructions how to integrate Template Binary Sensors into Home Assistant."
|
||||
date: 2016-02-25 15:00
|
||||
sidebar: true
|
||||
comments: false
|
||||
sharing: true
|
||||
footer: true
|
||||
ha_category: Binary Sensor
|
||||
ha_release: 0.12
|
||||
ha_iot_class: "Local Push"
|
||||
logo: home-assistant.png
|
||||
---
|
||||
|
||||
The `template` platform supports sensors which breaks out the `state` and `state_attributes` from other entities. The state of a template binary sensor can only be `on` or `off`.
|
||||
The `template` platform supports sensors which breaks out the `state` and
|
||||
`state_attributes` from other entities. The state of a Template Binary Sensor
|
||||
can only be `on` or `off`.
|
||||
|
||||
To enable template binary sensors in your installation, add the following to your `configuration.yaml` file:
|
||||
To enable Template Binary Sensors in your installation, add the following to
|
||||
your `configuration.yaml` file:
|
||||
|
||||
{% raw %}
|
||||
```yaml
|
||||
# Example configuration.yaml entry
|
||||
binary_sensor:
|
||||
- platform: template
|
||||
sensors:
|
||||
sun_up:
|
||||
value_template: {% raw %}'{{ states.sun.sun.attributes.elevation > 0}}'{% endraw %}
|
||||
friendly_name: 'Sun is up'
|
||||
friendly_name: "Sun is up"
|
||||
value_template: >-
|
||||
{{ states.sun.sun.attributes.elevation|float > 0 }}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
Configuration variables:
|
||||
{% configuration binary_sensor.template %}
|
||||
sensors:
|
||||
description: List of your sensors.
|
||||
required: true
|
||||
type: map
|
||||
keys:
|
||||
friendly_name:
|
||||
description: Name to use in the frontend.
|
||||
required: false
|
||||
type: string
|
||||
entity_id:
|
||||
description: Add a list of entity IDs so the sensor only reacts to state changes of these entities. This will reduce the number of times the sensor will try to update its state.
|
||||
required: false
|
||||
type: string, list
|
||||
device_class:
|
||||
description: The type/class of the sensor to set the icon in the frontend.
|
||||
required: false
|
||||
type: device_class
|
||||
default: None
|
||||
value_template:
|
||||
description: Defines a template to set the state of the sensor.
|
||||
required: true
|
||||
type: template
|
||||
on_delay:
|
||||
description: The amount of time the template state must be ***met*** before this sensor will switch to `on`.
|
||||
required: false
|
||||
type: time
|
||||
off_delay:
|
||||
description: The amount of time the template state must be ***not met*** before this sensor will switch to `off`.
|
||||
required: false
|
||||
type: time
|
||||
{% endconfiguration %}
|
||||
|
||||
- **sensors** array (*Required*): List of your sensors.
|
||||
- **friendly_name** (*Optional*): Name to use in the Frontend.
|
||||
- **device_class** (*Optional*): The [type/class](/components/binary_sensor/) of the sensor to set the icon in the frontend.
|
||||
- **value_template** (*Optional*): Defines a [template](/topics/templating/) to extract a value from the payload.
|
||||
- **entity_id** (*Optional*): Add a list of entity IDs so the sensor only reacts to state changes of these entities. This will reduce the number of times the sensor will try to update it's state.
|
||||
- **on_delay** (*Optional*): The amount of time the template state must be met before this sensor will switch to on.
|
||||
- **off_delay** (*Optional*): The amount of time the template state must be not met before this sensor will switch to off.
|
||||
## {% linkable_title Considerations %}
|
||||
|
||||
If you are using the state of a platform that takes extra time to load, the
|
||||
Template Binary Sensor 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 %}
|
||||
|
||||
## {% linkable_title Examples %}
|
||||
|
||||
In this section you find some real life examples of how to use this sensor.
|
||||
|
||||
### {% linkable_title Sensor threshold %}
|
||||
### {% linkable_title Sensor Threshold %}
|
||||
|
||||
This example indicates true if a sensor is above a given threshold. Assuming a sensor of `furnace` that provides a current reading for the fan motor, we can determine if the furnace is running by checking that it is over some threshold:
|
||||
This example indicates true if a sensor is above a given threshold. Assuming a
|
||||
sensor of `furnace` that provides a current reading for the fan motor, we can
|
||||
determine if the furnace is running by checking that it is over some threshold:
|
||||
|
||||
{% raw %}
|
||||
```yaml
|
||||
sensor:
|
||||
- platform: template
|
||||
sensors:
|
||||
furnace_on:
|
||||
value_template: {% raw %}{{ states.sensor.furnace.state > 2.5 }}{% endraw %}
|
||||
friendly_name: 'Furnace Running'
|
||||
friendly_name: "Furnace Running"
|
||||
device_class: heat
|
||||
value_template: "{{ states('sensor.furnace')|float > 2.5 }}"
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
### {% linkable_title Switch as sensor %}
|
||||
### {% linkable_title Switch as Sensor %}
|
||||
|
||||
Some movement sensors and door/window sensors will appear as a switch. By using a template binary sensor, the switch can be displayed as a binary sensors. The original switch can then be hidden by [customizing.](/getting-started/customizing-devices/)
|
||||
Some movement sensors and door/window sensors will appear as a switch. By using
|
||||
a Template Binary Sensor, the switch can be displayed as a binary sensors. The
|
||||
original switch can then be hidden by
|
||||
[customizing](/getting-started/customizing-devices/).
|
||||
|
||||
{% raw %}
|
||||
```yaml
|
||||
binary_sensor:
|
||||
- platform: template
|
||||
sensors:
|
||||
movement:
|
||||
value_template: {% raw %}"{{ states.switch.movement.state == 'on' }}"{% endraw %}
|
||||
device_class: motion
|
||||
value_template: "{{ is_state('switch.movement', 'on') }}"
|
||||
door:
|
||||
value_template: {% raw %}"{{ states.switch.door.state == 'on' }}"{% endraw %}
|
||||
device_class: opening
|
||||
value_template: "{{ is_state('switch.door', 'on') }}"
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
|
||||
### {% linkable_title Combining multiple sensors, and using entity_id: %}
|
||||
### {% linkable_title Combining Multiple Sensors, and Using `entity_id` %}
|
||||
|
||||
This example combines multiple CO sensors into a single overall
|
||||
status. When using templates with binary sensors, you need to return
|
||||
`True` or `False` explicitly. `entity_id` is used to limit which
|
||||
`true` or `false` explicitly. `entity_id` is used to limit which
|
||||
sensors are being monitored to update the state, making computing this
|
||||
sensor far more efficient.
|
||||
|
||||
{% raw %}
|
||||
```yaml
|
||||
binary_sensor:
|
||||
- platform: template
|
||||
sensors:
|
||||
co:
|
||||
friendly_name: 'CO'
|
||||
device_class: 'gas'
|
||||
value_template: {% raw %}>-
|
||||
{%- if is_state("sensor.bedroom_co_status", "Ok")
|
||||
and is_state("sensor.kitchen_co_status", "Ok")
|
||||
and is_state("sensor.wardrobe_co_status", "Ok") -%}
|
||||
False
|
||||
{%- else -%}
|
||||
True
|
||||
{%- endif %}{% endraw %}
|
||||
friendly_name: "CO"
|
||||
device_class: gas
|
||||
entity_id:
|
||||
- sensor.bedroom_co_status
|
||||
- sensor.kitchen_co_status
|
||||
- sensor.wardrobe_co_status
|
||||
value_template: >-
|
||||
{{ is_state('sensor.bedroom_co_status', 'Ok')
|
||||
and is_state('sensor.kitchen_co_status', 'Ok')
|
||||
and is_state('sensor.wardrobe_co_status', 'Ok') }}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
### {% linkable_title 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 `off_delay`, we can have this sensor only turn off if there has been no washer activity for 5 minutes.
|
||||
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 `off_delay`, 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.
|
||||
binary_sensor:
|
||||
- platform: template
|
||||
name: Washing Machine
|
||||
value_template: {% raw %}'{{ states.sensor.washing_machine_power.state > 0 }}'{% endraw %}
|
||||
off_delay:
|
||||
minutes: 5
|
||||
sensors:
|
||||
washing_machine:
|
||||
friendly_name: "Washing Machine"
|
||||
off_delay:
|
||||
minutes: 5
|
||||
value_template: >-
|
||||
{{ states('sensor.washing_machine_power')|float > 0 }}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
### {% linkable_title Is anyone home? %}
|
||||
### {% linkable_title 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
|
||||
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 wifi based device tracking
|
||||
and z-wave multisensor presence sensors.
|
||||
assistant. This is providing a composite of WiFi based device tracking
|
||||
and Z-Wave multisensor presence sensors.
|
||||
|
||||
{% raw %}
|
||||
```yaml
|
||||
binary_sensor:
|
||||
- platform: template
|
||||
sensors:
|
||||
people_home:
|
||||
value_template: {% raw %}>-
|
||||
{%- if 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")
|
||||
-%}
|
||||
True
|
||||
{%- else -%}
|
||||
False
|
||||
{%- endif %}{% endraw %}
|
||||
entity_id:
|
||||
- device_tracker.sean
|
||||
- device_tracker.susan
|
||||
@ -148,4 +194,13 @@ binary_sensor:
|
||||
- binary_sensor.living_room_139
|
||||
- binary_sensor.porch_ms6_1_129
|
||||
- binary_sensor.family_room_144
|
||||
value_template: >-
|
||||
{{ 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 %}
|
||||
|
@ -1,7 +1,7 @@
|
||||
---
|
||||
layout: page
|
||||
title: "Template Cover"
|
||||
description: "Instructions how to integrate Template covers into Home Assistant."
|
||||
description: "Instructions how to integrate Template Covers into Home Assistant."
|
||||
date: 2017-06-19 20:32
|
||||
sidebar: true
|
||||
comments: false
|
||||
@ -13,10 +13,14 @@ ha_iot_class: "Local Push"
|
||||
logo: home-assistant.png
|
||||
---
|
||||
|
||||
The `template` platform can create covers that combine components and provides the ability to run scripts or invoke services for each of the open, close, stop, position, and tilt commands of a cover.
|
||||
The `template` platform can create covers that combine components and provides
|
||||
the ability to run scripts or invoke services for each of the open, close,
|
||||
stop, position, and tilt commands of a cover.
|
||||
|
||||
To enable Template covers in your installation, add the following to your `configuration.yaml` file:
|
||||
To enable Template Covers in your installation, add the following to your
|
||||
`configuration.yaml` file:
|
||||
|
||||
{% raw %}
|
||||
```yaml
|
||||
# Example configuration.yaml entry
|
||||
cover:
|
||||
@ -24,7 +28,7 @@ cover:
|
||||
covers:
|
||||
garage_door:
|
||||
friendly_name: "Garage Door"
|
||||
value_template: "{% raw %}'{{is_state('sensor.garage_door > 0'}}'{% endraw %}"
|
||||
value_template: "{{ states('sensor.garage_door')|float > 0 }}"
|
||||
open_cover:
|
||||
service: script.open_garage_door
|
||||
close_cover:
|
||||
@ -32,27 +36,93 @@ cover:
|
||||
stop_cover:
|
||||
service: script.stop_garage_door
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
Configuration variables:
|
||||
{% 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
|
||||
entity_id:
|
||||
description: Add a list of entity IDs so the switch only reacts to state changes of these entities. This will reduce the number of times the cover will try to update its state.
|
||||
required: false
|
||||
type: [string, list]
|
||||
value_template:
|
||||
description: Defines a template to get the state of the cover. Valid values are `open`/`true` or `closed`/`false`. [`value_template`](#value_template) and [`position_template`](#position_template) cannot be specified concurrently.
|
||||
required: exclusive
|
||||
type: template
|
||||
position_template:
|
||||
description: Defines a template to get the state of the cover. Legal values are numbers between `0` (closed) and `100` (open). [`value_template`](#value_template) and [`position_template`](#position_template) cannot be specified concurrently.
|
||||
required: exclusive
|
||||
type: template
|
||||
icon_template:
|
||||
description: Defines a template to specify which icon to use.
|
||||
required: false
|
||||
type: template
|
||||
open_cover:
|
||||
description: Defines an action to run when the cover is opened. 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 run when the cover is closed.
|
||||
required: inclusive
|
||||
type: action
|
||||
stop_cover:
|
||||
description: Defines an action to run when the cover is stopped.
|
||||
required: false
|
||||
type: action
|
||||
set_cover_position:
|
||||
description: Defines an action to run when the cover is set to a specific value (between `0` and `100`).
|
||||
required: false
|
||||
type: action
|
||||
set_cover_tilt_position:
|
||||
description: Defines an action to run when the cover tilt is set to a specific value (between `0` and `100`).
|
||||
required: false
|
||||
type: action
|
||||
optimistic:
|
||||
description: Force cover position to use [optimistic mode](#optimistic-mode).
|
||||
required: false
|
||||
type: bool
|
||||
default: false
|
||||
tilt_optimistic:
|
||||
description: Force cover tilt position to use [optimistic mode](#optimistic-mode).
|
||||
required: false
|
||||
type: bool
|
||||
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).
|
||||
required: false
|
||||
type: template
|
||||
{% endconfiguration %}
|
||||
|
||||
- **covers** array (*Required*): List of your coverss.
|
||||
- **open_cover** (*Optional*): Defines an [action](/getting-started/automation/) to run when the cover is opened. If `open_cover` is specified, `close_cover` must also be specified. At least one of `open_cover` and `set_cover_position` must be specified.
|
||||
- **close_cover** (*Optional*): Defines an [action](/getting-started/automation/) to run when the cover is closed.
|
||||
- **stop_cover** (*Optional*): Defines an [action](/getting-started/automation/) to run when the cover is stopped.
|
||||
- **set_cover_position** (*Optional*): Defines an [action](/getting-started/automation/) to run when the cover is set to a specific value (between 0 and 100).
|
||||
- **set_cover_tilt_position** (*Optional*): Defines an [action](/getting-started/automation/) to run when the cover tilt is set to a specific value (between 0 and 100).
|
||||
- **value_template** (*Optional*): Defines a [template](/topics/templating/) to get the state of the cover. Valid values are open/true or closed/false. `value_template` and `position_template` cannot be specified concurrently.
|
||||
- **position_template** (*Optional*): Defines a [template](/topics/templating/) to get the state of the cover. Legal values are numbers between 0 (closed) and 100 (open). `value_template` and `position_template` cannot be specified concurrently.
|
||||
- **tilt_template** (*Optional*): Defines a [template](/topics/templating/) to get the tilt state of the cover. Legal values are numbers between 0 (closed) and 100 (open).
|
||||
- **optimistic** (*Optional*): Force cover position to use optimistic mode. Value is either `true` or `false`. [See below](#optimistic-mode) for more details.
|
||||
- **tilt_optimistic** (*Optional*): Force cover tilt position to use optimistic mode. Value is either `true` or `false`. [See below](#optimistic mode) for more details.
|
||||
- **icon_template** (*Optional*): Defines a [template](/topics/templating/) to specify which icon to use. Either `value_template` or `position_template` must be specified.
|
||||
- **friendly_name** (*Optional*): Name to use in the frontend.
|
||||
- **entity_id** (*Optional*): Add a list of entity IDs so the switch only reacts to state changes of these entities. This will reduce the number of times the cover will try to update it's state.
|
||||
## {% linkable_title Considerations %}
|
||||
|
||||
## {% linkable_title Optitmistic Mode %}
|
||||
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.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 %}
|
||||
|
||||
In optmistic mode, the cover position state is maintained internally. This mode is automatically enabled if neither `value_template` or `position_template` are sepcified. 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_template` is not specified or when the `tilt-optimistic` attribute is used.
|
||||
## {% linkable_title 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.
|
||||
|
||||
## {% linkable_title Examples %}
|
||||
|
||||
@ -60,34 +130,44 @@ In this section you will find some real life examples of how to use this cover.
|
||||
|
||||
### {% linkable_title Garage Door %}
|
||||
|
||||
This example converts a garage door with a controllable switch and position sensor into a cover.
|
||||
This example converts a garage door with a controllable switch and position
|
||||
sensor into a cover.
|
||||
|
||||
```yaml
|
||||
{% raw %}
|
||||
```yaml
|
||||
cover:
|
||||
- platform: template
|
||||
covers:
|
||||
garage_door:
|
||||
friendly_name: 'Garage Door'
|
||||
value_template: "{{ sensor.garage_door }}"
|
||||
friendly_name: "Garage Door"
|
||||
position_template: "{{ states('sensor.garage_door') }}"
|
||||
open_cover:
|
||||
service: switch.turn_on
|
||||
entity_id: switch.garage_door
|
||||
data:
|
||||
entity_id: switch.garage_door
|
||||
close_cover:
|
||||
service: switch.turn_off
|
||||
entity_id: switch.garage_door
|
||||
data:
|
||||
entity_id: switch.garage_door
|
||||
stop_cover:
|
||||
service: switch.turn_on
|
||||
entity_id: switch.garage_door
|
||||
icon_template: "{% if not is_state('sensor.garage_door', 'on') %}mdi:garage-open{% else %}mdi:garage{% endif %}"{% endraw %}
|
||||
data:
|
||||
entity_id: switch.garage_door
|
||||
icon_template: >-
|
||||
{% if states('sensor.garage_door')|float > 0 %}
|
||||
mdi:garage-open
|
||||
{% else %}
|
||||
mdi:garage
|
||||
{% endif %}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
### {% linkable_title Multi Covers %}
|
||||
### {% linkable_title Multiple Covers %}
|
||||
|
||||
This example allows you to control two or more covers at once.
|
||||
|
||||
```yaml
|
||||
{% raw %}
|
||||
```yaml
|
||||
homeassistant:
|
||||
customize:
|
||||
all_covers:
|
||||
@ -97,7 +177,7 @@ cover:
|
||||
- platform: template
|
||||
covers:
|
||||
all_covers:
|
||||
friendly_name: 'All Covers'
|
||||
friendly_name: "All Covers"
|
||||
open_cover:
|
||||
service: script.cover_all_open
|
||||
close_cover:
|
||||
@ -107,21 +187,14 @@ cover:
|
||||
set_cover_position:
|
||||
service: script.cover_all_set_position
|
||||
data_template:
|
||||
position: "{{ position }}"
|
||||
value_template: >
|
||||
{% if is_state('sensor.all_covers', 'open') %}
|
||||
open
|
||||
{% else %}
|
||||
closed
|
||||
{% endif %}
|
||||
|
||||
icon_template: >
|
||||
position: "{{ position }}"
|
||||
value_template: "{{ is_state('sensor.all_covers', 'open') }}"
|
||||
icon_template: >-
|
||||
{% if is_state('sensor.all_covers', 'open') %}
|
||||
mdi:window-open
|
||||
{% else %}
|
||||
mdi:window-closed
|
||||
{% endif %}
|
||||
|
||||
entity_id:
|
||||
- cover.bedroom
|
||||
- cover.livingroom
|
||||
@ -130,7 +203,7 @@ sensor:
|
||||
- platform: template
|
||||
sensors:
|
||||
all_covers:
|
||||
value_template: >
|
||||
value_template: >-
|
||||
{% if is_state('cover.bedroom', 'open') %}
|
||||
open
|
||||
{% elif is_state('cover.livingroom', 'open') %}
|
||||
@ -138,7 +211,6 @@ sensor:
|
||||
{% else %}
|
||||
closed
|
||||
{% endif %}
|
||||
|
||||
entity_id:
|
||||
- cover.bedroom
|
||||
- cover.livingroom
|
||||
@ -147,41 +219,43 @@ script:
|
||||
cover_all_open:
|
||||
sequence:
|
||||
- service: cover.open_cover
|
||||
entity_id: cover.bedroom
|
||||
- service: cover.open_cover
|
||||
entity_id: cover.livingroom
|
||||
data:
|
||||
entity_id:
|
||||
- cover.bedroom
|
||||
- cover.livingroom
|
||||
cover_all_stop:
|
||||
sequence:
|
||||
- service: cover.stop_cover
|
||||
entity_id: cover.bedroom
|
||||
- service: cover.stop_cover
|
||||
entity_id: cover.livingroom
|
||||
data:
|
||||
entity_id:
|
||||
- cover.bedroom
|
||||
- cover.livingroom
|
||||
cover_all_close:
|
||||
sequence:
|
||||
- service: cover.close_cover
|
||||
entity_id: cover.bedroom
|
||||
- service: cover.close_cover
|
||||
entity_id: cover.livingroom
|
||||
data:
|
||||
entity_id:
|
||||
- cover.bedroom
|
||||
- cover.livingroom
|
||||
cover_all_set_position:
|
||||
sequence:
|
||||
- service: cover.set_cover_position
|
||||
entity_id: cover.bedroom
|
||||
data_template:
|
||||
position: "{{ position }}"
|
||||
- service: cover.set_cover_position
|
||||
entity_id: cover.livingroom
|
||||
data_template:
|
||||
entity_id:
|
||||
- cover.bedroom
|
||||
- cover.livingroom
|
||||
position: "{{ position }}"
|
||||
|
||||
automation:
|
||||
- alias: 'Close covers at night'
|
||||
- alias: "Close covers at night"
|
||||
trigger:
|
||||
- platform: sun
|
||||
event: sunset
|
||||
offset: '+00:30:00'
|
||||
action:
|
||||
service: cover.set_cover_position
|
||||
entity_id: cover.all_covers
|
||||
data_template:
|
||||
position: 25{% endraw %}
|
||||
- service: cover.set_cover_position
|
||||
data:
|
||||
entity_id: cover.all_covers
|
||||
position: 25
|
||||
```
|
||||
{% endraw %}
|
||||
|
@ -1,7 +1,7 @@
|
||||
---
|
||||
layout: page
|
||||
title: "Template Light"
|
||||
description: "Instructions how to integrate Template lights into Home Assistant."
|
||||
description: "Instructions how to integrate Template Lights into Home Assistant."
|
||||
date: 2016-05-18 20:32
|
||||
sidebar: true
|
||||
comments: false
|
||||
@ -13,10 +13,14 @@ ha_iot_class: "Local Push"
|
||||
logo: home-assistant.png
|
||||
---
|
||||
|
||||
The `template` platform creates lights that combine components and provides the ability to run scripts or invoke services for each of the on, off, and brightness commands of a light.
|
||||
The `template` platform creates lights that combine components and provides the
|
||||
ability to run scripts or invoke services for each of the on, off, and
|
||||
brightness commands of a light.
|
||||
|
||||
To enable Template lights in your installation, add the following to your `configuration.yaml` file:
|
||||
To enable Template Lights in your installation, add the following to your
|
||||
`configuration.yaml` file:
|
||||
|
||||
{% raw %}
|
||||
```yaml
|
||||
# Example configuration.yaml entry
|
||||
light:
|
||||
@ -24,7 +28,8 @@ light:
|
||||
lights:
|
||||
theater_lights:
|
||||
friendly_name: "Theater Lights"
|
||||
value_template: "{% raw %}{{is_state('sensor.theater_brightness.attributes.lux > 0'}}{% endraw %}"
|
||||
level_template: "{{ sensor.theater_brightness.attributes.lux|int }}"
|
||||
value_template: "{{ sensor.theater_brightness.attributes.lux|int > 0 }}"
|
||||
turn_on:
|
||||
service: script.theater_lights_on
|
||||
turn_off:
|
||||
@ -32,26 +37,59 @@ light:
|
||||
set_level:
|
||||
service: script.theater_lights_level
|
||||
data_template:
|
||||
brightness: "{% raw %}{{brightness}}{% endraw %}"
|
||||
level_template: "{% raw %}{{is_state('sensor.theater_brightness.attributes.lux'}}{% endraw %}"
|
||||
brightness: "{{ brightness }}"
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
Configuration variables:
|
||||
|
||||
- **lights** array (*Required*): List of your lights.
|
||||
- **friendly_name** (*Optional*): Name to use in the Frontend.
|
||||
- **value_template** (*Optional*): Defines a [template](/topics/templating/) to get the state of the light. If not provided the component defaults to optimisitc state determination.
|
||||
- **turn_on** (*Required*): Defines an [action](/getting-started/automation/) to run when the light is turned on.
|
||||
- **turn_off** (*Required*): Defines an [action](/getting-started/automation/) to run when the light is turned off.
|
||||
- **set_level** (*Optional*): Defines an [action](/getting-started/automation/) to run when the light is given a brightness command.
|
||||
- **level_template** (*Optional): Defines a [template](/topics/templating/) to get the brightness of the light. If not provided the component defaults to optimisitc brightness determination.
|
||||
- **entity_id** (*Optional*): Add a list of entity IDs so the switch only reacts to state changes of these entities. This will reduce the number of times the light will try to update it's state.
|
||||
|
||||
{% configuration %}
|
||||
switches:
|
||||
description: List of your lights.
|
||||
required: true
|
||||
type: map
|
||||
keys:
|
||||
friendly_name:
|
||||
description: Name to use in the frontend.
|
||||
required: false
|
||||
type: string
|
||||
entity_id:
|
||||
description: Add a list of entity IDs so the switch only reacts to state changes of these entities. This will reduce the number of times the light will try to update its state.
|
||||
required: false
|
||||
type: [string, list]
|
||||
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
|
||||
turn_on:
|
||||
description: Defines an action to run when the light is turned on.
|
||||
required: true
|
||||
type: action
|
||||
turn_off:
|
||||
description: Defines an action to run when the light is turned off.
|
||||
required: true
|
||||
type: action
|
||||
set_level:
|
||||
description: Defines an action to run when the light is given a brightness command.
|
||||
required: false
|
||||
type: action
|
||||
{% endconfiguration %}
|
||||
|
||||
## {% linkable_title 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 }}'{% endraw %} with this equivalent that returns true/false and never gives an unknown result:
|
||||
{% raw %}'{{ is_state('switch.source', 'on') }}'{% endraw %}
|
||||
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 %}
|
||||
|
||||
## {% linkable_title Examples %}
|
||||
|
||||
@ -59,26 +97,29 @@ In this section you will find some real life examples of how to use this light.
|
||||
|
||||
### {% linkable_title Theater Volume Control %}
|
||||
|
||||
This example shows a light that is actually a home theater's volume. This component 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 component needs a floating point percentage value 0.0-1.0
|
||||
This example shows a light that is actually a home theater's volume. This
|
||||
component 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 component](/components/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'
|
||||
friendly_name: "Receiver Volume"
|
||||
value_template: >-
|
||||
{% raw %}
|
||||
{%- if is_state("media_player.receiver", "on") -%}
|
||||
{%- if states.media_player.receiver.attributes.is_volume_muted -%}
|
||||
off
|
||||
{%- else -%}
|
||||
on
|
||||
{%- endif -%}
|
||||
{%- else -%}
|
||||
{% if is_state('media_player.receiver', 'on') %}
|
||||
{% if states.media_player.receiver.attributes.is_volume_muted %}
|
||||
off
|
||||
{% else %}
|
||||
on
|
||||
{% endif %}
|
||||
{% else %}
|
||||
off
|
||||
{%- endif -%}
|
||||
{% endraw %}
|
||||
{% endif %}
|
||||
turn_on:
|
||||
service: media_player.volume_mute
|
||||
data:
|
||||
@ -91,16 +132,14 @@ light:
|
||||
is_volume_muted: true
|
||||
set_level:
|
||||
service: media_player.volume_set
|
||||
data:
|
||||
entity_id: media_player.receiver
|
||||
data_template:
|
||||
volume_level: '{% raw %}{{((brightness / 255 * 100) | int)/100}}{% endraw %}'
|
||||
entity_id: media_player.receiver
|
||||
volume_level: "{{ (brightness / 255 * 100)|int / 100 }}"
|
||||
level_template: >-
|
||||
{% raw %}
|
||||
{%- if is_state("media_player.receiver", "on") -%}
|
||||
{{(255 * states.media_player.receiver.attributes.volume_level) | int}}
|
||||
{%- else -%}
|
||||
{% if is_state('media_player.receiver', 'on') %}
|
||||
{{ (states.media_player.receiver.attributes.volume_level|float * 255)|int }}
|
||||
{% else %}
|
||||
0
|
||||
{%- endif -%}
|
||||
{% endraw %}
|
||||
{% endif %}
|
||||
```
|
||||
{% endraw %}
|
||||
|
@ -1,7 +1,7 @@
|
||||
---
|
||||
layout: page
|
||||
title: "Template Sensor"
|
||||
description: "Instructions how to integrate Template sensors into Home Assistant."
|
||||
description: "Instructions how to integrate Template Sensors into Home Assistant."
|
||||
date: 2016-01-27 07:00
|
||||
sidebar: true
|
||||
comments: false
|
||||
@ -13,142 +13,205 @@ ha_iot_class: "Local Push"
|
||||
logo: home-assistant.png
|
||||
---
|
||||
|
||||
The `template` platform supports sensors which break out `state_attributes` from other entities.
|
||||
The `template` platform supports sensors which break out `state_attributes`
|
||||
from other entities.
|
||||
|
||||
To enable Template sensors in your installation, add the following to your `configuration.yaml` file:
|
||||
To enable Template Sensors in your installation, add the following to your
|
||||
`configuration.yaml` file:
|
||||
|
||||
{% raw %}
|
||||
```yaml
|
||||
# Example configuration.yaml entry
|
||||
sensor:
|
||||
- platform: template
|
||||
sensors:
|
||||
solar_angle:
|
||||
value_template: {% raw %}'{{ states.sun.sun.attributes.elevation }}'{% endraw %}
|
||||
friendly_name: 'Sun angle'
|
||||
friendly_name: "Sun angle"
|
||||
unit_of_measurement: 'degrees'
|
||||
value_template: "{{ states.sun.sun.attributes.elevation }}"
|
||||
|
||||
sunrise:
|
||||
value_template: {% raw %}'{{ states.sun.sun.attributes.next_rising }}'{% endraw %}
|
||||
value_template: "{{ states.sun.sun.attributes.next_rising }}"
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
Configuration variables:
|
||||
{% configuration %}
|
||||
sensors:
|
||||
description: List of your sensors.
|
||||
required: true
|
||||
type: map
|
||||
keys:
|
||||
friendly_name:
|
||||
description: Name to use in the frontend.
|
||||
required: false
|
||||
type: string
|
||||
entity_id:
|
||||
description: Add a list of entity IDs so the sensor only reacts to state changes of these entities. This will reduce the number of times the sensor will try to update its state.
|
||||
required: false
|
||||
type: string, list
|
||||
unit_of_measurement:
|
||||
description: Defines the units of measurement of the sensor, if any.
|
||||
required: false
|
||||
type: string
|
||||
value_template:
|
||||
description: Defines a template to get the state of the sensor.
|
||||
required: true
|
||||
type: template
|
||||
icon_template:
|
||||
description: Defines a template for the icon of the sensor.
|
||||
required: false
|
||||
type: template
|
||||
{% endconfiguration %}
|
||||
|
||||
- **sensors** array (*Required*): List of your sensors.
|
||||
- **friendly_name** (*Optional*): Name to use in the Frontend.
|
||||
- **unit_of_measurement** (*Optional*): Defines the units of measurement of the sensor, if any.
|
||||
- **value_template** (*Required*): Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract a value from the event bus.
|
||||
- **icon_template** (*Optional*): Defines a [template](/topics/templating/) for the icon of the sensor.
|
||||
- **entity_id** (*Optional*): Add a list of entity IDs so the sensor only reacts to state changes of these entities. This will reduce the number of times the sensor will try to update its state.
|
||||
## {% linkable_title Considerations %}
|
||||
|
||||
If you are using the state of a platform that takes extra time to load, the
|
||||
Template Sensor 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 %}
|
||||
|
||||
## {% linkable_title Examples %}
|
||||
|
||||
In this section you find some real life examples of how to use this sensor.
|
||||
|
||||
### {% linkable_title Sun angle %}
|
||||
### {% linkable_title Sun Angle %}
|
||||
|
||||
This example shows the sun angle in the frontend.
|
||||
|
||||
{% raw %}
|
||||
```yaml
|
||||
sensor:
|
||||
- platform: template
|
||||
sensors:
|
||||
solar_angle:
|
||||
value_template: {% raw %}'{{ "%+.1f"|format(states.sun.sun.attributes.elevation) }}'{% endraw %}
|
||||
friendly_name: 'Sun Angle'
|
||||
friendly_name: "Sun Angle"
|
||||
unit_of_measurement: '°'
|
||||
value_template: "{{ '%+.1f'|format(states.sun.sun.attributes.elevation) }}"
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
### {% linkable_title Renaming sensor output %}
|
||||
### {% linkable_title Renaming Sensor 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 component](/components/sun/) as a simple example:
|
||||
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 component](/components/sun/) as
|
||||
a simple example:
|
||||
|
||||
{% raw %}
|
||||
```yaml
|
||||
sensor:
|
||||
- platform: template
|
||||
sensors:
|
||||
sun_state:
|
||||
value_template: {% raw %}'{% if is_state("sun.sun", "above_horizon") %}up{% else %}down{% endif %}'{% endraw %}
|
||||
friendly_name: 'Sun state'
|
||||
friendly_name: "Sun State"
|
||||
value_template: >-
|
||||
{% if is_state('sun.sun', 'above_horizon') %}
|
||||
up
|
||||
{% else %}
|
||||
down
|
||||
{% endif %}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
Processes monitored by the [System Monitor sensor](/components/sensor.systemmonitor/) show `on` or `off` if they are running or not. This example shows how the output of a monitored `glances` process can be renamed.
|
||||
Processes monitored by the [System Monitor sensor](/components/sensor.systemmonitor/)
|
||||
show `on` or `off` if they are running or not. This example shows how the
|
||||
output of a monitored `glances` process can be renamed.
|
||||
|
||||
{% raw %}
|
||||
```yaml
|
||||
sensor:
|
||||
- platform: template
|
||||
sensors:
|
||||
glances:
|
||||
value_template: {% raw %}'{% if is_state("sensor.process_glances", "off") %}not running{% else %}running{% endif %}'{% endraw %}
|
||||
friendly_name: 'Glances'
|
||||
friendly_name: "Glances"
|
||||
value_template: >-
|
||||
{% if is_state('sensor.process_glances', 'on') %}
|
||||
running
|
||||
{% else %}
|
||||
not running
|
||||
{% endif %}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
By comparing the details published on the [template](/topics/templating/) page the same can be achieved with a different approach:
|
||||
The [Template Binary Sensor](/components/binary_sensor.template/) is the one in
|
||||
similar cases if you prefer to see an icon instead of text.
|
||||
|
||||
```yaml
|
||||
value_template: {% raw %}"{%if states.sensor.ENTITY_ID.state == 'on' %}running{%elif states.switch.ENTITY_ID.state == 'off' %}not running{% endif %}"{% endraw %}
|
||||
```
|
||||
### {% linkable_title Multiline Example With an `if` Test %}
|
||||
|
||||
The [Binary template sensor](/components/binary_sensor.template/) is the one in similar cases if you prefer to see an icon instead of text.
|
||||
|
||||
### {% linkable_title Multiline example 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.
|
||||
This example shows a multiple line template with an `if` test. It looks at a
|
||||
sensing switch and shows `on`/`off` in the frontend.
|
||||
|
||||
{% raw %}
|
||||
```yaml
|
||||
sensor:
|
||||
- platform: template
|
||||
sensors:
|
||||
kettle:
|
||||
friendly_name: 'Kettle'
|
||||
{% raw %}value_template: >-
|
||||
{%- if is_state("switch.kettle", "off") %}
|
||||
off
|
||||
{% elif states.switch.kettle.attributes.kwh < 1000 %}
|
||||
standby
|
||||
{% elif is_state("switch.kettle", "on") %}
|
||||
on
|
||||
{% else %}
|
||||
failed
|
||||
{%- endif %}{% endraw %}
|
||||
friendly_name: "Kettle"
|
||||
value_template: >-
|
||||
{% if is_state('switch.kettle', 'off') %}
|
||||
off
|
||||
{% elif states.switch.kettle.attributes.kwh|float < 1000 %}
|
||||
standby
|
||||
{% elif is_state('switch.kettle', 'on') %}
|
||||
on
|
||||
{% else %}
|
||||
failed
|
||||
{% endif %}
|
||||
|
||||
next_sensor:
|
||||
[...]
|
||||
...
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
<p class='note'>
|
||||
Please note the blank line to close the multi-line template.
|
||||
</p>
|
||||
### {% linkable_title Change The Unit of Measurement %}
|
||||
|
||||
### {% linkable_title Change the unit of measurement %}
|
||||
|
||||
With a template sensor it's easy to convert given values into others if the unit of measurement doesn't fit your needs.
|
||||
With a Template Sensor it's easy to convert given values into others if the
|
||||
unit of measurement doesn't fit your needs.
|
||||
|
||||
{% raw %}
|
||||
```yaml
|
||||
sensor:
|
||||
- platform: template
|
||||
sensors:
|
||||
transmission_down_speed_kbps:
|
||||
value_template: {% raw %}'{{ states.sensor.transmission_down_speed.state | multiply(1024) }}'{% endraw %}
|
||||
friendly_name: 'Transmission Down Speed'
|
||||
friendly_name: "Transmission Down Speed"
|
||||
unit_of_measurement: 'kB/s'
|
||||
transmission_up_speed_kbps:
|
||||
value_template: {% raw %}'{{ states.sensor.transmission_up_speed.state | multiply(1024) }}'{% endraw %}
|
||||
friendly_name: 'Transmission Up Speed'
|
||||
unit_of_measurement: 'kB/s'
|
||||
```
|
||||
value_template: "{{ states('sensor.transmission_down_speed')|float * 1024 }}"
|
||||
|
||||
### {% linkable_title Change the icon %}
|
||||
transmission_up_speed_kbps:
|
||||
friendly_name: "Transmission Up Speed"
|
||||
unit_of_measurement: 'kB/s'
|
||||
value_template: "{{ states('sensor.transmission_up_speed')|float * 1024 }}"
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
### {% linkable_title Change The Icon %}
|
||||
|
||||
This example shows how to change the icon based on the day/night cycle.
|
||||
|
||||
{% raw %}
|
||||
```yaml
|
||||
sensor:
|
||||
- platform: template
|
||||
sensors:
|
||||
day_night:
|
||||
friendly_name: 'Day/Night'
|
||||
value_template: {% raw %}'{% if is_state("sun.sun", "above_horizon") %}Day{% else %}Night{% endif %}'{% endraw %}
|
||||
icon_template: {% raw %}'{% if is_state("sun.sun", "above_horizon") %}mdi:weather-sunny{% else %}mdi:weather-night{% endif %}'{% endraw %}
|
||||
|
||||
friendly_name: "Day/Night"
|
||||
value_template: >-
|
||||
{% if is_state('sun.sun', 'above_horizon') %}
|
||||
Day
|
||||
{% else %}
|
||||
Night
|
||||
{% endif %}
|
||||
icon_template: >-
|
||||
{% if is_state('sun.sun', 'above_horizon') %}
|
||||
mdi:weather-sunny
|
||||
{% else %}
|
||||
mdi:weather-night
|
||||
{% endif %}
|
||||
```
|
||||
|
||||
{% endraw %}
|
||||
|
@ -1,7 +1,7 @@
|
||||
---
|
||||
layout: page
|
||||
title: "Template switch"
|
||||
description: "Instructions how to integrate Template switches into Home Assistant."
|
||||
title: "Template Switch"
|
||||
description: "Instructions how to integrate Template Switches into Home Assistant."
|
||||
date: 2016-02-07 07:00
|
||||
sidebar: true
|
||||
comments: false
|
||||
@ -15,116 +15,174 @@ logo: home-assistant.png
|
||||
|
||||
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.
|
||||
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. You can mark the components you have combined as `hidden` so they don't appear themselves.
|
||||
This can simplify the GUI and make it easier to write automations. You can mark
|
||||
the components you have combined as `hidden` so they don't appear themselves.
|
||||
|
||||
To enable Template switches in your installation, add the following to your `configuration.yaml` file:
|
||||
To enable Template Switches in your installation, add the following to your
|
||||
`configuration.yaml` file:
|
||||
|
||||
{% raw %}
|
||||
```yaml
|
||||
# Example configuration.yaml entry
|
||||
switch:
|
||||
- platform: template
|
||||
switches:
|
||||
skylight:
|
||||
value_template: {% raw %}"{{ is_state('sensor.skylight', 'on') }}"{% endraw %}
|
||||
value_template: "{{ is_state('sensor.skylight', 'on') }}"
|
||||
turn_on:
|
||||
service: switch.turn_on
|
||||
entity_id: switch.skylight_open
|
||||
data:
|
||||
entity_id: switch.skylight_open
|
||||
turn_off:
|
||||
service: switch.turn_on
|
||||
entity_id: switch.skylight_close
|
||||
data:
|
||||
entity_id: switch.skylight_close
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
Configuration variables:
|
||||
|
||||
- **switches** array (*Required*): List of your switches.
|
||||
- **friendly_name** (*Optional*): Name to use in the Frontend.
|
||||
- **value_template** (*Required*): Defines a [template](/topics/templating/) to set the state of the switch.
|
||||
- **turn_on** (*Required*): Defines an [action](/getting-started/automation/) to run when the switch is turned on.
|
||||
- **turn_off** (*Required*): Defines an [action](/getting-started/automation/) to run when the switch is turned off.
|
||||
- **entity_id** (*Optional*): Add a list of entity IDs so the switch only reacts to state changes of these entities. This will reduce the number of times the switch will try to update it's state.
|
||||
|
||||
{% 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
|
||||
entity_id:
|
||||
description: Add a list of entity IDs so the switch only reacts to state changes of these entities. This will reduce the number of times the switch will try to update its state.
|
||||
required: false
|
||||
type: [string, list]
|
||||
value_template:
|
||||
description: Defines a template to set the state of the switch.
|
||||
required: true
|
||||
type: template
|
||||
turn_on:
|
||||
description: Defines an action to run when the switch is turned on.
|
||||
required: true
|
||||
type: action
|
||||
turn_off:
|
||||
description: Defines an action to run when the switch is turned off.
|
||||
required: true
|
||||
type: action
|
||||
{% endconfiguration %}
|
||||
|
||||
## {% linkable_title 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 }}`{% endraw %} with this equivalent that returns true/false and never gives an unknown result:
|
||||
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 %}
|
||||
|
||||
## {% linkable_title Examples %}
|
||||
|
||||
In this section you find some real life examples of how to use this switch.
|
||||
|
||||
### {% linkable_title Copy switch %}
|
||||
### {% linkable_title Copy Switch %}
|
||||
|
||||
This example shows a switch that copies another switch.
|
||||
|
||||
{% raw %}
|
||||
```yaml
|
||||
switch:
|
||||
- platform: template
|
||||
switches:
|
||||
copy:
|
||||
value_template: {% raw %}"{{ is_state('switch.source', 'on') }}"{% endraw %}
|
||||
value_template: "{{ is_state('switch.source', 'on') }}"
|
||||
turn_on:
|
||||
service: switch.turn_on
|
||||
entity_id: switch.source
|
||||
data:
|
||||
entity_id: switch.source
|
||||
turn_off:
|
||||
service: switch.turn_off
|
||||
entity_id: switch.source
|
||||
````
|
||||
data:
|
||||
entity_id: switch.source
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
### {% linkable_title Toggle switch %}
|
||||
### {% linkable_title Toggle Switch %}
|
||||
|
||||
This example shows a switch that takes its state from a sensor, and toggles a 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: {% raw %}"{{ is_state_attr('switch.blind_toggle', 'sensor_state', 'on') }}"{% endraw %}
|
||||
friendly_name: "Blind"
|
||||
value_template: "{{ is_state_attr('switch.blind_toggle', 'sensor_state', 'on') }}"
|
||||
turn_on:
|
||||
service: switch.toggle
|
||||
entity_id: switch.blind_toggle
|
||||
data:
|
||||
entity_id: switch.blind_toggle
|
||||
turn_off:
|
||||
service: switch.toggle
|
||||
entity_id: switch.blind_toggle
|
||||
data:
|
||||
entity_id: switch.blind_toggle
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
### {% linkable_title Sensor and two switches %}
|
||||
### {% linkable_title 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.
|
||||
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: {% raw %}"{{ is_state('sensor.skylight.state', 'on') }}"{% endraw %}
|
||||
friendly_name: "Skylight"
|
||||
value_template: "{{ is_state('sensor.skylight.state', 'on') }}"
|
||||
turn_on:
|
||||
service: switch.turn_on
|
||||
entity_id: switch.skylight_open
|
||||
data:
|
||||
entity_id: switch.skylight_open
|
||||
turn_off:
|
||||
service: switch.turn_on
|
||||
entity_id: switch.skylight_close
|
||||
data:
|
||||
entity_id: switch.skylight_close
|
||||
```
|
||||
### {% linkable_title Change the icon %}
|
||||
{% endraw %}
|
||||
|
||||
### {% linkable_title Change The Icon %}
|
||||
|
||||
This example shows how to change the icon based on the day/night cycle.
|
||||
|
||||
{% raw %}
|
||||
```yaml
|
||||
switch:
|
||||
- platform: template
|
||||
switches:
|
||||
garage:
|
||||
value_template: {% raw %}"{{ is_state(cover.garage_door', 'on') }}"{% endraw %}
|
||||
value_template: "{{ is_state('cover.garage_door', 'on') }}"
|
||||
turn_on:
|
||||
service: cover.open_cover
|
||||
entity_id: cover.garage_door
|
||||
data:
|
||||
entity_id: cover.garage_door
|
||||
turn_off:
|
||||
service: cover.close_cover
|
||||
entity_id: cover.garage_door
|
||||
icon_template: {% raw %}"{% if is_state('cover.garage_door', 'open') %}mdi:garage-open{% else %}mdi:garage{% endif %}"{% endraw %}
|
||||
data:
|
||||
entity_id: cover.garage_door
|
||||
icon_template: >-
|
||||
{% if is_state('cover.garage_door', 'open') %}
|
||||
mdi:garage-open
|
||||
{% else %}
|
||||
mdi:garage
|
||||
{% endif %}
|
||||
```
|
||||
{% endraw %}
|
||||
|
Loading…
x
Reference in New Issue
Block a user