Add generic interface for accessing device features (#741)

This adds a generic interface for all device classes to introspect available device features,
that is necessary to make it easier to support a wide variety of supported devices with different set of features.
This will allow constructing generic interfaces (e.g., in homeassistant) that fetch and change these features without hard-coding the API calls.

`Device.features()` now returns a mapping of `<identifier, Feature>` where the `Feature` contains all necessary information (like the name, the icon, a way to get and change the setting) to present and change the defined feature through its interface.

kasa/iot/iotdevice.py

@@ -22,6 +22,7 @@ from ..device import Device, WifiNetwork
 from ..deviceconfig import DeviceConfig
 from ..emeterstatus import EmeterStatus
 from ..exceptions import SmartDeviceException
+from ..feature import Feature
 from ..protocol import BaseProtocol
 from .modules import Emeter, IotModule
 
@@ -184,8 +185,9 @@ class IotDevice(Device):
         super().__init__(host=host, config=config, protocol=protocol)
 
         self._sys_info: Any = None  # TODO: this is here to avoid changing tests
-        self._features: Set[str] = set()
         self._children: Sequence["IotDevice"] = []
+        self._supported_modules: Optional[Dict[str, IotModule]] = None
+        self._legacy_features: Set[str] = set()
 
     @property
     def children(self) -> Sequence["IotDevice"]:
@@ -260,7 +262,7 @@ class IotDevice(Device):
 
     @property  # type: ignore
     @requires_update
-    def features(self) -> Set[str]:
+    def features(self) -> Dict[str, Feature]:
         """Return a set of features that the device supports."""
         return self._features
 
@@ -276,7 +278,7 @@ class IotDevice(Device):
     @requires_update
     def has_emeter(self) -> bool:
         """Return True if device has an energy meter."""
-        return "ENE" in self.features
+        return "ENE" in self._legacy_features
 
     async def get_sys_info(self) -> Dict[str, Any]:
         """Retrieve system information."""
@@ -299,9 +301,28 @@ class IotDevice(Device):
             self._last_update = response
             self._set_sys_info(response["system"]["get_sysinfo"])
 
+        if not self._features:
+            await self._initialize_features()
+
         await self._modular_update(req)
         self._set_sys_info(self._last_update["system"]["get_sysinfo"])
 
+    async def _initialize_features(self):
+        self._add_feature(
+            Feature(
+                device=self, name="RSSI", attribute_getter="rssi", icon="mdi:signal"
+            )
+        )
+        if "on_time" in self._sys_info:
+            self._add_feature(
+                Feature(
+                    device=self,
+                    name="On since",
+                    attribute_getter="on_since",
+                    icon="mdi:clock",
+                )
+            )
+
     async def _modular_update(self, req: dict) -> None:
         """Execute an update query."""
         if self.has_emeter:
@@ -310,6 +331,18 @@ class IotDevice(Device):
             )
             self.add_module("emeter", Emeter(self, self.emeter_type))
 
+        # TODO: perhaps modules should not have unsupported modules,
+        #  making separate handling for this unnecessary
+        if self._supported_modules is None:
+            supported = {}
+            for module in self.modules.values():
+                if module.is_supported:
+                    supported[module._module] = module
+                for module_feat in module._module_features.values():
+                    self._add_feature(module_feat)
+
+            self._supported_modules = supported
+
         request_list = []
         est_response_size = 1024 if "system" in req else 0
         for module in self.modules.values():
@@ -357,9 +390,7 @@ class IotDevice(Device):
         """Set sys_info."""
         self._sys_info = sys_info
         if features := sys_info.get("feature"):
-            self._features = _parse_features(features)
-        else:
-            self._features = set()
+            self._legacy_features = _parse_features(features)
 
     @property  # type: ignore
     @requires_update

kasa/iot/iotplug.py

@@ -4,6 +4,7 @@ from typing import Any, Dict, Optional
 
 from ..device_type import DeviceType
 from ..deviceconfig import DeviceConfig
+from ..feature import Feature, FeatureType
 from ..protocol import BaseProtocol
 from .iotdevice import IotDevice, requires_update
 from .modules import Antitheft, Cloud, Schedule, Time, Usage
@@ -56,6 +57,17 @@ class IotPlug(IotDevice):
         self.add_module("time", Time(self, "time"))
         self.add_module("cloud", Cloud(self, "cnCloud"))
 
+        self._add_feature(
+            Feature(
+                device=self,
+                name="LED",
+                icon="mdi:led-{state}",
+                attribute_getter="led",
+                attribute_setter="set_led",
+                type=FeatureType.Switch,
+            )
+        )
+
     @property  # type: ignore
     @requires_update
     def is_on(self) -> bool:
@@ -88,5 +100,4 @@ class IotPlug(IotDevice):
     @requires_update
     def state_information(self) -> Dict[str, Any]:
         """Return switch-specific state information."""
-        info = {"LED state": self.led, "On since": self.on_since}
-        return info
+        return {}

kasa/iot/modules/cloud.py

@@ -4,6 +4,7 @@ try:
 except ImportError:
     from pydantic import BaseModel
 
+from ...feature import Feature, FeatureType
 from .module import IotModule
 
 
@@ -25,6 +26,24 @@ class CloudInfo(BaseModel):
 class Cloud(IotModule):
     """Module implementing support for cloud services."""
 
+    def __init__(self, device, module):
+        super().__init__(device, module)
+        self._add_feature(
+            Feature(
+                device=device,
+                container=self,
+                name="Cloud connection",
+                icon="mdi:cloud",
+                attribute_getter="is_connected",
+                type=FeatureType.BinarySensor,
+            )
+        )
+
+    @property
+    def is_connected(self) -> bool:
+        """Return true if device is connected to the cloud."""
+        return self.info.binded
+
     def query(self):
         """Request cloud connectivity info."""
         return self.query_for_command("get_info")

kasa/iot/modules/module.py

@@ -2,9 +2,10 @@
 import collections
 import logging
 from abc import ABC, abstractmethod
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Dict
 
 from ...exceptions import SmartDeviceException
+from ...feature import Feature
 
 if TYPE_CHECKING:
     from kasa.iot import IotDevice
@@ -34,6 +35,14 @@ class IotModule(ABC):
     def __init__(self, device: "IotDevice", module: str):
         self._device = device
         self._module = module
+        self._module_features: Dict[str, Feature] = {}
+
+    def _add_feature(self, feature: Feature):
+        """Add module feature."""
+        feature_name = f"{self._module}_{feature.name}"
+        if feature_name in self._module_features:
+            raise SmartDeviceException("Duplicate name detected %s" % feature_name)
+        self._module_features[feature_name] = feature
 
     @abstractmethod
     def query(self):