From b8a6688787fc019cce888cf4323597e43064ea85 Mon Sep 17 00:00:00 2001 From: Eugenio Panadero Date: Sun, 6 Aug 2017 18:05:27 +0200 Subject: [PATCH] Xiaomi vacuum documentation (#3076) * move previous work for switch to xiaomi vacuum platform * add doc for vacuum component and extra services of the xiaomi platform --- .../_components/switch.xiaomi_vacuum.markdown | 79 ----------- source/_components/vacuum.markdown | 96 +++++++++++++ source/_components/vacuum.xiaomi.markdown | 126 ++++++++++++++++++ 3 files changed, 222 insertions(+), 79 deletions(-) delete mode 100644 source/_components/switch.xiaomi_vacuum.markdown create mode 100644 source/_components/vacuum.markdown create mode 100644 source/_components/vacuum.xiaomi.markdown diff --git a/source/_components/switch.xiaomi_vacuum.markdown b/source/_components/switch.xiaomi_vacuum.markdown deleted file mode 100644 index f0be339ee8d..00000000000 --- a/source/_components/switch.xiaomi_vacuum.markdown +++ /dev/null @@ -1,79 +0,0 @@ ---- -layout: page -title: "Xiaomi Mi Robot Vacuum" -description: "Instructions how to integrate your Xiaomi Mi Robot Vacuum within Home Assistant." -date: 2017-05-05 18:11 -sidebar: true -comments: false -sharing: true -footer: true -logo: xiaomi.png -ha_category: Switch -ha_release: 0.48 ---- - -The `xiaomi_vacuum`switch platform allows you to control the state of your [Xiaomi Mi Robot Vacuum](http://www.mi.com/roomrobot/). -Current supported features are `start` and `stop` (goes to dock). - -{% linkable_title Getting started %} - -Follow the pairing process using your phone and Mi-Home app. From here you will be able to retrieve the token from a SQLite file inside your phone. - -

-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 -``` - -In order to fetch the token follow these instructions depending on your mobile phone platform. - -### 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 ADB tool for Windows : https://developer.android.com/studio/releases/platform-tools.html -4. Create a backup of the application com.xiaomi.smarthome: -```bash -.\adb backup -noapk com.xiaomi.smarthome -f backup.ab -``` -5. If you have this message : "More than one device or emulator", use this command to list all devices: -```bash -.\adb devices -``` -and execute this command: -```bash -.\adb -s DEVICEID backup -noapk com.xiaomi.smarthome -f backup.ab # (with DEVICEID the device id from the previous command) -``` -6. On the phone, you must confirm the backup. DO NOT enter any password and press button to make the backup. -7. Get ADB Backup Extractor : https://sourceforge.net/projects/adbextractor/ -8. Extract All files from the backup: -```bash -java.exe -jar ../android-backup-extractor/abe.jar unpack backup.ab backup.tar "" -``` -9. Unzip the ".tar" file. -10. Open the sqlite DB miio2.db with a tool like SQLite Manager extension for FireFox. -11. Get token from "devicerecord" table. - - -### macOS and iOS -1. Setup iOS device with the Mi-Home app. -2. Create an unencrypted backup of the device using iTunes. -3. Install iBackup Viewer from here: http://www.imactools.com/iphonebackupviewer/ -4. Extract this file /raw data/com.xiami.mihome/_mihome.sqlite to your computer -5. Open the file extracted using notepad. You will then see the list of all the device in your account with their token. - -{% linkable_title Configuration %} - -```yaml -# Example configuration.yaml entry -- platform: xiaomi_vacuum - name: 'name of the robot' - host: 192.168.1.2 - token: your-token-here -``` - -Configuration variables: -- **name** (*Optional*): The name of your robot -- **host** (*Required*): The IP of your robot -- **token** (*Required*): The token of your robot. Go to Getting started section to read more about how to get it diff --git a/source/_components/vacuum.markdown b/source/_components/vacuum.markdown new file mode 100644 index 00000000000..08af82d66ac --- /dev/null +++ b/source/_components/vacuum.markdown @@ -0,0 +1,96 @@ +--- +layout: page +title: "Vacuum cleaner robots" +description: "Instructions how to setup a botvac in Home Assistant." +date: 2017-07-28 15:00 +sidebar: true +comments: false +sharing: true +footer: true +--- + +The `vacuum` component enables the ability to control home cleaning robots within Home Assistant. + +To use this component in your installation, add a `vacuum` platform to your `configuration.yaml` file, like the [Xiaomi](/components/vacuum.xiaomi/). + +```yaml +# Example configuration.yaml entry +vacuum: +- platform: xiaomi + name: 'name of the robot' + host: 192.168.1.2 + token: your-token-here +``` + +### {% linkable_title Component services %} + +Available services: `turn_on`, `turn_off`, `start_pause`, `stop`, `return_to_home`, `locate`, `set_fanspeed` and `send_command`. + +Before calling one of these services, make sure your botvac platform supports it. + +#### {% linkable_title Service `vacuum/turn_on` %} + +Start a new cleaning task. + +| Service data attribute | Optional | Description | +|---------------------------|----------|-------------------------------------------------------| +| `entity_id` | yes | Only act on specific botvac. Else targets all. | + +#### {% linkable_title Service `vacuum/turn_off` %} + +Stop the current cleaning task and return to the dock. + +| Service data attribute | Optional | Description | +|---------------------------|----------|-------------------------------------------------------| +| `entity_id` | yes | Only act on specific botvac. Else targets all. | + +#### {% linkable_title Service `vacuum/start_pause` %} + +Start, pause or resume a cleaning task. + +| Service data attribute | Optional | Description | +|---------------------------|----------|-------------------------------------------------------| +| `entity_id` | yes | Only act on specific botvac. Else targets all. | + +#### {% linkable_title Service `vacuum/stop` %} + +Stop the current activity of the botvac. + +| Service data attribute | Optional | Description | +|---------------------------|----------|-------------------------------------------------------| +| `entity_id` | yes | Only act on specific botvac. Else targets all. | + +#### {% linkable_title Service `vacuum/return_to_home` %} + +Tell the botvac to return home. + +| Service data attribute | Optional | Description | +|---------------------------|----------|-------------------------------------------------------| +| `entity_id` | yes | Only act on specific botvac. Else targets all. | + +#### {% linkable_title Service `vacuum/locate` %} + +Start a new cleaning task. + +| Service data attribute | Optional | Description | +|---------------------------|----------|-------------------------------------------------------| +| `entity_id` | yes | Only act on specific botvac. Else targets all. | + +#### {% linkable_title Service `vacuum/set_fanspeed` %} + +Set the fan speed of the botvac. The `fanspeed` can be a label, as `balanced` or `turbo`, or be a number, it depends of the `vacuum` platform. + +| Service data attribute | Optional | Description | +|---------------------------|----------|-------------------------------------------------------| +| `entity_id` | yes | Only act on specific botvac. Else targets all. | +| `fanspeed` | no | Platform dependent vacuum cleaner fan speed, with speed steps, like 'medium', or by percentage, between 0 and 100. | + +#### {% linkable_title Service `vacuum/send_command` %} + +Send a platform-specific command to the vacuum cleaner. + +| Service data attribute | Optional | Description | +|---------------------------|----------|-------------------------------------------------------| +| `entity_id` | yes | Only act on specific botvac. Else targets all. | +| `command` | no | Command to execute. | +| `params` | yes | Parameters for the command. | diff --git a/source/_components/vacuum.xiaomi.markdown b/source/_components/vacuum.xiaomi.markdown new file mode 100644 index 00000000000..92582c58a2b --- /dev/null +++ b/source/_components/vacuum.xiaomi.markdown @@ -0,0 +1,126 @@ +--- +layout: page +title: "Xiaomi Mi Robot Vacuum" +description: "Instructions how to integrate your Xiaomi Mi Robot Vacuum within Home Assistant." +date: 2017-05-05 18:11 +sidebar: true +comments: false +sharing: true +footer: true +logo: xiaomi.png +ha_category: Hub +ha_release: 0.50 +--- + +The `xiaomi` 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`, `set_fanspeed` and even remote control your robot. + +## {% linkable_title Getting started %} + +Follow the pairing process using your phone and Mi-Home app. From here you will be able to retrieve the token from a SQLite file inside your phone. + +

+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 +``` + +In order to fetch the token follow these instructions depending on your mobile phone platform. + +### 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 ADB tool for Windows : https://developer.android.com/studio/releases/platform-tools.html +4. Create a backup of the application com.xiaomi.smarthome: +```bash +.\adb backup -noapk com.xiaomi.smarthome -f backup.ab +``` +5. If you have this message : "More than one device or emulator", use this command to list all devices: +```bash +.\adb devices +``` +and execute this command: +```bash +.\adb -s DEVICEID backup -noapk com.xiaomi.smarthome -f backup.ab # (with DEVICEID the device id from the previous command) +``` +6. On the phone, you must confirm the backup. DO NOT enter any password and press button to make the backup. +7. Get ADB Backup Extractor : https://sourceforge.net/projects/adbextractor/ +8. Extract All files from the backup: +```bash +java.exe -jar ../android-backup-extractor/abe.jar unpack backup.ab backup.tar "" +``` +9. Unzip the ".tar" file. +10. Open the sqlite DB miio2.db with a tool like SQLite Manager extension for FireFox. +11. Get token from "devicerecord" table. + + +### macOS and iOS +1. Setup iOS device with the Mi-Home app. +2. Create an unencrypted backup of the device using iTunes. +3. Install iBackup Viewer from here: http://www.imactools.com/iphonebackupviewer/ +4. Extract this file /raw data/com.xiami.mihome/_mihome.sqlite to your computer +5. Open the file extracted using notepad. You will then see the list of all the device in your account with their token. + +## {% linkable_title Configuration %} + +```yaml +# Example configuration.yaml entry +vacuum: +- platform: xiaomi + name: 'name of the robot' + host: 192.168.1.2 + token: your-token-here +``` + +Configuration variables: +- **name** (*Optional*): The name of your robot +- **host** (*Required*): The IP of your robot +- **token** (*Required*): The token of your robot. Go to Getting started section to read more about how to get it + +### {% 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. + +These are: `xiaomi_remote_control_start`, `xiaomi_remote_control_stop`, `xiaomi_remote_control_move` and `xiaomi_remote_control_move_step`. + +#### {% 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`. + +| Service data attribute | Optional | Description | +|---------------------------|----------|-------------------------------------------------------| +| `entity_id` | yes | Only act on specific botvac. Else targets all. | + +#### {% linkable_title Service `vacuum/xiaomi_remote_control_stop` %} + +Exit the remote control mode of the vacuum cleaner. + +| Service data attribute | Optional | Description | +|---------------------------|----------|-------------------------------------------------------| +| `entity_id` | yes | Only act on specific botvac. Else targets all. | + +#### {% 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`. + +| 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. | + + +#### {% linkable_title Service `vacuum/xiaomi_remote_control_move_step` %} + +Use this call to enter the remote control mode, make one movement, and stop and exit the 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. |