aiohomematic 2026.1.29__py3-none-any.whl

aiohomematic/model/event.py

@@ -0,0 +1,216 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2026
+"""
+Event model for AioHomematic.
+
+This module defines the event data point hierarchy used to expose Homematic
+button presses, device errors, and impulse notifications to applications.
+
+Included classes:
+- GenericEvent: Base event that integrates with the common data point API
+  (category, usage, names/paths, subscriptions) and provides publish_event handling.
+- ClickEvent: Represents key press events (EventType.KEYPRESS).
+- DeviceErrorEvent: Represents device error signaling with special value change
+  semantics before publishing an event (EventType.DEVICE_ERROR).
+- ImpulseEvent: Represents impulse events (EventType.IMPULSE).
+
+Factory helpers:
+- create_event_and_append_to_channel: Determines the appropriate event type for
+  a given parameter description and attaches an instance to the channel.
+
+Typical flow:
+1) During device initialization, model.create_data_points_and_events inspects
+   paramset descriptions.
+2) For parameters that support Operations.EVENT and match known event names
+   (CLICK_EVENTS, DEVICE_ERROR_EVENTS, IMPULSE_EVENTS), an event data point is
+   created and registered on the channel.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+import logging
+from typing import Any, Final
+
+from aiohomematic import i18n, support as hms
+from aiohomematic.async_support import loop_check
+from aiohomematic.const import (
+    CLICK_EVENTS,
+    DATA_POINT_EVENTS,
+    DEVICE_ERROR_EVENTS,
+    IMPULSE_EVENTS,
+    DataPointCategory,
+    DataPointUsage,
+    DeviceTriggerEventType,
+    Operations,
+    ParameterData,
+    ParamsetKey,
+    ServiceScope,
+)
+from aiohomematic.decorators import inspector
+from aiohomematic.exceptions import AioHomematicException
+from aiohomematic.interfaces import ChannelProtocol, GenericEventProtocolAny
+from aiohomematic.model.data_point import BaseParameterDataPointAny
+from aiohomematic.model.support import DataPointNameData, get_event_name
+from aiohomematic.property_decorators import DelegatedProperty
+
+__all__ = [
+    "ClickEvent",
+    "DeviceErrorEvent",
+    "GenericEvent",
+    "ImpulseEvent",
+    "create_event_and_append_to_channel",
+]
+
+
+_LOGGER: Final = logging.getLogger(__name__)
+
+
+class GenericEvent(BaseParameterDataPointAny, GenericEventProtocolAny):
+    """Base class for events."""
+
+    __slots__ = ("_device_trigger_event_type",)
+
+    _category = DataPointCategory.EVENT
+    _device_trigger_event_type: DeviceTriggerEventType
+
+    def __init__(
+        self,
+        *,
+        channel: ChannelProtocol,
+        parameter: str,
+        parameter_data: ParameterData,
+    ) -> None:
+        """Initialize the event handler."""
+        super().__init__(
+            channel=channel,
+            paramset_key=ParamsetKey.VALUES,
+            parameter=parameter,
+            parameter_data=parameter_data,
+            unique_id_prefix=f"event_{channel.device.central_info.name}",
+        )
+
+    event_type: Final = DelegatedProperty[DeviceTriggerEventType](path="_device_trigger_event_type")
+
+    @property
+    def usage(self) -> DataPointUsage:
+        """Return the data_point usage."""
+        if (forced_by_com := self._enabled_by_channel_operation_mode) is None:
+            return self._get_data_point_usage()
+        return DataPointUsage.EVENT if forced_by_com else DataPointUsage.NO_CREATE
+
+    async def event(self, *, value: Any, received_at: datetime) -> None:
+        """Handle event for which this handler has subscribed."""
+        if self.event_type in DATA_POINT_EVENTS:
+            self.publish_data_point_updated_event()
+        self._set_modified_at(modified_at=received_at)
+        self.publish_event(value=value)
+
+    @loop_check
+    def publish_event(self, *, value: Any) -> None:
+        """Do what is needed to publish an event."""
+        self._event_publisher.publish_device_trigger_event(
+            trigger_type=self.event_type, event_data=self.get_event_data(value=value)
+        )
+
+    def _get_data_point_name(self) -> DataPointNameData:
+        """Create the name for the data_point."""
+        return get_event_name(
+            channel=self._channel,
+            parameter=self._parameter,
+        )
+
+    def _get_data_point_usage(self) -> DataPointUsage:
+        """Generate the usage for the data_point."""
+        return DataPointUsage.EVENT
+
+
+class ClickEvent(GenericEvent):
+    """class for handling click events."""
+
+    __slots__ = ()
+
+    _device_trigger_event_type = DeviceTriggerEventType.KEYPRESS
+
+
+class DeviceErrorEvent(GenericEvent):
+    """class for handling device error events."""
+
+    __slots__ = ()
+
+    _device_trigger_event_type = DeviceTriggerEventType.DEVICE_ERROR
+
+    async def event(self, *, value: Any, received_at: datetime) -> None:
+        """Handle event for which this handler has subscribed."""
+        old_value, new_value = self.write_value(value=value, write_at=received_at)
+
+        if (
+            isinstance(new_value, bool)
+            and ((old_value is None and new_value is True) or (isinstance(old_value, bool) and old_value != new_value))
+        ) or (
+            isinstance(new_value, int)
+            and ((old_value is None and new_value > 0) or (isinstance(old_value, int) and old_value != new_value))
+        ):
+            self.publish_event(value=new_value)
+
+
+class ImpulseEvent(GenericEvent):
+    """class for handling impulse events."""
+
+    __slots__ = ()
+
+    _device_trigger_event_type = DeviceTriggerEventType.IMPULSE
+
+
+@inspector(scope=ServiceScope.INTERNAL)
+def create_event_and_append_to_channel(
+    *, channel: ChannelProtocol, parameter: str, parameter_data: ParameterData
+) -> None:
+    """Create action event data_point."""
+    _LOGGER.debug(
+        "CREATE_EVENT_AND_APPEND_TO_DEVICE: Creating event for %s, %s, %s",
+        channel.address,
+        parameter,
+        channel.device.interface_id,
+    )
+    if (event_t := _determine_event_type(parameter=parameter, parameter_data=parameter_data)) and (
+        event := _safe_create_event(
+            event_t=event_t, channel=channel, parameter=parameter, parameter_data=parameter_data
+        )
+    ):
+        channel.add_data_point(data_point=event)
+
+
+def _determine_event_type(*, parameter: str, parameter_data: ParameterData) -> type[GenericEvent] | None:
+    event_t: type[GenericEvent] | None = None
+    if parameter_data["OPERATIONS"] & Operations.EVENT:
+        if parameter in CLICK_EVENTS:
+            event_t = ClickEvent
+        if parameter.startswith(DEVICE_ERROR_EVENTS):
+            event_t = DeviceErrorEvent
+        if parameter in IMPULSE_EVENTS:
+            event_t = ImpulseEvent
+    return event_t
+
+
+def _safe_create_event(
+    *,
+    event_t: type[GenericEvent],
+    channel: ChannelProtocol,
+    parameter: str,
+    parameter_data: ParameterData,
+) -> GenericEvent:
+    """Safely create a event and handle exceptions."""
+    try:
+        return event_t(
+            channel=channel,
+            parameter=parameter,
+            parameter_data=parameter_data,
+        )
+    except Exception as exc:
+        raise AioHomematicException(
+            i18n.tr(
+                key="exception.model.event.create_event.failed",
+                reason=hms.extract_exc_args(exc=exc),
+            )
+        ) from exc

aiohomematic/model/generic/__init__.py

@@ -0,0 +1,327 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2026
+"""
+Generic data points for AioHomematic.
+
+Overview
+- This subpackage provides the default, device-agnostic data point classes
+  (switch, number, sensor, select, text, button, binary_sensor) used for most
+  parameters across Homematic devices.
+- It also exposes a central factory function that selects the appropriate data
+  point class for a parameter based on its description provided by the backend.
+
+Factory
+- create_data_point_and_append_to_channel(channel, paramset_key, parameter, parameter_data)
+  inspects ParameterData (TYPE, OPERATIONS, FLAGS, etc.) to determine which
+  GenericDataPoint subclass to instantiate, creates it safely and appends it to
+  the given channel.
+
+Mapping rules (simplified)
+- TYPE==ACTION:
+  - OPERATIONS==WRITE -> DpButton (for specific button-like actions or virtual
+    remotes) else DpAction; otherwise, when also readable, treat as DpSwitch.
+- TYPE in {BOOL, ENUM, FLOAT, INTEGER, STRING} with WRITE capabilities ->
+  DpSwitch, DpSelect, DpFloat, DpInteger, DpText respectively.
+- Read-only parameters (no WRITE) become sensors; BOOL-like sensors are mapped
+  to DpBinarySensor when heuristics indicate binary semantics.
+
+Special cases
+- Virtual remote models and click parameters are recognized and mapped to
+  button-style data points.
+- Certain device/parameter combinations may be wrapped into a different
+  category (e.g., switch shown as sensor) when the parameter is not meant to be
+  user-visible or is better represented as a sensor, depending on configuration
+  and device model.
+
+Exports
+- Generic data point base and concrete types: GenericDataPoint, DpSwitch,
+  DpAction, DpButton, DpBinarySensor, DpSelect, DpFloat, DpInteger, DpText,
+  DpSensor, BaseDpNumber.
+- Factory: create_data_point_and_append_to_channel.
+
+See Also
+--------
+- aiohomematic.model.custom: Custom data points for specific devices/features.
+- aiohomematic.model.calculated: Calculated/derived data points.
+- aiohomematic.model.device: Device and channel abstractions used here.
+
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+import logging
+from typing import Final
+
+from aiohomematic import i18n, support as hms
+from aiohomematic.const import (
+    CLICK_EVENTS,
+    VIRTUAL_REMOTE_MODELS,
+    Operations,
+    Parameter,
+    ParameterData,
+    ParameterType,
+    ParamsetKey,
+    ServiceScope,
+)
+from aiohomematic.decorators import inspector
+from aiohomematic.exceptions import AioHomematicException
+from aiohomematic.interfaces.model import ChannelProtocol, GenericDataPointProtocolAny
+from aiohomematic.model.generic.action import DpAction
+from aiohomematic.model.generic.action_select import DpActionSelect
+from aiohomematic.model.generic.binary_sensor import DpBinarySensor
+from aiohomematic.model.generic.button import DpButton
+from aiohomematic.model.generic.data_point import GenericDataPoint, GenericDataPointAny
+from aiohomematic.model.generic.dummy import DpDummy
+from aiohomematic.model.generic.number import BaseDpNumber, DpFloat, DpInteger
+from aiohomematic.model.generic.select import DpSelect
+from aiohomematic.model.generic.sensor import DpSensor
+from aiohomematic.model.generic.switch import DpSwitch
+from aiohomematic.model.generic.text import DpText
+from aiohomematic.model.support import is_binary_sensor
+
+__all__ = [
+    # Base
+    "BaseDpNumber",
+    "GenericDataPoint",
+    "GenericDataPointAny",
+    # Data points
+    "DpAction",
+    "DpActionSelect",
+    "DpBinarySensor",
+    "DpButton",
+    "DpDummy",
+    "DpFloat",
+    "DpInteger",
+    "DpSelect",
+    "DpSensor",
+    "DpSwitch",
+    "DpText",
+    # Factory
+    "create_data_point_and_append_to_channel",
+]
+
+_LOGGER: Final = logging.getLogger(__name__)
+_BUTTON_ACTIONS: Final[tuple[str, ...]] = ("RESET_MOTION", "RESET_PRESENCE")
+
+
+class DataPointTypeResolver:
+    """
+    Resolver for determining data point types based on parameter characteristics.
+
+    Uses a lookup table strategy for extensible parameter type mapping.
+    This class centralizes the logic for determining which GenericDataPoint
+    subclass should be used for a given parameter.
+    """
+
+    # Mapping of parameter types to data point classes for writable parameters
+    _WRITABLE_TYPE_MAP: Final[Mapping[ParameterType, type[GenericDataPointAny]]] = {
+        ParameterType.BOOL: DpSwitch,
+        ParameterType.ENUM: DpSelect,
+        ParameterType.FLOAT: DpFloat,
+        ParameterType.INTEGER: DpInteger,
+        ParameterType.STRING: DpText,
+    }
+
+    @classmethod
+    def _resolve_action(
+        cls,
+        *,
+        channel: ChannelProtocol,
+        parameter: str,
+        parameter_data: ParameterData,
+        p_operations: int,
+    ) -> type[GenericDataPointAny]:
+        """Resolve data point type for ACTION parameters."""
+        if p_operations == Operations.WRITE:
+            # Write-only action
+            if parameter in _BUTTON_ACTIONS or channel.device.model in VIRTUAL_REMOTE_MODELS:
+                return DpButton
+            # Write-only action with value_list -> DpActionSelect
+            if parameter_data.get("VALUE_LIST"):
+                return DpActionSelect
+            return DpAction
+
+        if parameter in CLICK_EVENTS:
+            return DpButton
+
+        # Read+write action treated as switch
+        return DpSwitch
+
+    @classmethod
+    def _resolve_readonly(
+        cls,
+        *,
+        parameter: str,
+        parameter_data: ParameterData,
+    ) -> type[GenericDataPointAny] | None:
+        """Resolve data point type for read-only parameters."""
+        if parameter in CLICK_EVENTS:
+            return None
+
+        if is_binary_sensor(parameter_data=parameter_data):
+            parameter_data["TYPE"] = ParameterType.BOOL
+            return DpBinarySensor
+
+        return DpSensor
+
+    @classmethod
+    def _resolve_writable(
+        cls,
+        *,
+        channel: ChannelProtocol,
+        parameter: str,
+        parameter_data: ParameterData,
+        p_type: ParameterType,
+        p_operations: int,
+    ) -> type[GenericDataPointAny] | None:
+        """Resolve data point type for writable parameters."""
+        # Handle ACTION type specially
+        if p_type == ParameterType.ACTION:
+            return cls._resolve_action(
+                channel=channel,
+                parameter=parameter,
+                parameter_data=parameter_data,
+                p_operations=p_operations,
+            )
+
+        # Write-only non-ACTION parameters
+        if p_operations == Operations.WRITE:
+            # Write-only with value_list -> DpActionSelect
+            if parameter_data.get("VALUE_LIST"):
+                return DpActionSelect
+            return DpAction
+
+        # Use lookup table for standard types
+        return cls._WRITABLE_TYPE_MAP.get(p_type)
+
+    @classmethod
+    def resolve(
+        cls,
+        *,
+        channel: ChannelProtocol,
+        parameter: str,
+        parameter_data: ParameterData,
+    ) -> type[GenericDataPointAny] | None:
+        """
+        Determine the appropriate data point type for a parameter.
+
+        Args:
+            channel: The channel the data point belongs to.
+            parameter: The parameter name.
+            parameter_data: The parameter description from the backend.
+
+        Returns:
+            The data point class to use, or None if no match.
+
+        """
+        p_type = parameter_data["TYPE"]
+        p_operations = parameter_data["OPERATIONS"]
+
+        if p_operations & Operations.WRITE:
+            return cls._resolve_writable(
+                channel=channel,
+                parameter=parameter,
+                parameter_data=parameter_data,
+                p_type=p_type,
+                p_operations=p_operations,
+            )
+        return cls._resolve_readonly(parameter=parameter, parameter_data=parameter_data)
+
+
+# data points that should be wrapped in a new data point on a new category.
+_SWITCH_DP_TO_SENSOR: Final[Mapping[str | tuple[str, ...], Parameter]] = {
+    ("HmIP-eTRV", "HmIP-HEATING"): Parameter.LEVEL,
+}
+
+
+@inspector(scope=ServiceScope.INTERNAL)
+def create_data_point_and_append_to_channel(
+    *,
+    channel: ChannelProtocol,
+    paramset_key: ParamsetKey,
+    parameter: str,
+    parameter_data: ParameterData,
+) -> None:
+    """Decides which generic category should be used, and creates the required data points."""
+    _LOGGER.debug(
+        "CREATE_DATA_POINTS: Creating data_point for %s, %s, %s",
+        channel.address,
+        parameter,
+        channel.device.interface_id,
+    )
+
+    if (dp_t := _determine_data_point_type(channel=channel, parameter=parameter, parameter_data=parameter_data)) and (
+        dp := _safe_create_data_point(
+            dp_t=dp_t, channel=channel, paramset_key=paramset_key, parameter=parameter, parameter_data=parameter_data
+        )
+    ):
+        _LOGGER.debug(
+            "CREATE_DATA_POINT_AND_APPEND_TO_CHANNEL: %s: %s %s",
+            dp.category,
+            channel.address,
+            parameter,
+        )
+        channel.add_data_point(data_point=dp)
+        if _check_switch_to_sensor(data_point=dp):
+            dp.force_to_sensor()
+
+
+def _determine_data_point_type(
+    *, channel: ChannelProtocol, parameter: str, parameter_data: ParameterData
+) -> type[GenericDataPointAny] | None:
+    """
+    Determine the type of data point based on parameter and operations.
+
+    Delegates to DataPointTypeResolver for extensible type resolution.
+    """
+    return DataPointTypeResolver.resolve(
+        channel=channel,
+        parameter=parameter,
+        parameter_data=parameter_data,
+    )
+
+
+def _safe_create_data_point(
+    *,
+    dp_t: type[GenericDataPointAny],
+    channel: ChannelProtocol,
+    paramset_key: ParamsetKey,
+    parameter: str,
+    parameter_data: ParameterData,
+) -> GenericDataPointAny:
+    """Safely create a data point and handle exceptions."""
+    try:
+        return dp_t(
+            channel=channel,
+            paramset_key=paramset_key,
+            parameter=parameter,
+            parameter_data=parameter_data,
+        )
+    except Exception as exc:
+        raise AioHomematicException(
+            i18n.tr(
+                key="exception.model.generic.create_data_point.failed",
+                reason=hms.extract_exc_args(exc=exc),
+            )
+        ) from exc
+
+
+def _check_switch_to_sensor(*, data_point: GenericDataPointProtocolAny) -> bool:
+    """Check if parameter of a device should be wrapped to a different category."""
+    if data_point.device.parameter_visibility_provider.parameter_is_un_ignored(
+        channel=data_point.channel,
+        paramset_key=data_point.paramset_key,
+        parameter=data_point.parameter,
+    ):
+        return False
+    for devices, parameter in _SWITCH_DP_TO_SENSOR.items():
+        if (
+            hms.element_matches_key(
+                search_elements=devices,
+                compare_with=data_point.device.model,
+            )
+            and data_point.parameter == parameter
+        ):
+            return True
+    return False

