aiohomematic 2025.11.3__py3-none-any.whl

aiohomematic/model/custom/lock.py

@@ -0,0 +1,394 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2025
+"""Module for data points implemented using the lock category."""
+
+from __future__ import annotations
+
+from abc import abstractmethod
+from collections.abc import Mapping
+from enum import StrEnum
+
+from aiohomematic.const import DataPointCategory, DeviceProfile, Field, Parameter
+from aiohomematic.model import device as hmd
+from aiohomematic.model.custom import definition as hmed
+from aiohomematic.model.custom.data_point import CustomDataPoint
+from aiohomematic.model.custom.support import CustomConfig, ExtendedConfig
+from aiohomematic.model.data_point import CallParameterCollector, bind_collector
+from aiohomematic.model.generic import DpAction, DpSensor, DpSwitch
+from aiohomematic.property_decorators import state_property
+
+
+class _LockActivity(StrEnum):
+    """Enum with lock activities."""
+
+    LOCKING = "DOWN"
+    UNLOCKING = "UP"
+
+
+class _LockError(StrEnum):
+    """Enum with lock errors."""
+
+    NO_ERROR = "NO_ERROR"
+    CLUTCH_FAILURE = "CLUTCH_FAILURE"
+    MOTOR_ABORTED = "MOTOR_ABORTED"
+
+
+class _LockTargetLevel(StrEnum):
+    """Enum with lock target levels."""
+
+    LOCKED = "LOCKED"
+    OPEN = "OPEN"
+    UNLOCKED = "UNLOCKED"
+
+
+class LockState(StrEnum):
+    """Enum with lock states."""
+
+    LOCKED = "LOCKED"
+    UNKNOWN = "UNKNOWN"
+    UNLOCKED = "UNLOCKED"
+
+
+class BaseCustomDpLock(CustomDataPoint):
+    """Class for HomematicIP lock data point."""
+
+    __slots__ = ()
+
+    _category = DataPointCategory.LOCK
+    _ignore_multiple_channels_for_name = True
+
+    @state_property
+    @abstractmethod
+    def is_locked(self) -> bool:
+        """Return true if lock is on."""
+
+    @state_property
+    def is_jammed(self) -> bool:
+        """Return true if lock is jammed."""
+        return False
+
+    @state_property
+    def is_locking(self) -> bool | None:
+        """Return true if the lock is locking."""
+        return None
+
+    @state_property
+    def is_unlocking(self) -> bool | None:
+        """Return true if the lock is unlocking."""
+        return None
+
+    @property
+    @abstractmethod
+    def supports_open(self) -> bool:
+        """Flag if lock supports open."""
+
+    @abstractmethod
+    @bind_collector()
+    async def lock(self, *, collector: CallParameterCollector | None = None) -> None:
+        """Lock the lock."""
+
+    @abstractmethod
+    @bind_collector()
+    async def unlock(self, *, collector: CallParameterCollector | None = None) -> None:
+        """Unlock the lock."""
+
+    @abstractmethod
+    @bind_collector()
+    async def open(self, *, collector: CallParameterCollector | None = None) -> None:
+        """Open the lock."""
+
+
+class CustomDpIpLock(BaseCustomDpLock):
+    """Class for HomematicIP lock data point."""
+
+    __slots__ = (
+        "_dp_direction",
+        "_dp_lock_state",
+        "_dp_lock_target_level",
+    )
+
+    def _init_data_point_fields(self) -> None:
+        """Init the data_point fields."""
+        super()._init_data_point_fields()
+        self._dp_lock_state: DpSensor[str | None] = self._get_data_point(
+            field=Field.LOCK_STATE, data_point_type=DpSensor[str | None]
+        )
+        self._dp_lock_target_level: DpAction = self._get_data_point(
+            field=Field.LOCK_TARGET_LEVEL, data_point_type=DpAction
+        )
+        self._dp_direction: DpSensor[str | None] = self._get_data_point(
+            field=Field.DIRECTION, data_point_type=DpSensor[str | None]
+        )
+
+    @state_property
+    def is_locked(self) -> bool:
+        """Return true if lock is on."""
+        return self._dp_lock_state.value == LockState.LOCKED
+
+    @state_property
+    def is_locking(self) -> bool | None:
+        """Return true if the lock is locking."""
+        if self._dp_direction.value is not None:
+            return str(self._dp_direction.value) == _LockActivity.LOCKING
+        return None
+
+    @state_property
+    def is_unlocking(self) -> bool | None:
+        """Return true if the lock is unlocking."""
+        if self._dp_direction.value is not None:
+            return str(self._dp_direction.value) == _LockActivity.UNLOCKING
+        return None
+
+    @property
+    def supports_open(self) -> bool:
+        """Flag if lock supports open."""
+        return True
+
+    @bind_collector()
+    async def lock(self, *, collector: CallParameterCollector | None = None) -> None:
+        """Lock the lock."""
+        await self._dp_lock_target_level.send_value(value=_LockTargetLevel.LOCKED, collector=collector)
+
+    @bind_collector()
+    async def unlock(self, *, collector: CallParameterCollector | None = None) -> None:
+        """Unlock the lock."""
+        await self._dp_lock_target_level.send_value(value=_LockTargetLevel.UNLOCKED, collector=collector)
+
+    @bind_collector()
+    async def open(self, *, collector: CallParameterCollector | None = None) -> None:
+        """Open the lock."""
+        await self._dp_lock_target_level.send_value(value=_LockTargetLevel.OPEN, collector=collector)
+
+
+class CustomDpButtonLock(BaseCustomDpLock):
+    """Class for HomematicIP button lock data point."""
+
+    __slots__ = ("_dp_button_lock",)
+
+    def _init_data_point_fields(self) -> None:
+        """Init the data_point fields."""
+        super()._init_data_point_fields()
+        self._dp_button_lock: DpSwitch = self._get_data_point(field=Field.BUTTON_LOCK, data_point_type=DpSwitch)
+
+    @property
+    def data_point_name_postfix(self) -> str:
+        """Return the data_point name postfix."""
+        return "BUTTON_LOCK"
+
+    @state_property
+    def is_locked(self) -> bool:
+        """Return true if lock is on."""
+        return self._dp_button_lock.value is True
+
+    @property
+    def supports_open(self) -> bool:
+        """Flag if lock supports open."""
+        return False
+
+    @bind_collector()
+    async def lock(self, *, collector: CallParameterCollector | None = None) -> None:
+        """Lock the lock."""
+        await self._dp_button_lock.turn_on(collector=collector)
+
+    @bind_collector()
+    async def unlock(self, *, collector: CallParameterCollector | None = None) -> None:
+        """Unlock the lock."""
+        await self._dp_button_lock.turn_off(collector=collector)
+
+    @bind_collector()
+    async def open(self, *, collector: CallParameterCollector | None = None) -> None:
+        """Open the lock."""
+        return
+
+
+class CustomDpRfLock(BaseCustomDpLock):
+    """Class for classic Homematic lock data point."""
+
+    __slots__ = (
+        "_dp_direction",
+        "_dp_error",
+        "_dp_open",
+        "_dp_state",
+    )
+
+    def _init_data_point_fields(self) -> None:
+        """Init the data_point fields."""
+        super()._init_data_point_fields()
+        self._dp_state: DpSwitch = self._get_data_point(field=Field.STATE, data_point_type=DpSwitch)
+        self._dp_open: DpAction = self._get_data_point(field=Field.OPEN, data_point_type=DpAction)
+        self._dp_direction: DpSensor[str | None] = self._get_data_point(
+            field=Field.DIRECTION, data_point_type=DpSensor[str | None]
+        )
+        self._dp_error: DpSensor[str | None] = self._get_data_point(
+            field=Field.ERROR, data_point_type=DpSensor[str | None]
+        )
+
+    @state_property
+    def is_locked(self) -> bool:
+        """Return true if lock is on."""
+        return self._dp_state.value is not True
+
+    @state_property
+    def is_locking(self) -> bool | None:
+        """Return true if the lock is locking."""
+        if self._dp_direction.value is not None:
+            return str(self._dp_direction.value) == _LockActivity.LOCKING
+        return None
+
+    @state_property
+    def is_unlocking(self) -> bool | None:
+        """Return true if the lock is unlocking."""
+        if self._dp_direction.value is not None:
+            return str(self._dp_direction.value) == _LockActivity.UNLOCKING
+        return None
+
+    @state_property
+    def is_jammed(self) -> bool:
+        """Return true if lock is jammed."""
+        return self._dp_error.value is not None and self._dp_error.value != _LockError.NO_ERROR
+
+    @property
+    def supports_open(self) -> bool:
+        """Flag if lock supports open."""
+        return True
+
+    @bind_collector()
+    async def lock(self, *, collector: CallParameterCollector | None = None) -> None:
+        """Lock the lock."""
+        await self._dp_state.send_value(value=False, collector=collector)
+
+    @bind_collector()
+    async def unlock(self, *, collector: CallParameterCollector | None = None) -> None:
+        """Unlock the lock."""
+        await self._dp_state.send_value(value=True, collector=collector)
+
+    @bind_collector()
+    async def open(self, *, collector: CallParameterCollector | None = None) -> None:
+        """Open the lock."""
+        await self._dp_open.send_value(value=True, collector=collector)
+
+
+def make_ip_lock(
+    *,
+    channel: hmd.Channel,
+    custom_config: CustomConfig,
+) -> None:
+    """Create HomematicIP lock data point."""
+    hmed.make_custom_data_point(
+        channel=channel,
+        data_point_class=CustomDpIpLock,
+        device_profile=DeviceProfile.IP_LOCK,
+        custom_config=custom_config,
+    )
+
+
+def make_ip_button_lock(
+    *,
+    channel: hmd.Channel,
+    custom_config: CustomConfig,
+) -> None:
+    """Create HomematicIP ip button lock data point."""
+    hmed.make_custom_data_point(
+        channel=channel,
+        data_point_class=CustomDpButtonLock,
+        device_profile=DeviceProfile.IP_BUTTON_LOCK,
+        custom_config=custom_config,
+    )
+
+
+def make_rf_button_lock(
+    *,
+    channel: hmd.Channel,
+    custom_config: CustomConfig,
+) -> None:
+    """Create Homematic button lock data point."""
+    hmed.make_custom_data_point(
+        channel=channel,
+        data_point_class=CustomDpButtonLock,
+        device_profile=DeviceProfile.RF_BUTTON_LOCK,
+        custom_config=custom_config,
+    )
+
+
+def make_rf_lock(
+    *,
+    channel: hmd.Channel,
+    custom_config: CustomConfig,
+) -> None:
+    """Create Homematic lock data point."""
+    hmed.make_custom_data_point(
+        channel=channel,
+        data_point_class=CustomDpRfLock,
+        device_profile=DeviceProfile.RF_LOCK,
+        custom_config=custom_config,
+    )
+
+
+# Case for device model is not relevant.
+# HomeBrew (HB-) devices are always listed as HM-.
+DEVICES: Mapping[str, CustomConfig | tuple[CustomConfig, ...]] = {
+    "HM-Sec-Key": CustomConfig(
+        make_ce_func=make_rf_lock,
+        channels=(1,),
+        extended=ExtendedConfig(
+            additional_data_points={
+                1: (
+                    Parameter.DIRECTION,
+                    Parameter.ERROR,
+                ),
+            }
+        ),
+    ),
+    "HmIP-DLD": (
+        CustomConfig(
+            make_ce_func=make_ip_lock,
+            extended=ExtendedConfig(
+                additional_data_points={
+                    0: (Parameter.ERROR_JAMMED,),
+                }
+            ),
+        ),
+        CustomConfig(
+            make_ce_func=make_ip_button_lock,
+            channels=(0,),
+        ),
+    ),
+    "HM-TC-IT-WM-W-EU": CustomConfig(
+        make_ce_func=make_rf_button_lock,
+        channels=(None,),
+    ),
+    "ALPHA-IP-RBG": CustomConfig(
+        make_ce_func=make_ip_button_lock,
+        channels=(0,),
+    ),
+    "HmIP-BWTH": CustomConfig(
+        make_ce_func=make_ip_button_lock,
+        channels=(0,),
+    ),
+    "HmIP-FAL": CustomConfig(
+        make_ce_func=make_ip_button_lock,
+        channels=(0,),
+    ),
+    "HmIP-WGT": CustomConfig(
+        make_ce_func=make_ip_button_lock,
+        channels=(0,),
+    ),
+    "HmIP-WTH": CustomConfig(
+        make_ce_func=make_ip_button_lock,
+        channels=(0,),
+    ),
+    "HmIP-eTRV": CustomConfig(
+        make_ce_func=make_ip_button_lock,
+        channels=(0,),
+    ),
+    "HmIPW-FAL": CustomConfig(
+        make_ce_func=make_ip_button_lock,
+        channels=(0,),
+    ),
+    "HmIPW-WTH": CustomConfig(
+        make_ce_func=make_ip_button_lock,
+        channels=(0,),
+    ),
+}
+
+hmed.ALL_DEVICES[DataPointCategory.LOCK] = DEVICES

