Zones - documentation and syntax check

[svenove]

Just spent a couple of hours to get “zoned_clean” to work.

The documentation just states you need to input a “zone”, but couldn’t find any reference to how a zone should look like: https://python-miio.readthedocs.io/en/latest/device_docs/vacuum.html#mirobo-zoned-clean

I found some examples on various forums/GitHub issues, but still wasn’t able to get it working. Each time I issued the command, the robot (Roborock Q7 Max) would do a full clean and ignore the zone I inputted.

I also looked up the code: https://github.com/rytilahti/python-miio/blob/ecdabcd963d77526a84b0a3df4023595de22a657/miio/integrations/vacuum/roborock/vacuum.py#L320

I tried things like: [23200,25400,27400,27900] [27400,27900, 23200,25400] (a tip said it matter which corner you give first) [23200,25400,27400,27900,1] (wasn’t sure if iterations was mandatory)

Right before I was going to create an issue to ask for help, I found the solution on a OpenHab-forum: https://community.openhab.org/t/xiaomi-vacuum-map-viewer-to-find-coordinates-for-zone-cleaning/103500

Double sqare brackets are required, even when having just one zone (I thought it was just needed when giving multiple zones)! So this works: [[23200,25400,27400,27900,1]]

Suggestions:

1. Improve documentation on how to correctly input a zone
2. Add syntax check in the code, so it doesn’t accept wrongly formatted zones
3. Don’t require double brackets when entering just one zone

Finding coordinates isn’t too easy either, so a more general info in the documentation about the methods to find coordinates for goto/zoned_clean would be great. If the docs are on GitHub, I sure can make a PR with a proposal of improvement on the documentation. :)

[rytilahti]

The API documentation is in the code itself and pull requests for improving them are very welcome!

The vacuum documentation page itself is still describing the old (but still working, I suppose) mirobo tool, and is located here: https://github.com/rytilahti/python-miio/blob/master/docs/device_docs/vacuum.rst .

I have not personally ever used the zone cleaning, so I cannot help much on issues related to that feature, sorry. Improving the code by adding a check that the input is indeed in correct format and extending the docstring would be really helpful for anyone else having the same issue!