aiohomematic/model/generic/action.py

@@ -0,0 +1,40 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2026
+"""
+Generic action data points for triggering operations.
+
+Public API of this module is defined by __all__.
+
+Actions are used to send data for write only parameters to backend.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from aiohomematic.const import DataPointCategory
+from aiohomematic.model.generic.data_point import GenericDataPoint
+from aiohomematic.model.support import get_index_of_value_from_value_list
+
+
+class DpAction(GenericDataPoint[None, Any]):
+    """
+    Implementation of an action.
+
+    This is an internal default category that gets automatically generated.
+    """
+
+    __slots__ = ()
+
+    _category = DataPointCategory.ACTION
+    _validate_state_change = False
+
+    def _prepare_value_for_sending(self, *, value: Any, do_validate: bool = True) -> Any:
+        """Prepare value before sending."""
+        # For string-based ENUMs (HmIP), send the string value directly.
+        # For index-based ENUMs (HM), convert string to index.
+        if self._values is not None and isinstance(value, str) and value in self._values:
+            if self._enum_value_is_index:
+                return get_index_of_value_from_value_list(value=value, value_list=self._values)
+            return value
+        return value

aiohomematic/model/generic/action_select.py

@@ -0,0 +1,62 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2026
+"""
+Generic action select data points for write-only parameters with selectable values.
+
+Public API of this module is defined by __all__.
+
+Action selects are used for write-only ENUM parameters that have a VALUE_LIST.
+They provide a value getter for displaying the current selection.
+"""
+
+from __future__ import annotations
+
+from aiohomematic import i18n
+from aiohomematic.const import DataPointCategory
+from aiohomematic.exceptions import ValidationException
+from aiohomematic.model.generic.data_point import GenericDataPoint
+from aiohomematic.model.support import get_value_from_value_list
+
+
+class DpActionSelect(GenericDataPoint[int | str | None, int | str]):
+    """
+    Implementation of an action with selectable values.
+
+    This is a write-only data point with a VALUE_LIST that provides
+    a value getter for displaying the current selection.
+    Used for ENUM parameters that are write-only but have defined values.
+    """
+
+    __slots__ = ()
+
+    _category = DataPointCategory.ACTION_SELECT
+    _validate_state_change = False
+
+    def _get_value(self) -> int | str | None:
+        """Return the value for readings."""
+        # For index-based ENUMs (HM), convert integer index to string value.
+        if (value := get_value_from_value_list(value=self._value, value_list=self.values)) is not None:
+            return value
+        # For string-based ENUMs (HmIP), return the string value directly if valid.
+        if isinstance(self._value, str) and self._values is not None and self._value in self._values:
+            return self._value
+        return self._default
+
+    def _prepare_value_for_sending(self, *, value: int | str, do_validate: bool = True) -> int | str:
+        """Prepare value before sending with validation against value_list."""
+        # We allow setting the value via index as well, just in case.
+        if isinstance(value, int | float) and self._values and 0 <= value < len(self._values):
+            return int(value)
+        if self._values and value in self._values:
+            # For string-based ENUMs (HmIP), send the string value directly.
+            # For index-based ENUMs (HM), convert string to index.
+            if self._enum_value_is_index:
+                return self._values.index(value)
+            return str(value)
+        raise ValidationException(
+            i18n.tr(
+                key="exception.model.action_select.value_not_in_value_list",
+                name=self.name,
+                unique_id=self.unique_id,
+            )
+        )

aiohomematic/model/generic/binary_sensor.py

@@ -0,0 +1,30 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2026
+"""
+Generic binary sensor data points for boolean state values.
+
+Public API of this module is defined by __all__.
+"""
+
+from __future__ import annotations
+
+from aiohomematic.const import DataPointCategory
+from aiohomematic.model.generic.data_point import GenericDataPoint
+
+
+class DpBinarySensor(GenericDataPoint[bool | None, bool]):
+    """
+    Implementation of a binary_sensor.
+
+    This is a default data point that gets automatically generated.
+    """
+
+    __slots__ = ()
+
+    _category = DataPointCategory.BINARY_SENSOR
+
+    def _get_value(self) -> bool | None:
+        """Return the value for readings."""
+        if self._value is not None:
+            return self._value
+        return self._default