Add --ip for install_sound, update_firmware & update docs (#262)

* Add --ip option for install_sound and update_firmware, allowing to override the autodetected one

* Update documentation for sound pack & firmware updates

* Update broken link + fix a sentence

* add --ip for install_sound for real..

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 <HelpOutput>`
@@ -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 <https://github.com/dgiese/dustcloud>`_ provides a way to generate your own firmware images,
+and they also have `a firmware archive <https://github.com/dgiese/dustcloud/tree/master/devices/xiaomi.vacuum.gen1/firmware>`_
+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
 ~~~~~~~~~~~~~~~~~

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()