Xiaomi Mi Robot Vacuum
The xiaomi miio
vacuum platform allows you to control the state of your Xiaomi Mi Robot Vacuum.
Currently supported features are:
turn_on
pause
stop
return_to_home
turn_off
(stop all activity and return to dock)locate
clean_spot
set_fan_speed
- remote control of your robot.
Please follow Retrieving the Access Token to retrieve the API token used in
configuration.yaml
.
Configuring the Platform
To add a vacuum to your installation, add the following to configuration.yaml
:
vacuum:
- platform: xiaomi_miio
host: 192.168.1.2
token: YOUR_TOKEN
Configuration variables:
- host (Required): The IP of your robot.
- token (Required): The API token of your robot.
- name (Optional): The name of your robot.
Platform Services
In addition to all of the services provided by the vacuum
component (turn_on
, turn_off
, start_pause
, stop
, return_to_home
, locate
, set_fan_speed
and send_command
), the xiaomi
platform introduces specific services to access the remote control mode of the robot. These are:
xiaomi_remote_control_start
xiaomi_remote_control_stop
xiaomi_remote_control_move
xiaomi_remote_control_move_step
Service vacuum.xiaomi_remote_control_start
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 robot; default targets all |
Service vacuum.xiaomi_remote_control_stop
Exit the remote control mode of the robot.
Service data attribute | Optional | Description |
---|---|---|
entity_id |
yes | Only act on specific robot; default targets all |
Service vacuum.xiaomi_remote_control_move
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 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 |
Service vacuum.xiaomi_remote_control_move_step
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 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 |
Attributes
In addition to all of the attributes provided by the vacuum
component,
(battery_icon
, cleaned_area
, fan_speed
, fan_speed_list
, status
, and params
), the xiaomi
platform introduces specific attributes. These are:
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 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 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 cycles | |
total_cleaned_area |
square meter | Total cleaned area in square meters |
total_cleaning_time |
minutes | Total cleaning time in minutes |
Retrieving the Access Token
As per python-miio issue 185 the Mi-Home app no longer stores the token within the database (it’s retrieved from Xiaomi servers from version 5.0.31+). Currently the only known fix is to uninstall, then install a downgraded version of the apk. Apkmirror is a trusted source for older versions of the app. Mi-Home version 5.0.0 is confirmed as working for the following Android methods.
This token (32 hexadecimal characters) is required for the Xiaomi Mi Robot Vacuum, Xiaomi Philips Lights and Xiaomi IR Remote. 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 or using the miio
command line tool.
Miio command line tool
You can install the command line tool with:
$ npm install -g miio
Discovering devices on current network
$ miio discover
This will list devices that are connected to the same network as your computer. Let it run for a while so it has a chance to reach all devices, as it might take a minute or two for all devices to answer.
The commands outputs each device on this format:
Device ID: 48765421
Model info: zhimi.airpurifier.m1
Address: 192.168.100.9
Token: token-as-hex-here via auto-token
Support: At least basic
The information output is:
- Device ID - the unique identifier of the device, does not change if the device is reset.
- Model ID - the model id if it could be determined, this indicates what type of device it is
- Address - the IP that the device has on the network
- Token - the token of the device or ??? if it could not be automatically determined
Windows and Android
To fetch the token follow these instructions depending on your mobile phone platform.
- Configure the robot with the Mi-Home app.
- Download and extract the MiToolKit.zip.
- Enable developer mode and USB debugging on the Android phone and plug it into the computer.
- Change the MiToolKit language to English if you need to.
- Click “Extract Token”
- On the phone, you must confirm the backup. DO NOT enter any password and press the button to make the backup.
- Once you have confirmed the backup the token extraction will begin, it should appear in the MiToolKit shortly.
Linux and Android (not rooted)
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-miio
to be installed correctly.
$ sudo apt-get install libffi-dev libssl-dev
If your Home Assistant installation is running in a Virtualenv, make sure you activate it by running the commands below.
$ sudo su -s /bin/bash homeassistant
$ source /srv/homeassistant/bin/activate
To fetch the token follow these instructions depending on your mobile phone platform.
- Configure the robot with the Mi-Home app.
- Enable developer mode, USB debugging and plug the Android phone into the computer.
- Get ADB e.g.
apt-get install android-tools-adb
orapt-get install adb
adb devices
should list your device. Consult ADB manual if necessary.- Issue a backup command via adb:
adb backup -noapk com.xiaomi.smarthome -f backup.ab
(set a password if prompted on your phone). Some devices may required single quotes in the commandadb backup '-noapk com.xiaomi.smarthome -f backup.ab'
- Download the ‘ADB Backup Extractor’ from here
- Extract the data from the backup:
java -jar Android\ Backup\ Utilities/Android\ Backup\ Extractor/android-backup-extractor-20171005-bin/abe.jar unpack backup.ab unpacked.tar
(enter the password, if prompted) - Untar the unpacked data:
tar -xvf unpacked.tar
sqlite3 apps/com.xiaomi.smarthome/db/miio2.db 'select token from devicerecord where name = "Mi Robot Vacuum";'
returns the token for your Xiaomi vacuum bot.
Linux and Android (rooted!)
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-miio
to be installed correctly.
$ sudo apt-get install libffi-dev libssl-dev
If your Home Assistant installation is running in a Virtualenv, make sure you activate it by running the commands below.
$ sudo su -s /bin/bash homeassistant
$ source /srv/homeassistant/bin/activate
To fetch the token follow these instructions depending on your mobile phone platform.
- Configure the robot with the Mi-Home app.
- Enable developer mode, USB debugging and root permission only for ADB on the Android phone and plug it into the computer.
- Get ADB f.e.
apt-get install android-tools-adb
adb devices
should list your deviceadb root
(does work for development builds only: ones withro.debuggable=1
)adb shell
(for those using Magisk based root the previous command won’t work. After entering a shell, typesu
to enter the root shell)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.
iOS
- Configure the robot with the Mi-Home app.
- Using iTunes, create an unencrypted backup of your iPhone.
- Install iBackup Viewer, open it, and open your backup.
- Open the “Raw Data” module.
- Navigate to
com.xiaomi.mihome
. - Search for a file that looks like this:
123456789_mihome.sqlite
– note that_mihome.sqlite
is not the correct file. - Save this file to your filesystem.
- Install DB Browser for SQLite.
- Open DB Browser and load the
.sqlite
file you saved from your backup. - Click on the
Execute SQL
tab. - Input and run this query:
SELECT ZTOKEN FROM ZDEVICE WHERE ZNAME = "Mi Robot Vacuum"
- Copy the returned 32-digit hexadecimal string to your clipboard.
- Open
Terminal
and execute this command:echo '0: <YOUR HEXADECIMAL STRING>' | xxd -r -p | openssl enc -d -aes-128-ecb -nopad -nosalt -K 00000000000000000000000000000000
- Use the resulting string as your token.