aiohomematic 2025.8.6__py3-none-any.whl

aiohomematic/model/__init__.py

@@ -0,0 +1,137 @@
+"""
+Data point and event model for AioHomematic.
+
+This package wires together the model subpackages that turn device/channel
+parameter descriptions into concrete data points and events:
+- generic: Default data point types (switch, number, sensor, select, etc.).
+- custom: Higher-level composites and device-specific behaviors.
+- calculated: Derived metrics (e.g., dew point, apparent temperature).
+- hub: Program and system variable data points from the backend hub (CCU/Homegear).
+
+The create_data_points_and_events entrypoint inspects a device’s paramset
+information, applies visibility rules, creates events where appropriate, and
+instantiates the required data point objects. It is invoked during device
+initialization to populate the runtime model used by the central unit.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Final
+
+from aiohomematic.const import (
+    CLICK_EVENTS,
+    DEVICE_ERROR_EVENTS,
+    IMPULSE_EVENTS,
+    Flag,
+    Operations,
+    Parameter,
+    ParameterData,
+    ParamsetKey,
+)
+from aiohomematic.decorators import inspector
+from aiohomematic.model import device as hmd
+from aiohomematic.model.calculated import create_calculated_data_points
+from aiohomematic.model.event import create_event_and_append_to_channel
+from aiohomematic.model.generic import create_data_point_and_append_to_channel
+
+__all__ = ["create_data_points_and_events"]
+
+# Some parameters are marked as INTERNAL in the paramset and not considered by default,
+# but some are required and should be added here.
+_ALLOWED_INTERNAL_PARAMETERS: Final[tuple[Parameter, ...]] = (Parameter.DIRECTION,)
+_LOGGER: Final = logging.getLogger(__name__)
+
+
+@inspector()
+def create_data_points_and_events(device: hmd.Device) -> None:
+    """Create the data points associated to this device."""
+    for channel in device.channels.values():
+        for paramset_key, paramsset_key_descriptions in channel.paramset_descriptions.items():
+            if not device.central.parameter_visibility.is_relevant_paramset(
+                channel=channel,
+                paramset_key=paramset_key,
+            ):
+                continue
+            for (
+                parameter,
+                parameter_data,
+            ) in paramsset_key_descriptions.items():
+                parameter_is_un_ignored = channel.device.central.parameter_visibility.parameter_is_un_ignored(
+                    channel=channel,
+                    paramset_key=paramset_key,
+                    parameter=parameter,
+                )
+                if channel.device.central.parameter_visibility.should_skip_parameter(
+                    channel=channel,
+                    paramset_key=paramset_key,
+                    parameter=parameter,
+                    parameter_is_un_ignored=parameter_is_un_ignored,
+                ):
+                    continue
+                _process_parameter(
+                    channel=channel,
+                    paramset_key=paramset_key,
+                    parameter=parameter,
+                    parameter_data=parameter_data,
+                    parameter_is_un_ignored=parameter_is_un_ignored,
+                )
+
+        create_calculated_data_points(channel=channel)
+
+
+def _process_parameter(
+    channel: hmd.Channel,
+    paramset_key: ParamsetKey,
+    parameter: str,
+    parameter_data: ParameterData,
+    parameter_is_un_ignored: bool,
+) -> None:
+    """Process individual parameter to create data points and events."""
+
+    if paramset_key == ParamsetKey.MASTER and parameter_data["OPERATIONS"] == 0:
+        # required to fix hm master paramset operation values
+        parameter_data["OPERATIONS"] = 3
+
+    if _should_create_event(parameter_data=parameter_data, parameter=parameter):
+        create_event_and_append_to_channel(
+            channel=channel,
+            parameter=parameter,
+            parameter_data=parameter_data,
+        )
+    if _should_skip_data_point(
+        parameter_data=parameter_data, parameter=parameter, parameter_is_un_ignored=parameter_is_un_ignored
+    ):
+        _LOGGER.debug(
+            "CREATE_DATA_POINTS: Skipping %s (no event or internal)",
+            parameter,
+        )
+        return
+    # CLICK_EVENTS are allowed for Buttons
+    if parameter not in IMPULSE_EVENTS and (not parameter.startswith(DEVICE_ERROR_EVENTS) or parameter_is_un_ignored):
+        create_data_point_and_append_to_channel(
+            channel=channel,
+            paramset_key=paramset_key,
+            parameter=parameter,
+            parameter_data=parameter_data,
+        )
+
+
+def _should_create_event(parameter_data: ParameterData, parameter: str) -> bool:
+    """Determine if an event should be created for the parameter."""
+    return bool(
+        parameter_data["OPERATIONS"] & Operations.EVENT
+        and (parameter in CLICK_EVENTS or parameter.startswith(DEVICE_ERROR_EVENTS) or parameter in IMPULSE_EVENTS)
+    )
+
+
+def _should_skip_data_point(parameter_data: ParameterData, parameter: str, parameter_is_un_ignored: bool) -> bool:
+    """Determine if a data point should be skipped."""
+    return bool(
+        (not parameter_data["OPERATIONS"] & Operations.EVENT and not parameter_data["OPERATIONS"] & Operations.WRITE)
+        or (
+            parameter_data["FLAGS"] & Flag.INTERNAL
+            and parameter not in _ALLOWED_INTERNAL_PARAMETERS
+            and not parameter_is_un_ignored
+        )
+    )

aiohomematic/model/calculated/__init__.py

@@ -0,0 +1,65 @@
+"""
+Calculated (derived) data points for AioHomematic.
+
+This subpackage provides data points whose values are computed from one or more
+underlying device data points. Typical examples include climate-related metrics
+(such as dew point, apparent temperature, frost point, vapor concentration) and
+battery/voltage related assessments (such as operating voltage level).
+
+How it works:
+- Each calculated data point is a lightweight model that subscribes to one or
+  more generic data points of a channel and recomputes its value when any of
+  the source data points change.
+- Relevance is determined per channel. A calculated data point class exposes an
+  "is_relevant_for_model" method that decides if the channel provides the
+  necessary inputs.
+- Creation is handled centrally via the factory function below.
+
+Factory:
+- create_calculated_data_points(channel): Iterates over the known calculated
+  implementations, checks their relevance against the given channel, and, if
+  applicable, creates and attaches instances to the channel so they behave like
+  normal read-only data points.
+
+Modules/classes:
+- ApparentTemperature, DewPoint, FrostPoint, VaporConcentration: Climate-related
+  sensors implemented in climate.py using well-known formulas (see
+  aiohomematic.model.calculated.support for details and references).
+- OperatingVoltageLevel: Interprets battery/voltage values and exposes a human
+  readable operating level classification.
+
+These calculated data points complement generic and custom data points by
+exposing useful metrics not directly provided by the device/firmware.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Final
+
+from aiohomematic.decorators import inspector
+from aiohomematic.model import device as hmd
+from aiohomematic.model.calculated.climate import ApparentTemperature, DewPoint, FrostPoint, VaporConcentration
+from aiohomematic.model.calculated.data_point import CalculatedDataPoint
+from aiohomematic.model.calculated.operating_voltage_level import OperatingVoltageLevel
+
+__all__ = [
+    "ApparentTemperature",
+    "CalculatedDataPoint",
+    "DewPoint",
+    "FrostPoint",
+    "OperatingVoltageLevel",
+    "VaporConcentration",
+    "create_calculated_data_points",
+]
+
+_CALCULATED_DATA_POINTS: Final = (ApparentTemperature, DewPoint, FrostPoint, OperatingVoltageLevel, VaporConcentration)
+_LOGGER: Final = logging.getLogger(__name__)
+
+
+@inspector()
+def create_calculated_data_points(channel: hmd.Channel) -> None:
+    """Decides which data point category should be used, and creates the required data points."""
+    for cdp in _CALCULATED_DATA_POINTS:
+        if cdp.is_relevant_for_model(channel=channel):
+            channel.add_data_point(data_point=cdp(channel=channel))

