Merge remote-tracking branch 'upstream/master' into feat/device_update

kasa/interfaces/__init__.py

@@ -0,0 +1,16 @@
+"""Package for interfaces."""
+
+from .fan import Fan
+from .firmware import Firmware
+from .led import Led
+from .light import Light, LightPreset
+from .lighteffect import LightEffect
+
+__all__ = [
+    "Fan",
+    "Firmware",
+    "Led",
+    "Light",
+    "LightEffect",
+    "LightPreset",
+]

kasa/interfaces/fan.py

@@ -0,0 +1,20 @@
+"""Module for Fan Interface."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from ..module import Module
+
+
+class Fan(Module, ABC):
+    """Interface for a Fan."""
+
+    @property
+    @abstractmethod
+    def fan_speed_level(self) -> int:
+        """Return fan speed level."""
+
+    @abstractmethod
+    async def set_fan_speed_level(self, level: int):
+        """Set fan speed level."""

kasa/interfaces/firmware.py

@@ -0,0 +1,51 @@
+"""Interface for firmware updates."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from datetime import date
+from typing import Callable, Coroutine
+
+from ..module import Module
+
+UpdateResult = bool
+
+
+class FirmwareDownloadState(ABC):
+    """Download state."""
+
+    status: int
+    progress: int
+    reboot_time: int
+    upgrade_time: int
+    auto_upgrade: bool
+
+
+@dataclass
+class FirmwareUpdateInfo:
+    """Update info status object."""
+
+    update_available: bool | None = None
+    current_version: str | None = None
+    available_version: str | None = None
+    release_date: date | None = None
+    release_notes: str | None = None
+
+
+class Firmware(Module, ABC):
+    """Interface to access firmware information and perform updates."""
+
+    @abstractmethod
+    async def update_firmware(
+        self, *, progress_cb: Callable[[FirmwareDownloadState], Coroutine] | None = None
+    ) -> UpdateResult:
+        """Perform firmware update.
+
+        This "blocks" until the update process has finished.
+        You can set *progress_cb* to get progress updates.
+        """
+
+    @abstractmethod
+    async def check_for_updates(self) -> FirmwareUpdateInfo:
+        """Return firmware update information."""

kasa/interfaces/led.py