aiohomematic/model/custom/siren.py

@@ -0,0 +1,275 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2025
+"""Module for data points implemented using the siren category."""
+
+from __future__ import annotations
+
+from abc import abstractmethod
+from collections.abc import Mapping
+from enum import StrEnum
+from typing import Final, TypedDict, Unpack
+
+from aiohomematic.const import DataPointCategory, DeviceProfile, Field
+from aiohomematic.exceptions import ValidationException
+from aiohomematic.model import device as hmd
+from aiohomematic.model.custom import definition as hmed
+from aiohomematic.model.custom.data_point import CustomDataPoint
+from aiohomematic.model.custom.support import CustomConfig
+from aiohomematic.model.data_point import CallParameterCollector, bind_collector
+from aiohomematic.model.generic import DpAction, DpBinarySensor, DpSensor
+from aiohomematic.property_decorators import state_property
+
+_SMOKE_DETECTOR_ALARM_STATUS_IDLE_OFF: Final = "IDLE_OFF"
+
+
+class _SirenCommand(StrEnum):
+    """Enum with siren commands."""
+
+    OFF = "INTRUSION_ALARM_OFF"
+    ON = "INTRUSION_ALARM"
+
+
+class SirenOnArgs(TypedDict, total=False):
+    """Matcher for the siren arguments."""
+
+    acoustic_alarm: str
+    optical_alarm: str
+    duration: str
+
+
+class BaseCustomDpSiren(CustomDataPoint):
+    """Class for Homematic siren data point."""
+
+    __slots__ = ()
+
+    _category = DataPointCategory.SIREN
+
+    @state_property
+    @abstractmethod
+    def is_on(self) -> bool:
+        """Return true if siren is on."""
+
+    @state_property
+    @abstractmethod
+    def available_tones(self) -> tuple[str, ...] | None:
+        """Return available tones."""
+
+    @state_property
+    @abstractmethod
+    def available_lights(self) -> tuple[str, ...] | None:
+        """Return available lights."""
+
+    @property
+    @abstractmethod
+    def supports_duration(self) -> bool:
+        """Flag if siren supports duration."""
+
+    @property
+    def supports_tones(self) -> bool:
+        """Flag if siren supports tones."""
+        return self.available_tones is not None
+
+    @property
+    def supports_lights(self) -> bool:
+        """Flag if siren supports lights."""
+        return self.available_lights is not None
+
+    @abstractmethod
+    @bind_collector()
+    async def turn_on(
+        self,
+        *,
+        collector: CallParameterCollector | None = None,
+        **kwargs: Unpack[SirenOnArgs],
+    ) -> None:
+        """Turn the device on."""
+
+    @abstractmethod
+    @bind_collector()
+    async def turn_off(self, *, collector: CallParameterCollector | None = None) -> None:
+        """Turn the device off."""
+
+
+class CustomDpIpSiren(BaseCustomDpSiren):
+    """Class for HomematicIP siren data point."""
+
+    __slots__ = (
+        "_dp_acoustic_alarm_active",
+        "_dp_acoustic_alarm_selection",
+        "_dp_duration",
+        "_dp_duration_unit",
+        "_dp_optical_alarm_active",
+        "_dp_optical_alarm_selection",
+    )
+
+    def _init_data_point_fields(self) -> None:
+        """Init the data_point fields."""
+        super()._init_data_point_fields()
+        self._dp_acoustic_alarm_active: DpBinarySensor = self._get_data_point(
+            field=Field.ACOUSTIC_ALARM_ACTIVE, data_point_type=DpBinarySensor
+        )
+        self._dp_acoustic_alarm_selection: DpAction = self._get_data_point(
+            field=Field.ACOUSTIC_ALARM_SELECTION, data_point_type=DpAction
+        )
+        self._dp_optical_alarm_active: DpBinarySensor = self._get_data_point(
+            field=Field.OPTICAL_ALARM_ACTIVE, data_point_type=DpBinarySensor
+        )
+        self._dp_optical_alarm_selection: DpAction = self._get_data_point(
+            field=Field.OPTICAL_ALARM_SELECTION, data_point_type=DpAction
+        )
+        self._dp_duration: DpAction = self._get_data_point(field=Field.DURATION, data_point_type=DpAction)
+        self._dp_duration_unit: DpAction = self._get_data_point(field=Field.DURATION_UNIT, data_point_type=DpAction)
+
+    @state_property
+    def is_on(self) -> bool:
+        """Return true if siren is on."""
+        return self._dp_acoustic_alarm_active.value is True or self._dp_optical_alarm_active.value is True
+
+    @state_property
+    def available_tones(self) -> tuple[str, ...] | None:
+        """Return available tones."""
+        return self._dp_acoustic_alarm_selection.values
+
+    @state_property
+    def available_lights(self) -> tuple[str, ...] | None:
+        """Return available lights."""
+        return self._dp_optical_alarm_selection.values
+
+    @property
+    def supports_duration(self) -> bool:
+        """Flag if siren supports duration."""
+        return True
+
+    @bind_collector()
+    async def turn_on(
+        self,
+        *,
+        collector: CallParameterCollector | None = None,
+        **kwargs: Unpack[SirenOnArgs],
+    ) -> None:
+        """Turn the device on."""
+
+        acoustic_alarm = kwargs.get("acoustic_alarm", self._dp_acoustic_alarm_selection.default)
+        if self.available_tones and acoustic_alarm and acoustic_alarm not in self.available_tones:
+            raise ValidationException(
+                f"Invalid tone specified for data_point {self.full_name}: {acoustic_alarm}, "
+                "check the available_tones attribute for valid tones to pass in"
+            )
+
+        optical_alarm = kwargs.get("optical_alarm", self._dp_optical_alarm_selection.default)
+        if self.available_lights and optical_alarm and optical_alarm not in self.available_lights:
+            raise ValidationException(
+                f"Invalid light specified for data_point {self.full_name}: {optical_alarm}, "
+                "check the available_lights attribute for valid tones to pass in"
+            )
+
+        await self._dp_acoustic_alarm_selection.send_value(value=acoustic_alarm, collector=collector)
+        await self._dp_optical_alarm_selection.send_value(value=optical_alarm, collector=collector)
+        await self._dp_duration_unit.send_value(value=self._dp_duration_unit.default, collector=collector)
+        duration = kwargs.get("duration", self._dp_duration.default)
+        await self._dp_duration.send_value(value=duration, collector=collector)
+
+    @bind_collector()
+    async def turn_off(self, *, collector: CallParameterCollector | None = None) -> None:
+        """Turn the device off."""
+        await self._dp_acoustic_alarm_selection.send_value(
+            value=self._dp_acoustic_alarm_selection.default, collector=collector
+        )
+        await self._dp_optical_alarm_selection.send_value(
+            value=self._dp_optical_alarm_selection.default, collector=collector
+        )
+        await self._dp_duration_unit.send_value(value=self._dp_duration_unit.default, collector=collector)
+        await self._dp_duration.send_value(value=self._dp_duration.default, collector=collector)
+
+
+class CustomDpIpSirenSmoke(BaseCustomDpSiren):
+    """Class for HomematicIP siren smoke data point."""
+
+    __slots__ = (
+        "_dp_smoke_detector_alarm_status",
+        "_dp_smoke_detector_command",
+    )
+
+    def _init_data_point_fields(self) -> None:
+        """Init the data_point fields."""
+        super()._init_data_point_fields()
+        self._dp_smoke_detector_alarm_status: DpSensor[str | None] = self._get_data_point(
+            field=Field.SMOKE_DETECTOR_ALARM_STATUS, data_point_type=DpSensor[str | None]
+        )
+        self._dp_smoke_detector_command: DpAction = self._get_data_point(
+            field=Field.SMOKE_DETECTOR_COMMAND, data_point_type=DpAction
+        )
+
+    @state_property
+    def is_on(self) -> bool:
+        """Return true if siren is on."""
+        if not self._dp_smoke_detector_alarm_status.value:
+            return False
+        return bool(self._dp_smoke_detector_alarm_status.value != _SMOKE_DETECTOR_ALARM_STATUS_IDLE_OFF)
+
+    @state_property
+    def available_tones(self) -> tuple[str, ...] | None:
+        """Return available tones."""
+        return None
+
+    @state_property
+    def available_lights(self) -> tuple[str, ...] | None:
+        """Return available lights."""
+        return None
+
+    @property
+    def supports_duration(self) -> bool:
+        """Flag if siren supports duration."""
+        return False
+
+    @bind_collector()
+    async def turn_on(
+        self,
+        *,
+        collector: CallParameterCollector | None = None,
+        **kwargs: Unpack[SirenOnArgs],
+    ) -> None:
+        """Turn the device on."""
+        await self._dp_smoke_detector_command.send_value(value=_SirenCommand.ON, collector=collector)
+
+    @bind_collector()
+    async def turn_off(self, *, collector: CallParameterCollector | None = None) -> None:
+        """Turn the device off."""
+        await self._dp_smoke_detector_command.send_value(value=_SirenCommand.OFF, collector=collector)
+
+
+def make_ip_siren(
+    *,
+    channel: hmd.Channel,
+    custom_config: CustomConfig,
+) -> None:
+    """Create HomematicIP siren data point."""
+    hmed.make_custom_data_point(
+        channel=channel,
+        data_point_class=CustomDpIpSiren,
+        device_profile=DeviceProfile.IP_SIREN,
+        custom_config=custom_config,
+    )
+
+
+def make_ip_siren_smoke(
+    *,
+    channel: hmd.Channel,
+    custom_config: CustomConfig,
+) -> None:
+    """Create HomematicIP siren data point."""
+    hmed.make_custom_data_point(
+        channel=channel,
+        data_point_class=CustomDpIpSirenSmoke,
+        device_profile=DeviceProfile.IP_SIREN_SMOKE,
+        custom_config=custom_config,
+    )
+
+
+# Case for device model is not relevant.
+# HomeBrew (HB-) devices are always listed as HM-.
+DEVICES: Mapping[str, CustomConfig | tuple[CustomConfig, ...]] = {
+    "HmIP-ASIR": CustomConfig(make_ce_func=make_ip_siren, channels=(3,)),
+    "HmIP-SWSD": CustomConfig(make_ce_func=make_ip_siren_smoke),
+}
+hmed.ALL_DEVICES[DataPointCategory.SIREN] = DEVICES