aiohomematic/model/calculated/climate.py

@@ -0,0 +1,230 @@
+"""Module for calculating the apparent temperature in the sensor category."""
+
+from __future__ import annotations
+
+import logging
+from typing import Final
+
+from aiohomematic.const import CalulatedParameter, DataPointCategory, Parameter, ParameterType, ParamsetKey
+from aiohomematic.model import device as hmd
+from aiohomematic.model.calculated.data_point import CalculatedDataPoint
+from aiohomematic.model.calculated.support import (
+    calculate_apparent_temperature,
+    calculate_dew_point,
+    calculate_frost_point,
+    calculate_vapor_concentration,
+)
+from aiohomematic.model.decorators import state_property
+from aiohomematic.model.generic import DpSensor
+from aiohomematic.support import element_matches_key
+
+_LOGGER: Final = logging.getLogger(__name__)
+
+
+class BaseClimateSensor[SensorT: float | None](CalculatedDataPoint[SensorT]):
+    """Implementation of a calculated climate sensor."""
+
+    __slots__ = (
+        "_dp_temperature",
+        "_dp_humidity",
+        "_dp_wind_speed",
+    )
+
+    _category = DataPointCategory.SENSOR
+
+    def __init__(self, channel: hmd.Channel) -> None:
+        """Initialize the data point."""
+
+        super().__init__(channel=channel)
+        self._type = ParameterType.FLOAT
+
+    def _init_data_point_fields(self) -> None:
+        """Init the data point fields."""
+        super()._init_data_point_fields()
+        self._dp_temperature: DpSensor = (
+            self._add_data_point(
+                parameter=Parameter.TEMPERATURE, paramset_key=ParamsetKey.VALUES, data_point_type=DpSensor
+            )
+            if self._channel.get_generic_data_point(parameter=Parameter.TEMPERATURE, paramset_key=ParamsetKey.VALUES)
+            else self._add_data_point(
+                parameter=Parameter.ACTUAL_TEMPERATURE, paramset_key=ParamsetKey.VALUES, data_point_type=DpSensor
+            )
+        )
+        self._dp_humidity: DpSensor = (
+            self._add_data_point(
+                parameter=Parameter.HUMIDITY, paramset_key=ParamsetKey.VALUES, data_point_type=DpSensor
+            )
+            if self._channel.get_generic_data_point(parameter=Parameter.HUMIDITY, paramset_key=ParamsetKey.VALUES)
+            else self._add_data_point(
+                parameter=Parameter.ACTUAL_HUMIDITY, paramset_key=ParamsetKey.VALUES, data_point_type=DpSensor
+            )
+        )
+
+
+class ApparentTemperature(BaseClimateSensor):
+    """Implementation of a calculated sensor for apparent temperature."""
+
+    __slots__ = ()
+
+    _calculated_parameter = CalulatedParameter.APPARENT_TEMPERATURE
+
+    def __init__(self, channel: hmd.Channel) -> None:
+        """Initialize the data point."""
+        super().__init__(channel=channel)
+        self._unit = "°C"
+
+    def _init_data_point_fields(self) -> None:
+        """Init the data point fields."""
+        super()._init_data_point_fields()
+        self._dp_wind_speed: DpSensor = self._add_data_point(
+            parameter=Parameter.WIND_SPEED, paramset_key=ParamsetKey.VALUES, data_point_type=DpSensor
+        )
+
+    @staticmethod
+    def is_relevant_for_model(channel: hmd.Channel) -> bool:
+        """Return if this calculated data point is relevant for the model."""
+        return (
+            element_matches_key(
+                search_elements=_RELEVANT_MODELS_APPARENT_TEMPERATURE, compare_with=channel.device.model
+            )
+            and channel.get_generic_data_point(parameter=Parameter.ACTUAL_TEMPERATURE, paramset_key=ParamsetKey.VALUES)
+            is not None
+            and channel.get_generic_data_point(parameter=Parameter.HUMIDITY, paramset_key=ParamsetKey.VALUES)
+            is not None
+            and channel.get_generic_data_point(parameter=Parameter.WIND_SPEED, paramset_key=ParamsetKey.VALUES)
+            is not None
+        )
+
+    @state_property
+    def value(self) -> float | None:
+        """Return the value."""
+        if (
+            self._dp_temperature.value is not None
+            and self._dp_humidity.value is not None
+            and self._dp_wind_speed.value is not None
+        ):
+            return calculate_apparent_temperature(
+                temperature=self._dp_temperature.value,
+                humidity=self._dp_humidity.value,
+                wind_speed=self._dp_wind_speed.value,
+            )
+        return None
+
+
+class DewPoint(BaseClimateSensor):
+    """Implementation of a calculated sensor for dew point."""
+
+    __slots__ = ()
+
+    _calculated_parameter = CalulatedParameter.DEW_POINT
+
+    def __init__(self, channel: hmd.Channel) -> None:
+        """Initialize the data point."""
+        super().__init__(channel=channel)
+        self._unit = "°C"
+
+    @staticmethod
+    def is_relevant_for_model(channel: hmd.Channel) -> bool:
+        """Return if this calculated data point is relevant for the model."""
+        return _is_relevant_for_model_temperature_and_humidity(channel=channel)
+
+    @state_property
+    def value(self) -> float | None:
+        """Return the value."""
+        if self._dp_temperature.value is not None and self._dp_humidity.value is not None:
+            return calculate_dew_point(
+                temperature=self._dp_temperature.value,
+                humidity=self._dp_humidity.value,
+            )
+        return None
+
+
+class FrostPoint(BaseClimateSensor):
+    """Implementation of a calculated sensor for frost point."""
+
+    __slots__ = ()
+
+    _calculated_parameter = CalulatedParameter.FROST_POINT
+
+    def __init__(self, channel: hmd.Channel) -> None:
+        """Initialize the data point."""
+        super().__init__(channel=channel)
+        self._unit = "°C"
+
+    @staticmethod
+    def is_relevant_for_model(channel: hmd.Channel) -> bool:
+        """Return if this calculated data point is relevant for the model."""
+        return _is_relevant_for_model_temperature_and_humidity(
+            channel=channel, relevant_models=_RELEVANT_MODELS_FROST_POINT
+        )
+
+    @state_property
+    def value(self) -> float | None:
+        """Return the value."""
+        if self._dp_temperature.value is not None and self._dp_humidity.value is not None:
+            return calculate_frost_point(
+                temperature=self._dp_temperature.value,
+                humidity=self._dp_humidity.value,
+            )
+        return None
+
+
+class VaporConcentration(BaseClimateSensor):
+    """Implementation of a calculated sensor for vapor concentration."""
+
+    __slots__ = ()
+
+    _calculated_parameter = CalulatedParameter.VAPOR_CONCENTRATION
+
+    def __init__(self, channel: hmd.Channel) -> None:
+        """Initialize the data point."""
+        super().__init__(channel=channel)
+        self._unit = "g/m³"
+
+    @staticmethod
+    def is_relevant_for_model(channel: hmd.Channel) -> bool:
+        """Return if this calculated data point is relevant for the model."""
+        return _is_relevant_for_model_temperature_and_humidity(channel=channel)
+
+    @state_property
+    def value(self) -> float | None:
+        """Return the value."""
+        if self._dp_temperature.value is not None and self._dp_humidity.value is not None:
+            return calculate_vapor_concentration(
+                temperature=self._dp_temperature.value,
+                humidity=self._dp_humidity.value,
+            )
+        return None
+
+
+def _is_relevant_for_model_temperature_and_humidity(
+    channel: hmd.Channel, relevant_models: tuple[str, ...] | None = None
+) -> bool:
+    """Return if this calculated data point is relevant for the model with temperature and humidity."""
+    return (
+        (
+            relevant_models is not None
+            and element_matches_key(search_elements=relevant_models, compare_with=channel.device.model)
+        )
+        or relevant_models is None
+    ) and (
+        (
+            channel.get_generic_data_point(parameter=Parameter.TEMPERATURE, paramset_key=ParamsetKey.VALUES) is not None
+            or channel.get_generic_data_point(parameter=Parameter.ACTUAL_TEMPERATURE, paramset_key=ParamsetKey.VALUES)
+            is not None
+        )
+        and (
+            channel.get_generic_data_point(parameter=Parameter.HUMIDITY, paramset_key=ParamsetKey.VALUES) is not None
+            or channel.get_generic_data_point(parameter=Parameter.ACTUAL_HUMIDITY, paramset_key=ParamsetKey.VALUES)
+            is not None
+        )
+    )
+
+
+_RELEVANT_MODELS_APPARENT_TEMPERATURE: Final[tuple[str, ...]] = ("HmIP-SWO",)
+
+
+_RELEVANT_MODELS_FROST_POINT: Final[tuple[str, ...]] = (
+    "HmIP-STHO",
+    "HmIP-SWO",
+)