Vacuum

Following features of the vacuum cleaner are currently supported:

Starting, stopping, pausing, locating.
Controlling the fan speed.
Fetching the current status.
Fetching and reseting the state of consumables.
Fetching and setting the schedules.
Setting and querying the timezone.
Installing sound packs.
Installing firmware updates.
Manual control of the robot. Patches for a nicer API are very welcome.

Use mirobo –help for help on available commands and their parameters.

Usage examples

Status reporting

$ mirobo --ip <Vacuum IP> --token <Token>
State: Charging
Battery: 100
Fanspeed: 60
Cleaning since: 0:00:00
Cleaned area: 0.0 m²
Water box attached: False

Start cleaning

$ mirobo start
Starting cleaning: 0

Return home

$ mirobo home
Requesting return to home: 0

Setting the fanspeed

$ mirobo fanspeed 30
Setting fan speed to 30

State of consumables

$ mirobo consumables
Main brush:   2 days, 16:14:00 (left 9 days, 19:46:00)
Side brush:   2 days, 16:14:00 (left 5 days, 15:46:00)
Filter:       2 days, 16:14:00 (left 3 days, 13:46:00)
Sensor dirty: 2:37:48 (left 1 day, 3:22:12)

Schedule information

$ mirobo timer
Timer #0, id 1488667794112 (ts: 2017-03-04 23:49:54.111999)
  49 22 * * 6
  At 14:49 every Saturday
Timer #1, id 1488667777661 (ts: 2017-03-04 23:49:37.661000)
  49 21 * * 3,4,5,6
  At 13:49 every Wednesday, Thursday, Friday and Saturday
Timer #2, id 1488667756246 (ts: 2017-03-04 23:49:16.246000)
  49 20 * * 0,1,2
  At 12:49 every Sunday, Monday and Tuesday
Timer #3, id 1488667742238 (ts: 2017-03-04 23:49:02.237999)
  49 19 * * 0,6
  At 11:49 every Sunday and Saturday
Timer #4, id 1488667726378 (ts: 2017-03-04 23:48:46.378000)
  48 18 * * 1,2,3,4,5
  At 10:48 every Monday, Tuesday, Wednesday, Thursday and Friday
Timer #5, id 1488667715725 (ts: 2017-03-04 23:48:35.724999)
  48 17 * * 0,1,2,3,4,5,6
  At 09:48 every Sunday, Monday, Tuesday, Wednesday, Thursday, Friday and Saturday
Timer #6, id 1488667697356 (ts: 2017-03-04 23:48:17.355999)
  48 16 5 3 *
  At 08:48 on the 5th of March

Adding a new timer

$ mirobo timer add --cron '* * * * *'

Activating/deactivating an existing timer, use mirobo timer to get the required id.

$ mirobo timer update <id> [--enable|--disable]

Deleting a timer

$ mirobo timer delete <id>

Cleaning history

Will also report amount of times the dust was collected if available.

$ mirobo cleaning-history
Total clean count: 43
Clean #0: 2017-03-05 19:09:40-2017-03-05 19:09:50 (complete: False, error: No error)
  Area cleaned: 0.0 m²
  Duration: (0:00:00)
Clean #1: 2017-03-05 16:17:52-2017-03-05 17:14:59 (complete: False, error: No error)
  Area cleaned: 32.16 m²
  Duration: (0:23:54)

Sounds

To get information about current sound settings:

mirobo sound

You can use dustcloud’s audio generator to create your own language packs, which will handle both generation and encrypting the package for you.

There are two ways to install install sound packs:

Install by using self-hosting server, where you just need to point the sound pack you want to install.

mirobo install-sound my_sounds.pkg

Install from an URL, in which case you need to pass the md5 hash of the file as a second parameter.

mirobo install-sound http://10.10.20.1:8000/my_sounds.pkg b50cfea27e52ebd5f46038ac7b9330c8

–sid can be used to select the sound ID (SID) for the new file, using an existing SID will overwrite the old.

If the automatic detection of the IP address for self-hosting server is not working, you can override this by using –ip option.