@@ -0,0 +1,38 @@
+"""Module for base light effect module."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from ..feature import Feature
+from ..module import Module
+
+
+class Led(Module, ABC):
+    """Base interface to represent a LED module."""
+
+    def _initialize_features(self):
+        """Initialize features."""
+        device = self._device
+        self._add_feature(
+            Feature(
+                device=device,
+                container=self,
+                name="LED",
+                id="led",
+                icon="mdi:led",
+                attribute_getter="led",
+                attribute_setter="set_led",
+                type=Feature.Type.Switch,
+                category=Feature.Category.Config,
+            )
+        )
+
+    @property
+    @abstractmethod
+    def led(self) -> bool:
+        """Return current led status."""
+
+    @abstractmethod
+    async def set_led(self, enable: bool) -> None:
+        """Set led."""

kasa/interfaces/light.py

@@ -0,0 +1,135 @@
+"""Module for Device base class."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import NamedTuple, Optional
+
+from pydantic.v1 import BaseModel
+
+from ..module import Module
+
+
+class ColorTempRange(NamedTuple):
+    """Color temperature range."""
+
+    min: int
+    max: int
+
+
+class HSV(NamedTuple):
+    """Hue-saturation-value."""
+
+    hue: int
+    saturation: int
+    value: int
+
+
+class LightPreset(BaseModel):
+    """Light configuration preset."""
+
+    index: int
+    brightness: int
+
+    # These are not available for effect mode presets on light strips
+    hue: Optional[int]  # noqa: UP007
+    saturation: Optional[int]  # noqa: UP007
+    color_temp: Optional[int]  # noqa: UP007
+
+    # Variables for effect mode presets
+    custom: Optional[int]  # noqa: UP007
+    id: Optional[str]  # noqa: UP007
+    mode: Optional[int]  # noqa: UP007
+
+
+class Light(Module, ABC):
+    """Base class for TP-Link Light."""
+
+    @property
+    @abstractmethod
+    def is_dimmable(self) -> bool:
+        """Whether the light supports brightness changes."""
+
+    @property
+    @abstractmethod
+    def is_color(self) -> bool:
+        """Whether the bulb supports color changes."""
+
+    @property
+    @abstractmethod
+    def is_variable_color_temp(self) -> bool:
+        """Whether the bulb supports color temperature changes."""
+
+    @property
+    @abstractmethod
+    def valid_temperature_range(self) -> ColorTempRange:
+        """Return the device-specific white temperature range (in Kelvin).
+
+        :return: White temperature range in Kelvin (minimum, maximum)
+        """
+
+    @property
+    @abstractmethod
+    def has_effects(self) -> bool:
+        """Return True if the device supports effects."""
+
+    @property
+    @abstractmethod
+    def hsv(self) -> HSV:
+        """Return the current HSV state of the bulb.
+
+        :return: hue, saturation and value (degrees, %, %)
+        """
+
+    @property
+    @abstractmethod
+    def color_temp(self) -> int:
+        """Whether the bulb supports color temperature changes."""
+
+    @property
+    @abstractmethod
+    def brightness(self) -> int:
+        """Return the current brightness in percentage."""
+
+    @abstractmethod
+    async def set_hsv(
+        self,
+        hue: int,
+        saturation: int,
+        value: int | None = None,
+        *,
+        transition: int | None = None,
+    ) -> dict:
+        """Set new HSV.
+
+        Note, transition is not supported and will be ignored.
+
+        :param int hue: hue in degrees
+        :param int saturation: saturation in percentage [0,100]
+        :param int value: value in percentage [0, 100]
+        :param int transition: transition in milliseconds.
+        """
+
+    @abstractmethod
+    async def set_color_temp(
+        self, temp: int, *, brightness=None, transition: int | None = None
+    ) -> dict:
+        """Set the color temperature of the device in kelvin.
+
+        Note, transition is not supported and will be ignored.
+
+        :param int temp: The new color temperature, in Kelvin
+        :param int transition: transition in milliseconds.
+        """
+
+    @abstractmethod
+    async def set_brightness(
+        self, brightness: int, *, transition: int | None = None
+    ) -> dict:
+        """Set the brightness in percentage.
+
+        Note, transition is not supported and will be ignored.
+
+        :param int brightness: brightness in percent
+        :param int transition: transition in milliseconds.
+        """

kasa/interfaces/lighteffect.py

@@ -0,0 +1,80 @@
+"""Module for base light effect module."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from ..feature import Feature
+from ..module import Module
+
+
+class LightEffect(Module, ABC):
+    """Interface to represent a light effect module."""
+
+    LIGHT_EFFECTS_OFF = "Off"
+
+    def _initialize_features(self):
+        """Initialize features."""
+        device = self._device
+        self._add_feature(
+            Feature(
+                device,
+                id="light_effect",
+                name="Light effect",
+                container=self,
+                attribute_getter="effect",
+                attribute_setter="set_effect",
+                category=Feature.Category.Primary,
+                type=Feature.Type.Choice,
+                choices_getter="effect_list",
+            )
+        )
+
+    @property
+    @abstractmethod
+    def has_custom_effects(self) -> bool:
+        """Return True if the device supports setting custom effects."""
+
+    @property
+    @abstractmethod
+    def effect(self) -> str:
+        """Return effect state or name."""
+
+    @property
+    @abstractmethod
+    def effect_list(self) -> list[str]:
+        """Return built-in effects list.
+
+        Example:
+            ['Aurora', 'Bubbling Cauldron', ...]
+        """
+
+    @abstractmethod
+    async def set_effect(
+        self,
+        effect: str,
+        *,
+        brightness: int | None = None,
+        transition: int | None = None,
+    ) -> None:
+        """Set an effect on the device.
+
+        If brightness or transition is defined,
+        its value will be used instead of the effect-specific default.
+
+        See :meth:`effect_list` for available effects,
+        or use :meth:`set_custom_effect` for custom effects.
+
+        :param str effect: The effect to set
+        :param int brightness: The wanted brightness
+        :param int transition: The wanted transition time
+        """
+
+    async def set_custom_effect(
+        self,
+        effect_dict: dict,
+    ) -> None:
+        """Set a custom effect on the device.
+
+        :param str effect_dict: The custom effect dict to set
+        """