diff --git a/source/_components/vacuum.xiaomi_miio.markdown b/source/_components/vacuum.xiaomi_miio.markdown index 0b4f7b5c90cb..17f608a4e752 100644 --- a/source/_components/vacuum.xiaomi_miio.markdown +++ b/source/_components/vacuum.xiaomi_miio.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Xiaomi Mi Robot Vacuum" -description: "Instructions how to integrate your Xiaomi Mi Robot Vacuum within Home Assistant." +description: "Instructions on how to integrate your Xiaomi Mi Robot Vacuum within Home Assistant." date: 2017-05-05 18:11 sidebar: true comments: false @@ -13,16 +13,29 @@ ha_release: 0.51 ha_iot_class: "Local Polling" --- -The `xiaomi miio` vacuum platform allows you to control the state of your [Xiaomi Mi Robot Vacuum](http://www.mi.com/roomrobot/). +The `xiaomi miio` vacuum platform allows you to control the state of your +[Xiaomi Mi Robot Vacuum](http://www.mi.com/roomrobot/). -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. +Currently supported features are: -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. +- `turn_on` +- `pause` +- `stop` +- `return_to_home` +- `turn_off` (stop all activity and return to dock) +- `locate` +- `clean_spot` +- `set_fanspeed` +- remote control of your robot. -To add a vacuum to your installation, add the following to your `configuration.yaml` file: +Please follow [Retrieving the Access Token](/components/vacuum.xiaomi/#retrieving-the-access-token) to retrieve the API token used in +`configuration.yaml`. + +## {% linkable_title Configuring the Platform %} + +To add a vacuum to your installation, add the following to `configuration.yaml`: ```yaml -# Example configuration.yaml entry vacuum: - platform: xiaomi_miio host: 192.168.1.2 @@ -35,77 +48,99 @@ Configuration variables: - **token** (*Required*): The API token of your robot. - **name** (*Optional*): The name of your robot. -### {% linkable_title Platform services %} +## {% linkable_title Platform Services %} -In addition to all [`vacuum` component services](/components/vacuum#component-services) (`turn_on`, `turn_off`, `start_pause`, `stop`, `return_to_home`, `locate`, `set_fanspeed` and `send_command`), the `xiaomi` platform introduces specific services to access the remote control mode of the botvac. +In addition to [all of the services provided by the `vacuum` component] +]) (`turn_on`, `turn_off`, `start_pause`, `stop`, `return_to_home`, `locate`, +`set_fanspeed` and `send_command`), the `xiaomi` platform introduces specific +services to access the remote control mode of the robot. These are: -These are: `xiaomi_remote_control_start`, `xiaomi_remote_control_stop`, `xiaomi_remote_control_move` and `xiaomi_remote_control_move_step`. +- `xiaomi_remote_control_start` +- `xiaomi_remote_control_stop` +- `xiaomi_remote_control_move` +- `xiaomi_remote_control_move_step` -#### {% linkable_title Service `vacuum/xiaomi_remote_control_start` %} +### {% linkable_title Service `vacuum/xiaomi_remote_control_start` %} -Start the remote control mode of the vacuum cleaner. You can then move it with `remote_control_move`, when done call `remote_control_stop`. +Start the remote control mode of the robot. You can then move it with +`remote_control_move`; when done, call `remote_control_stop`. | Service data attribute | Optional | Description | |---------------------------|----------|-------------------------------------------------------| -| `entity_id` | yes | Only act on specific botvac. Else targets all. | +| `entity_id` | yes | Only act on specific robot; default targets all | -#### {% linkable_title Service `vacuum/xiaomi_remote_control_stop` %} +### {% linkable_title Service `vacuum/xiaomi_remote_control_stop` %} -Exit the remote control mode of the vacuum cleaner. +Exit the remote control mode of the robot. | Service data attribute | Optional | Description | |---------------------------|----------|-------------------------------------------------------| -| `entity_id` | yes | Only act on specific botvac. Else targets all. | +| `entity_id` | yes | Only act on specific robot; default targets all | -#### {% linkable_title Service `vacuum/xiaomi_remote_control_move` %} +### {% linkable_title Service `vacuum/xiaomi_remote_control_move` %} -Remote control the vacuum cleaner, make sure you first set it in remote control mode with `remote_control_start`. +Remote control the robot. Please ensure you first set it in remote control +mode with `remote_control_start`. | Service data attribute | Optional | Description | |---------------------------|----------|-------------------------------------------------------| -| `entity_id` | yes | Only act on specific botvac. Else targets all. | -| `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. | +| `entity_id` | yes | Only act on specific robot; default targets all | +| `velocity` | no | Speed: between -0.29 and 0.29 | +| `rotation` | no | Rotation: between -179 degrees and 179 degrees | +| `duration` | no | The number of seconds that the robot should move for | -#### {% linkable_title Service `vacuum/xiaomi_remote_control_move_step` %} +### {% linkable_title Service `vacuum/xiaomi_remote_control_move_step` %} -Use this call to enter the remote control mode, make one move, and stop and exit the remote control mode. +Enter remote control mode, make one move, stop, and exit remote control mode. | Service data attribute | Optional | Description | |---------------------------|----------|-------------------------------------------------------| -| `entity_id` | yes | Only act on specific botvac. Else targets all. | -| `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. | +| `entity_id` | yes | Only act on specific robot; default targets all | +| `velocity` | no | Speed: between -0.29 and 0.29. | +| `rotation` | no | Rotation: between -179 degrees and 179 degrees. | +| `duration` | no | The number of seconds that the robot should move for | -### {% linkable_title Attributes %} +## {% linkable_title Attributes %} -In addition to all [`vacuum` component attributes] (`battery_icon`, `cleaned_area`, `fan_speed`, `fan_speed_list`, `status`, `params`), the `xiaomi` platform introduces specific attributes to get information of the botvac. +In addition to [all of the attributes provided by the `vacuum` component](https://home-assistant.io/components/vacuum/#attributes), +(`battery_icon`, `cleaned_area`, `fan_speed`, `fan_speed_list`, `status`, and +`params`), the `xiaomi` platform introduces specific attributes. These are: -These are: `cleaning_time`, `do_not_disturb`, `main_brush_left`, `side_brush_left`, `filter_left`, `cleaning_count`, `total_cleaned_area` and `total_cleaning_time`. +- `cleaning_time` +- `do_not_disturb` +- `main_brush_left` +- `side_brush_left` +- `filter_left` +- `cleaning_count` +- `total_cleaned_area` +- `total_cleaning_time` -The following table shows the units of measurement for the single attributes. +The following table shows the units of measurement for each attribute: | Attribute | Unit of measurement | Description | |---------------------------|---------------------|-------------------------------------------------------| | `do_not_disturb` | | DND mode on / off | | `cleaning_time` | minutes | Last / actual cleaning time in minutes | -| `cleaned_area` | square meter | Last / actual cleaned area in square meter | +| `cleaned_area` | square meter | Last / actual cleaned area in square meters | | `main_brush_left` | hours | Hours left until a change of the main brush is needed | | `side_brush_left` | hours | Hours left until a change of the side brush is needed | | `filter_left` | hours | Hours left until a change of the filter is needed | -| `cleaning_count` | | Number of total cleaning passage | -| `total_cleaned_area` | square meter | Total cleaned area in square meter | +| `cleaning_count` | | Number of total cleaning cycles | +| `total_cleaned_area` | square meter | Total cleaned area in square meters | | `total_cleaning_time` | minutes | Total cleaning time in minutes | -### {% linkable_title Retrieving the Access Token %} +## {% linkable_title Retrieving the Access Token %}

