aiohomematic 2026.1.29__py3-none-any.whl

aiohomematic/model/calculated/field.py

@@ -0,0 +1,147 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2026
+"""
+Descriptor-based field definitions for calculated data points.
+
+This module provides a declarative way to define data point fields,
+eliminating boilerplate in _post_init() methods.
+
+Public API of this module is defined by __all__.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Final, cast, overload
+
+from aiohomematic.const import ParamsetKey
+from aiohomematic.interfaces import GenericDataPointProtocolAny
+from aiohomematic.property_decorators import DelegatedProperty
+
+if TYPE_CHECKING:
+    from typing import Self
+
+    from aiohomematic.model.calculated import CalculatedDataPoint
+
+__all__ = ["CalculatedDataPointField"]
+
+# Key type for calculated data point dictionary
+type _DataPointKey = tuple[str, ParamsetKey | None]
+
+
+class CalculatedDataPointField[DataPointT: GenericDataPointProtocolAny]:
+    """
+    Descriptor for declarative calculated data point field definitions.
+
+    This descriptor eliminates the need for explicit _post_init()
+    boilerplate by lazily resolving data points on first access.
+
+    Usage:
+        class MyCalculatedSensor(CalculatedDataPoint):
+            # Simple field
+            _dp_wind_speed: Final = CalculatedDataPointField(
+                parameter=Parameter.WIND_SPEED,
+                paramset_key=ParamsetKey.VALUES,
+                dpt=DpSensor,
+            )
+
+            # Field with fallback parameters
+            _dp_temperature: Final = CalculatedDataPointField(
+                parameter=Parameter.TEMPERATURE,
+                paramset_key=ParamsetKey.VALUES,
+                dpt=DpSensor,
+                fallback_parameters=[Parameter.ACTUAL_TEMPERATURE],
+            )
+
+            # Field with device fallback (tries device address if not on channel)
+            _dp_low_bat_limit: Final = CalculatedDataPointField(
+                parameter=Parameter.LOW_BAT_LIMIT,
+                paramset_key=ParamsetKey.MASTER,
+                dpt=DpFloat,
+                use_device_fallback=True,
+            )
+
+    The descriptor:
+    - Resolves the data point from _data_points dict on each access (O(1) lookup)
+    - Tries fallback_parameters in order if primary parameter doesn't exist
+    - Tries device address if use_device_fallback=True and not found on channel
+    - Returns a DpDummy fallback if no data point exists
+    - Subscribes to data point updates automatically
+    - Provides correct type information to mypy
+    """
+
+    __slots__ = ("_parameter", "_paramset_key", "_data_point_type", "_fallback_parameters", "_use_device_fallback")
+
+    def __init__(
+        self,
+        *,
+        parameter: str,
+        paramset_key: ParamsetKey | None,
+        dpt: type[DataPointT],
+        fallback_parameters: list[str] | None = None,
+        use_device_fallback: bool = False,
+    ) -> None:
+        """
+        Initialize the calculated data point field descriptor.
+
+        Args:
+            parameter: The parameter name identifying this data point
+            paramset_key: The paramset key (VALUES, MASTER, etc.)
+            dpt: The expected data point type (e.g., DpSensor, DpFloat)
+            fallback_parameters: Optional list of fallback parameter names to try if primary not found
+            use_device_fallback: If True, try device address (channel 0) if not found on current channel
+
+        """
+        self._parameter: Final = parameter
+        self._paramset_key: Final = paramset_key
+        self._data_point_type: Final = dpt
+        self._fallback_parameters: Final = fallback_parameters or []
+        self._use_device_fallback: Final = use_device_fallback
+
+    @overload
+    def __get__(self, instance: None, owner: type) -> Self: ...  # kwonly: disable
+
+    @overload
+    def __get__(self, instance: CalculatedDataPoint[Any], owner: type) -> DataPointT: ...  # kwonly: disable
+
+    def __get__(self, instance: CalculatedDataPoint[Any] | None, owner: type) -> Self | DataPointT:  # kwonly: disable
+        """
+        Get the data point for this field.
+
+        On class-level access (instance=None), returns the descriptor itself.
+        On instance access, looks up the data point from _data_points dict.
+        """
+        if instance is None:
+            return self  # Class-level access returns descriptor
+
+        key: _DataPointKey = (self._parameter, self._paramset_key)
+
+        # Resolve from _data_points dict (O(1) lookup)
+        if found_dp := instance._data_points.get(key):
+            return cast(DataPointT, found_dp)
+
+        # Try primary parameter first, then fallbacks on current channel
+        for param in (self._parameter, *self._fallback_parameters):
+            if instance._channel.get_generic_data_point(parameter=param, paramset_key=self._paramset_key):
+                dp = instance._resolve_data_point(parameter=param, paramset_key=self._paramset_key)
+                instance._data_points[key] = dp
+                return cast(DataPointT, dp)
+
+        # Try device address (channel 0) if enabled
+        if self._use_device_fallback:
+            dp = instance._add_device_data_point(
+                channel_address=instance._channel.device.address,
+                parameter=self._parameter,
+                paramset_key=self._paramset_key,
+                dpt=self._data_point_type,
+            )
+            instance._data_points[key] = dp
+            return cast(DataPointT, dp)
+
+        # No data point found - resolve DpDummy for primary parameter
+        dp = instance._resolve_data_point(parameter=self._parameter, paramset_key=self._paramset_key)
+        instance._data_points[key] = dp
+        return cast(DataPointT, dp)
+
+    data_point_type: Final = DelegatedProperty[type[DataPointT]](path="_data_point_type")
+    parameter: Final = DelegatedProperty[str](path="_parameter")
+    paramset_key: Final = DelegatedProperty[ParamsetKey | None](path="_paramset_key")

aiohomematic/model/calculated/operating_voltage_level.py

@@ -0,0 +1,286 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2026
+"""Module for calculating the operating voltage level in the sensor category."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from enum import StrEnum
+import logging
+from typing import Any, Final
+
+from aiohomematic.const import CalculatedParameter, DataPointCategory, Parameter, ParameterType, ParamsetKey
+from aiohomematic.interfaces import ChannelProtocol
+from aiohomematic.model.calculated import CalculatedDataPoint
+from aiohomematic.model.calculated.field import CalculatedDataPointField
+from aiohomematic.model.calculated.support import calculate_operating_voltage_level
+from aiohomematic.model.generic import DpFloat, DpSensor
+from aiohomematic.property_decorators import state_property
+from aiohomematic.support import element_matches_key, extract_exc_args
+
+_BATTERY_QTY: Final = "Battery Qty"
+_BATTERY_TYPE: Final = "Battery Type"
+_LOW_BAT_LIMIT: Final = "Low Battery Limit"
+_LOW_BAT_LIMIT_DEFAULT: Final = "Low Battery Limit Default"
+_VOLTAGE_MAX: Final = "Voltage max"
+
+_LOGGER: Final = logging.getLogger(__name__)
+
+
+class OperatingVoltageLevel[SensorT: float | None](CalculatedDataPoint[SensorT]):
+    """Implementation of a calculated sensor for operating voltage level."""
+
+    __slots__ = (
+        "_battery_data",
+        "_low_bat_limit_default",
+        "_voltage_max",
+    )
+
+    _calculated_parameter = CalculatedParameter.OPERATING_VOLTAGE_LEVEL
+    _category = DataPointCategory.SENSOR
+
+    _dp_low_bat_limit: Final = CalculatedDataPointField(
+        parameter=Parameter.LOW_BAT_LIMIT,
+        paramset_key=ParamsetKey.MASTER,
+        dpt=DpFloat,
+        use_device_fallback=True,
+    )
+    _dp_operating_voltage: Final = CalculatedDataPointField(
+        parameter=Parameter.OPERATING_VOLTAGE,
+        paramset_key=ParamsetKey.VALUES,
+        dpt=DpSensor,
+        fallback_parameters=[Parameter.BATTERY_STATE],
+    )
+
+    def __init__(self, *, channel: ChannelProtocol) -> None:
+        """Initialize the data point."""
+        super().__init__(channel=channel)
+        self._type = ParameterType.FLOAT
+        self._unit = "%"
+
+    @staticmethod
+    def is_relevant_for_model(*, channel: ChannelProtocol) -> bool:
+        """Return if this calculated data point is relevant for the model."""
+        if element_matches_key(
+            search_elements=_IGNORE_OPERATING_VOLTAGE_LEVEL_MODELS, compare_with=channel.device.model
+        ):
+            return False
+        return element_matches_key(
+            search_elements=_OPERATING_VOLTAGE_LEVEL_MODELS.keys(), compare_with=channel.device.model
+        ) and (
+            (
+                channel.get_generic_data_point(
+                    parameter=Parameter.OPERATING_VOLTAGE,
+                    paramset_key=ParamsetKey.VALUES,
+                )
+                and channel.get_generic_data_point(parameter=Parameter.LOW_BAT_LIMIT, paramset_key=ParamsetKey.MASTER)
+            )
+            is not None
+            or (
+                channel.get_generic_data_point(
+                    parameter=Parameter.BATTERY_STATE,
+                    paramset_key=ParamsetKey.VALUES,
+                )
+                and channel.device.get_generic_data_point(
+                    channel_address=channel.device.address,
+                    parameter=Parameter.LOW_BAT_LIMIT,
+                    paramset_key=ParamsetKey.MASTER,
+                )
+            )
+            is not None
+        )
+
+    @property
+    def _low_bat_limit(self) -> float | None:
+        """Return the min value."""
+        return (
+            float(self._dp_low_bat_limit.value)
+            if self._dp_low_bat_limit is not None and self._dp_low_bat_limit.value is not None
+            else None
+        )
+
+    @state_property
+    def additional_information(self) -> dict[str, Any]:
+        """Return additional information about the data point."""
+        ainfo = super().additional_information
+        if self._battery_data is not None:
+            ainfo.update(
+                {
+                    _BATTERY_QTY: self._battery_data.quantity,
+                    _BATTERY_TYPE: self._battery_data.battery,
+                    _LOW_BAT_LIMIT: f"{self._low_bat_limit}V",
+                    _LOW_BAT_LIMIT_DEFAULT: f"{self._low_bat_limit_default}V",
+                    _VOLTAGE_MAX: f"{self._voltage_max}V",
+                }
+            )
+        return ainfo
+
+    @state_property
+    def value(self) -> float | None:
+        """Return the value."""
+        try:
+            return calculate_operating_voltage_level(
+                operating_voltage=self._dp_operating_voltage.value,
+                low_bat_limit=self._low_bat_limit_default,
+                voltage_max=self._voltage_max,
+            )
+        except Exception as exc:
+            _LOGGER.debug(
+                "OperatingVoltageLevel: Failed to calculate sensor for %s: %s",
+                self._channel.name,
+                extract_exc_args(exc=exc),
+            )
+        return None
+
+    def _post_init(self) -> None:
+        """Post action after initialisation of the data point fields."""
+        super()._post_init()
+
+        self._battery_data = _get_battery_data(model=self._channel.device.model)
+        self._low_bat_limit_default = (
+            float(self._dp_low_bat_limit.default)
+            if isinstance(self._dp_low_bat_limit, DpFloat) and self._dp_low_bat_limit.default is not None
+            else None
+        )
+        self._voltage_max = (
+            float(_BatteryVoltage[self._battery_data.battery] * self._battery_data.quantity)
+            if self._battery_data is not None
+            else None
+        )
+
+
+class _BatteryType(StrEnum):
+    CR2032 = "CR2032"
+    LR44 = "LR44"
+    R03 = "AAA"
+    R14 = "BABY"
+    R6 = "AA"
+    UNKNOWN = "UNKNOWN"
+
+
+_BatteryVoltage: Final[Mapping[_BatteryType, float]] = {
+    _BatteryType.CR2032: 3.0,
+    _BatteryType.LR44: 1.5,
+    _BatteryType.R03: 1.5,
+    _BatteryType.R14: 1.5,
+    _BatteryType.R6: 1.5,
+}
+
+
+@dataclass(frozen=True, kw_only=True, slots=True)
+class _BatteryData:
+    model: str
+    battery: _BatteryType
+    quantity: int = 1
+
+
+# This list is sorted. models with shorted model types are sorted to
+_BATTERY_DATA: Final = (
+    # HM long model str
+    _BatteryData(model="HM-CC-RT-DN", battery=_BatteryType.R6, quantity=2),
+    _BatteryData(model="HM-Dis-EP-WM55", battery=_BatteryType.R03, quantity=2),
+    _BatteryData(model="HM-ES-TX-WM", battery=_BatteryType.R6, quantity=4),
+    _BatteryData(model="HM-OU-CFM-TW", battery=_BatteryType.R14, quantity=2),
+    _BatteryData(model="HM-PB-2-FM", battery=_BatteryType.R03, quantity=2),
+    _BatteryData(model="HM-PB-2-WM55", battery=_BatteryType.R03, quantity=2),
+    _BatteryData(model="HM-PB-6-WM55", battery=_BatteryType.R03, quantity=2),
+    _BatteryData(model="HM-PBI-4-FM", battery=_BatteryType.CR2032),
+    _BatteryData(model="HM-RC-4-2", battery=_BatteryType.R03),
+    _BatteryData(model="HM-RC-8", battery=_BatteryType.R03, quantity=2),
+    _BatteryData(model="HM-RC-Key4-3", battery=_BatteryType.R03),
+    _BatteryData(model="HM-SCI-3-FM", battery=_BatteryType.CR2032),
+    _BatteryData(model="HM-Sec-Key", battery=_BatteryType.R6, quantity=3),
+    _BatteryData(model="HM-Sec-MDIR-2", battery=_BatteryType.R6, quantity=3),
+    _BatteryData(model="HM-Sec-RHS", battery=_BatteryType.LR44, quantity=2),
+    _BatteryData(model="HM-Sec-SC-2", battery=_BatteryType.LR44, quantity=2),
+    _BatteryData(model="HM-Sec-SCo", battery=_BatteryType.R03),
+    _BatteryData(model="HM-Sec-SD-2", battery=_BatteryType.UNKNOWN),
+    _BatteryData(model="HM-Sec-Sir-WM", battery=_BatteryType.R14, quantity=2),
+    _BatteryData(model="HM-Sec-TiS", battery=_BatteryType.CR2032),
+    _BatteryData(model="HM-Sec-Win", battery=_BatteryType.UNKNOWN),
+    _BatteryData(model="HM-Sen-MDIR-O-2", battery=_BatteryType.R6, quantity=3),
+    _BatteryData(model="HM-Sen-MDIR-SM", battery=_BatteryType.R6, quantity=3),
+    _BatteryData(model="HM-Sen-MDIR-WM55", battery=_BatteryType.R03, quantity=2),
+    _BatteryData(model="HM-SwI-3-FM", battery=_BatteryType.CR2032),
+    _BatteryData(model="HM-TC-IT-WM-W-EU", battery=_BatteryType.R03, quantity=2),
+    _BatteryData(model="HM-WDS10-TH-O", battery=_BatteryType.R6, quantity=2),
+    _BatteryData(model="HM-WDS30-OT2-SM", battery=_BatteryType.R6, quantity=2),
+    _BatteryData(model="HM-WDS30-T-O", battery=_BatteryType.R03, quantity=2),
+    _BatteryData(model="HM-WDS40-TH-I", battery=_BatteryType.R6, quantity=2),
+    # HM short model str
+    _BatteryData(model="HM-Sec-SD", battery=_BatteryType.R6, quantity=3),
+    # HmIP model > 4
+    _BatteryData(model="HmIP-ASIR-O", battery=_BatteryType.UNKNOWN),
+    _BatteryData(model="HmIP-DSD-PCB", battery=_BatteryType.R03, quantity=2),
+    _BatteryData(model="HmIP-PCBS-BAT", battery=_BatteryType.UNKNOWN),
+    _BatteryData(model="HmIP-SMI55", battery=_BatteryType.R03, quantity=2),
+    _BatteryData(model="HmIP-SMO230", battery=_BatteryType.UNKNOWN),
+    _BatteryData(model="HmIP-STE2-PCB", battery=_BatteryType.R6, quantity=2),
+    _BatteryData(model="HmIP-SWDO-I", battery=_BatteryType.R03, quantity=2),
+    _BatteryData(model="HmIP-SWDO-PL", battery=_BatteryType.R03, quantity=2),
+    _BatteryData(model="HmIP-WTH-B-2", battery=_BatteryType.R6, quantity=2),
+    _BatteryData(model="HmIP-eTRV-CL", battery=_BatteryType.R6, quantity=4),
+    # HmIP model 4
+    _BatteryData(model="ELV-SH-SW1-BAT", battery=_BatteryType.R6, quantity=2),
+    _BatteryData(model="ELV-SH-TACO", battery=_BatteryType.R03, quantity=1),
+    _BatteryData(model="HmIP-ASIR", battery=_BatteryType.R6, quantity=3),
+    _BatteryData(model="HmIP-FCI1", battery=_BatteryType.CR2032),
+    _BatteryData(model="HmIP-FCI6", battery=_BatteryType.R03),
+    _BatteryData(model="HmIP-MP3P", battery=_BatteryType.R14, quantity=2),
+    _BatteryData(model="HmIP-RCB1", battery=_BatteryType.R03, quantity=2),
+    _BatteryData(model="HmIP-SPDR", battery=_BatteryType.R6, quantity=2),
+    _BatteryData(model="HmIP-STHD", battery=_BatteryType.R03, quantity=2),
+    _BatteryData(model="HmIP-STHO", battery=_BatteryType.R6, quantity=2),
+    _BatteryData(model="HmIP-SWDM", battery=_BatteryType.R03, quantity=2),
+    _BatteryData(model="HmIP-SWDO", battery=_BatteryType.R03),
+    _BatteryData(model="HmIP-SWSD", battery=_BatteryType.UNKNOWN),
+    _BatteryData(model="HmIP-eTRV", battery=_BatteryType.R6, quantity=2),
+    # HmIP model 3
+    _BatteryData(model="ELV-SH-CTH", battery=_BatteryType.CR2032),
+    _BatteryData(model="ELV-SH-WSM", battery=_BatteryType.R6, quantity=2),
+    _BatteryData(model="HmIP-DBB", battery=_BatteryType.R03),
+    _BatteryData(model="HmIP-DLD", battery=_BatteryType.R6, quantity=3),
+    _BatteryData(model="HmIP-DLS", battery=_BatteryType.CR2032),
+    _BatteryData(model="HmIP-ESI", battery=_BatteryType.R6, quantity=2),
+    _BatteryData(model="HmIP-KRC", battery=_BatteryType.R03),
+    _BatteryData(model="HmIP-RC8", battery=_BatteryType.R03, quantity=2),
+    _BatteryData(model="HmIP-SAM", battery=_BatteryType.R6, quantity=2),
+    _BatteryData(model="HmIP-SCI", battery=_BatteryType.R03, quantity=2),
+    _BatteryData(model="HmIP-SLO", battery=_BatteryType.R6, quantity=2),
+    _BatteryData(model="HmIP-SMI", battery=_BatteryType.R6, quantity=2),
+    _BatteryData(model="HmIP-SMO", battery=_BatteryType.R6, quantity=2),
+    _BatteryData(model="HmIP-SPI", battery=_BatteryType.R6, quantity=2),
+    _BatteryData(model="HmIP-SRH", battery=_BatteryType.R03),
+    _BatteryData(model="HmIP-STH", battery=_BatteryType.R03, quantity=2),
+    _BatteryData(model="HmIP-STV", battery=_BatteryType.R03, quantity=2),
+    _BatteryData(model="HmIP-SWD", battery=_BatteryType.R03, quantity=2),
+    _BatteryData(model="HmIP-SWO", battery=_BatteryType.R6, quantity=3),
+    _BatteryData(model="HmIP-WGC", battery=_BatteryType.R6, quantity=2),
+    _BatteryData(model="HmIP-WKP", battery=_BatteryType.R03, quantity=2),
+    _BatteryData(model="HmIP-WRC", battery=_BatteryType.R03, quantity=2),
+    _BatteryData(model="HmIP-WSM", battery=_BatteryType.R6, quantity=2),
+    _BatteryData(model="HmIP-WTH", battery=_BatteryType.R03, quantity=2),
+)
+
+_OPERATING_VOLTAGE_LEVEL_MODELS: Final[Mapping[str, _BatteryData]] = {
+    battery.model: battery for battery in _BATTERY_DATA if battery.battery != _BatteryType.UNKNOWN
+}
+
+_IGNORE_OPERATING_VOLTAGE_LEVEL_MODELS: Final[tuple[str, ...]] = tuple(
+    [battery.model for battery in _BATTERY_DATA if battery.battery == _BatteryType.UNKNOWN]
+)
+
+
+def _get_battery_data(*, model: str) -> _BatteryData | None:
+    """Return the battery data by model."""
+    model_l = model.lower()
+    for battery_data in _OPERATING_VOLTAGE_LEVEL_MODELS.values():
+        if battery_data.model.lower() == model_l:
+            return battery_data
+
+    for battery_data in _OPERATING_VOLTAGE_LEVEL_MODELS.values():
+        if model_l.startswith(battery_data.model.lower()):
+            return battery_data
+
+    return None

