aiohomematic 2026.1.29__py3-none-any.whl

aiohomematic/model/hub/metrics.py

@@ -0,0 +1,208 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2026
+"""
+Hub sensors for system metrics.
+
+This module provides hub sensor data points for exposing key system metrics
+to Home Assistant. These sensors allow monitoring of system health,
+connection latency, and event timing without needing separate diagnostic entities.
+
+Public API
+----------
+- HmSystemHealthSensor: Overall system health score (0-100%)
+- HmConnectionLatencySensor: Average RPC connection latency in milliseconds
+- HmLastEventAgeSensor: Seconds since last backend event
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+import logging
+from typing import TYPE_CHECKING, Final
+
+from slugify import slugify
+
+from aiohomematic.const import (
+    HUB_ADDRESS,
+    METRICS_SENSOR_CONNECTION_LATENCY_NAME,
+    METRICS_SENSOR_LAST_EVENT_AGE_NAME,
+    METRICS_SENSOR_SYSTEM_HEALTH_NAME,
+    DataPointCategory,
+    HubValueType,
+)
+from aiohomematic.interfaces import (
+    CentralInfoProtocol,
+    ChannelProtocol,
+    ConfigProviderProtocol,
+    EventBusProviderProtocol,
+    EventPublisherProtocol,
+    HubSensorDataPointProtocol,
+    ParameterVisibilityProviderProtocol,
+    ParamsetDescriptionProviderProtocol,
+    TaskSchedulerProtocol,
+)
+from aiohomematic.model.data_point import CallbackDataPoint
+from aiohomematic.model.support import HubPathData, PathData, generate_unique_id, get_hub_data_point_name_data
+from aiohomematic.property_decorators import DelegatedProperty, Kind, state_property
+from aiohomematic.support import PayloadMixin
+
+if TYPE_CHECKING:
+    from aiohomematic.metrics import MetricsObserver
+
+_LOGGER: Final = logging.getLogger(__name__)
+
+
+class _BaseMetricsSensor(CallbackDataPoint, HubSensorDataPointProtocol, PayloadMixin):
+    """Base class for metrics hub sensors."""
+
+    __slots__ = (
+        "_cached_value",
+        "_metrics_observer",
+        "_name_data",
+        "_state_uncertain",
+    )
+
+    _category = DataPointCategory.HUB_SENSOR
+    _enabled_default = True
+    _sensor_name: str
+    _unit: str
+
+    def __init__(
+        self,
+        *,
+        metrics_observer: MetricsObserver,
+        config_provider: ConfigProviderProtocol,
+        central_info: CentralInfoProtocol,
+        event_bus_provider: EventBusProviderProtocol,
+        event_publisher: EventPublisherProtocol,
+        task_scheduler: TaskSchedulerProtocol,
+        paramset_description_provider: ParamsetDescriptionProviderProtocol,
+        parameter_visibility_provider: ParameterVisibilityProviderProtocol,
+    ) -> None:
+        """Initialize the metrics sensor."""
+        PayloadMixin.__init__(self)
+        self._metrics_observer: Final = metrics_observer
+        unique_id: Final = generate_unique_id(
+            config_provider=config_provider,
+            address=HUB_ADDRESS,
+            parameter=slugify(self._sensor_name),
+        )
+        self._name_data: Final = get_hub_data_point_name_data(
+            channel=None, legacy_name=self._sensor_name, central_name=central_info.name
+        )
+        super().__init__(
+            unique_id=unique_id,
+            central_info=central_info,
+            event_bus_provider=event_bus_provider,
+            event_publisher=event_publisher,
+            task_scheduler=task_scheduler,
+            paramset_description_provider=paramset_description_provider,
+            parameter_visibility_provider=parameter_visibility_provider,
+        )
+        self._state_uncertain: bool = True
+        self._cached_value: float = 0.0
+
+    available: Final = DelegatedProperty[bool](path="_central_info.available", kind=Kind.STATE)
+    enabled_default: Final = DelegatedProperty[bool](path="_enabled_default")
+    full_name: Final = DelegatedProperty[str](path="_name_data.full_name")
+    name: Final = DelegatedProperty[str](path="_name_data.name", kind=Kind.CONFIG)
+    state_uncertain: Final = DelegatedProperty[bool](path="_state_uncertain")
+    unit: Final = DelegatedProperty[str](path="_unit", kind=Kind.CONFIG)
+
+    @property
+    def channel(self) -> ChannelProtocol | None:
+        """Return the identified channel."""
+        return None
+
+    @property
+    def data_type(self) -> HubValueType | None:
+        """Return the data type of the sensor."""
+        return HubValueType.FLOAT
+
+    @property
+    def description(self) -> str | None:
+        """Return data point description."""
+        return None
+
+    @property
+    def legacy_name(self) -> str | None:
+        """Return the original name."""
+        return None
+
+    @state_property
+    def value(self) -> float:
+        """Return the system health score as percentage (0-100)."""
+        return self._get_current_value()
+
+    def refresh(self, *, write_at: datetime) -> None:
+        """Refresh the sensor value from metrics observer."""
+        current_value = self._get_current_value()
+        if self._cached_value != current_value:
+            self._cached_value = current_value
+            self._set_modified_at(modified_at=write_at)
+        else:
+            self._set_refreshed_at(refreshed_at=write_at)
+        self._state_uncertain = False
+        self.publish_data_point_updated_event()
+
+    def _get_current_value(self) -> float:
+        """Return the current metric value. Override in subclasses."""
+        raise NotImplementedError
+
+    def _get_path_data(self) -> PathData:
+        """Return the path data of the data_point."""
+        return HubPathData(name=slugify(self._sensor_name))
+
+    def _get_signature(self) -> str:
+        """Return the signature of the data_point."""
+        return f"{self._category}/{self.name}"
+
+
+class HmSystemHealthSensor(_BaseMetricsSensor):
+    """
+    Hub sensor for system health score.
+
+    Exposes the overall system health as a percentage (0-100%).
+    The health score is derived from client connection states.
+    """
+
+    __slots__ = ()
+    _sensor_name = METRICS_SENSOR_SYSTEM_HEALTH_NAME
+    _unit = "%"
+
+    def _get_current_value(self) -> float:
+        """Return the current health score as percentage."""
+        return round(self._metrics_observer.get_overall_health_score() * 100, 1)
+
+
+class HmConnectionLatencySensor(_BaseMetricsSensor):
+    """
+    Hub sensor for connection latency.
+
+    Exposes the average RPC connection latency in milliseconds.
+    """
+
+    __slots__ = ()
+    _sensor_name = METRICS_SENSOR_CONNECTION_LATENCY_NAME
+    _unit = "ms"
+
+    def _get_current_value(self) -> float:
+        """Return the current average latency from ping/pong metrics."""
+        return round(self._metrics_observer.get_aggregated_latency(pattern="ping_pong").avg_ms, 1)
+
+
+class HmLastEventAgeSensor(_BaseMetricsSensor):
+    """
+    Hub sensor for last event age.
+
+    Exposes the time in seconds since the last backend event was received.
+    A value of -1 indicates no events have been received yet.
+    """
+
+    __slots__ = ()
+    _sensor_name = METRICS_SENSOR_LAST_EVENT_AGE_NAME
+    _unit = "s"
+
+    def _get_current_value(self) -> float:
+        """Return the current last event age in seconds."""
+        return round(self._metrics_observer.get_last_event_age_seconds(), 1)

aiohomematic/model/hub/number.py

@@ -0,0 +1,42 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2026
+"""Module for data points implemented using the number category."""
+
+from __future__ import annotations
+
+import logging
+from typing import Final
+
+from aiohomematic import i18n
+from aiohomematic.const import DataPointCategory
+from aiohomematic.decorators import inspector
+from aiohomematic.model.hub.data_point import GenericSysvarDataPoint
+
+_LOGGER: Final = logging.getLogger(__name__)
+
+
+class SysvarDpNumber(GenericSysvarDataPoint):
+    """Implementation of a sysvar number."""
+
+    __slots__ = ()
+
+    _category = DataPointCategory.HUB_NUMBER
+    _is_extended = True
+
+    @inspector
+    async def send_variable(self, *, value: float) -> None:
+        """Set the value of the data_point."""
+        if value is not None and self.max is not None and self.min is not None:
+            if self.min <= float(value) <= self.max:
+                await super().send_variable(value=value)
+            else:
+                _LOGGER.error(
+                    i18n.tr(
+                        key="exception.model.hub.number.invalid_value",
+                        value=value,
+                        min=self.min,
+                        max=self.max,
+                    )
+                )
+            return
+        await super().send_variable(value=value)

aiohomematic/model/hub/select.py

@@ -0,0 +1,52 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2026
+"""Module for hub data points implemented using the select category."""
+
+from __future__ import annotations
+
+import logging
+from typing import Final
+
+from aiohomematic import i18n
+from aiohomematic.const import DataPointCategory
+from aiohomematic.decorators import inspector
+from aiohomematic.model.hub.data_point import GenericSysvarDataPoint
+from aiohomematic.model.support import get_value_from_value_list
+from aiohomematic.property_decorators import state_property
+
+_LOGGER: Final = logging.getLogger(__name__)
+
+
+class SysvarDpSelect(GenericSysvarDataPoint):
+    """Implementation of a sysvar select data_point."""
+
+    __slots__ = ()
+
+    _category = DataPointCategory.HUB_SELECT
+    _is_extended = True
+
+    @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 None
+
+    @inspector
+    async def send_variable(self, *, value: int | str) -> None:
+        """Set the value of the data_point."""
+        # We allow setting the value via index as well, just in case.
+        if isinstance(value, int) and self._values:
+            if 0 <= value < len(self._values):
+                await super().send_variable(value=value)
+        elif self._values:
+            if value in self._values:
+                await super().send_variable(value=self._values.index(value))
+        else:
+            _LOGGER.error(
+                i18n.tr(
+                    key="exception.model.select.value_not_in_value_list",
+                    name=self.name,
+                    unique_id=self.unique_id,
+                )
+            )

aiohomematic/model/hub/sensor.py

@@ -0,0 +1,37 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2026
+"""Module for hub data points implemented using the sensor category."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Final
+
+from aiohomematic.const import DataPointCategory, HubValueType
+from aiohomematic.model.hub.data_point import GenericSysvarDataPoint
+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 SysvarDpSensor(GenericSysvarDataPoint):
+    """Implementation of a sysvar sensor."""
+
+    __slots__ = ()
+
+    _category = DataPointCategory.HUB_SENSOR
+
+    @state_property
+    def value(self) -> Any | None:
+        """Return the value."""
+        if (
+            self._data_type == HubValueType.LIST
+            and (value := get_value_from_value_list(value=self._value, value_list=self.values)) is not None
+        ):
+            return value
+        return (
+            check_length_and_log(name=self._legacy_name, value=self._value)
+            if self._data_type == HubValueType.STRING
+            else self._value
+        )

