jeans/home-assistant.io
jeans/home-assistant.io
1
0
Fork 0
mirror of https://github.com/home-assistant/home-assistant.io.git synced 2025-07-23 17:27:19 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add Jekyll plugin for Configuration Variables (#3415)

Browse Source 
* 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:
Dale Higgs 2017-09-22 19:51:02 -05:00 committed by Paulus Schoutsen
parent eb2e547237
commit 2676c87abe
7 changed files with 727 additions and 267 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

114
plugins/configuration.rb Normal file
View 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)

65
sass/custom/_paulus.scss
View File

@ -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 {
@ -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;
}
}
}
}

161
source/_components/binary_sensor.template.markdown
View File

@ -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 %}
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
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 %}

190
source/_components/cover.template.markdown
View File

@ -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
data:
entity_id: switch.garage_door
close_cover:
service: switch.turn_off
data:
entity_id: switch.garage_door
stop_cover:
service: switch.turn_on
data:
entity_id: switch.garage_door
icon_template: "{% if not is_state('sensor.garage_door', 'on') %}mdi:garage-open{% else %}mdi:garage{% endif %}"{% endraw %}
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:
@ -108,20 +188,13 @@ cover:
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: >
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
- service: cover.set_cover_position
data:
entity_id: cover.all_covers
data_template:
position: 25{% endraw %}
position: 25
```
{% endraw %}

115
source/_components/light.template.markdown
View File

@ -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 -%}
{% if is_state('media_player.receiver', 'on') %}
{% if states.media_player.receiver.attributes.is_volume_muted %}
off
{%- else -%}
{% else %}
on
{%- endif -%}
{%- else -%}
{% 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 %}

179
source/_components/sensor.template.markdown
View File

@ -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") %}
friendly_name: "Kettle"
value_template: >-
{% if is_state('switch.kettle', 'off') %}
off
{% elif states.switch.kettle.attributes.kwh < 1000 %}
{% elif states.switch.kettle.attributes.kwh|float < 1000 %}
standby
{% elif is_state("switch.kettle", "on") %}
{% elif is_state('switch.kettle', 'on') %}
on
{% else %}
failed
{%- endif %}{% endraw %}
{% 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 %}

118
source/_components/switch.template.markdown
View File

@ -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
data:
entity_id: switch.skylight_open
turn_off:
service: switch.turn_on
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
data:
entity_id: switch.source
turn_off:
service: switch.turn_off
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
data:
entity_id: switch.blind_toggle
turn_off:
service: switch.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
data:
entity_id: switch.skylight_open
turn_off:
service: switch.turn_on
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
data:
entity_id: cover.garage_door
turn_off:
service: cover.close_cover
data:
entity_id: cover.garage_door
icon_template: {% raw %}"{% if is_state('cover.garage_door', 'open') %}mdi:garage-open{% else %}mdi:garage{% endif %}"{% endraw %}
icon_template: >-
{% if is_state('cover.garage_door', 'open') %}
mdi:garage-open
{% else %}
mdi:garage
{% endif %}
```
{% endraw %}