Firmware update

This can be useful if you want to downgrade or do updates without connecting to the cloud, or if you want to use a custom rooted firmware. Dustcloud project provides a way to generate your own firmware images, and they also have a firmware archive for original firmwares.

Warning

Updating firmware should not be taken lightly even when the device will automatically roll-back to the previous version when failing to do an update.

Using custom firmwares may hamper the functionality of your vacuum, and it is unknown how the factory reset works in these cases.

This feature works similarly to the sound updates, so passing a local file will create a self-hosting server and updating from an URL requires you to pass the md5 hash of the file.

mirobo update-firmware v11_003094.pkg

If you can control the device but the firmware update is not working (e.g., you are receiving a `BrokenPipeError during the update process <https://github.com/rytilahti/python-miio/issues/1154>`_ , you can host the file on any HTTP server (such as python3 -m http.server) by passing the URL and the md5sum of the file to the command:

mirobo update-firmware http://example.com/firmware_update.pkg 5eb63bbbe01eeed093cb22bb8f5acdc3

Manual control

To start the manual mode:

mirobo manual start

To move forward with velocity 0.3 for default amount of time:

mirobo manual forward 0.3

To turn 90 degrees to the right for default amount of time:

mirobo manual right 90

To stop the manual mode:

mirobo manual stop

To run the manual control TUI:

Note

Make sure you have got curses library installed on your system.

mirobo manual tui

DND functionality

To get current status:

mirobo dnd

To disable:

mirobo dnd off

To enable (dnd 22:00-0600):

mirobo dnd on 22 0 6 0

Carpet mode

Carpet mode increases the suction when encountering a carpet. The optional parameters (when using miiocli) are unknown and set as they were in the original firmware.

To enable:

mirobo carpet-mode 1 (or any other true-value, such as 'true')

To disable:

mirobo carpet-mode 0

Raw commands

It is also possible to run raw commands, which can be useful: for testing new unknown commands or if you want to have full access to what is being sent to the device:

mirobo raw-command app_start

or with parameters (same as above dnd on):

mirobo raw-command set_dnd_timer '[22,0,6,0]'

The input is passed as it is to the device as the params value, so it is also possible to pass dicts.

Note

If you find a new command please let us know by creating a pull request or an issue, if you do not want to implement it on your own!

mirobo –help

mirobo

A tool to command Xiaomi Vacuum robot.

mirobo [OPTIONS] COMMAND [ARGS]...

Options

--ip <ip>

--token <token>

-d, --debug

--id-file <id_file>

--version: Show the version and exit.

Environment variables

MIROBO_IP: Provide a default for --ip

MIROBO_TOKEN: Provide a default for --token

carpet-cleaning-mode

Query or set the carpet cleaning/avoidance mode.

Allowed values: Avoid, Rise, Ignore

mirobo carpet-cleaning-mode [OPTIONS] [MODE]

Arguments

MODE: Optional argument

carpet-mode

Query or set the carpet mode.

mirobo carpet-mode [OPTIONS] [ENABLED]

Arguments

ENABLED: Optional argument

cleaning-history

Query the cleaning history.

mirobo cleaning-history [OPTIONS]

configure-wifi

Configure the wifi settings.

Note that some newer firmwares may expect you to define the timezone by using –timezone.

mirobo configure-wifi [OPTIONS] SSID PASSWORD [UID]

Options

--timezone <timezone>

Arguments

SSID: Required argument

PASSWORD: Required argument

UID: Optional argument

consumables

Return consumables status.

mirobo consumables [OPTIONS]

discover

Search for robots in the network.

mirobo discover [OPTIONS]

Options

--handshake <handshake>

dnd

Query and adjust do-not-disturb mode.

mirobo dnd [OPTIONS] [CMD] [START_HR] [START_MIN] [END_HR] [END_MIN]

Arguments

CMD: Optional argument

START_HR: Optional argument

START_MIN: Optional argument

END_HR: Optional argument

END_MIN: Optional argument

fanspeed

Query and adjust the fan speed.

mirobo fanspeed [OPTIONS] [SPEED]

Arguments

SPEED: Optional argument

find

Find the robot.

mirobo find [OPTIONS]

goto

Go to specific target.

mirobo goto [OPTIONS] X_COORD Y_COORD

Arguments

X_COORD: Required argument

Y_COORD: Required argument

home

Return home.

mirobo home [OPTIONS]

info

Return device information.

mirobo info [OPTIONS]

install-sound

Install a sound.

When passing a local file this will create a self-hosting server: for the given file and the md5sum will be calculated automatically.

For URLs you have to specify the md5sum manually.

–ip can be used to override automatically detected IP address for: the device to contact for the update.

mirobo install-sound [OPTIONS] URL [MD5SUM]

Options

--sid <sid>

--ip <ip>

Arguments

URL: Required argument

MD5SUM: Optional argument

manual

Control the robot manually.

mirobo manual [OPTIONS] COMMAND [ARGS]...

backward

Run backwards.

mirobo manual backward [OPTIONS] AMOUNT

Arguments

AMOUNT: Required argument

forward

Run forwards.

mirobo manual forward [OPTIONS] AMOUNT

Arguments

AMOUNT: Required argument

left

Turn to left.

mirobo manual left [OPTIONS] DEGREES

Arguments

DEGREES: Required argument

move

Pass raw manual values.

mirobo manual move [OPTIONS] ROTATION VELOCITY DURATION

Arguments

ROTATION: Required argument

VELOCITY: Required argument

DURATION: Required argument

right

Turn to right.

mirobo manual right [OPTIONS] DEGREES

Arguments

DEGREES: Required argument

start

Activate the manual mode.

mirobo manual start [OPTIONS]

stop

Deactivate the manual mode.

mirobo manual stop [OPTIONS]

tui

TUI for the manual mode.

mirobo manual tui [OPTIONS]

map

Return the map token.

mirobo map [OPTIONS]

pause

Pause cleaning.

mirobo pause [OPTIONS]

raw-command

Run a raw command.

mirobo raw-command [OPTIONS] CMD [PARAMETERS]

Arguments

CMD: Required argument

PARAMETERS: Optional argument

reset-consumable

Reset consumable state.

Allowed values: main_brush, side_brush, filter, sensor_dirty

mirobo reset-consumable [OPTIONS] NAME

Arguments

NAME: Required argument

serial-number

Query serial number.

mirobo serial-number [OPTIONS]

sound

Query and change sound settings.

mirobo sound [OPTIONS] [VOLUME]

Options

--test: play a test tune

Arguments

VOLUME: Optional argument

spot

Start spot cleaning.

mirobo spot [OPTIONS]

start

Start cleaning.

mirobo start [OPTIONS]

status

Returns the state information.

mirobo status [OPTIONS]

stop

Stop cleaning.

mirobo stop [OPTIONS]

timer

List and modify existing timers.

mirobo timer [OPTIONS] COMMAND [ARGS]...

add

Add a timer.

mirobo timer add [OPTIONS]

Options

--cron <cron>

--command <command>

--params <params>

delete

Delete a timer.

mirobo timer delete [OPTIONS] TIMER_ID

Arguments

TIMER_ID: Required argument

update

Enable/disable a timer.

mirobo timer update [OPTIONS] TIMER_ID

Options

--enable

--disable

Arguments

TIMER_ID: Required argument

timezone

Query or set the timezone.

mirobo timezone [OPTIONS] [TZ]

Arguments

TZ: Optional argument

update-firmware

Update device firmware.

If url starts with http* it is expected to be an URL.: In that case md5sum of the file has to be given.
–ip can be used to override automatically detected IP address for: the device to contact for the update.

mirobo update-firmware [OPTIONS] URL [MD5]

Options

--ip <ip>

Arguments

URL: Required argument

MD5: Optional argument

update-status

Return update state and progress.

mirobo update-status [OPTIONS]

zoned-clean

Clean zone.

mirobo zoned-clean [OPTIONS] ZONES

Arguments

ZONES: Required argument

API