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

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