This meta task will track the progress and tasks to do for the next major release, which aims to simplify the use of the library for downstream users and reorganize the organically grown code base to be more maintainable.

This issue will give an overview of the planned changes, which are discussed more in-depth under their corresponding issues linked below as they get written. This meta issue shall serve as a checklist for the changelog, and is open for discussions.

Repository structure

• Motivation: all source files are currently stored in the main miio directory for historical reasons, making it messy.
• Goal: by splitting each individual implementation (integration?) and files related to it (e.g., tests and some data files) will clean up the code base.

Tasks

• Separate integrations and their tests to their own directories under miio/integrations/<name> or miio/integrations/<type of device>/<name>. [meta] Restructure integrations to their own directories #1115
• Consider adding __getattr__ to miio to inform about the breaking changes. #1696

"Device factory"

• Motivation: there is currently no way to construct device instances just by knowing their host and the token, making it necessary for downstreams to import the classes implementing the support and initializing it separately based on model information (or simply supporting a single implementation, like done by homeassistant's vacuum platform).
• Goal: allow initializing device-derived objects by simply knowing their host and the token which simplifies downstream implementations.

Tasks

• Add manifest files to integrations that describe supported models (miIO.info-based and mDNS entries) [meta] Add integration manifest files #1116
• Add facilities to access information about supported devices, and initialize implementations by using only the host and the token [meta] Add device registry & device factory facilities #1117

Common APIs

• Motivation: adding support for devices of the same device class (e.g., vacuums) is cumbersome as there is no well-defined API among the different implementations.
• Goal: provide device-type based base classes to make adding support for new device integrations on downstream just a matter of upgrading the python-miio.

Tasks

• Create base classes for individual device types where it makes sense to make it easier for downstreams to add support for a class of devices.
  • Need replaced partially with introspectable interfaces: [meta] Add introspectable interfaces #1495
• Add model detection based on miIO.info to consolidate handling of device-specific differences inside a single integration. Add model autodetection #1038
• Add supported_features or similar feature flags to allow integrations specify which features is supported by the device model. This will allow moving these checks from downstream (homeassistant most prominently) to where this information belongs.
  • Need replaced partially with introspectable interfaces: [meta] Add introspectable interfaces #1495
• Make available sensors introspectable (status class properties could be extended to allow defining metadata for available sensors). [meta] Add introspectable interfaces #1495
• Make available actions introspectable by exposing @commands.
• Implement common API for sensors, settings and actions #1814

MiOT support

• Motivation: all new devices are using miot instead of custom protocols to control devices, so it makes sense to add first class support to the library.
• Goal: all miot supporting devices can be controlled as long as internet-connectivity is available to fetch the required schema file.

Tasks

• Create generic miot integration Add generic miot support #1581
• Provide consolidated information (including descriptions, icons, etc.) for standard settings and actions using a yaml metadata file: Add metadata support for genericmiot #1618
• Add support for actions with multiple input parameters (exposed as custom services in homeassistant?): Implement input parameters for actions #1663
• Add support for write-only properties (exposed as custom services in homeassistant?): Handle non-readable miot properties #1662
• Clean up and deprecate old miot integrations that do not provide extra functionality compared to the generic interface

Other changes

• Clean-up constructors to use an "options" container instead of relying on separate kwarg arguments for special cases. Consolidate device class constructors #1156
• Replace lazy discovery in favor of configurable time-since-last-handshake #1683
• Consolidate out-of-range input values to raise standard exceptions (e.g., ValueError instead of custom exception types) Clean up raised library exceptions #1558
• Modify miiocli to store connection settings inside cache #1751
• Add support for pydantic v2 using v1 shims #1815