aiohomematic/model/calculated/support.py

@@ -0,0 +1,232 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2026
+"""
+A number of functions used to calculate values based on existing data.
+
+Climate related formula are based on:
+ - thermal comfort (https://github.com/dolezsa/thermal_comfort) ground works.
+ - https://gist.github.com/E3V3A/8f9f0aa18380d4ab2546cd50b725a219
+"""
+
+from __future__ import annotations
+
+import logging
+import math
+from typing import Final
+
+from aiohomematic.support import extract_exc_args
+
+_DEFAULT_PRESSURE_HPA: Final = 1013.25
+_LOGGER: Final = logging.getLogger(__name__)
+
+
+def calculate_dew_point_spread(*, temperature: float, humidity: int) -> float | None:
+    """
+    Calculate the dew point spread.
+
+    Dew point spread = Difference between current air temperature and dew point.
+    Specifies the safety margin against condensation(K).
+    """
+    if dew_point := calculate_dew_point(temperature=temperature, humidity=humidity):
+        return round(temperature - dew_point, 2)
+    return None
+
+
+def calculate_enthalpy(
+    *, temperature: float, humidity: int, pressure_hPa: float = _DEFAULT_PRESSURE_HPA
+) -> float | None:
+    """
+    Calculate the enthalpy based on temperature and humidity.
+
+    Calculates the specific enthalpy of humid air in kJ/kg (relative to dry air).
+    temperature: Air temperature in °C
+    humidity: Relative humidity in %
+    pressure_hPa: Air pressure (default: 1013.25 hPa)
+
+    """
+    # Saturation vapor pressure according to Magnus in hPa
+    e_s = 6.112 * math.exp((17.62 * temperature) / (243.12 + temperature))
+    e = humidity / 100.0 * e_s  # aktueller Dampfdruck in hPa
+
+    # Mixing ratio (g water / kg dry air)
+    r = 622 * e / (pressure_hPa - e)
+
+    # Specific enthalpy (kJ/kg dry air)
+    h = 1.006 * temperature + r * (2501 + 1.86 * temperature) / 1000  # in kJ/kg
+    return round(h, 2)
+
+
+def _calculate_heat_index(*, temperature: float, humidity: int) -> float:
+    """
+    Calculate the Heat Index (feels like temperature) based on the NOAA equation.
+
+    References:
+    [1] https://en.wikipedia.org/wiki/Heat_index
+    [2] http://www.wpc.ncep.noaa.gov/html/heatindex_equation.shtml
+    [3] https://github.com/geanders/weathermetrics/blob/master/R/heat_index.R
+    [4] https://www.ncbi.nlm.nih.gov/pmc/articles/PMC3801457/
+
+    """
+    # SI units (Celsius)
+    c1 = -8.78469475556
+    c2 = 1.61139411
+    c3 = 2.33854883889
+    c4 = -0.14611605
+    c5 = -0.012308094
+    c6 = -0.0164248277778
+    c7 = 0.002211732
+    c8 = 0.00072546
+    c9 = -0.000003582
+
+    temperature_fahrenheit = (temperature * 9 / 5) + 32
+    heat_index_fahrenheit = 0.5 * (
+        temperature_fahrenheit + 61.0 + (temperature_fahrenheit - 68.0) * 1.2 + humidity * 0.094
+    )
+
+    if ((heat_index_fahrenheit + temperature_fahrenheit) / 2) >= 80:  # [°F]
+        # temperature > 27C and humidity > 40 %
+        heat_index_celsius = math.fsum(
+            [
+                c1,
+                c2 * temperature,
+                c3 * humidity,
+                c4 * temperature * humidity,
+                c5 * temperature**2,
+                c6 * humidity**2,
+                c7 * temperature**2 * humidity,
+                c8 * temperature * humidity**2,
+                c9 * temperature**2 * humidity**2,
+            ]
+        )
+    else:
+        heat_index_celsius = (heat_index_fahrenheit - 32) * 5 / 9
+
+    return heat_index_celsius
+
+
+def _calculate_wind_chill(*, temperature: float, wind_speed: float) -> float | None:
+    """
+    Calculate the Wind Chill (feels like temperature) based on NOAA.
+
+    References:
+    [1] https://en.wikipedia.org/wiki/Wind_chill
+    [2] https://www.wpc.ncep.noaa.gov/html/windchill.shtml
+
+    """
+    # Wind Chill Temperature is only defined for temperatures at or below 10°C and wind speeds above 4.8 Km/h.
+    if temperature > 10 or wind_speed <= 4.8:  # if temperature > 50 or wind_speed <= 3:    # (°F, Mph)
+        return None
+
+    return float(13.12 + (0.6215 * temperature) - 11.37 * wind_speed**0.16 + 0.3965 * temperature * wind_speed**0.16)
+
+
+def calculate_vapor_concentration(*, temperature: float, humidity: int) -> float | None:
+    """Calculate the vapor concentration."""
+    try:
+        abs_temperature = temperature + 273.15
+        vapor_concentration = 6.112
+        vapor_concentration *= math.exp((17.67 * temperature) / (243.5 + temperature))
+        vapor_concentration *= humidity
+        vapor_concentration *= 2.1674
+        vapor_concentration /= abs_temperature
+
+        return round(vapor_concentration, 2)
+    except ValueError as verr:
+        _LOGGER.debug(
+            "Unable to calculate 'vapor concentration' with temperature: %s, humidity: %s (%s)",
+            temperature,
+            humidity,
+            extract_exc_args(exc=verr),
+        )
+    return None
+
+
+def calculate_apparent_temperature(*, temperature: float, humidity: int, wind_speed: float) -> float | None:
+    """Calculate the apparent temperature based on NOAA."""
+    try:
+        if temperature <= 10 and wind_speed > 4.8:
+            # Wind Chill for low temp cases (and wind)
+            apparent_temperature = _calculate_wind_chill(temperature=temperature, wind_speed=wind_speed)
+        elif temperature >= 26.7:
+            # Heat Index for High temp cases
+            apparent_temperature = _calculate_heat_index(temperature=temperature, humidity=humidity)
+        else:
+            apparent_temperature = temperature
+
+        return round(apparent_temperature, 1)  # type: ignore[arg-type]
+    except ValueError as verr:
+        if temperature == 0.0 and humidity == 0:
+            return 0.0
+        _LOGGER.debug(
+            "Unable to calculate 'apparent temperature' with temperature: %s, humidity: %s (%s)",
+            temperature,
+            humidity,
+            extract_exc_args(exc=verr),
+        )
+    return None
+
+
+def calculate_dew_point(*, temperature: float, humidity: int) -> float | None:
+    """Calculate the dew point."""
+    try:
+        a0 = 373.15 / (273.15 + temperature)
+        s = -7.90298 * (a0 - 1)
+        s += 5.02808 * math.log(a0, 10)
+        s += -1.3816e-7 * (pow(10, (11.344 * (1 - 1 / a0))) - 1)
+        s += 8.1328e-3 * (pow(10, (-3.49149 * (a0 - 1))) - 1)
+        s += math.log(1013.246, 10)
+        vp = pow(10, s - 3) * humidity
+        td = math.log(vp / 0.61078)
+
+        return round((241.88 * td) / (17.558 - td), 1)
+    except ValueError as verr:
+        if temperature == 0.0 and humidity == 0:
+            return 0.0
+        _LOGGER.debug(
+            "Unable to calculate 'dew point' with temperature: %s, humidity: %s (%s)",
+            temperature,
+            humidity,
+            extract_exc_args(exc=verr),
+        )
+    return None
+
+
+def calculate_frost_point(*, temperature: float, humidity: int) -> float | None:
+    """Calculate the frost point."""
+    try:
+        if (dew_point := calculate_dew_point(temperature=temperature, humidity=humidity)) is None:
+            return None
+        t = temperature + 273.15
+        td = dew_point + 273.15
+
+        return round((td + (2671.02 / ((2954.61 / t) + 2.193665 * math.log(t) - 13.3448)) - t) - 273.15, 1)
+    except ValueError as verr:
+        if temperature == 0.0 and humidity == 0:
+            return 0.0
+        _LOGGER.debug(
+            "Unable to calculate 'frost point' with temperature: %s, humidity: %s (%s)",
+            temperature,
+            humidity,
+            extract_exc_args(exc=verr),
+        )
+    return None
+
+
+def calculate_operating_voltage_level(
+    *, operating_voltage: float | None, low_bat_limit: float | None, voltage_max: float | None
+) -> float | None:
+    """Return the operating voltage level."""
+    if operating_voltage is None or low_bat_limit is None or voltage_max is None:
+        return None
+    return max(
+        0,
+        min(
+            100,
+            float(
+                round(
+                    ((float(operating_voltage) - low_bat_limit) / (voltage_max - low_bat_limit) * 100),
+                    1,
+                )
+            ),
+        ),
+    )