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

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