-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. +This token (32 hexadecimal characters) is required for the Xiaomi Mi Robot +Vacuum and Xiaomi Philips Lights. 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.

+#### {% linkable_title Windows and Android %} + 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. @@ -123,8 +158,6 @@ $ 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). @@ -152,10 +185,44 @@ $ java.exe -jar ../android-backup-extractor/abe.jar unpack backup.ab backup.tar #### {% linkable_title Linux and Android (rooted!) %} -1. Configure the light with the Mi-Home app. +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. + +1. Configure the robot 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 iOS %} + +1. Configure the robot with the Mi-Home app. +2. Using iTunes, create an unencrypted backup of your iPhone. +3. Install [iBackup Viewer](Get ADB f.e. `apt-get install android-tools-adb`), open it, and open your backup. +4. Open the "Raw Data" module. +5. Navigate to `com.xiaomi.mihome`. +6. Search for a file that looks like this: `123456789_mihome.sqlite` – note that `_mihome.sqlite` is *not* the correct file. +7. Save this file to your filesystem. +8. Install [DB Browser for SQLite](http://sqlitebrowser.org/). +9. Open DB Browser and load the `.sqlite` file you saved from your backup. +10. Click on the `Execute SQL` tab. +11. Input and run this query: `SELECT ZTOKEN FROM ZDEVICE WHERE ZNAME = "Mi Robot Vacuum"` +12. Copy the returned 32-digit hexadecimal string to your clipboard. +13. Open `Terminal` and execute this command: `echo '0: ' | xxd -r -p | openssl enc -d -aes-128-ecb -nopad -nosalt -K 00000000000000000000000000000000` +14. Use the resulting string as your token.