diff --git a/docs/vacuum.rst b/docs/vacuum.rst index 2f97788f1..aadf63b3a 100644 --- a/docs/vacuum.rst +++ b/docs/vacuum.rst @@ -5,11 +5,12 @@ Following features of the vacuum cleaner are currently supported: - Starting, stopping, pausing, locating. - Controlling the fan speed. -- Fetching status and state of consumables. **Resetting consumable state - is not currently implemented, patches welcome!** +- 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 :ref:`mirobo --help ` @@ -140,17 +141,53 @@ To get information about current sound settings: You can use dustcloud's `audio generator`_ to create your own language packs, which will handle both generation and encrypting the package for you. -To install your newly generated sound pack, you have to host it somewhere accessible to the vacuum, -and you have to know its md5sum. -The last parameter to give to the command is sound id (or `sid`), -which you can choose by yourself. +There are two ways to install install sound packs: + +1. 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 + +2. 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 1005 + 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. + + +.. _audio generator: https://github.com/dgiese/dustcloud/tree/master/devices/xiaomi.vacuum/audio_generator + +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 -.. _audio generator: https://github.com/dgiese/dustcloud/tree/master/xiaomi.vacuum.gen1/audio_generator DND functionality ~~~~~~~~~~~~~~~~~ diff --git a/miio/vacuum_cli.py b/miio/vacuum_cli.py index cf44b331a..db71af9cb 100644 --- a/miio/vacuum_cli.py +++ b/miio/vacuum_cli.py @@ -430,10 +430,20 @@ def sound(vac: miio.Vacuum, volume: int, test_mode: bool): @cli.command() @click.argument('url') @click.argument('md5sum', required=False, default=None) -@click.argument('sid', type=int, required=False, default=10000) +@click.option('--sid', type=int, required=False, default=10000) +@click.option('--ip', required=False) @pass_dev -def install_sound(vac: miio.Vacuum, url: str, md5sum: str, sid: int): - """Install a sound.""" +def install_sound(vac: miio.Vacuum, url: str, md5sum: str, sid: int, ip: str): + """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. + """ click.echo("Installing from %s (md5: %s) for id %s" % (url, md5sum, sid)) local_url = None @@ -445,7 +455,7 @@ def install_sound(vac: miio.Vacuum, url: str, md5sum: str, sid: int): local_url = url else: server = OneShotServer(url) - local_url = server.url() + local_url = server.url(ip) md5sum = server.md5 t = threading.Thread(target=server.serve_once) @@ -519,12 +529,17 @@ def update_status(vac: miio.Vacuum): @cli.command() @click.argument('url', required=True) @click.argument('md5', required=False, default=None) +@click.option('--ip', required=False) @pass_dev -def update_firmware(vac: miio.Vacuum, url: str, md5: str): +def update_firmware(vac: miio.Vacuum, url: str, md5: str, ip: str): """Update device firmware. - If `file` starts with http* it is expected to be an URL. - In that case md5sum of the file has to be given.""" + 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. + """ # TODO Check that the device is in updateable state. @@ -537,7 +552,7 @@ def update_firmware(vac: miio.Vacuum, url: str, md5: str): click.echo("Using %s (md5: %s)" % (url, md5)) else: server = OneShotServer(url) - url = server.url() + url = server.url(ip) t = threading.Thread(target=server.serve_once) t.start()