Add common alarm interface (#1479)

Add a common interface for the `alarm` module across `smart` and `smartcam` devices.

kasa/interfaces/__init__.py

@@ -1,5 +1,6 @@
 """Package for interfaces."""
 
+from .alarm import Alarm
 from .childsetup import ChildSetup
 from .energy import Energy
 from .fan import Fan
@@ -11,6 +12,7 @@ from .thermostat import Thermostat, ThermostatState
 from .time import Time
 
 __all__ = [
+    "Alarm",
     "ChildSetup",
     "Fan",
     "Energy",

kasa/interfaces/alarm.py

@@ -0,0 +1,75 @@
+"""Module for base alarm module."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Annotated
+
+from ..module import FeatureAttribute, Module
+
+
+class Alarm(Module, ABC):
+    """Base interface to represent an alarm module."""
+
+    @property
+    @abstractmethod
+    def alarm_sound(self) -> Annotated[str, FeatureAttribute()]:
+        """Return current alarm sound."""
+
+    @abstractmethod
+    async def set_alarm_sound(self, sound: str) -> Annotated[dict, FeatureAttribute()]:
+        """Set alarm sound.
+
+        See *alarm_sounds* for list of available sounds.
+        """
+
+    @property
+    @abstractmethod
+    def alarm_sounds(self) -> list[str]:
+        """Return list of available alarm sounds."""
+
+    @property
+    @abstractmethod
+    def alarm_volume(self) -> Annotated[int, FeatureAttribute()]:
+        """Return alarm volume."""
+
+    @abstractmethod
+    async def set_alarm_volume(
+        self, volume: int
+    ) -> Annotated[dict, FeatureAttribute()]:
+        """Set alarm volume."""
+
+    @property
+    @abstractmethod
+    def alarm_duration(self) -> Annotated[int, FeatureAttribute()]:
+        """Return alarm duration."""
+
+    @abstractmethod
+    async def set_alarm_duration(
+        self, duration: int
+    ) -> Annotated[dict, FeatureAttribute()]:
+        """Set alarm duration."""
+
+    @property
+    @abstractmethod
+    def active(self) -> bool:
+        """Return true if alarm is active."""
+
+    @abstractmethod
+    async def play(
+        self,
+        *,
+        duration: int | None = None,
+        volume: int | None = None,
+        sound: str | None = None,
+    ) -> dict:
+        """Play alarm.
+
+        The optional *duration*, *volume*, and *sound* to override the device settings.
+        *duration* is in seconds.
+        See *alarm_sounds* for the list of sounds available for the device.
+        """
+
+    @abstractmethod
+    async def stop(self) -> dict:
+        """Stop alarm."""