jeena/home-assistant.github.io
1
0
Fork 0
Code Issues Pull requests Projects Packages Wiki Activity Actions

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
Download patch file Download diff file Expand all files Collapse all files

189
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") %}
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 %}