Merge pull request #597 from n8henrie/issue_1949

Combine Garage and Rollershutter Components -> Cover (home-assistant#1949)
2025-07-17 06:16:50 +00:00 · 2016-08-24 00:02:12 -07:00 · 2016-08-24 00:02:12 -07:00 · 1b99a8c3ec
commit 1b99a8c3ec
parent c8fafbba06 5602df3bba
5 changed files with 203 additions and 0 deletions
--- a/source/_components/cover.command_line.markdown
+++ b/source/_components/cover.command_line.markdown
@ -0,0 +1,56 @@
+---
+layout: page
+title: "Command Line Cover"
+description: "How to control a cover with the command line."
+date: 2016-06-28 17:30
+sidebar: true
+comments: false
+sharing: true
+footer: true
+logo: command_line.png
+ha_category: Cover
+---
+A cover platform that issues specific commands when it is moved up, down and
+stopped. It allows anyone to integrate any type of cover into Home Assistant
+that can be controlled from the command line.
+
+To enable a command line cover in your installation, add the following to your
+`configuration.yaml` file:
+
+```yaml
+# Example configuration.yaml entry
+cover:
+- platform: command_line
+  covers:
+    Garage door:
+      open_cmd: move_command up kitchen
+      close_cmd: move_command down kitchen
+      stop_cmd: move_command stop kitchen
+      state_cmd: state_command kitchen
+      value_template: {% raw %}>
+        {% if value == 'open' %}
+        100
+        {% elif value == 'closed' %}
+        0
+        {% endif %}
+        {% endraw %}
+```
+
+Configuration variables:
+
+- **covers** (*Required*): The array that contains all command line covers.
+  - **entry** (*Required*): Name of the command line cover. Multiple entries
+    are possible.
+    - **open_cmd** (*Required*): The command to open the cover.
+    - **close_cmd** (*Required*): The action to close the cover.
+    - **stop_cmd** (*Required*): The action to stop the cover.
+    - **state_cmd** (*Optional*): If given, this will act as a sensor that runs
+      in the background and updates the state of the cover. If the command
+      returns a `0` the indicates the cover is fully closed, whereas a 100
+      indicates the cover is fully open.
+    - **value_template** (*optional - default: '{% raw %}{{ value }}{% endraw
+      %}'*): if specified, `state_cmd` will ignore the result code of the
+      command but the template evaluating will indicate the position of the
+      cover. For example, if your `state_cmd` returns a string "open",
+      using `value_template` as in the example config above will allow you to
+      translate that into the valid state `100`.
--- a/source/_components/cover.markdown
+++ b/source/_components/cover.markdown
@ -0,0 +1,13 @@
+---
+layout: page
+title: "Covers"
+description: "Instructions how to integrate covers into Home Assistant."
+date: 2016-06-28 17:30
+sidebar: true
+comments: false
+sharing: true
+footer: true
+---
+
+Home Assistant can give you an interface to control covers such as
+rollershutters and garage doors.
--- a/source/_components/cover.mqtt.markdown
+++ b/source/_components/cover.mqtt.markdown
@ -0,0 +1,71 @@
+---
+layout: page
+title: "MQTT Cover"
+description: "Instructions how to integrate MQTT covers into Home Assistant."
+date: 2016-06-28 17:30
+sidebar: true
+comments: false
+sharing: true
+footer: true
+logo: mqtt.png
+ha_category: Cover
+---
+
+
+The `mqtt` cover platform enables the possibility to control an MQTT
+cover. The device state will be updated only after receiving the a new
+state from `state_topic`. If these messages are published with RETAIN flag, the
+MQTT device will receive an instant state update after subscription and will
+start with correct state. Otherwise, the initial state will be `unknown`.
+
+There is a state attribute that stores the relative position of the device,
+where 0 means the device is `closed` and all other intermediate positions
+means the device is `open`.
+
+When a state topic is not available, the switch will work in optimistic mode.
+In this mode, the switch will immediately change state after every command.
+Otherwise, the switch will wait for state confirmation from device (message
+from `state_topic`).
+
+Optimistic mode can be forced, even if state topic is available. Try to enable
+it, if experiencing incorrect switch operation.
+
+To use your MQTT binary sensor in your installation, add the following to your
+`configuration.yaml` file:
+
+```yaml
+# Example configuration.yml entry
+cover:
+  platform: mqtt
+  state_topic: "home-assistant/cover"
+  command_topic: "home-assistant/cover/set"
+  name: "MQTT Sensor"
+  optimistic: false
+  qos: 0
+  retain: true
+  state_open: "STATE_OPEN"
+  state_closed: "STATE_CLOSED"
+  service_open: "SERVICE_OPEN"
+  service_close: "SERVICE_CLOSE"
+  value_template: '{% raw %}{{ value.x }}{% endraw %}'
+```
+
+Configuration variables:
+
+- **state_topic** (*Required*): The MQTT topic subscribed to receive sensor values.
+- **name** (*Optional*): The name of the sensor. Default is 'MQTT Sensor'. 
+- **state_open** (*Optional*): The payload that represents open state. Default is"STATE_OPEN"
+- **state_closed** (*Optional*): The payload that represents closed state. Default is "STATE_CLOSED"
+- **service_open** (*Optional*):  The payload that represents open state in service mode. Default is"SERVICE_OPEN"
+- **service_close** (*Optional*): The payload that represents closed state in service mode. Default is "SERVICE_CLOSE"
+- **optimistic** (*Optional*): Flag that defines if switch works in optimistic mode. Default is true if no state topic defined, else false.
+- **qos** (*Optional*): The maximum QoS level of the state topic. Default is 0 and will also be used to publishing messages.
+- **retain** (*Optional*): If the published message should have the retain flag on or not.
+- **value_template** (*Optional*): Defines a [template](/topics/templating/) to extract a value from the payload.
+
+For a quick check you can use the commandline tools shipped with `mosquitto` to send MQTT messages. Set the state of your sensor manually:
+
+```bash
+$  mosquitto_pub -h 127.0.0.1 -t home-assistant/cover/set -m "OFF"
+```
+
--- a/source/_components/cover.scsgate.markdown
+++ b/source/_components/cover.scsgate.markdown
@ -0,0 +1,35 @@
+---
+layout: page
+title: "SCSGate Cover"
+description: "Instructions how to integrate SCSGate motorized devices into Home Assistant."
+date: 2016-06-28 17:30
+sidebar: true
+comments: false
+sharing: true
+footer: true
+logo: bus_scs.png
+ha_category: Cover
+---
+The SCSGate devices can control motorized covers connected to the BTicino
+MyHome system.
+
+To enable SCSGate covers in your installation, add the following to your
+`configuration.yaml` file:
+
+```yaml
+# Example configuration.yaml entry
+cover:
+  platform: scsgate
+  devices:
+    living_room:
+      name: Living Room
+      scs_id: XXXXX
+```
+
+Configuration variables:
+
+- **devices** (*Required*): A list of devices with their name to use in the
+  frontend.
+
+**Known limitation:** it is not possible to know the current state of the
+cover.
--- a/source/_components/cover.wink.markdown
+++ b/source/_components/cover.wink.markdown
@ -0,0 +1,28 @@
+---
+layout: page
+title: "Wink Cover"
+description: "Instructions how to setup the Wink garage doors within Home Assistant."
+date: 2016-06-28 17:30
+sidebar: true
+comments: false
+sharing: true
+footer: true
+logo: wink.png
+ha_category: Cover
+---
+
+Wink cover / garage door functionality is currently limited to view only. Wink
+garage doors will still show the current state of the door, but control has
+been disabled for third parties. If you have a Chamberlain garage door, and
+would like to control it via Home Assistant, please contact Chamberlain and
+request that they re-enabled third-party control.
+
+The following quote is from Wink.
+
+> As part of our agreement with Chamberlain, third-party access to control
+  Chamberlain garage doors has been restricted. Please contact Chamberlain
+  directly to inquire about permissions.
+
+~~The Wink garage door platform allows you to control your [Wink](http://www.wink.com/) enabled garage door.~~
+
+The requirement is that you have setup your [Wink hub](/components/wink/).