[meta] Add introspectable interfaces

[rytilahti]

This is a meta task to keep track on what interfaces needs to be added to allow defining all the necessary information inside python-miio to make interfacing with it from homeassistant (and other downstreams) as straightforward as possible.

This issue serves three purposes:

1. As a single point check list to keep track of the progress.
2. As a call for help as I have access only to very limited set of devices.
3. As something that can be linked to homeassistant contributors submitting PRs to enhance support for individual devices.

If you are reading this, and you have a Xiaomi device that is supported in homeassistant by this library, please consider contributing to this project by adding some simple metadata to the status containers of the devices you own (see "call for help" below for details).

The end goal of this journey is that this library provides enough information directly to avoid hard-coding any device-specific details–available features, actions, sensors, settings etc.–inside the downstream applications like homeassistant.
This would make this library the single source of truth when it comes to the devices supported by it, and relieves downstream maintainers from the painstaking process of adapting their implementation whenever this library gets extended.

Call for help

If you possess any devices besides the 1st gen Roborock vacuum and a zhimi powerstrip which I have, please consider creating a pull request to add the @sensor, @setting and @action descriptor decorators so that homeassistant (and other potential downstreams) can create entities for your device automatically in the future. https://python-miio.readthedocs.io/en/latest/contributing.html#status-containers contains some documentation on the topic, and the issues linked below in the checklist show an example of how they look like in homeassistant.

The homeassistant fork at https://github.com/rytilahti/home-assistant/tree/xiaomi_miio/feat/entities_from_upstream allows testing your changes. When we get feature parity (or close to it) with the existing homeassistant support, the plan is to create smaller PRs (per platform, most likely) based on the fork to first enable the additional entities, and sunset the hard-coded ones afterward.

When adding the descriptors to the status classes, you can provide the following extra kwargs that are currently used by the fork:

• device_class would be great to have besides the name and the unit
• icon for defining custom icons when no device_class is set
• state_class is not a priority at the moment, the default value should be chosen inside homeassistant and overridden only when needed

If you want to contribute information on several devices, please create a single pull request for each separate integration.
Feel free to ping me on the homeassistant discord or via e-mail if you have any questions!

Checklist

• Device initialization: Implement device factory #1556
• Sensors: Implement introspectable sensors #1488
  • sensor and binary_sensor platforms on homeassistant
• Switches: Implement introspectable switches #1494
  • switch platform on homeassistant
• Settings: Implement introspectable settings #1500
  • number, select platforms on homeassistant
• Actions: Implement introspectable actions #1588
  • button platform on homeassistant
• Embedding extra status containers: Implement embedding DeviceStatus containers #1526
• Binding decorator constraints (ranged values) based on model information (miio): Add range_attribute parameter to NumberSettingDescriptor #1602
• Convert existing devices to expose their functionalities help needed, read above!: [meta] Add descriptors to existing integrations #1617

Any help and contributions are welcome!

[starkillerOG]

@rytilahti I am getting my new Roborock S7 maxV plus today.
I will be away coming week, but after that I am going to help cleaning up and moving over the vacuum platform to this new way of setting up the entities in HomeAssistant.

[rytilahti]

@starkillerOG The roborock integration has already been converted to use dynamic sensors and my homeassistant branch has already converted vacuum platform to present the exposed sensors but what is still needed is to find sane a way to embed other status containers (e.g., for timers and consumables, that require separate I/O) into the main status container.

[starkillerOG]

@rytilahti I started testing the dynamic vacuum sensors on my Roborock S7MaxV and have finished polishing the sensors, added some sensors and fixed some issues. The PR for it is here: #1543
Would you mind taking a look?

[rytilahti]

@starkillerOG great! I'll do a quick review take a deeper look at it when I return from travels.

[starkillerOG]

@rytilahti thanks, that would be great!
When do you expect to return from travels (and have time to publish a new python-miio version)?

[rytilahti]

@starkillerOG I'll be back some time next week, but I'll have to see when I have some time to work on getting the last larger missing piece done. I want to have a way to initialize devices given only the host and the token, so that we have no blockers from python-miio's side to start removing hard-coded models from the homeassistant integration.

Getting a new release done and shipped with the 2022.11 like you mentioned elsewhere would be a good target!

[rytilahti]

As the interfaces are already there, I'm closing this. The conversion of existing integrations to have descriptors is tracked in #1617.