From 6ec17327ae6165730db4f79a51eb631d62d910d3 Mon Sep 17 00:00:00 2001
From: Luuk <luukd@users.noreply.github.com>
Date: Fri, 28 Jun 2019 21:40:42 +0200
Subject: [PATCH] Add Template vacuum documentation (#9496)

* Add documentation for template vacuum component

* Remove optional configuration items from example

* Added more example configurations

* Update template_vacuum version and date

* Update source/_components/vacuum.template.markdown

Co-Authored-By: Klaas Schoute <klaas_schoute@hotmail.com>

* :pencil2: Tweaks

* :arrow_up: ha_release 0.96
---
 source/_components/vacuum.template.markdown | 153 ++++++++++++++++++++
 1 file changed, 153 insertions(+)
 create mode 100644 source/_components/vacuum.template.markdown

diff --git a/source/_components/vacuum.template.markdown b/source/_components/vacuum.template.markdown
new file mode 100644
index 00000000000..f327654fe4e
--- /dev/null
+++ b/source/_components/vacuum.template.markdown
@@ -0,0 +1,153 @@
+---
+layout: page
+title: "Template Vacuum"
+description: "Instructions how to setup Template vacuums within Home Assistant."
+date: 2019-05-20 16:00
+sidebar: true
+comments: false
+sharing: true
+footer: true
+ha_category: Vacuum
+ha_release: 0.96
+ha_iot_class: Local Push
+logo: home-assistant.png
+ha_qa_scale: internal
+---
+
+The `template` platform creates vacuums that combine integrations and provides the
+ability to run scripts or invoke services for each of the start, pause, stop,
+return_to_base, clean_spot, locate and set_fan_speed commands of a vacuum.
+
+To enable Template Vacuums in your installation, add the following to your
+`configuration.yaml` file:
+
+```yaml
+# Example configuration.yaml entry
+vacuum:
+  - platform: template
+    vacuums:
+      living_room_vacuum:
+        start:
+            service: script.vacuum_start
+```
+
+{% configuration %}
+  vacuums:
+    description: List of your vacuums.
+    required: true
+    type: map
+    keys:
+      friendly_name:
+        description: Name to use in the frontend.
+        required: false
+        type: string
+      value_template:
+        description: "Defines a template to get the state of the vacuum. Valid value: `docked`/`cleaning`/`idle`/`paused`/`returning`/`error`"
+        required: false
+        type: template
+      battery_level_template:
+        description: "Defines a template to get the battery level of the vacuum. Legal values are numbers between `0` and `100`."
+        required: false
+        type: template
+      fan_speed_template:
+        description: Defines a template to get the fan speed of the vacuum.
+        required: false
+        type: template
+      start:
+        description: Defines an action to run when the vacuum is started.
+        required: true
+        type: action
+      pause:
+        description: Defines an action to run when the vacuum is paused.
+        required: false
+        type: action
+      stop:
+        description: Defines an action to run when the vacuum is stopped.
+        required: false
+        type: action
+      return_to_base:
+        description: Defines an action to run when the vacuum is given a return to base command.
+        required: false
+        type: action
+      clean_spot:
+        description: Defines an action to run when the vacuum is given a clean spot command.
+        required: false
+        type: action
+      locate:
+        description: Defines an action to run when the vacuum is given a locate command.
+        required: false
+        type: action
+      set_fan_speed:
+        description: Defines an action to run when the vacuum is given a command to set the fan speed.
+        required: false
+        type: action
+      fan_speeds:
+        description: List of fan speeds supported by the vacuum.
+        required: false
+        type: string list
+{% endconfiguration %}
+
+## {% linkable_title Examples %}
+
+### {% linkable_title Control vacuum with Harmony Hub %}
+
+This example shows how you can use a Template Vacuum to control an IR vacuum cleaner using the [Harmony Hub Remote component](/components/remote.harmony/).
+
+```yaml
+vacuum:
+  - platform: template
+    vacuums:
+      living_room_vacuum:
+        start:
+          - service: remote.send_command
+            data:
+              entity_id: remote.harmony_hub
+              command: Clean
+              device: 52840686
+        return_to_base:
+          - service: remote.send_command
+            data:
+              entity_id: remote.harmony_hub
+              command: Home
+              device: 52840686
+        clean_spot:
+          - service: remote.send_command
+            data:
+              entity_id: remote.harmony_hub
+              command: SpotCleaning
+              device: 52840686
+```
+
+### {% linkable_title Vacuum with state %}
+
+This example shows how to use templates to specify the state of the vacuum.
+
+{% raw %}
+```yaml
+vacuum:
+  - platform: template
+    vacuums:
+      living_room_vacuum:
+        value_template: "{{ states('sensor.vacuum_state') }}"
+        battery_level_template: "{{ states('sensor.vacuum_battery_level')|int }}"
+        fan_speed_template: "{{ states('sensor.vacuum_fan_speed') }}"
+        start:
+            service: script.vacuum_start
+        pause:
+            service: script.vacuum_pause
+        stop:
+            service: script.vacuum_stop
+        return_to_base:
+            service: script.vacuum_return_to_base
+        clean_spot:
+            service: script.vacuum_clean_spot
+        locate:
+            service: script.vacuum_locate_vacuum
+        set_fan_speed:
+            service: script.vacuum_set_fan_speed
+        fan_speeds:
+            - Low
+            - Medium
+            - High
+```
+{% endraw %}