From 9e5887dac0ad334e45347779b1e1faa4c29f0c8f Mon Sep 17 00:00:00 2001
From: Teemu R <tpr@iki.fi>
Date: Fri, 22 Feb 2019 17:12:30 +0100
Subject: [PATCH] Add documentation for TP-Link Smart Home devices (#7338)

* Update tplink documentation

* Make configuration linkable, add documentation for list elements

* :pencil2: Tweaks

* Add KL series of bulbs from #8134

* Add LB230 from #8090

* Add extracting energy sensor data from the switch platform

* fix indent

* add 0.89 for version

* re-add HS103
---
 source/_components/tplink.markdown          | 133 ++++++++++++++++++++
 source/_docs/configuration/devices.markdown |   5 +-
 2 files changed, 134 insertions(+), 4 deletions(-)
 create mode 100644 source/_components/tplink.markdown

diff --git a/source/_components/tplink.markdown b/source/_components/tplink.markdown
new file mode 100644
index 00000000000..e32f37d9ec4
--- /dev/null
+++ b/source/_components/tplink.markdown
@@ -0,0 +1,133 @@
+---
+layout: page
+title: "TP-Link Smart Home Devices"
+description: "Instructions on integrating TP-Link Smart Home Devices to Home Assistant."
+date: 2018-09-12 13:00
+sidebar: true
+comments: false
+sharing: true
+footer: true
+logo: tp-link.png
+ha_category: Hub
+featured: false
+ha_release: 0.89
+ha_iot_class: "Local Polling"
+redirect_from:
+  - /components/switch.tplink/
+  - /components/light.tplink/
+---
+
+The `tplink` component allows you to control your [TP-Link Smart Home Devices](https://www.tp-link.com/kasa-smart/) such as smart plugs and smart bulbs.
+
+In order to activate the support, you will have to enable the integration inside the config panel.
+The supported devices in your network are automatically discovered, but if you want to control devices residing in other networks you will need to configure them manually as shown below.
+
+## {% linkable_title Supported Devices %}
+
+This component supports devices that are controllable with the [KASA app](https://www.tp-link.com/us/kasa-smart/kasa.html).
+The following devices are known to work with this component.
+
+### {% linkable_title Plugs %}
+
+- HS100
+- HS103
+- HS105
+- HS110
+
+### {% linkable_title Wall Switches %}
+
+- HS200
+- HS210
+- HS220 (acts as a light)
+
+### {% linkable_title Bulbs %}
+
+- LB100
+- LB110
+- LB120
+- LB130
+- LB230
+- KL110
+- KL120
+- KL130
+
+## {% linkable_title Configuration %}
+
+```yaml
+# Example configuration.yaml
+tplink:
+```
+
+{% configuration %}
+discovery:
+  description: Whether to do automatic discovery of devices.
+  required: false
+  type: boolean
+  default: true
+light:
+  description: List of light devices.
+  required: false
+  type: list
+  keys:
+    host:
+      description: Hostname or IP address of the device.
+      required: true
+      type: string
+switch:
+  description: List of switch devices.
+  required: false
+  type: list
+  keys:
+    host:
+      description: Hostname or IP address of the device.
+      required: true
+      type: string
+{% endconfiguration %}
+
+## {% linkable_title Manual configuration example %}
+
+```yaml
+# Example configuration.yaml entry with manually specified addresses
+tplink:
+  discovery: false
+  light:
+    - host: 192.168.200.1
+    - host: 192.168.200.2
+  switch:
+    - host: 192.168.200.3
+    - host: 192.168.200.4
+```
+
+## {% linkable_title Extracting Energy Sensor data %}
+
+In order to get the power consumption readings from supported devices, you'll have to create a [template sensor](/components/switch.template/).
+In the example below, change all of the `my_tp_switch`'s to match your device's entity ID.
+
+{% raw %}
+```yaml
+sensor:
+  - platform: template
+    sensors:
+      my_tp_switch_amps:
+        friendly_name_template: "{{ states.switch.my_tp_switch.name}} Current"
+        value_template: '{{ states.switch.my_tp_switch.attributes["current_a"] | float }}'
+        unit_of_measurement: 'A'
+      my_tp_switch_watts:
+        friendly_name_template: "{{ states.switch.my_tp_switch.name}} Current Consumption"
+        value_template: '{{ states.switch.my_tp_switch.attributes["current_power_w"] | float }}'
+        unit_of_measurement: 'W'
+      my_tp_switch_total_kwh:
+        friendly_name_template: "{{ states.switch.my_tp_switch.name}} Total Consumption"
+        value_template: '{{ states.switch.my_tp_switch.attributes["total_energy_kwh"] | float }}'
+        unit_of_measurement: 'kWh'
+      my_tp_switch_volts:
+        friendly_name_template: "{{ states.switch.my_tp_switch.name}} Voltage"
+        value_template: '{{ states.switch.my_tp_switch.attributes["voltage"] | float }}'
+        unit_of_measurement: 'V'
+      my_tp_switch_today_kwh:
+        friendly_name_template: "{{ states.switch.my_tp_switch.name}} Today's Consumption"
+        value_template: '{{ states.switch.my_tp_switch.attributes["today_energy_kwh"] | float }}'
+        unit_of_measurement: 'kWh'
+```
+{% endraw %}
+
diff --git a/source/_docs/configuration/devices.markdown b/source/_docs/configuration/devices.markdown
index 6aedad89483..61b2213feda 100644
--- a/source/_docs/configuration/devices.markdown
+++ b/source/_docs/configuration/devices.markdown
@@ -37,8 +37,6 @@ sensor:
 
 switch:
   - platform: vera
-  - platform: tplink
-    host: IP_ADDRESS
 ```
 
 ## {% linkable_title Style 2: List each device separately %}
@@ -65,8 +63,7 @@ switch 1:
   platform: vera
 
 switch 2:
-  platform: tplink
-  host: IP_ADDRESS
+  platform: vera
 ```
 
 ## {% linkable_title Grouping devices %}