aiohomematic 2025.11.3__py3-none-any.whl

aiohomematic/model/generic/dummy.py

@@ -0,0 +1,147 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2025
+"""
+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 entity.
+- 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.model import device as hmd
+from aiohomematic.model.data_point import CallParameterCollector
+from aiohomematic.model.generic.data_point import GenericDataPoint
+from aiohomematic.model.support import DataPointNameData
+
+
+class DpDummy(GenericDataPoint[Any, Any]):
+    """
+    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: hmd.Channel, 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=(),
+            ),
+        )
+
+    # --- Metadata and identity -------------------------------------------
+    @property
+    def usage(self) -> DataPointUsage:
+        """Never create/ expose this data point as a real entity."""
+        return DataPointUsage.NO_CREATE
+
+    @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 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 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 value(self) -> Any:
+        """Return the value of the data_point."""
+        return None
+
+    # Optional: provide a stable, recognizable name to aid debugging
+    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}",
+        )
+
+    # --- Backend interactions (all no-ops) --------------------------------
+    async def event(self, *, value: Any, received_at: datetime) -> None:
+        """Ignore backend events entirely."""
+        return
+
+    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()

aiohomematic/model/generic/number.py

@@ -0,0 +1,76 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2025
+"""Module for data points implemented using the number category."""
+
+from __future__ import annotations
+
+from typing import cast
+
+from aiohomematic.const import DataPointCategory
+from aiohomematic.exceptions import ValidationException
+from aiohomematic.model.generic.data_point import GenericDataPoint
+from aiohomematic.property_decorators import state_property
+
+
+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(
+            f"NUMBER failed: Invalid 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)
+
+    @state_property
+    def value(self) -> float | None:
+        """Return the value of the data_point."""
+        return cast(float | None, self._value)
+
+
+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)
+
+    @state_property
+    def value(self) -> int | None:
+        """Return the value of the data_point."""
+        return cast(int | None, self._value)

aiohomematic/model/generic/select.py

@@ -0,0 +1,39 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2025
+"""Module for data points implemented using the select category."""
+
+from __future__ import annotations
+
+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
+from aiohomematic.property_decorators import state_property
+
+
+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
+
+    @state_property
+    def value(self) -> str | None:
+        """Get the value of the data_point."""
+        if (value := get_value_from_value_list(value=self._value, value_list=self.values)) is not None:
+            return value
+        return str(self._default)
+
+    def _prepare_value_for_sending(self, *, value: int | float | str, do_validate: bool = True) -> int:
+        """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:
+            return self._values.index(value)
+        raise ValidationException(f"Value not in value_list for {self.name}/{self.unique_id}")

aiohomematic/model/generic/sensor.py

@@ -0,0 +1,74 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2025
+"""Module for data points implemented using the sensor category."""
+
+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
+from aiohomematic.property_decorators import state_property
+
+_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
+
+    @state_property
+    def value(self) -> SensorT:
+        """Return the value."""
+        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 _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 _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-2025
+"""Module for data points implemented using the switch category."""
+
+from __future__ import annotations
+
+from typing import cast
+
+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
+from aiohomematic.property_decorators import state_property
+
+
+class DpSwitch(GenericDataPoint[bool | None, bool]):
+    """
+    Implementation of a switch.
+
+    This is a default data point that gets automatically generated.
+    """
+
+    __slots__ = ()
+
+    _category = DataPointCategory.SWITCH
+
+    @state_property
+    def value(self) -> bool | None:
+        """Get the value of the data_point."""
+        if self._type == ParameterType.ACTION:
+            return False
+        return cast(bool | None, self._value)
+
+    @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)
+
+    @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 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),
+        )

aiohomematic/model/generic/text.py

@@ -0,0 +1,29 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2025
+"""Module for data points implemented using the text category."""
+
+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
+from aiohomematic.property_decorators import state_property
+
+
+class DpText(GenericDataPoint[str, str]):
+    """
+    Implementation of a text.
+
+    This is a default data point that gets automatically generated.
+    """
+
+    __slots__ = ()
+
+    _category = DataPointCategory.TEXT
+
+    @state_property
+    def value(self) -> str | None:
+        """Get the value of the data_point."""
+        return cast(str | None, check_length_and_log(name=self.name, value=self._value))