aiohomematic/model/hub/switch.py

@@ -0,0 +1,43 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2026
+"""Module for hub data points implemented using the switch category."""
+
+from __future__ import annotations
+
+from typing import Final
+
+from aiohomematic.const import DataPointCategory
+from aiohomematic.decorators import inspector
+from aiohomematic.model.hub.data_point import GenericProgramDataPoint, GenericSysvarDataPoint
+from aiohomematic.property_decorators import DelegatedProperty, Kind
+
+
+class SysvarDpSwitch(GenericSysvarDataPoint):
+    """Implementation of a sysvar switch data_point."""
+
+    __slots__ = ()
+
+    _category = DataPointCategory.HUB_SWITCH
+    _is_extended = True
+
+
+class ProgramDpSwitch(GenericProgramDataPoint):
+    """Implementation of a program switch data_point."""
+
+    __slots__ = ()
+
+    _category = DataPointCategory.HUB_SWITCH
+
+    value: Final = DelegatedProperty[bool | None](path="_is_active", kind=Kind.STATE)
+
+    @inspector
+    async def turn_off(self) -> None:
+        """Turn the program off."""
+        await self._hub_data_fetcher.set_program_state(pid=self._pid, state=False)
+        await self._hub_data_fetcher.fetch_program_data(scheduled=False)
+
+    @inspector
+    async def turn_on(self) -> None:
+        """Turn the program on."""
+        await self._hub_data_fetcher.set_program_state(pid=self._pid, state=True)
+        await self._hub_data_fetcher.fetch_program_data(scheduled=False)

