home-assistant.io/vacuum.xiaomi_miio.markdown at eaeb3fa161d2cb7799c36fbc5916b59a8abd36a6

mirror of https://github.com/home-assistant/home-assistant.io.git synced 2025-07-23 01:06:52 +00:00

Aaron Bach e08c9cc6cb Xiaomi Mi Vacuum: various documentation additions and corrections (#3516 )

* Various documentation additions and corrections

* Couple of tiny changes in the Markdown

2017-10-20 09:34:40 +02:00

10 KiB

Raw Blame History

layout, title, description, date, sidebar, comments, sharing, footer, logo, ha_category, ha_release, ha_iot_class

layout	title	description	date	sidebar	comments	sharing	footer	logo	ha_category	ha_release	ha_iot_class
page	Xiaomi Mi Robot Vacuum	Instructions on how to integrate your Xiaomi Mi Robot Vacuum within Home Assistant.	2017-05-05 18:11	true	false	true	true	xiaomi.png	Vacuum	0.51	Local Polling

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_fanspeed
remote control of your robot.

Please follow 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:

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.

{% linkable_title 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_fanspeed 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

{% linkable_title 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

{% linkable_title 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

{% linkable_title 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

{% linkable_title 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

{% linkable_title 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

{% linkable_title Retrieving the Access Token %}

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.

$ 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 and USB debugging on the Android phone and plug it into the computer.
Get and install the ADB tool for Windows.
Create a backup of the application com.xiaomi.smarthome:

$ adb backup -noapk com.xiaomi.smarthome -f backup.ab

If you have this message: "More than one device or emulator", use this command to list all devices:

$ adb devices

and execute this command:

$ adb -s DEVICEID backup -noapk com.xiaomi.smarthome -f backup.ab # (with DEVICEID the device id from the previous command)

On the phone, you must confirm the backup. DO NOT enter any password and press button to make the backup.
Get and install ADB Backup Extractor.
Extract All files from the backup:

$ java.exe -jar ../android-backup-extractor/abe.jar unpack backup.ab backup.tar ""

Unzip the ".tar" file.
Open the SQLite database miio2.db with a tool like SQLite Manager extension for FireFox.
Get the token from "devicerecord" table.

{% linkable_title Linux and Android (rooted!) %}