Xiaomi token retrieval moved and extended (home-assistant#3339)

syssi · Landrash · commit 545826487b0d · 2017-09-12T14:40:33.000+02:00
* Xiaomi token retrieval moved and extended.

* Misleading sentence removed.

* Additional item added to the trouble shooting section.

* API token reference removed from the Xiaomi Gateway introduction.

* The iOS app method does not work anymore. The ZToken column contains a 96 character encrypted token now. A 32 character token is still needed.
diff --git a/source/_components/light.xiaomi_philipslight.markdown b/source/_components/light.xiaomi_philipslight.markdown
@@ -17,7 +17,7 @@ The `xiaomi_philipslight` platform allows you to control the state of your Xiaom
 
 Currently, the supported features are `on`, `off`, `set_cct` (colortemp) , `set_bright` (brightness).
 
-Please follow the instructions on [Retrieving the Access Token](/components/xiaomi/#retrieving-the-access-token) to get the API token to use in the `configuration.yaml` file.
+Please follow the instructions on [Retrieving the Access Token](/components/vacuum.xiaomi/#retrieving-the-access-token) to get the API token to use in the `configuration.yaml` file.
 
 To add a Xiaomi Philips Light to your installation, add the following to your configuration.yaml file:
 
diff --git a/source/_components/vacuum.xiaomi.markdown b/source/_components/vacuum.xiaomi.markdown
@@ -17,7 +17,7 @@ The `xiaomi` vacuum platform allows you to control the state of your [Xiaomi Mi
 
 Current supported features are `turn_on`, `pause`, `stop`, `return_to_home`, `turn_off` (stops goes to dock), `locate`, `clean_spot`, `set_fanspeed` and even remote control your robot.
 
-Please follow the instructions on [Retrieving the Access Token](/components/xiaomi/#retrieving-the-access-token) to get the API token to use in the `configuration.yaml` file.
+Please follow the instructions on [Retrieving the Access Token](/components/vacuum.xiaomi/#retrieving-the-access-token) to get the API token to use in the `configuration.yaml` file.
 
 To add a vacuum to your installation, add the following to your `configuration.yaml` file:
 
@@ -79,3 +79,63 @@ Use this call to enter the remote control mode, make one move, and stop and exit
 | `velocity`                |       no | Speed, between -0.29 and 0.29.                        |
 | `rotation`                |       no | Rotation, between -179 degrees and 179 degrees.       |
 | `duration`                |       no | Parameter affecting the duration of the movement.     |
+
+### {% linkable_title Retrieving the Access Token %}
+
+<p class='note'>
+This token (32 hexadecimal characters) is required for the Xiaomi Mi Robot Vacuum and Xiaomi Philips Light. The Xiaomi Gateway uses another security method and requires a `key` (16 alphanumeric chars) which can be obtained easily via a hidden menu item at the Mi-Home app.
+</p>
+
+Follow the pairing process using your phone and Mi-Home app. You will be able to retrieve the token from a SQLite file inside your phone.
+
+Before you begin you need to install `libffi-dev` and `libssl-dev` by running the command below. This is needed for `python-mirobo` to be installed correctly.
+
+```bash
+$ sudo apt-get install libffi-dev libssl-dev
+```
+
+If your Home Assistant installation is running in a [Virtualenv](/docs/installation/virtualenv/#upgrading-home-assistant), make sure you activate it by running the commands below.
+
+```bash
+$ sudo su -s /bin/bash homeassistant
+$ source /srv/homeassistant/bin/activate
+```
+
+To fetch the token follow these instructions depending on your mobile phone platform.
+
+#### {% linkable_title Windows and Android %}
+
+1. Configure the robot with the Mi-Home app.
+2. Enable developer mode and USB debugging on the Android phone and plug it into the computer.
+3. Get and install the [ADB tool for Windows](https://developer.android.com/studio/releases/platform-tools.html).
+4. Create a backup of the application `com.xiaomi.smarthome`:
+```bash
+$ adb backup -noapk com.xiaomi.smarthome -f backup.ab
+```
+5. If you have this message: "More than one device or emulator", use this command to list all devices:
+```bash
+$ adb devices
+```
+and execute this command:
+```bash
+$ adb -s DEVICEID backup -noapk com.xiaomi.smarthome -f backup.ab # (with DEVICEID the device id from the previous command)
+```
+6. On the phone, you must confirm the backup. DO NOT enter any password and press button to make the backup.
+7. Get and install [ADB Backup Extractor](https://sourceforge.net/projects/adbextractor/).
+8. Extract All files from the backup:
+```bash
+$ java.exe -jar ../android-backup-extractor/abe.jar unpack backup.ab backup.tar ""
+```
+9. Unzip the ".tar" file.
+10. Open the SQLite database `miio2.db` with a tool like SQLite Manager extension for FireFox.
+11. Get the token from "devicerecord" table.
+
+#### {% linkable_title Linux and Android (rooted!) %}
+
+1. Configure the light with the Mi-Home app.
+2. Enable developer mode, USB debugging and root permission only for ADB on the Android phone and plug it into the computer.
+3. Get ADB f.e. `apt-get install android-tools-adb`
+4. `adb devices` should list your device
+5. `adb root` (does work for development builds only: ones with `ro.debuggable=1`)
+6. `adb shell`
+7. `echo "select name,localIP,token from devicerecord;" | sqlite3 /data/data/com.xiaomi.smarthome/databases/miio2.db` returns a list of all registered devices including IP address and token.
diff --git a/source/_components/xiaomi.markdown b/source/_components/xiaomi.markdown
@@ -46,8 +46,6 @@ What's not available?
 
 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)
 
-Please check the instructions in this [section](/xiaomi/#retrieving-the-access-token) to get the API token to use with your platforms.
-
 To enable Xiaomi gateway in your installation, add the following to your `configuration.yaml` file:
 
 ### {% linkable_title One Gateway %}
@@ -140,72 +138,8 @@ 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
-- Turn off the firewall on the system where Home Assistant is running 
+- 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`
-- Try to disable and then enable LAN access
-
-### {% linkable_title Retrieving the Access Token %}
-
-Follow the pairing process using your phone and Mi-Home app. You will be able to retrieve the token from a SQLite file inside your phone. This token is needed for using various `xiaomi_*` platforms.
-
-Before you begin you need to install `libffi-dev` and `libssl-dev` by running the command below. This is needed for `python-mirobo` to be installed correctly.
-
-```bash
-$ sudo apt-get install libffi-dev libssl-dev
-```
-
-If your Home Assistant installation is running in a [Virtualenv](/docs/installation/virtualenv/#upgrading-home-assistant), make sure you activate it by running the commands below.
-
-```bash
-$ sudo su -s /bin/bash homeassistant
-$ source /srv/homeassistant/bin/activate
-```
-
-To fetch the token follow these instructions depending on your mobile phone platform.
-
-#### {% linkable_title Windows and Android %}
-
-1. Configure the robot with the Mi-Home app.
-2. Enable developer mode and USB debugging on the Android phone and plug it into the computer.
-3. Get and install the [ADB tool for Windows](https://developer.android.com/studio/releases/platform-tools.html).
-4. Create a backup of the application `com.xiaomi.smarthome`:
-```bash
-$ adb backup -noapk com.xiaomi.smarthome -f backup.ab
-```
-5. If you have this message: "More than one device or emulator", use this command to list all devices:
-```bash
-$ adb devices
-```
-and execute this command:
-```bash
-$ adb -s DEVICEID backup -noapk com.xiaomi.smarthome -f backup.ab # (with DEVICEID the device id from the previous command)
-```
-6. On the phone, you must confirm the backup. DO NOT enter any password and press button to make the backup.
-7. Get and install [ADB Backup Extractor](https://sourceforge.net/projects/adbextractor/).
-8. Extract All files from the backup:
-```bash
-$ java.exe -jar ../android-backup-extractor/abe.jar unpack backup.ab backup.tar ""
-```
-9. Unzip the ".tar" file.
-10. Open the SQLite database `miio2.db` with a tool like SQLite Manager extension for FireFox.
-11. Get the token from "devicerecord" table.
-
-#### {% linkable_title Linux and Android (rooted!) %}
-
-1. Configure the light with the Mi-Home app.
-2. Enable developer mode, USB debugging and root permission only for ADB on the Android phone and plug it into the computer.
-3. Get ADB f.e. `apt-get install android-tools-adb`
-4. `adb devices` should list your device
-5. `adb root` (does work for development builds only: ones with `ro.debuggable=1`)
-6. `adb shell`
-7. `echo "select name,localIP,token from devicerecord;" | sqlite3 /data/data/com.xiaomi.smarthome/databases/miio2.db` returns a list of all registered devices including IP address and token.
-
-#### {% linkable_title macOS and iOS %}
-
-1. Setup iOS device with the Mi-Home app.
-2. Create an unencrypted backup of the device using iTunes.
-3. Install [iBackup Viewer](http://www.imactools.com/iphonebackupviewer/).
-4. Extract this file: **`/raw data/com.xiami.mihome/1234567_mihome.sqlite`** to your computer, where `_1234567_` is any string of numbers.
-5. Open the SQLite database with a tool like SQLite Manager extension for FireFox or DB Browser. You will then see the list of all the devices in your account with their token. The token you need is in the column **`ZToken`** and looks like **`123a1234567b12345c1d123456789e12`**.
-(Location of SQLite files directly on iOS devices **/private/var/mobile/Containers/Data/Application/A80CE9E4-AD2E-4649-8C28-801C96B16BD7/Documents/**)
+- Try to set `discovery_retry: 10`.
+- Try to disable and then enable LAN access.
+- Hard reset the gateway: Press the button of the gateway 30 seconds and start again from scratch.
