Skip to content

Commit e08c9cc

Browse files
bachyafrenck
bachya
authored and
frenck
committed
Xiaomi Mi Vacuum: various documentation additions and corrections (home-assistant#3516)
* Various documentation additions and corrections * Couple of tiny changes in the Markdown
1 parent ed90bce commit e08c9cc

File tree

1 file changed

+106
-39
lines changed

1 file changed

+106
-39
lines changed

‎source/_components/vacuum.xiaomi_miio.markdown

Lines changed: 106 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
layout: page
33
title: "Xiaomi Mi Robot Vacuum"
4-
description: "Instructions how to integrate your Xiaomi Mi Robot Vacuum within Home Assistant."
4+
description: "Instructions on how to integrate your Xiaomi Mi Robot Vacuum within Home Assistant."
55
date: 2017-05-05 18:11
66
sidebar: true
77
comments: false
@@ -13,16 +13,29 @@ ha_release: 0.51
1313
ha_iot_class: "Local Polling"
1414
---
1515

16-
The `xiaomi miio` vacuum platform allows you to control the state of your [Xiaomi Mi Robot Vacuum](http://www.mi.com/roomrobot/).
16+
The `xiaomi miio` vacuum platform allows you to control the state of your
17+
[Xiaomi Mi Robot Vacuum](http://www.mi.com/roomrobot/).
1718

18-
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.
19+
Currently supported features are:
1920

20-
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.
21+
- `turn_on`
22+
- `pause`
23+
- `stop`
24+
- `return_to_home`
25+
- `turn_off` (stop all activity and return to dock)
26+
- `locate`
27+
- `clean_spot`
28+
- `set_fanspeed`
29+
- remote control of your robot.
2130

22-
To add a vacuum to your installation, add the following to your `configuration.yaml` file:
31+
Please follow [Retrieving the Access Token](/components/vacuum.xiaomi/#retrieving-the-access-token) to retrieve the API token used in
32+
`configuration.yaml`.
33+
34+
## {% linkable_title Configuring the Platform %}
35+
36+
To add a vacuum to your installation, add the following to `configuration.yaml`:
2337

2438
```yaml
25-
# Example configuration.yaml entry
2639
vacuum:
2740
- platform: xiaomi_miio
2841
host: 192.168.1.2
@@ -35,77 +48,99 @@ Configuration variables:
3548
- **token** (*Required*): The API token of your robot.
3649
- **name** (*Optional*): The name of your robot.
3750
38-
### {% linkable_title Platform services %}
51+
## {% linkable_title Platform Services %}
3952
40-
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.
53+
In addition to [all of the services provided by the `vacuum` component]
54+
]) (`turn_on`, `turn_off`, `start_pause`, `stop`, `return_to_home`, `locate`,
55+
`set_fanspeed` and `send_command`), the `xiaomi` platform introduces specific
56+
services to access the remote control mode of the robot. These are:
4157

42-
These are: `xiaomi_remote_control_start`, `xiaomi_remote_control_stop`, `xiaomi_remote_control_move` and `xiaomi_remote_control_move_step`.
58+
- `xiaomi_remote_control_start`
59+
- `xiaomi_remote_control_stop`
60+
- `xiaomi_remote_control_move`
61+
- `xiaomi_remote_control_move_step`
4362

44-
#### {% linkable_title Service `vacuum/xiaomi_remote_control_start` %}
63+
### {% linkable_title Service `vacuum/xiaomi_remote_control_start` %}
4564

46-
Start the remote control mode of the vacuum cleaner. You can then move it with `remote_control_move`, when done call `remote_control_stop`.
65+
Start the remote control mode of the robot. You can then move it with
66+
`remote_control_move`; when done, call `remote_control_stop`.
4767

4868
| Service data attribute | Optional | Description |
4969
|---------------------------|----------|-------------------------------------------------------|
50-
| `entity_id` | yes | Only act on specific botvac. Else targets all. |
70+
| `entity_id` | yes | Only act on specific robot; default targets all |
5171

52-
#### {% linkable_title Service `vacuum/xiaomi_remote_control_stop` %}
72+
### {% linkable_title Service `vacuum/xiaomi_remote_control_stop` %}
5373

54-
Exit the remote control mode of the vacuum cleaner.
74+
Exit the remote control mode of the robot.
5575

5676
| Service data attribute | Optional | Description |
5777
|---------------------------|----------|-------------------------------------------------------|
58-
| `entity_id` | yes | Only act on specific botvac. Else targets all. |
78+
| `entity_id` | yes | Only act on specific robot; default targets all |
5979

60-
#### {% linkable_title Service `vacuum/xiaomi_remote_control_move` %}
80+
### {% linkable_title Service `vacuum/xiaomi_remote_control_move` %}
6181

62-
Remote control the vacuum cleaner, make sure you first set it in remote control mode with `remote_control_start`.
82+
Remote control the robot. Please ensure you first set it in remote control
83+
mode with `remote_control_start`.
6384

6485
| Service data attribute | Optional | Description |
6586
|---------------------------|----------|-------------------------------------------------------|
66-
| `entity_id` | yes | Only act on specific botvac. Else targets all. |
67-
| `velocity` | no | Speed, between -0.29 and 0.29. |
68-
| `rotation` | no | Rotation, between -179 degrees and 179 degrees. |
69-
| `duration` | no | Parameter affecting the duration of the movement. |
87+
| `entity_id` | yes | Only act on specific robot; default targets all |
88+
| `velocity` | no | Speed: between -0.29 and 0.29 |
89+
| `rotation` | no | Rotation: between -179 degrees and 179 degrees |
90+
| `duration` | no | The number of seconds that the robot should move for |
7091

7192

72-
#### {% linkable_title Service `vacuum/xiaomi_remote_control_move_step` %}
93+
### {% linkable_title Service `vacuum/xiaomi_remote_control_move_step` %}
7394

74-
Use this call to enter the remote control mode, make one move, and stop and exit the remote control mode.
95+
Enter remote control mode, make one move, stop, and exit remote control mode.
7596

7697
| Service data attribute | Optional | Description |
7798
|---------------------------|----------|-------------------------------------------------------|
78-
| `entity_id` | yes | Only act on specific botvac. Else targets all. |
79-
| `velocity` | no | Speed, between -0.29 and 0.29. |
80-
| `rotation` | no | Rotation, between -179 degrees and 179 degrees. |
81-
| `duration` | no | Parameter affecting the duration of the movement. |
99+
| `entity_id` | yes | Only act on specific robot; default targets all |
100+
| `velocity` | no | Speed: between -0.29 and 0.29. |
101+
| `rotation` | no | Rotation: between -179 degrees and 179 degrees. |
102+
| `duration` | no | The number of seconds that the robot should move for |
82103

83-
### {% linkable_title Attributes %}
104+
## {% linkable_title Attributes %}
84105

85-
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.
106+
In addition to [all of the attributes provided by the `vacuum` component](https://home-assistant.io/components/vacuum/#attributes),
107+
(`battery_icon`, `cleaned_area`, `fan_speed`, `fan_speed_list`, `status`, and
108+
`params`), the `xiaomi` platform introduces specific attributes. These are:
86109

87-
These are: `cleaning_time`, `do_not_disturb`, `main_brush_left`, `side_brush_left`, `filter_left`, `cleaning_count`, `total_cleaned_area` and `total_cleaning_time`.
110+
- `cleaning_time`
111+
- `do_not_disturb`
112+
- `main_brush_left`
113+
- `side_brush_left`
114+
- `filter_left`
115+
- `cleaning_count`
116+
- `total_cleaned_area`
117+
- `total_cleaning_time`
88118

89-
The following table shows the units of measurement for the single attributes.
119+
The following table shows the units of measurement for each attribute:
90120

91121
| Attribute | Unit of measurement | Description |
92122
|---------------------------|---------------------|-------------------------------------------------------|
93123
| `do_not_disturb` | | DND mode on / off |
94124
| `cleaning_time` | minutes | Last / actual cleaning time in minutes |
95-
| `cleaned_area` | square meter | Last / actual cleaned area in square meter |
125+
| `cleaned_area` | square meter | Last / actual cleaned area in square meters |
96126
| `main_brush_left` | hours | Hours left until a change of the main brush is needed |
97127
| `side_brush_left` | hours | Hours left until a change of the side brush is needed |
98128
| `filter_left` | hours | Hours left until a change of the filter is needed |
99-
| `cleaning_count` | | Number of total cleaning passage |
100-
| `total_cleaned_area` | square meter | Total cleaned area in square meter |
129+
| `cleaning_count` | | Number of total cleaning cycles |
130+
| `total_cleaned_area` | square meter | Total cleaned area in square meters |
101131
| `total_cleaning_time` | minutes | Total cleaning time in minutes |
102132

103-
### {% linkable_title Retrieving the Access Token %}
133+
## {% linkable_title Retrieving the Access Token %}
104134

105135
<p class='note'>
106-
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.
136+
This token (32 hexadecimal characters) is required for the Xiaomi Mi Robot
137+
Vacuum and Xiaomi Philips Lights. The Xiaomi Gateway uses another security
138+
method and requires a `key` (16 alphanumeric chars), which can be obtained
139+
easily via a hidden menu item at the Mi-Home app.
107140
</p>
108141

142+
#### {% linkable_title Windows and Android %}
143+
109144
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.
110145

111146
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
123158

124159
To fetch the token follow these instructions depending on your mobile phone platform.
125160

126-
#### {% linkable_title Windows and Android %}
127-
128161
1. Configure the robot with the Mi-Home app.
129162
2. Enable developer mode and USB debugging on the Android phone and plug it into the computer.
130163
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
152185

153186
#### {% linkable_title Linux and Android (rooted!) %}
154187

155-
1. Configure the light with the Mi-Home app.
188+
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.
189+
190+
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.
191+
192+
```bash
193+
$ sudo apt-get install libffi-dev libssl-dev
194+
```
195+
196+
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.
197+
198+
```bash
199+
$ sudo su -s /bin/bash homeassistant
200+
$ source /srv/homeassistant/bin/activate
201+
```
202+
203+
To fetch the token follow these instructions depending on your mobile phone platform.
204+
205+
1. Configure the robot with the Mi-Home app.
156206
2. Enable developer mode, USB debugging and root permission only for ADB on the Android phone and plug it into the computer.
157207
3. Get ADB f.e. `apt-get install android-tools-adb`
158208
4. `adb devices` should list your device
159209
5. `adb root` (does work for development builds only: ones with `ro.debuggable=1`)
160210
6. `adb shell`
161211
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.
212+
213+
#### {% linkable_title iOS %}
214+
215+
1. Configure the robot with the Mi-Home app.
216+
2. Using iTunes, create an unencrypted backup of your iPhone.
217+
3. Install [iBackup Viewer](Get ADB f.e. `apt-get install android-tools-adb`), open it, and open your backup.
218+
4. Open the "Raw Data" module.
219+
5. Navigate to `com.xiaomi.mihome`.
220+
6. Search for a file that looks like this: `123456789_mihome.sqlite` – note that `_mihome.sqlite` is *not* the correct file.
221+
7. Save this file to your filesystem.
222+
8. Install [DB Browser for SQLite](http://sqlitebrowser.org/).
223+
9. Open DB Browser and load the `.sqlite` file you saved from your backup.
224+
10. Click on the `Execute SQL` tab.
225+
11. Input and run this query: `SELECT ZTOKEN FROM ZDEVICE WHERE ZNAME = "Mi Robot Vacuum"`
226+
12. Copy the returned 32-digit hexadecimal string to your clipboard.
227+
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`
228+
14. Use the resulting string as your token.

0 commit comments

Comments
 (0)