aiohomematic 2025.11.3__py3-none-any.whl

aiohomematic/hmcli.py

@@ -0,0 +1,186 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2025
+#!/usr/bin/python3
+"""
+Commandline tool to query Homematic hubs via XML-RPC.
+
+Public API of this module is defined by __all__.
+
+This module provides a command-line interface; as a library surface it only
+exposes the 'main' entrypoint for invocation. All other names are internal.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import Any
+from xmlrpc.client import ServerProxy
+
+from aiohomematic import __version__
+from aiohomematic.const import ParamsetKey
+from aiohomematic.support import build_xml_rpc_headers, build_xml_rpc_uri, get_tls_context
+
+# Define public API for this module (CLI only)
+__all__ = ["main"]
+
+
+def main() -> None:
+    """Start the cli."""
+    parser = argparse.ArgumentParser(
+        description="Commandline tool to query Homematic hubs via XML-RPC",
+    )
+    parser.add_argument("--version", action="version", version=__version__)
+    parser.add_argument(
+        "--host",
+        "-H",
+        required=True,
+        type=str,
+        help="Hostname / IP address to connect to",
+    )
+    parser.add_argument(
+        "--port",
+        "-p",
+        required=True,
+        type=int,
+        help="Port to connect to",
+    )
+    parser.add_argument(
+        "--path",
+        type=str,
+        help="Path, used for heating groups",
+    )
+    parser.add_argument(
+        "--username",
+        "-U",
+        nargs="?",
+        help="Username required for access",
+    )
+    parser.add_argument(
+        "--password",
+        "-P",
+        nargs="?",
+        help="Password required for access",
+    )
+    parser.add_argument(
+        "--tls",
+        "-t",
+        action="store_true",
+        help="Enable TLS encryption",
+    )
+    parser.add_argument(
+        "--verify",
+        "-v",
+        action="store_true",
+        help="Verify TLS encryption",
+    )
+    parser.add_argument(
+        "--json",
+        "-j",
+        action="store_true",
+        help="Output as JSON",
+    )
+    parser.add_argument(
+        "--address",
+        "-a",
+        required=True,
+        type=str,
+        help="Address of Homematic device, including channel",
+    )
+    parser.add_argument(
+        "--paramset_key",
+        default=ParamsetKey.VALUES,
+        choices=[ParamsetKey.VALUES, ParamsetKey.MASTER],
+        help="Paramset of Homematic device. Default: VALUES",
+    )
+    parser.add_argument(
+        "--parameter",
+        required=True,
+        help="Parameter of Homematic device",
+    )
+    parser.add_argument(
+        "--value",
+        type=str,
+        help="Value to set for parameter. Use 0/1 for boolean",
+    )
+    parser.add_argument(
+        "--type",
+        choices=["int", "float", "bool"],
+        help="Type of value when setting a value. Using str if not provided",
+    )
+    args = parser.parse_args()
+
+    url = build_xml_rpc_uri(
+        host=args.host,
+        port=args.port,
+        path=args.path,
+        tls=args.tls,
+    )
+    headers = build_xml_rpc_headers(username=args.username, password=args.password)
+    context = None
+    if args.tls:
+        context = get_tls_context(verify_tls=args.verify)
+    proxy = ServerProxy(url, context=context, headers=headers)
+
+    try:
+        if args.paramset_key == ParamsetKey.VALUES and args.value is None:
+            result = proxy.getValue(args.address, args.parameter)
+            if args.json:
+                print(
+                    json.dumps(
+                        {"address": args.address, "parameter": args.parameter, "value": result}, ensure_ascii=False
+                    )
+                )
+            else:
+                print(result)
+            sys.exit(0)
+        elif args.paramset_key == ParamsetKey.VALUES and args.value:
+            value: Any
+            if args.type == "int":
+                value = int(args.value)
+            elif args.type == "float":
+                value = float(args.value)
+            elif args.type == "bool":
+                value = bool(int(args.value))
+            else:
+                value = args.value
+            proxy.setValue(args.address, args.parameter, value)
+            sys.exit(0)
+        elif args.paramset_key == ParamsetKey.MASTER and args.value is None:
+            paramset: dict[str, Any] | None
+            if (paramset := proxy.getParamset(args.address, args.paramset_key)) and (args.parameter in paramset):  # type: ignore[assignment]
+                result = paramset[args.parameter]
+                if args.json:
+                    print(
+                        json.dumps(
+                            {
+                                "address": args.address,
+                                "paramset_key": args.paramset_key,
+                                "parameter": args.parameter,
+                                "value": result,
+                            },
+                            ensure_ascii=False,
+                        )
+                    )
+                else:
+                    print(result)
+            sys.exit(0)
+        elif args.paramset_key == ParamsetKey.MASTER and args.value:
+            if args.type == "int":
+                value = int(args.value)
+            elif args.type == "float":
+                value = float(args.value)
+            elif args.type == "bool":
+                value = bool(int(args.value))
+            else:
+                value = args.value
+            proxy.putParamset(args.address, args.paramset_key, {args.parameter: value})
+            sys.exit(0)
+    except Exception as ex:
+        print(str(ex), file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

aiohomematic/model/__init__.py

@@ -0,0 +1,140 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2025
+"""
+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.
+
+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,84 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2025
+"""
+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, DewPointSpread, Enthalphy, 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,
+    DewPointSpread,
+    Enthalpy,
+    FrostPoint,
+    VaporConcentration,
+)
+from aiohomematic.model.calculated.data_point import CalculatedDataPoint
+from aiohomematic.model.calculated.operating_voltage_level import OperatingVoltageLevel
+
+__all__ = [
+    "ApparentTemperature",
+    "CalculatedDataPoint",
+    "DewPoint",
+    "DewPointSpread",
+    "Enthalpy",
+    "FrostPoint",
+    "OperatingVoltageLevel",
+    "VaporConcentration",
+    "create_calculated_data_points",
+]
+
+_CALCULATED_DATA_POINTS: Final = (
+    ApparentTemperature,
+    DewPoint,
+    DewPointSpread,
+    Enthalpy,
+    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 dp in _CALCULATED_DATA_POINTS:
+        if dp.is_relevant_for_model(channel=channel):
+            channel.add_data_point(data_point=dp(channel=channel))

aiohomematic/model/calculated/climate.py

@@ -0,0 +1,290 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2025
+"""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_dew_point_spread,
+    calculate_enthalpy,
+    calculate_frost_point,
+    calculate_vapor_concentration,
+)
+from aiohomematic.model.generic import DpSensor
+from aiohomematic.property_decorators import state_property
+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 DewPointSpread(BaseClimateSensor):
+    """Implementation of a calculated sensor for dew point spread."""
+
+    __slots__ = ()
+
+    _calculated_parameter = CalulatedParameter.DEW_POINT_SPREAD
+
+    def __init__(self, *, channel: hmd.Channel) -> None:
+        """Initialize the data point."""
+        super().__init__(channel=channel)
+        self._unit = "K"
+
+    @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_spread(
+                temperature=self._dp_temperature.value,
+                humidity=self._dp_humidity.value,
+            )
+        return None
+
+
+class Enthalpy(BaseClimateSensor):
+    """Implementation of a calculated sensor for enthalpy."""
+
+    __slots__ = ()
+
+    _calculated_parameter = CalulatedParameter.ENTHALPY
+
+    def __init__(self, *, channel: hmd.Channel) -> None:
+        """Initialize the data point."""
+        super().__init__(channel=channel)
+        self._unit = "kJ/kg"
+
+    @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_enthalpy(
+                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",
+)