aiohomematic 2026.1.29__py3-none-any.whl

aiohomematic/model/generic/button.py

@@ -0,0 +1,31 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2026
+"""
+Generic button data points for momentary press actions.
+
+Public API of this module is defined by __all__.
+"""
+
+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,177 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2026
+"""
+Base implementation for generic data points.
+
+Public API of this module is defined by __all__.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+import logging
+from typing import Any, Final, TypeAlias
+
+from aiohomematic import i18n
+from aiohomematic.central.events import DeviceLifecycleEvent, DeviceLifecycleEventType
+from aiohomematic.const import DP_KEY_VALUE, DataPointUsage, Parameter, ParameterData, ParamsetKey
+from aiohomematic.decorators import inspector
+from aiohomematic.exceptions import ValidationException
+from aiohomematic.interfaces import ChannelProtocol, GenericDataPointProtocol
+from aiohomematic.model import data_point as hme
+from aiohomematic.model.support import DataPointNameData, get_data_point_name_data
+from aiohomematic.property_decorators import hm_property
+from aiohomematic.type_aliases import ParamType
+
+_LOGGER: Final = logging.getLogger(__name__)
+
+
+class GenericDataPoint[ParameterT: ParamType, InputParameterT: ParamType](
+    hme.BaseParameterDataPoint[ParameterT, InputParameterT],
+    GenericDataPointProtocol[ParameterT | None],
+):
+    """Base class for generic data point."""
+
+    __slots__ = ("_cached_usage",)
+
+    _validate_state_change: bool = True
+    is_hmtype: bool = True
+
+    def __init__(
+        self,
+        *,
+        channel: ChannelProtocol,
+        paramset_key: ParamsetKey,
+        parameter: str,
+        parameter_data: ParameterData,
+    ) -> None:
+        """Initialize the generic data_point."""
+        super().__init__(
+            channel=channel,
+            paramset_key=paramset_key,
+            parameter=parameter,
+            parameter_data=parameter_data,
+        )
+
+    @hm_property(cached=True)
+    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:
+        """Handle event for which this data_point has subscribed."""
+        self._device.client.last_value_send_tracker.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
+
+        if self._parameter == Parameter.CONFIG_PENDING and new_value is False and old_value is True:
+            # do what is needed on device config change.
+            await self._device.on_config_changed()
+
+        # send device availability events
+        if self._parameter in (
+            Parameter.UN_REACH,
+            Parameter.STICKY_UN_REACH,
+        ):
+            # notify_data_points=True ensures entities on all channels refresh their availability
+            self._device.publish_device_updated_event(notify_data_points=True)
+            await self._event_bus_provider.event_bus.publish(
+                event=DeviceLifecycleEvent(
+                    timestamp=datetime.now(),
+                    event_type=DeviceLifecycleEventType.AVAILABILITY_CHANGED,
+                    availability_changes=((self._device.address, new_value is False),),
+                )
+            )
+
+    def is_state_change(self, *, value: ParameterT | None) -> 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
+
+    @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_writable:
+            _LOGGER.error(
+                i18n.tr(
+                    key="log.model.generic_data_point.send_value.not_writable",
+                    full_name=self.full_name,
+                )
+            )
+            return set()
+        try:
+            prepared_value = self._prepare_value_for_sending(value=value, do_validate=do_validate)
+        except (ValueError, ValidationException) as verr:
+            _LOGGER.warning(verr)
+            return set()
+
+        converted_value = self._convert_value(value=prepared_value)
+        # if collector is set, then add value to collector
+        if collector:
+            collector.add_data_point(data_point=self, value=converted_value, collector_order=collector_order)
+            return set()
+
+        # if collector is not set, then send value directly
+        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 _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._parameter_visibility_provider.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 _prepare_value_for_sending(self, *, value: InputParameterT, do_validate: bool = True) -> ParameterT:
+        """Prepare value, if required, before send."""
+        return value  # type: ignore[return-value]
+
+
+GenericDataPointAny: TypeAlias = GenericDataPoint[Any, Any]

aiohomematic/model/generic/dummy.py

@@ -0,0 +1,150 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2026
+"""
+Dummy generic data point (backend-detached placeholder).
+
+This class derives from `GenericDataPoint` but overrides all methods that would
+normally interact with the backend so it behaves like an inert data point that
+uses safe default values only.
+The DpDummy class is intended to be used as a placeholder for custom data
+points that are not implemented in the backend.
+
+Key properties:
+- It never triggers backend I/O (no reads, no writes, no subscriptions).
+- It always reports `usage = DataPointUsage.NO_CREATE` so it is not created as a
+  real data point.
+- It is not readable or writable and does not require polling nor support
+  events.
+- It exposes safe, static defaults for metadata and state.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, cast
+
+from aiohomematic.const import (
+    DP_KEY_VALUE,
+    INIT_DATETIME,
+    CallSource,
+    DataPointKey,
+    DataPointUsage,
+    Field,
+    ParameterData,
+    ParameterType,
+    ParamsetKey,
+)
+from aiohomematic.decorators import inspector
+from aiohomematic.interfaces import ChannelProtocol
+from aiohomematic.model.data_point import CallParameterCollector
+from aiohomematic.model.generic.data_point import GenericDataPointAny
+from aiohomematic.model.support import DataPointNameData
+from aiohomematic.property_decorators import Kind, _GenericProperty
+
+
+class DpDummy(GenericDataPointAny):
+    """
+    Backend-detached `GenericDataPoint` using only default values.
+
+    All backend-touching operations are overridden to be no-ops.
+    """
+
+    __slots__ = ()
+
+    is_hmtype = False
+
+    def __init__(self, *, channel: ChannelProtocol, param_field: str | Field) -> None:
+        """
+        Initialize the dummy data point.
+
+        We still call `super().__init__` to get a valid object layout, but all
+        runtime behavior that would contact the backend is disabled via
+        overrides below.
+        """
+        super().__init__(
+            channel=channel,
+            paramset_key=ParamsetKey.DUMMY,
+            parameter=f"DUMMY-{str(param_field)}",
+            parameter_data=ParameterData(
+                DEFAULT=None,
+                FLAGS=0,
+                ID="0",
+                MAX=None,
+                MIN=None,
+                OPERATIONS=0,
+                SPECIAL={},
+                TYPE=ParameterType.DUMMY,
+                UNIT="",
+                VALUE_LIST=(),
+            ),
+        )
+
+    @property
+    def dpk(self) -> DataPointKey:
+        """Return a stable placeholder data point key."""
+        # Return a stable placeholder key so equality/set operations are safe.
+        return cast(DataPointKey, ("", "", ""))
+
+    @property
+    def modified_at(self) -> datetime:
+        """Never report modification timestamp for this data point."""
+        return INIT_DATETIME
+
+    @property
+    def refreshed_at(self) -> datetime:
+        """Never report refresh timestamp for this data point."""
+        return INIT_DATETIME
+
+    @property
+    def requires_polling(self) -> bool:
+        """Never poll from this data point."""
+        return False
+
+    @property
+    def state_uncertain(self) -> bool:
+        """Never report state uncertainty for this data point."""
+        return True
+
+    @property
+    def usage(self) -> DataPointUsage:
+        """Never create/ expose this data point as a real data point."""
+        return DataPointUsage.NO_CREATE
+
+    async def event(self, *, value: Any, received_at: datetime) -> None:
+        """Ignore backend events entirely."""
+        return
+
+    @inspector(re_raise=False)
+    async def load_data_point_value(self, *, call_source: CallSource, direct_call: bool = False) -> None:
+        """Do not read from backend; keep defaults as-is."""
+        return
+
+    async def send_value(
+        self,
+        *,
+        value: Any,
+        collector: CallParameterCollector | None = None,
+        collector_order: int = 50,
+        do_validate: bool = True,
+    ) -> set[DP_KEY_VALUE]:
+        """Do not write to backend; accept but perform no operation."""
+        return set()
+
+    def _get_data_point_name(self) -> DataPointNameData:
+        """Return a stable, recognizable name to aid debugging."""
+        name = super()._get_data_point_name()
+        # Replace parameter part with a dummy marker without touching address
+        return DataPointNameData(
+            device_name=f"DUMMY_{name.name}",
+            channel_name=f"DUMMY_{name.full_name}",
+            parameter_name=f"DUMMY_{name.parameter_name}",
+        )
+
+    def _get_value(self) -> Any:
+        """Return the value of the data_point."""
+        return None
+
+    def _set_value(self, value: Any) -> None:  # kwonly: disable
+        """Ignore setting value for dummy data point."""
+
+    value: _GenericProperty[Any, Any] = _GenericProperty(fget=_get_value, fset=_set_value, kind=Kind.STATE)