aiohomematic/model/hub/text.py

@@ -0,0 +1,30 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2026
+"""Module for hub data points implemented using the text category."""
+
+from __future__ import annotations
+
+from typing import cast
+
+from aiohomematic.const import DataPointCategory
+from aiohomematic.model.hub.data_point import GenericSysvarDataPoint
+from aiohomematic.model.support import check_length_and_log
+from aiohomematic.property_decorators import state_property
+
+
+class SysvarDpText(GenericSysvarDataPoint):
+    """Implementation of a sysvar text data_point."""
+
+    __slots__ = ()
+
+    _category = DataPointCategory.HUB_TEXT
+    _is_extended = True
+
+    @state_property
+    def value(self) -> str | None:
+        """Get the value of the data_point."""
+        return cast(str | None, check_length_and_log(name=self._legacy_name, value=self._value))
+
+    async def send_variable(self, *, value: str | None) -> None:
+        """Set the value of the data_point."""
+        await super().send_variable(value=value)

aiohomematic/model/hub/update.py

@@ -0,0 +1,221 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2026
+"""Module for hub update data point."""
+
+from __future__ import annotations
+
+import asyncio
+from datetime import datetime
+import logging
+from typing import Final
+
+from slugify import slugify
+
+from aiohomematic import i18n
+from aiohomematic.const import HUB_ADDRESS, DataPointCategory, SystemUpdateData
+from aiohomematic.decorators import inspector
+from aiohomematic.interfaces import (
+    CentralInfoProtocol,
+    ChannelProtocol,
+    ConfigProviderProtocol,
+    EventBusProviderProtocol,
+    EventPublisherProtocol,
+    GenericHubDataPointProtocol,
+    ParameterVisibilityProviderProtocol,
+    ParamsetDescriptionProviderProtocol,
+    PrimaryClientProviderProtocol,
+    TaskSchedulerProtocol,
+)
+from aiohomematic.model.data_point import CallbackDataPoint
+from aiohomematic.model.support import HubPathData, PathData, generate_unique_id, get_hub_data_point_name_data
+from aiohomematic.property_decorators import DelegatedProperty, Kind
+from aiohomematic.support import PayloadMixin
+
+_LOGGER: Final = logging.getLogger(__name__)
+
+_UPDATE_NAME: Final = "System Update"
+
+
+class HmUpdate(CallbackDataPoint, GenericHubDataPointProtocol, PayloadMixin):
+    """Class for a Homematic system update data point."""
+
+    __slots__ = (
+        "_available_firmware",
+        "_config_provider",
+        "_current_firmware",
+        "_name_data",
+        "_primary_client_provider",
+        "_state_uncertain",
+        "_update_available",
+        "_update_in_progress",
+        "_version_before_update",
+    )
+
+    _category = DataPointCategory.HUB_UPDATE
+    _enabled_default = True
+
+    def __init__(
+        self,
+        *,
+        config_provider: ConfigProviderProtocol,
+        central_info: CentralInfoProtocol,
+        event_bus_provider: EventBusProviderProtocol,
+        event_publisher: EventPublisherProtocol,
+        task_scheduler: TaskSchedulerProtocol,
+        paramset_description_provider: ParamsetDescriptionProviderProtocol,
+        parameter_visibility_provider: ParameterVisibilityProviderProtocol,
+        primary_client_provider: PrimaryClientProviderProtocol,
+    ) -> None:
+        """Initialize the data_point."""
+        PayloadMixin.__init__(self)
+        unique_id: Final = generate_unique_id(
+            config_provider=config_provider,
+            address=HUB_ADDRESS,
+            parameter=slugify(_UPDATE_NAME),
+        )
+        self._name_data: Final = get_hub_data_point_name_data(
+            channel=None, legacy_name=_UPDATE_NAME, central_name=central_info.name
+        )
+
+        super().__init__(
+            unique_id=unique_id,
+            central_info=central_info,
+            event_bus_provider=event_bus_provider,
+            event_publisher=event_publisher,
+            task_scheduler=task_scheduler,
+            paramset_description_provider=paramset_description_provider,
+            parameter_visibility_provider=parameter_visibility_provider,
+        )
+        self._config_provider: Final = config_provider
+        self._primary_client_provider: Final = primary_client_provider
+        self._state_uncertain: bool = True
+        self._current_firmware: str = ""
+        self._available_firmware: str = ""
+        self._update_available: bool = False
+        self._update_in_progress: bool = False
+        self._version_before_update: str | None = None
+
+    available: Final = DelegatedProperty[bool](path="_central_info.available", kind=Kind.STATE)
+    available_firmware: Final = DelegatedProperty[str](path="_available_firmware", kind=Kind.STATE)
+    current_firmware: Final = DelegatedProperty[str](path="_current_firmware", kind=Kind.STATE)
+    enabled_default: Final = DelegatedProperty[bool](path="_enabled_default")
+    full_name: Final = DelegatedProperty[str](path="_name_data.full_name")
+    in_progress: Final = DelegatedProperty[bool](path="_update_in_progress", kind=Kind.STATE)
+    name: Final = DelegatedProperty[str](path="_name_data.name", kind=Kind.CONFIG)
+    state_uncertain: Final = DelegatedProperty[bool](path="_state_uncertain")
+    update_available: Final = DelegatedProperty[bool](path="_update_available", kind=Kind.STATE)
+
+    @property
+    def channel(self) -> ChannelProtocol | None:
+        """Return the identified channel."""
+        return None
+
+    @property
+    def description(self) -> str | None:
+        """Return data point description."""
+        return None
+
+    @property
+    def legacy_name(self) -> str | None:
+        """Return the original name."""
+        return None
+
+    @inspector
+    async def install(self) -> bool:
+        """Trigger the firmware update process with progress monitoring."""
+        if client := self._primary_client_provider.primary_client:
+            # Store current version for progress detection
+            self._version_before_update = self._current_firmware
+            if result := await client.trigger_firmware_update():
+                self._update_in_progress = True
+                self.publish_data_point_updated_event()
+
+                # Start progress monitoring task
+                self._task_scheduler.create_task(
+                    target=self._monitor_update_progress(),
+                    name="hub_update_progress_monitor",
+                )
+
+            return result
+        return False
+
+    def update_data(self, *, data: SystemUpdateData, write_at: datetime) -> None:
+        """Update the data point with new system update data."""
+        do_update: bool = False
+        if self._current_firmware != data.current_firmware:
+            self._current_firmware = data.current_firmware
+            do_update = True
+        if self._available_firmware != data.available_firmware:
+            self._available_firmware = data.available_firmware
+            do_update = True
+        if self._update_available != data.update_available:
+            self._update_available = data.update_available
+            do_update = True
+
+        if do_update:
+            self._set_modified_at(modified_at=write_at)
+        else:
+            self._set_refreshed_at(refreshed_at=write_at)
+        self._state_uncertain = False
+        self.publish_data_point_updated_event()
+
+    def _get_path_data(self) -> PathData:
+        """Return the path data of the data_point."""
+        return HubPathData(name=slugify(_UPDATE_NAME))
+
+    def _get_signature(self) -> str:
+        """Return the signature of the data_point."""
+        return f"{self._category}/{self.name}"
+
+    async def _monitor_update_progress(self) -> None:
+        """Monitor update progress by polling system information."""
+        start_time = datetime.now()
+
+        try:
+            while (
+                datetime.now() - start_time
+            ).total_seconds() < self._config_provider.config.schedule_timer_config.system_update_progress_timeout:
+                await asyncio.sleep(
+                    self._config_provider.config.schedule_timer_config.system_update_progress_check_interval
+                )
+
+                if client := self._primary_client_provider.primary_client:
+                    try:
+                        update_info = await client.get_system_update_info()
+
+                        if update_info and update_info.current_firmware != self._version_before_update:
+                            _LOGGER.info(
+                                i18n.tr(
+                                    key="log.model.hub.update.progress_completed",
+                                    old_version=self._version_before_update,
+                                    new_version=update_info.current_firmware,
+                                )
+                            )
+                            # Update data with new firmware info
+                            self._current_firmware = update_info.current_firmware
+                            self._available_firmware = update_info.available_firmware
+                            self._update_available = update_info.update_available
+                            # Reset circuit breakers after successful update
+                            # to allow immediate data refresh
+                            client.reset_circuit_breakers()
+                            break
+                    except Exception as err:
+                        # CCU may be offline during reboot - continue polling
+                        _LOGGER.debug(
+                            i18n.tr(
+                                key="log.model.hub.update.progress_poll_error",
+                                error=str(err),
+                            )
+                        )
+            else:
+                _LOGGER.warning(
+                    i18n.tr(
+                        key="log.model.hub.update.progress_timeout",
+                        timeout=self._config_provider.config.schedule_timer_config.system_update_progress_timeout,
+                    )
+                )
+        finally:
+            self._update_in_progress = False
+            self._version_before_update = None
+            self._set_modified_at(modified_at=datetime.now())
+            self.publish_data_point_updated_event()