aiohomematic 2025.8.6__py3-none-any.whl

aiohomematic/model/event.py

@@ -0,0 +1,210 @@
+"""
+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, callbacks) and provides fire_event handling.
+- ClickEvent: Represents key press events (EventType.KEYPRESS).
+- DeviceErrorEvent: Represents device error signaling with special value change
+  semantics before emitting 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 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,
+    EventType,
+    Operations,
+    ParameterData,
+    ParamsetKey,
+)
+from aiohomematic.decorators import inspector
+from aiohomematic.exceptions import AioHomematicException
+from aiohomematic.model import device as hmd
+from aiohomematic.model.data_point import BaseParameterDataPoint
+from aiohomematic.model.support import DataPointNameData, get_event_name
+
+__all__ = [
+    "ClickEvent",
+    "DeviceErrorEvent",
+    "GenericEvent",
+    "ImpulseEvent",
+    "create_event_and_append_to_channel",
+]
+
+_LOGGER: Final = logging.getLogger(__name__)
+
+
+class GenericEvent(BaseParameterDataPoint[Any, Any]):
+    """Base class for events."""
+
+    __slots__ = ("_event_type",)
+
+    _category = DataPointCategory.EVENT
+    _event_type: EventType
+
+    def __init__(
+        self,
+        channel: hmd.Channel,
+        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.central.name}",
+        )
+
+    @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  # pylint: disable=using-constant-test
+
+    @property
+    def event_type(self) -> EventType:
+        """Return the event_type of the event."""
+        return self._event_type
+
+    async def event(self, value: Any, received_at: datetime | None = None) -> None:
+        """Handle event for which this handler has subscribed."""
+        if received_at is None:
+            received_at = datetime.now()
+        if self.event_type in DATA_POINT_EVENTS:
+            self.fire_data_point_updated_callback()
+        self._set_modified_at(modified_at=received_at)
+        self.fire_event(value)
+
+    @loop_check
+    def fire_event(self, value: Any) -> None:
+        """Do what is needed to fire an event."""
+        self._central.fire_homematic_callback(event_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__ = ()
+
+    _event_type = EventType.KEYPRESS
+
+
+class DeviceErrorEvent(GenericEvent):
+    """class for handling device error events."""
+
+    __slots__ = ()
+
+    _event_type = EventType.DEVICE_ERROR
+
+    async def event(self, value: Any, received_at: datetime | None = None) -> None:
+        """Handle event for which this handler has subscribed."""
+        if received_at is None:
+            received_at = datetime.now()
+
+        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.fire_event(value=new_value)
+
+
+class ImpulseEvent(GenericEvent):
+    """class for handling impulse events."""
+
+    __slots__ = ()
+
+    _event_type = EventType.IMPULSE
+
+
+@inspector()
+def create_event_and_append_to_channel(channel: hmd.Channel, 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(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: hmd.Channel,
+    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(
+            f"CREATE_EVENT_AND_APPEND_TO_CHANNEL: Unable to create event:{hms.extract_exc_args(exc=exc)}"
+        ) from exc

aiohomematic/model/generic/__init__.py

@@ -0,0 +1,211 @@
+"""
+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 support as hms
+from aiohomematic.const import (
+    CLICK_EVENTS,
+    VIRTUAL_REMOTE_MODELS,
+    Operations,
+    Parameter,
+    ParameterData,
+    ParameterType,
+    ParamsetKey,
+)
+from aiohomematic.decorators import inspector
+from aiohomematic.exceptions import AioHomematicException
+from aiohomematic.model import device as hmd
+from aiohomematic.model.generic.action import DpAction
+from aiohomematic.model.generic.binary_sensor import DpBinarySensor
+from aiohomematic.model.generic.button import DpButton
+from aiohomematic.model.generic.data_point import GenericDataPoint
+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__ = [
+    "BaseDpNumber",
+    "DpAction",
+    "DpBinarySensor",
+    "DpButton",
+    "DpFloat",
+    "DpInteger",
+    "DpSelect",
+    "DpSensor",
+    "DpSwitch",
+    "DpText",
+    "GenericDataPoint",
+    "create_data_point_and_append_to_channel",
+]
+
+_LOGGER: Final = logging.getLogger(__name__)
+_BUTTON_ACTIONS: Final[tuple[str, ...]] = ("RESET_MOTION", "RESET_PRESENCE")
+
+# 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()
+def create_data_point_and_append_to_channel(
+    channel: hmd.Channel,
+    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, parameter, 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(dp)
+        if _check_switch_to_sensor(data_point=dp):
+            dp.force_to_sensor()
+
+
+def _determine_data_point_type(
+    channel: hmd.Channel, parameter: str, parameter_data: ParameterData
+) -> type[GenericDataPoint] | None:
+    """Determine the type of data point based on parameter and operations."""
+    p_type = parameter_data["TYPE"]
+    p_operations = parameter_data["OPERATIONS"]
+    dp_t: type[GenericDataPoint] | None = None
+    if p_operations & Operations.WRITE:
+        if p_type == ParameterType.ACTION:
+            if p_operations == Operations.WRITE:
+                if parameter in _BUTTON_ACTIONS or channel.device.model in VIRTUAL_REMOTE_MODELS:
+                    dp_t = DpButton
+                else:
+                    dp_t = DpAction
+            elif parameter in CLICK_EVENTS:
+                dp_t = DpButton
+            else:
+                dp_t = DpSwitch
+        elif p_operations == Operations.WRITE:
+            dp_t = DpAction
+        elif p_type == ParameterType.BOOL:
+            dp_t = DpSwitch
+        elif p_type == ParameterType.ENUM:
+            dp_t = DpSelect
+        elif p_type == ParameterType.FLOAT:
+            dp_t = DpFloat
+        elif p_type == ParameterType.INTEGER:
+            dp_t = DpInteger
+        elif p_type == ParameterType.STRING:
+            dp_t = DpText
+    elif parameter not in CLICK_EVENTS:
+        # Also check, if sensor could be a binary_sensor due to.
+        if is_binary_sensor(parameter_data):
+            parameter_data["TYPE"] = ParameterType.BOOL
+            dp_t = DpBinarySensor
+        else:
+            dp_t = DpSensor
+
+    return dp_t
+
+
+def _safe_create_data_point(
+    dp_t: type[GenericDataPoint],
+    channel: hmd.Channel,
+    paramset_key: ParamsetKey,
+    parameter: str,
+    parameter_data: ParameterData,
+) -> GenericDataPoint:
+    """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(
+            f"CREATE_DATA_POINT_AND_APPEND_TO_CHANNEL: Unable to create data_point:{hms.extract_exc_args(exc=exc)}"
+        ) from exc
+
+
+def _check_switch_to_sensor(data_point: GenericDataPoint) -> bool:
+    """Check if parameter of a device should be wrapped to a different category."""
+    if data_point.device.central.parameter_visibility.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,32 @@
+"""
+Module for action data points.
+
+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."""
+        if (index := get_index_of_value_from_value_list(value=value, value_list=self._values)) is not None:
+            return index
+        return value

aiohomematic/model/generic/binary_sensor.py

@@ -0,0 +1,28 @@
+"""Module for data points implemented using the binary_sensor category."""
+
+from __future__ import annotations
+
+from typing import cast
+
+from aiohomematic.const import DataPointCategory
+from aiohomematic.model.decorators import state_property
+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
+
+    @state_property
+    def value(self) -> bool | None:
+        """Return the value of the data_point."""
+        if self._value is not None:
+            return cast(bool | None, self._value)
+        return cast(bool | None, self._default)

aiohomematic/model/generic/button.py

@@ -0,0 +1,25 @@
+"""Module for data points implemented using the button category."""
+
+from __future__ import annotations
+
+from aiohomematic.const import DataPointCategory
+from aiohomematic.decorators import inspector
+from aiohomematic.model.generic.data_point import GenericDataPoint
+
+
+class DpButton(GenericDataPoint[None, bool]):
+    """
+    Implementation of a button.
+
+    This is a default data point that gets automatically generated.
+    """
+
+    __slots__ = ()
+
+    _category = DataPointCategory.BUTTON
+    _validate_state_change = False
+
+    @inspector()
+    async def press(self) -> None:
+        """Handle the button press."""
+        await self.send_value(value=True)

aiohomematic/model/generic/data_point.py

@@ -0,0 +1,162 @@
+"""Generic python representation of a CCU parameter."""
+
+from __future__ import annotations
+
+from datetime import datetime
+import logging
+from typing import Any, Final
+
+from aiohomematic.const import (
+    DP_KEY_VALUE,
+    CallSource,
+    DataPointUsage,
+    EventType,
+    Parameter,
+    ParameterData,
+    ParamsetKey,
+)
+from aiohomematic.decorators import inspector
+from aiohomematic.model import data_point as hme, device as hmd
+from aiohomematic.model.decorators import cached_slot_property
+from aiohomematic.model.support import DataPointNameData, GenericParameterType, get_data_point_name_data
+
+_LOGGER: Final = logging.getLogger(__name__)
+
+
+class GenericDataPoint[ParameterT: GenericParameterType, InputParameterT: GenericParameterType](
+    hme.BaseParameterDataPoint
+):
+    """Base class for generic data point."""
+
+    __slots__ = ("_cached_usage",)
+
+    _validate_state_change: bool = True
+    is_hmtype: Final = True
+
+    def __init__(
+        self,
+        channel: hmd.Channel,
+        paramset_key: ParamsetKey,
+        parameter: str,
+        parameter_data: ParameterData,
+    ) -> None:
+        """Init the generic data_point."""
+        super().__init__(
+            channel=channel,
+            paramset_key=paramset_key,
+            parameter=parameter,
+            parameter_data=parameter_data,
+        )
+
+    @cached_slot_property
+    def usage(self) -> DataPointUsage:
+        """Return the data_point usage."""
+        if self._is_forced_sensor or self._is_un_ignored:
+            return DataPointUsage.DATA_POINT
+        if (force_enabled := self._enabled_by_channel_operation_mode) is None:
+            return self._get_data_point_usage()
+        return DataPointUsage.DATA_POINT if force_enabled else DataPointUsage.NO_CREATE  # pylint: disable=using-constant-test
+
+    async def event(self, value: Any, received_at: datetime | None = None) -> None:
+        """Handle event for which this data_point has subscribed."""
+        if received_at is None:
+            received_at = datetime.now()
+        self._device.client.last_value_send_cache.remove_last_value_send(
+            dpk=self.dpk,
+            value=value,
+        )
+        old_value, new_value = self.write_value(value=value, write_at=received_at)
+        if old_value == new_value:
+            return
+
+        # reload paramset_descriptions, if value has changed
+        if self._parameter == Parameter.CONFIG_PENDING and new_value is False and old_value is True:
+            await self._device.reload_paramset_descriptions()
+
+            for dp in self._device.get_readable_data_points(paramset_key=ParamsetKey.MASTER):
+                await dp.load_data_point_value(call_source=CallSource.MANUAL_OR_SCHEDULED, direct_call=True)
+
+        # send device availability events
+        if self._parameter in (
+            Parameter.UN_REACH,
+            Parameter.STICKY_UN_REACH,
+        ):
+            self._device.fire_device_updated_callback(self._unique_id)
+            self._central.fire_homematic_callback(
+                event_type=EventType.DEVICE_AVAILABILITY,
+                event_data=self.get_event_data(new_value),
+            )
+
+    @inspector()
+    async def send_value(
+        self,
+        value: InputParameterT,
+        collector: hme.CallParameterCollector | None = None,
+        collector_order: int = 50,
+        do_validate: bool = True,
+    ) -> set[DP_KEY_VALUE]:
+        """Send value to ccu, or use collector if set."""
+        if not self.is_writeable:
+            _LOGGER.error("SEND_VALUE: writing to non-writable data_point %s is not possible", self.full_name)
+            return set()
+        try:
+            prepared_value = self._prepare_value_for_sending(value=value, do_validate=do_validate)
+        except ValueError as verr:
+            _LOGGER.warning(verr)
+            return set()
+
+        converted_value = self._convert_value(value=prepared_value)
+        if collector:
+            collector.add_data_point(self, value=converted_value, collector_order=collector_order)
+            return set()
+
+        if self._validate_state_change and not self.is_state_change(value=converted_value):
+            return set()
+
+        return await self._client.set_value(
+            channel_address=self._channel.address,
+            paramset_key=self._paramset_key,
+            parameter=self._parameter,
+            value=converted_value,
+        )
+
+    def _prepare_value_for_sending(self, value: InputParameterT, do_validate: bool = True) -> ParameterT:
+        """Prepare value, if required, before send."""
+        return value  # type: ignore[return-value]
+
+    def _get_data_point_name(self) -> DataPointNameData:
+        """Create the name for the data_point."""
+        return get_data_point_name_data(
+            channel=self._channel,
+            parameter=self._parameter,
+        )
+
+    def _get_data_point_usage(self) -> DataPointUsage:
+        """Generate the usage for the data_point."""
+        if self._forced_usage:
+            return self._forced_usage
+        if self._central.parameter_visibility.parameter_is_hidden(
+            channel=self._channel,
+            paramset_key=self._paramset_key,
+            parameter=self._parameter,
+        ):
+            return DataPointUsage.NO_CREATE
+
+        return (
+            DataPointUsage.NO_CREATE
+            if (self._device.has_custom_data_point_definition and not self._device.allow_undefined_generic_data_points)
+            else DataPointUsage.DATA_POINT
+        )
+
+    def is_state_change(self, value: ParameterT) -> bool:
+        """
+        Check if the state/value changes.
+
+        If the state is uncertain, the state should also marked as changed.
+        """
+        if value != self._value:
+            return True
+        if self.state_uncertain:
+            return True
+        _LOGGER.debug("NO_STATE_CHANGE: %s", self.name)
+        return False