From 5602df3bba8d5f52b98083e502f5c01fa0cf7b1c Mon Sep 17 00:00:00 2001 From: Nathan Henrie Date: Tue, 28 Jun 2016 18:06:36 -0600 Subject: [PATCH] Copy rollershutter and garage_door docs to cover Re: home-assistant/home-assistant#1949 --- .../_components/cover.command_line.markdown | 56 +++++++++++++++ source/_components/cover.markdown | 13 ++++ source/_components/cover.mqtt.markdown | 71 +++++++++++++++++++ source/_components/cover.scsgate.markdown | 35 +++++++++ source/_components/cover.wink.markdown | 28 ++++++++ 5 files changed, 203 insertions(+) create mode 100644 source/_components/cover.command_line.markdown create mode 100644 source/_components/cover.markdown create mode 100644 source/_components/cover.mqtt.markdown create mode 100644 source/_components/cover.scsgate.markdown create mode 100644 source/_components/cover.wink.markdown diff --git a/source/_components/cover.command_line.markdown b/source/_components/cover.command_line.markdown new file mode 100644 index 00000000000..23778344f76 --- /dev/null +++ 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`. diff --git a/source/_components/cover.markdown b/source/_components/cover.markdown new file mode 100644 index 00000000000..4dab26c9d2f --- /dev/null +++ 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. diff --git a/source/_components/cover.mqtt.markdown b/source/_components/cover.mqtt.markdown new file mode 100644 index 00000000000..2275b83e082 --- /dev/null +++ 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" +``` + diff --git a/source/_components/cover.scsgate.markdown b/source/_components/cover.scsgate.markdown new file mode 100644 index 00000000000..7d8542f5b64 --- /dev/null +++ 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. diff --git a/source/_components/cover.wink.markdown b/source/_components/cover.wink.markdown new file mode 100644 index 00000000000..be2c0394605 --- /dev/null +++ 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/).