Skip to content

Commit

Permalink
Xiaomi Mi Vacuum: various documentation additions and corrections (ho…
Browse files Browse the repository at this point in the history 
…me-assistant#3516)

* Various documentation additions and corrections

* Couple of tiny changes in the Markdown
  • Loading branch information
@bachya @frenck
bachya authored and frenck committed Oct 20, 2017
1 parent ed90bce commit e08c9cc
Showing 1 changed file with 106 additions and 39 deletions.
145 changes: 106 additions & 39 deletions source/_components/vacuum.xiaomi_miio.markdown
View file
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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
Expand All @@ -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 %}

<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.
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.
</p>

#### {% 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.
Expand All @@ -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).
Expand Down Expand Up @@ -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: <YOUR HEXADECIMAL STRING>' | xxd -r -p | openssl enc -d -aes-128-ecb -nopad -nosalt -K 00000000000000000000000000000000`
14. Use the resulting string as your token.

0 comments on commit e08c9cc

Please sign in to comment.