Add Xiaomi redirect and other misc improvements (#3425)

source/_components/xiaomi_aqara.markdown

@@ -1,7 +1,7 @@
 ---
 layout: page
-title: "Xiaomi Gateway"
-description: "Instructions how to integrate your Xiaomi Gateway within Home Assistant."
+title: "Xiaomi Gateway (Aqara)"
+description: "Instructions for how to integrate the Xiaomi Gateway (Aqara) within Home Assistant."
 date: 2017-07-21 16:34
 sidebar: true
 comments: false
@@ -11,15 +11,18 @@ logo: xiaomi.png
 ha_category: Hub
 ha_release: "0.50"
 ha_iot_class: "Local Push"
+redirect_from: /components/xiaomi/
 ---
 
-The `xiaomi aqara` platform allows you to integrate the following [Xiaomi](http://www.mi.com/en/) devices into Home Assistant.
+The `xiaomi_aqara` component allows you to integrate [Xiaomi](http://www.mi.com/en/) Aqara-compatible devices into Home Assistant.
+
+#### {% linkable_title Supported Devices %}
 
 - Temperature and Humidity Sensor (1st and 2nd generation)
 - Motion Sensor (1st and 2nd generation)
 - Door and Window Sensor (1st and 2nd generation)
 - Button (1st and 2nd generation)
-- Plug aka Socket (ZigBee version, reports power consumed, power load, state and if device in use)
+- Plug aka Socket (Zigbee version, reports power consumed, power load, state and if device in use)
 - Wall Plug (reports power consumed, power load and state)
 - Aqara Wall Switch (Single)
 - Aqara Wall Switch (Double)
@@ -35,7 +38,7 @@ The `xiaomi aqara` platform allows you to integrate the following [Xiaomi](http:
 - Water Leak Sensor
 - Battery
 
-What's not available?
+#### {% linkable_title Unsupported Devices %}
 
 - Gateway Radio
 - Gateway Button
@@ -44,9 +47,11 @@ 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
 
-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)
+## Setup
 
-To enable Xiaomi gateway in your installation, add the following to your `configuration.yaml` file:
+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).
+
+To enable {{ page.title }} in your installation, add the following to your `configuration.yaml` file:
 
 ### {% linkable_title One Gateway %}
 
@@ -81,14 +86,28 @@ xiaomi_aqara:
       key: xxxxxxxxxxxxxxxx
 ```
 
-Configuration variables:
+{% configuration %}
+  mac:
+    description: The MAC of your gateway. *Optional if only using one gateway.*
+    required: true
+    type: string
+  key:
+    description: The key of your gateway. *Optional if only using sensors and/or binary sensors.*
+    required: true
+    type: string
+  discovery_retry:
+    description: Number of times that Home Assistant should try to reconnect to the gateway.
+    required: false
+    type: int
+    default: 3
+  interface:
+    description: Which network interface to use.
+    required: false
+    type: string
+    default: any
+{% endconfiguration %}
 
-- **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. Defaults to any.
-
-## {% linkable_title Services %}
+### {% 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:
 
@@ -97,7 +116,13 @@ The gateway provides two services: `xiaomi.play_ringtone` and `xiaomi.stop_ringt
 - alarm clock [20-29]
 - custom ringtones (uploaded by the Mi Home app) starting from 10001
 
-Automation example
+## {% linkable_title Examples %}
+
+### Long Press on Smart Button
+
+This example plays the sound of a dog barking when the button is held down,
+and stops the sound when the button is pressed once.
+*Note: The sound will stop playing automatically when it has ended.*
 
 ```yaml
 - alias: Let a dog bark on long press
@@ -127,9 +152,9 @@ Automation example
       gw_mac: xxxxxxxxxxxx
 ```
 
-### {% linkable_title Troubleshooting %}
+## {% linkable_title Troubleshooting %}
 
-**Connection problem**
+### {% linkable_title Connection problem %}
 
 ```bash
 2017-08-20 16:51:19 ERROR (SyncWorker_0) [homeassistant.components.xiaomi] No gateway discovered
@@ -137,7 +162,7 @@ Automation example
 ```
 
 That means that Home Assistant is not getting any response from your Xiaomi gateway. Might be a local network problem or your firewall.
-- Make sure you have enabled LAN access: https://community.home-assistant.io/t/beta-xiaomi-gateway-integration/8213/1832
+- Make sure you have [enabled LAN access](https://community.home-assistant.io/t/beta-xiaomi-gateway-integration/8213/1832).
 - Turn off the firewall on the system where Home Assistant is running.
 - Try to leave the MAC address `mac:` blank.
 - Try to set `discovery_retry: 10`.