From a1afaf1bcb88dddaedac2a06b35667665c04555c Mon Sep 17 00:00:00 2001 From: Brian Cribbs Date: Thu, 18 May 2017 23:45:39 -0400 Subject: [PATCH 1/6] creating docs for light template platform --- source/_components/light.template.markdown | 81 ++++++++++++++++++++++ 1 file changed, 81 insertions(+) create mode 100755 source/_components/light.template.markdown diff --git a/source/_components/light.template.markdown b/source/_components/light.template.markdown new file mode 100755 index 000000000000..039a419a2dc1 --- /dev/null +++ b/source/_components/light.template.markdown @@ -0,0 +1,81 @@ +--- +layout: page +title: "Template Light" +description: "Instructions how to integrate Template lights into Home Assistant." +date: 2016-05-18 20:32 +sidebar: true +comments: false +sharing: true +footer: true +ha_category: Light +ha_release: 0.46 +ha_iot_class: "Local Push" +logo: home-assistant.png +--- + +The `template` platform creates lights that combine 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. If your garage door also has the ability to where you can set its position, you can bind the `set_level` command to a script or service and capture the brightness variable and manipulate it before sending it to your script or service. + +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 lights in your installation, add the following to your `configuration.yaml` file: + +```yaml +# Example configuration.yaml entry +light: + - platform: template + lights: + theater_volume: + friendly_name: 'Receiver Volume' + value_template: >- + {%- if is_state("media_player.receiver", "on") -%} + {%- if states.media_player.receiver.attributes.is_volume_muted -%} + off + {%- else -%} + on + {%- endif -%} + {%- else -%} + off + {%- endif -%} + turn_on: + service: media_player.volume_mute + data: + entity_id: media_player.receiver + is_volume_muted: false + turn_off: + service: media_player.volume_mute + data: + entity_id: media_player.receiver + is_volume_muted: true + set_level: + service: media_player.volume_set + data: + entity_id: media_player.receiver + data_template: + volume_level: '{{((brightness / 255 * 100) | int)/100}}' + level_template: >- + {%- if is_state("media_player.receiver", "on") -%} + {{(255 * states.media_player.receiver.attributes.volume_level) | int}} + {%- else -%} + 0 + {%- endif -%} + +``` + +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. + + +## {% 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 %} + From 7fb8bff81b0b68fdaf0aa12a827035dfd379ee83 Mon Sep 17 00:00:00 2001 From: Brian Cribbs Date: Fri, 19 May 2017 09:45:28 -0400 Subject: [PATCH 2/6] escaping templates --- source/_components/light.template.markdown | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/source/_components/light.template.markdown b/source/_components/light.template.markdown index 039a419a2dc1..03c74ec25a10 100755 --- a/source/_components/light.template.markdown +++ b/source/_components/light.template.markdown @@ -29,6 +29,7 @@ light: theater_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 @@ -38,6 +39,7 @@ light: {%- else -%} off {%- endif -%} + {% endraw %} turn_on: service: media_player.volume_mute data: @@ -53,14 +55,15 @@ light: data: entity_id: media_player.receiver data_template: - volume_level: '{{((brightness / 255 * 100) | int)/100}}' + volume_level: '{% raw %}{{((brightness / 255 * 100) | int)/100}}{% endraw %}' level_template: >- + {% raw %} {%- if is_state("media_player.receiver", "on") -%} {{(255 * states.media_player.receiver.attributes.volume_level) | int}} {%- else -%} 0 {%- endif -%} - + {% endraw %} ``` Configuration variables: From 7c9a8d659886b0f4c8104c2adfe5c604594a0c08 Mon Sep 17 00:00:00 2001 From: Brian Cribbs Date: Fri, 19 May 2017 15:39:40 -0400 Subject: [PATCH 3/6] updating docs with a more simple example --- source/_components/light.template.markdown | 73 ++++++++++++++-------- 1 file changed, 48 insertions(+), 25 deletions(-) diff --git a/source/_components/light.template.markdown b/source/_components/light.template.markdown index 03c74ec25a10..274db571100d 100755 --- a/source/_components/light.template.markdown +++ b/source/_components/light.template.markdown @@ -15,21 +15,61 @@ logo: home-assistant.png The `template` platform creates lights that combine 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. If your garage door also has the ability to where you can set its position, you can bind the `set_level` command to a script or service and capture the brightness variable and manipulate it before sending it to your script or service. +This provides pretty much the same functionality as a [template switch](/components/switch.template/) with the exception is that you can pass brightness commands through. -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. +You can run scripts or invoke services for each of the 3 commands: on/off/level To enable Template lights in your installation, add the following to your `configuration.yaml` file: ```yaml # Example configuration.yaml entry +light: + - platform: template + lights: + theater_volume: + friendly_name: "Theater Lights" + value_template: "{% raw %}{{is_state('sensor.theater_brightness.attributes.lux > 0'}}{% endraw %}" + turn_on: + service: script.theater_lights_on + turn_off: + service: script.theater_lights_off + set_level: + service: script.theater_lights_level + data_template: + volume_level: "{% raw %}{{brightness}}{% endraw %}" + level_template: "{% raw %}{{is_state('sensor.theater_brightness.attributes.lux'}}{% 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. + + +## {% 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 %} + +## {% linkable_title Examples %} + +## {% linkable_title Theater Volume Control %} + +You can even control things that aren't lights! 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 + +```yaml light: - platform: template lights: theater_volume: friendly_name: 'Receiver Volume' value_template: >- - {% raw %} + {% raw %} {%- if is_state("media_player.receiver", "on") -%} {%- if states.media_player.receiver.attributes.is_volume_muted -%} off @@ -39,7 +79,7 @@ light: {%- else -%} off {%- endif -%} - {% endraw %} + {% endraw %} turn_on: service: media_player.volume_mute data: @@ -55,30 +95,13 @@ light: data: entity_id: media_player.receiver data_template: - volume_level: '{% raw %}{{((brightness / 255 * 100) | int)/100}}{% endraw %}' + volume_level: '{% raw %}{{((brightness / 255 * 100) | int)/100}}{% endraw %}' level_template: >- - {% raw %} + {% raw %} {%- if is_state("media_player.receiver", "on") -%} {{(255 * states.media_player.receiver.attributes.volume_level) | int}} {%- else -%} 0 {%- endif -%} - {% 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. - - -## {% 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 %} - + {% endraw %} +``` \ No newline at end of file From 3c71c8b6f6bf3e4409ec13946848e82662fac8fe Mon Sep 17 00:00:00 2001 From: Brian Cribbs Date: Fri, 19 May 2017 15:56:34 -0400 Subject: [PATCH 4/6] updating example text --- source/_components/light.template.markdown | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/source/_components/light.template.markdown b/source/_components/light.template.markdown index 274db571100d..dc5c3022a1ac 100755 --- a/source/_components/light.template.markdown +++ b/source/_components/light.template.markdown @@ -58,9 +58,11 @@ If you are using the state of a platform that takes extra time to load, the temp ## {% linkable_title Examples %} -## {% linkable_title Theater Volume Control %} +In this section you will find some real life examples of how to use this light. -You can even control things that aren't lights! 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 +### {% 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 ```yaml light: From c125f89c8abc501352a78b9227bcd644635a43f9 Mon Sep 17 00:00:00 2001 From: Brian Cribbs Date: Mon, 22 May 2017 11:16:50 -0400 Subject: [PATCH 5/6] making descrption more standalone --- source/_components/light.template.markdown | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/source/_components/light.template.markdown b/source/_components/light.template.markdown index dc5c3022a1ac..b1c6e4eb6cab 100755 --- a/source/_components/light.template.markdown +++ b/source/_components/light.template.markdown @@ -13,11 +13,7 @@ ha_iot_class: "Local Push" logo: home-assistant.png --- -The `template` platform creates lights that combine components. - -This provides pretty much the same functionality as a [template switch](/components/switch.template/) with the exception is that you can pass brightness commands through. - -You can run scripts or invoke services for each of the 3 commands: on/off/level +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: From 9f32bc65654e8ce5cc34d6aecc24a7a1eb629e04 Mon Sep 17 00:00:00 2001 From: Brian Cribbs Date: Wed, 24 May 2017 14:30:27 -0400 Subject: [PATCH 6/6] updating docs to include missing field and make example name more inline with actual example --- source/_components/light.template.markdown | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/source/_components/light.template.markdown b/source/_components/light.template.markdown index b1c6e4eb6cab..08ab8cdb4095 100755 --- a/source/_components/light.template.markdown +++ b/source/_components/light.template.markdown @@ -22,7 +22,7 @@ To enable Template lights in your installation, add the following to your `confi light: - platform: template lights: - theater_volume: + theater_lights: friendly_name: "Theater Lights" value_template: "{% raw %}{{is_state('sensor.theater_brightness.attributes.lux > 0'}}{% endraw %}" turn_on: @@ -45,6 +45,7 @@ Configuration variables: - **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. ## {% linkable_title Considerations %}