aiohomematic/model/generic/number.py

@@ -0,0 +1,76 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2026
+"""
+Generic number data points for numeric input values.
+
+Public API of this module is defined by __all__.
+"""
+
+from __future__ import annotations
+
+from typing import cast
+
+from aiohomematic import i18n
+from aiohomematic.const import DataPointCategory
+from aiohomematic.exceptions import ValidationException
+from aiohomematic.model.generic.data_point import GenericDataPoint
+
+
+class BaseDpNumber[NumberParameterT: int | float | None](GenericDataPoint[NumberParameterT, int | float | str]):
+    """
+    Implementation of a number.
+
+    This is a default data point that gets automatically generated.
+    """
+
+    __slots__ = ()
+
+    _category = DataPointCategory.NUMBER
+
+    def _prepare_number_for_sending(
+        self, *, value: int | float | str, type_converter: type, do_validate: bool = True
+    ) -> NumberParameterT:
+        """Prepare value before sending."""
+        if not do_validate or (
+            value is not None and isinstance(value, int | float) and self._min <= type_converter(value) <= self._max
+        ):
+            return cast(NumberParameterT, type_converter(value))
+        if self._special and isinstance(value, str) and value in self._special:
+            return cast(NumberParameterT, type_converter(self._special[value]))
+        raise ValidationException(
+            i18n.tr(
+                key="exception.model.number.invalid_value",
+                value=value,
+                min=self._min,
+                max=self._max,
+                special=self._special,
+            )
+        )
+
+
+class DpFloat(BaseDpNumber[float | None]):
+    """
+    Implementation of a Float.
+
+    This is a default data point that gets automatically generated.
+    """
+
+    __slots__ = ()
+
+    def _prepare_value_for_sending(self, *, value: int | float | str, do_validate: bool = True) -> float | None:
+        """Prepare value before sending."""
+        return self._prepare_number_for_sending(value=value, type_converter=float, do_validate=do_validate)
+
+
+class DpInteger(BaseDpNumber[int | None]):
+    """
+    Implementation of an Integer.
+
+    This is a default data point that gets automatically generated.
+    """
+
+    __slots__ = ()
+
+    def _prepare_value_for_sending(self, *, value: int | float | str, do_validate: bool = True) -> int | None:
+        """Prepare value before sending."""
+        return self._prepare_number_for_sending(value=value, type_converter=int, do_validate=do_validate)