aiohomematic/model/custom/support.py

@@ -0,0 +1,41 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2025
+"""Support classes used by aiohomematic custom data points."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+
+from aiohomematic.const import Field, Parameter
+
+
+@dataclass(frozen=True, kw_only=True, slots=True)
+class CustomConfig:
+    """Data for custom data_point creation."""
+
+    make_ce_func: Callable
+    channels: tuple[int | None, ...] = (1,)
+    extended: ExtendedConfig | None = None
+
+
+@dataclass(frozen=True, kw_only=True, slots=True)
+class ExtendedConfig:
+    """Extended data for custom data_point creation."""
+
+    fixed_channels: Mapping[int, Mapping[Field, Parameter]] | None = None
+    additional_data_points: Mapping[int | tuple[int, ...], tuple[Parameter, ...]] | None = None
+
+    @property
+    def required_parameters(self) -> tuple[Parameter, ...]:
+        """Return vol.Required parameters from extended config."""
+        required_parameters: list[Parameter] = []
+        if fixed_channels := self.fixed_channels:
+            for mapping in fixed_channels.values():
+                required_parameters.extend(mapping.values())
+
+        if additional_dps := self.additional_data_points:
+            for parameters in additional_dps.values():
+                required_parameters.extend(parameters)
+
+        return tuple(required_parameters)