Add Xiaomi docs for platforms (#3045)

* Add Xiaomi docs for platforms

* Add service details

* Add Aqara Wireless Switch

* Escape templates

* Update 'ha_iot_class'

source/_components/binary_sensor.xiaomi.markdown

@@ -1,20 +1,25 @@
 ---
 layout: page
-title: "Xiaomi Binary sensors”
+title: "Xiaomi Binary Sensor"
-description: "Instructions how to integrate your Xiaomi Binary sensors within Home Assistant."
+description: "Instructions how to setup the Xiaomi binary sensors within Home Assistant."
 date: 2017-07-21 16:34
 sidebar: true
 comments: false
 sharing: true
 footer: true
 logo: xiaomi.png
-ha_category: Binary sensor
+ha_category: Binary Sensor
 ha_release: "0.50"
+ha_iot_class: "Local Polling"
 ---
 
-To get your Xiaomi binary sensors working with Home Assistant, follow the instructions for the general [Xiaomi Gateway component](/components/xiaomi/)
 
-### Type of sensors supported:
+The `xiaomi` binary sensor platform allows you to get data from your [Xiaomi](http://www.mi.com/en/) binary sensors.
+
+The requirement is that you have setup the [`xiaomi` component](/components/xiaomi/).
+
+
+### {% linkable_title Type of sensors supported %}
 - Motion
 - Door / Window
 - Smoke
@@ -22,11 +27,11 @@ To get your Xiaomi binary sensors working with Home Assistant, follow the instru
 - Xiaomi Wireless Button
 - Xiaomi Cube
 
-### Some automation examples to get you started:
+### {% linkable_title Automation examples %}
-- Motion
-```yaml
-    # Trigger for motion sensor
 
+#### {% linkable_title Motion %}
+
+```yaml
 - alias: If there is motion and its dark turn on the gateway light
   trigger:
     platform: state
@@ -42,7 +47,6 @@ To get your Xiaomi binary sensors working with Home Assistant, follow the instru
     entity_id: light.gateway_light_34ce00xxxx11
     data:
       brightness: 5
-
 - alias: If there no motion for 5 minutes turn off the gateway light
   trigger:
     platform: state
@@ -56,10 +60,9 @@ To get your Xiaomi binary sensors working with Home Assistant, follow the instru
     entity_id: light.gateway_light_34ce00xxxx11
 ```
   
-- Door / Window
+#### {% linkable_title Door and/or Window %}
- ```yaml
-    # Trigger for door window sensor
 
+```yaml
 - alias: If the window is open turn off the radiator
   trigger:
     platform: state
@@ -71,7 +74,6 @@ To get your Xiaomi binary sensors working with Home Assistant, follow the instru
     entity_id: climate.livingroom
     data:
       operation_mode: 'Off'
-
 - alias: If the window is closed for 5 minutes turn on the radiator again
   trigger:
     platform: state
@@ -86,10 +88,10 @@ To get your Xiaomi binary sensors working with Home Assistant, follow the instru
     data:
       operation_mode: 'Smart schedule'
 ```
-- Smoke
-  ```yaml
-    # Trigger for smoke sensor
 
+#### {% linkable_title Smoke %}
+
+```yaml
 - alias: Send notification on fire alarm
   trigger:
     platform: state
@@ -107,10 +109,10 @@ To get your Xiaomi binary sensors working with Home Assistant, follow the instru
         ringtone_id: 2
         ringtone_vol: 100
 ```
-- Gas
-```yaml
-    # Trigger for natgas detected
 
+#### {% linkable_title Gas %}
+
+```yaml
 - alias: Send notification on gas alarm
   trigger:
     platform: state
@@ -121,12 +123,14 @@ To get your Xiaomi binary sensors working with Home Assistant, follow the instru
     - service: notify.html5
       data_template:
         title: Gas alarm!
-            message: 'Gas with a density of {{ states.binary_sensor.natgas_sensor_158dxxxxxxxxxx.attributes.density }} detected.'
+        message: 'Gas with a density of {% raw %}{{ states.binary_sensor.natgas_sensor_158dxxxxxxxxxx.attributes.density }}{% endraw %} detected.'
 ```
-- Xiaomi Wireless Button (available events are `single`, `double`, `hold`, `long_click_press` and `long_click_release`). For Square version (Aqara brand) only `single` and `double` events are supported. Furthermore the space between two clicks to generate a double click must be quite large now
-```yaml
-    # Trigger for the wireless button with different click types
 
+#### {% linkable_title Xiaomi Wireless Button %}
+
+Available events are `single`, `double`, `hold`, `long_click_press` and `long_click_release`. For Square version (Aqara brand) only `single` and `double` events are supported. Furthermore the space between two clicks to generate a double click must be quite large now.
+
+```yaml
 - alias: Toggle dining light on single press
   trigger:
     platform: event
@@ -137,7 +141,6 @@ To get your Xiaomi binary sensors working with Home Assistant, follow the instru
   action:
     service: switch.toggle
     entity_id: switch.wall_switch_left_158d000xxxxx01
-
 - alias: Toggle couch light on double click
   trigger:
     platform: event
@@ -148,7 +151,6 @@ To get your Xiaomi binary sensors working with Home Assistant, follow the instru
   action:
     service: switch.toggle
     entity_id: switch.wall_switch_right_158d000xxxxx01
-
 - alias: Let a dog bark on long press
   trigger:
     platform: event
@@ -164,10 +166,11 @@ To get your Xiaomi binary sensors working with Home Assistant, follow the instru
       ringtone_vol: 8
 ```
 
-- Xiaomi Cube (available events are `flip90`, `flip180`, `move`, `tap_twice`, `shake_air`, `swing`, `alert`, `free_fall` and `rotate`).
+#### {% linkable_title Xiaomi Cube %}
-```yaml
-    # Trigger for a few cube events
 
+Available events are `flip90`, `flip180`, `move`, `tap_twice`, `shake_air`, `swing`, `alert`, `free_fall` and `rotate`.
+
+```yaml
 - alias: Cube event flip90
   trigger:
     platform: event
@@ -180,7 +183,6 @@ To get your Xiaomi binary sensors working with Home Assistant, follow the instru
       entity_id: light.gateway_light_28xxxxxxxxxx
       data:
         color_name: "springgreen"
-                                                                                                                                                                                                       
 - alias: Cube event flip180
   trigger:
     platform: event
@@ -193,7 +195,6 @@ To get your Xiaomi binary sensors working with Home Assistant, follow the instru
       entity_id: light.gateway_light_28xxxxxxxxxx
       data:
         color_name: "darkviolet"
-                                                                                                                                                                                                       
 - alias: Cube event move
   trigger:
     platform: event                            
@@ -206,7 +207,6 @@ To get your Xiaomi binary sensors working with Home Assistant, follow the instru
       entity_id: light.gateway_light_28xxxxxxxxxx
       data:
         color_name: "gold"
-                                                                                                                                                                                                       
 - alias: Cube event tap_twice
   trigger:
     platform: event
@@ -219,7 +219,6 @@ To get your Xiaomi binary sensors working with Home Assistant, follow the instru
       entity_id: light.gateway_light_28xxxxxxxxxx
       data:
         color_name: "deepskyblue"
-    
 - alias: Cube event shake_air
   trigger:
     platform: event
@@ -233,3 +232,63 @@ To get your Xiaomi binary sensors working with Home Assistant, follow the instru
       data:
         color_name: "blue"
 ```
+#### #### {% linkable_title Aqara Wireless Switch %}
+
+The Aqara Wireless Switch is available as single-key and double-key version. Each key behaves like the Wireless Button limited to the click event `single`. The double key version adds a third device called `binary_sensor.wall_switch_both_158xxxxxxxxx12` which reports a click event called `both` if both keys are pressed.
+
+```yaml
+- alias: Decrease brightness of the gateway light
+  trigger:
+    platform: event
+    event_type: click
+    event_data:
+      entity_id: binary_sensor.wall_switch_left_158xxxxxxxxx12
+      click_type: single
+  action:
+    service: light.turn_on
+    entity_id: light.gateway_light_34xxxxxxxx13
+    data_template:
+      brightness: {% raw %}>-
+        {% if states.light.gateway_light_34xxxxxxxx13.attributes.brightness %}
+          {% if states.light.gateway_light_34xxxxxxxx13.attributes.brightness - 60 >= 10 %}
+            {{states.light.gateway_light_34xxxxxxxx13.attributes.brightness - 60}}
+          {% else %}
+            {{states.light.gateway_light_34xxxxxxxx13.attributes.brightness}}
+          {% endif %}
+        {% else %}
+          10
+        {% endif %}{% endraw %}
+
+- alias: Increase brightness of the gateway light
+  trigger:
+    platform: event
+    event_type: click
+    event_data:
+      entity_id: binary_sensor.wall_switch_right_158xxxxxxxxx12
+      click_type: single
+  action:
+    service: light.turn_on
+    entity_id: light.gateway_light_34xxxxxxxx13
+    data_template:
+      brightness: {% raw %}>-
+        {% if states.light.gateway_light_34xxxxxxxx13.attributes.brightness %}
+          {% if states.light.gateway_light_34xxxxxxxx13.attributes.brightness + 60 <= 255 %}
+            {{states.light.gateway_light_34xxxxxxxx13.attributes.brightness + 60}}
+          {% else %}
+            {{states.light.gateway_light_34xxxxxxxx13.attributes.brightness}}
+          {% endif %}
+        {% else %}
+          10
+        {% endif %}{% endraw %}
+
+- alias: Turn off the gateway light
+  trigger:
+    platform: event
+    event_type: click
+    event_data:
+      entity_id: binary_sensor.wall_switch_both_158xxxxxxxxx12
+      click_type: both
+  action:
+    service: light.turn_off
+    entity_id: light.gateway_light_34xxxxxxxx13
+```

source/_components/cover.xiaomi.markdown

@@ -0,0 +1,20 @@
+---
+layout: page
+title: "Xiaomi Cover"
+description: "Instructions how to setup the Xiaomi cover within Home Assistant."
+date: 2017-07-21 16:34
+sidebar: true
+comments: false
+sharing: true
+footer: true
+logo: xiaomi.png
+ha_category: Cover
+ha_release: "0.50"
+ha_iot_class: "Local Polling"
+---
+
+
+The `xiaomi` cover platform allows you to get data from your [Xiaomi](http://www.mi.com/en/) covers.
+
+The requirement is that you have setup [Xiaomi](/components/xiaomi/).
+

source/_components/light.xiaomi.markdown

@@ -0,0 +1,20 @@
+---
+layout: page
+title: "Xiaomi Light"
+description: "Instructions how to setup the Xiaomi light within Home Assistant."
+date: 2017-07-21 16:34
+sidebar: true
+comments: false
+sharing: true
+footer: true
+logo: xiaomi.png
+ha_category: Light
+ha_release: "0.50"
+ha_iot_class: "Local Polling"
+---
+
+
+The `xiaomi` light platform allows you to get data from your [Xiaomi](http://www.mi.com/en/) lights.
+
+The requirement is that you have setup [Xiaomi](/components/xiaomi/).
+

source/_components/sensor.xiaomi.markdown

@@ -0,0 +1,20 @@
+---
+layout: page
+title: "Xiaomi Sensor"
+description: "Instructions how to setup the Xiaomi sensor within Home Assistant."
+date: 2017-07-21 16:34
+sidebar: true
+comments: false
+sharing: true
+footer: true
+logo: xiaomi.png
+ha_category: Sensor
+ha_release: "0.50"
+ha_iot_class: "Local Polling"
+---
+
+
+The `xiaomi` sensor platform allows you to get data from your [Xiaomi](http://www.mi.com/en/) sensors.
+
+The requirement is that you have setup [Xiaomi](/components/xiaomi/).
+

source/_components/switch.xiaomi.markdown

@@ -0,0 +1,20 @@
+---
+layout: page
+title: "Xiaomi Switch"
+description: "Instructions how to setup the Xiaomi switch within Home Assistant."
+date: 2017-07-21 16:34
+sidebar: true
+comments: false
+sharing: true
+footer: true
+logo: xiaomi.png
+ha_category: Switch
+ha_release: "0.50"
+ha_iot_class: "Local Polling"
+---
+
+
+The `xiaomi` switch platform allows you to get data from your [Xiaomi](http://www.mi.com/en/) switches.
+
+The requirement is that you have setup [Xiaomi](/components/xiaomi/).
+

source/_components/xiaomi.markdown

@@ -9,10 +9,11 @@ sharing: true
 footer: true
 logo: xiaomi.png
 ha_category: Hub
-ha_release: 0.50
+ha_release: "0.50"
+ha_iot_class: "Local Polling"
 ---
 
-The `xiaomi_gw` platform allows you to integrate the following devices into HA
+The `xiaomi_gw` platform allows you to integrate the following [Xiaomi](http://www.mi.com/en/) devices into Home Assistant.
 
 - Temperature and Humidity Sensor (old and new version)
 - Motion Sensor (old and new version)
@@ -44,22 +45,24 @@ What's not available?
 - Decoupled mode of the Aqara Wall Switches (Single & Double)
 - Additional alarm events of the Gas and Smoke Detector: Analog alarm, battery fault alarm (smoke detector only), sensitivity fault alarm, I2C communication failure
 
-{% linkable_title Getting started %}
 
 Follow the setup process using your phone and Mi Home app. From here you will be able to retrieve the key from within the app following [this tutorial](https://community.home-assistant.io/t/beta-xiaomi-gateway-integration/8213/1832)
 
-{% linkable_title Configuration %}
+To enable Xioami gateway in your installation, add the following to your `configuration.yaml` file:
 
 One Gateway
+
 ```yaml
- # You can leave mac empty if you only have one gateway
+# You can leave mac empty if you only have one gateway.
 xiaomi:
   gateways:
    - mac:
      key: xxxxxxxxxxxxxxxx
 ```
 
+
 Multiple Gateway
+
 ```yaml
 # 12 characters mac can be obtained from the gateway.
 xiaomi:
@@ -71,7 +74,47 @@ One Gateway
 ```
 
 Configuration variables:
+
 - **mac** (*Optional*): The MAC of your gateway. Required if you have more than one.
 - **key** (*Optional*): The key of your gateway. Required if you also want to control lights and switches; sensors and binary sensors will still work.
 - **discovery_retry** (*Optional*): Amount of times Home Assitant should try to reconnect to the Xiaomi Gateway. Default is 3.
 - **interface** (*Optional*): Which network interface to use. Default to any.
+
+## {% linkable_title Services %}
+
+The gateway provides two services: `xiaomi.play_ringtone` and `xiaomi.stop_ringtone`. To play ringtones by Home Assistant the version of the gateway firmware must be `1.4.1_145` at least. A `ringtone_id` and `gw_mac` must be supplied. The parameter `ringtone_vol` (percent) is optional. Allowed values of the `ringtone_id` are:
+
+- alarm ringtones [0-8]
+- doorbell ring [10-13]
+- alarm clock [20-29]
+- custom ringtones (uploaded by mi home app) starting from 10001
+
+Automation example
+
+```yaml
+- alias: Let a dog bark on long press
+  trigger:
+    platform: event
+    event_type: click
+    event_data:
+      entity_id: binary_sensor.switch_158d000xxxxxc2
+      click_type: long_click_press
+  action:
+    service: xiaomi.play_ringtone
+    data:
+      gw_mac: xxxxxxxxxxxx
+      ringtone_id: 8
+      ringtone_vol: 8
+
+- alias: Stop barking immediately on single click
+  trigger:
+    platform: event
+    event_type: click
+    event_data:
+      entity_id: binary_sensor.switch_158d000xxxxxc2
+      click_type: single
+  action:
+    service: xiaomi.stop_ringtone
+    data:
+      gw_mac: xxxxxxxxxxxx
+```