aiohomematic/model/generic/select.py

@@ -0,0 +1,56 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2026
+"""
+Generic select data points for dropdown selection values.
+
+Public API of this module is defined by __all__.
+"""
+
+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 DpSelect(GenericDataPoint[int | str, int | float | str]):
+    """
+    Implementation of a select data_point.
+
+    This is a default data point that gets automatically generated.
+    """
+
+    __slots__ = ()
+
+    _category = DataPointCategory.SELECT
+
+    def _get_value(self) -> int | str:
+        """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 | float | str, do_validate: bool = True) -> int | str:
+        """Prepare value before sending."""
+        # 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.select.value_not_in_value_list",
+                name=self.name,
+                unique_id=self.unique_id,
+            )
+        )

aiohomematic/model/generic/sensor.py

@@ -0,0 +1,76 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2026
+"""
+Generic sensor data points for numeric and text values.
+
+Public API of this module is defined by __all__.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+import logging
+from typing import Any, Final, cast
+
+from aiohomematic.const import DataPointCategory, Parameter, ParameterType
+from aiohomematic.model.generic.data_point import GenericDataPoint
+from aiohomematic.model.support import check_length_and_log, get_value_from_value_list
+
+_LOGGER: Final = logging.getLogger(__name__)
+
+
+class DpSensor[SensorT: float | int | str | None](GenericDataPoint[SensorT, None]):
+    """
+    Implementation of a sensor.
+
+    This is a default data point that gets automatically generated.
+    """
+
+    __slots__ = ()
+
+    _category = DataPointCategory.SENSOR
+
+    def _get_converter_func(self) -> Any:
+        """Return a converter based on sensor."""
+        if convert_func := _VALUE_CONVERTERS_BY_PARAM.get(self.parameter):
+            return convert_func
+        return None
+
+    def _get_value(self) -> SensorT:
+        """Return the value for readings."""
+        if (value := get_value_from_value_list(value=self._value, value_list=self.values)) is not None:
+            return cast(SensorT, value)
+        if convert_func := self._get_converter_func():
+            return cast(SensorT, convert_func(value=self._value))
+        return cast(
+            SensorT,
+            check_length_and_log(name=self.name, value=self._value)
+            if self._type == ParameterType.STRING
+            else self._value,
+        )
+
+
+def _fix_rssi(*, value: Any) -> int | None:
+    """
+    Fix rssi value.
+
+    See https://github.com/sukramj/aiohomematic/blob/devel/docs/rssi_fix.md.
+    """
+    if value is None:
+        return None
+    if isinstance(value, int):
+        if -127 < value < 0:
+            return value
+        if 1 < value < 127:
+            return value * -1
+        if -256 < value < -129:
+            return (value * -1) - 256
+        if 129 < value < 256:
+            return value - 256
+    return None
+
+
+_VALUE_CONVERTERS_BY_PARAM: Mapping[str, Any] = {
+    Parameter.RSSI_PEER: _fix_rssi,
+    Parameter.RSSI_DEVICE: _fix_rssi,
+}

aiohomematic/model/generic/switch.py

@@ -0,0 +1,54 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2026
+"""
+Generic switch data points for toggle operations.
+
+Public API of this module is defined by __all__.
+"""
+
+from __future__ import annotations
+
+from aiohomematic.const import DataPointCategory, Parameter, ParameterType
+from aiohomematic.decorators import inspector
+from aiohomematic.model.data_point import CallParameterCollector
+from aiohomematic.model.generic.data_point import GenericDataPoint
+
+
+class DpSwitch(GenericDataPoint[bool | None, bool]):
+    """
+    Implementation of a switch.
+
+    This is a default data point that gets automatically generated.
+    """
+
+    __slots__ = ()
+
+    _category = DataPointCategory.SWITCH
+
+    @inspector
+    async def set_on_time(self, *, on_time: float) -> None:
+        """Set the on time value in seconds."""
+        await self._client.set_value(
+            channel_address=self._channel.address,
+            paramset_key=self._paramset_key,
+            parameter=Parameter.ON_TIME,
+            value=float(on_time),
+        )
+
+    @inspector
+    async def turn_off(self, *, collector: CallParameterCollector | None = None) -> None:
+        """Turn the switch off."""
+        await self.send_value(value=False, collector=collector)
+
+    @inspector
+    async def turn_on(self, *, on_time: float | None = None, collector: CallParameterCollector | None = None) -> None:
+        """Turn the switch on."""
+        if on_time is not None:
+            await self.set_on_time(on_time=on_time)
+        await self.send_value(value=True, collector=collector)
+
+    def _get_value(self) -> bool | None:
+        """Return the value for readings."""
+        if self._type == ParameterType.ACTION:
+            return False
+        return self._value

aiohomematic/model/generic/text.py

@@ -0,0 +1,33 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2026
+"""
+Generic text data points for string input values.
+
+Public API of this module is defined by __all__.
+"""
+
+from __future__ import annotations
+
+from typing import cast
+
+from aiohomematic.const import DataPointCategory
+from aiohomematic.model.generic.data_point import GenericDataPoint
+from aiohomematic.model.support import check_length_and_log
+
+
+class DpText(GenericDataPoint[str, str]):
+    """
+    Implementation of a text.
+
+    This is a default data point that gets automatically generated.
+    """
+
+    __slots__ = ()
+
+    _category = DataPointCategory.TEXT
+
+    def _get_value(self) -> str:
+        """Return the value for readings."""
+        if (val := check_length_and_log(name=self.name, value=self._value)) is not None:
+            return cast(str, val)
+        return self._default