aiohomematic 2026.1.29__py3-none-any.whl

aiohomematic/metrics/stats.py

@@ -0,0 +1,172 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2026
+"""
+Mutable statistics classes for metrics tracking.
+
+This module provides mutable dataclasses for tracking runtime statistics.
+These are used by components to record metrics which are then aggregated.
+
+Public API
+----------
+- CacheStats: Cache hit/miss/size statistics
+- LatencyStats: Request latency statistics (count, min, max, avg)
+- ServiceStats: Service method execution statistics (call count, errors, timing)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import math
+
+
+@dataclass(slots=True)
+class SizeOnlyStats:
+    """
+    Size-only statistics for registries and trackers.
+
+    Used for components that are not true caches (no hit/miss semantics):
+    - DeviceDescriptionRegistry (authoritative store)
+    - ParamsetDescriptionRegistry (authoritative store)
+    - ParameterVisibilityRegistry (rule engine with memoization)
+    - PingPongTracker (connection health tracker)
+    - CommandTracker (sent command tracker)
+    """
+
+    size: int = 0
+    """Current number of entries."""
+
+    evictions: int = 0
+    """Number of entries removed (for memory management, not cache semantics)."""
+
+
+@dataclass(slots=True)
+class CacheStats:
+    """
+    Statistics for cache performance monitoring.
+
+    Used for true caches with hit/miss semantics:
+    - CentralDataCache
+    """
+
+    hits: int = 0
+    """Number of successful cache lookups."""
+
+    misses: int = 0
+    """Number of cache misses."""
+
+    size: int = 0
+    """Current number of entries in the cache."""
+
+    evictions: int = 0
+    """Number of entries evicted from the cache."""
+
+    @property
+    def hit_rate(self) -> float:
+        """Return hit rate as percentage."""
+        if (total := self.hits + self.misses) == 0:
+            return 100.0
+        return (self.hits / total) * 100
+
+    def record_hit(self) -> None:
+        """Record a cache hit."""
+        self.hits += 1
+
+    def record_miss(self) -> None:
+        """Record a cache miss."""
+        self.misses += 1
+
+    def reset(self) -> None:
+        """Reset cache statistics."""
+        self.hits = 0
+        self.misses = 0
+        self.size = 0
+        self.evictions = 0
+
+
+@dataclass(slots=True)
+class LatencyStats:
+    """Statistics for request latency tracking."""
+
+    count: int = 0
+    """Number of latency samples."""
+
+    total_ms: float = 0.0
+    """Total latency in milliseconds."""
+
+    min_ms: float = math.inf
+    """Minimum latency in milliseconds."""
+
+    max_ms: float = 0.0
+    """Maximum latency in milliseconds."""
+
+    @property
+    def avg_ms(self) -> float:
+        """Return average latency in milliseconds."""
+        if self.count == 0:
+            return 0.0
+        return self.total_ms / self.count
+
+    def record(self, *, duration_ms: float) -> None:
+        """Record a latency sample."""
+        self.count += 1
+        self.total_ms += duration_ms
+        self.min_ms = min(self.min_ms, duration_ms)
+        self.max_ms = max(self.max_ms, duration_ms)
+
+    def reset(self) -> None:
+        """Reset latency statistics."""
+        self.count = 0
+        self.total_ms = 0.0
+        self.min_ms = math.inf
+        self.max_ms = 0.0
+
+
+@dataclass(slots=True)
+class ServiceStats:
+    """
+    Statistics for service method execution tracking.
+
+    This class tracks call counts, errors, and timing for service methods
+    decorated with @inspector(measure_performance=True).
+    """
+
+    call_count: int = 0
+    """Total number of calls to this method."""
+
+    error_count: int = 0
+    """Number of calls that raised exceptions."""
+
+    total_duration_ms: float = 0.0
+    """Total execution time in milliseconds."""
+
+    max_duration_ms: float = 0.0
+    """Maximum execution time in milliseconds."""
+
+    @property
+    def avg_duration_ms(self) -> float:
+        """Return average execution time in milliseconds."""
+        if self.call_count == 0:
+            return 0.0
+        return self.total_duration_ms / self.call_count
+
+    @property
+    def error_rate(self) -> float:
+        """Return error rate as percentage."""
+        if self.call_count == 0:
+            return 0.0
+        return (self.error_count / self.call_count) * 100
+
+    def record(self, *, duration_ms: float, had_error: bool) -> None:
+        """Record a service call."""
+        self.call_count += 1
+        self.total_duration_ms += duration_ms
+        self.max_duration_ms = max(self.max_duration_ms, duration_ms)
+        if had_error:
+            self.error_count += 1
+
+    def reset(self) -> None:
+        """Reset all statistics."""
+        self.call_count = 0
+        self.error_count = 0
+        self.total_duration_ms = 0.0
+        self.max_duration_ms = 0.0

aiohomematic/model/__init__.py

@@ -0,0 +1,189 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2026
+"""
+Data point and event model for AioHomematic.
+
+Overview
+--------
+This package provides the runtime model layer that transforms device and channel
+parameter descriptions from Homematic backends into typed data point objects and
+events. It orchestrates the creation of data point hierarchies (devices, channels,
+data points) and manages their lifecycle.
+
+The model layer is purely domain-focused with no I/O operations. All backend
+communication is delegated to the client layer through protocol interfaces.
+
+Subpackages
+-----------
+The model is organized into specialized data point types:
+
+- **generic**: Default data point implementations (switch, number, sensor, select,
+  binary_sensor, button, action, text) for standard parameter types.
+- **custom**: Device-specific implementations providing higher-level abstractions
+  (climate, cover, light, lock, siren, valve) for complex multi-parameter devices.
+- **calculated**: Derived data points computing values from other data points
+  (e.g., dew point, apparent temperature, battery level percentage).
+- **hub**: Backend system data points including programs and system variables exposed
+  by the CCU/Homegear hub.
+
+Public API
+----------
+- `create_data_points_and_events`: Main factory function for populating device
+  channels with data points and events based on paramset descriptions.
+
+Workflow
+--------
+During device initialization, `create_data_points_and_events` is invoked for each
+device. It performs the following steps:
+
+1. Iterates through all device channels and their paramset descriptions.
+2. Applies visibility rules to filter relevant parameters.
+3. Creates event objects for parameters supporting EVENT operations.
+4. Creates appropriate data point instances (generic or custom).
+5. Instantiates calculated data points based on available source data points.
+
+The resulting data point objects are registered with their parent channels and
+become accessible through the central unit's query API.
+
+Notes
+-----
+The entrypoint function is decorated with `@inspector` for automatic exception
+handling and logging. All data point creation follows the factory pattern with
+type selection based on parameter metadata and device profiles.
+
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+import logging
+from typing import Final
+
+from aiohomematic.const import (
+    CLICK_EVENTS,
+    DEVICE_ERROR_EVENTS,
+    IMPULSE_EVENTS,
+    Field,
+    Flag,
+    Operations,
+    Parameter,
+    ParameterData,
+    ParamsetKey,
+    ServiceScope,
+)
+from aiohomematic.decorators import inspector
+from aiohomematic.interfaces.model import ChannelProtocol, DeviceProtocol
+from aiohomematic.model.availability import AvailabilityInfo
+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__ = [
+    # Data classes
+    "AvailabilityInfo",
+    # Factory
+    "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[Mapping[Field, Parameter]] = {
+    Field.DIRECTION: Parameter.DIRECTION,
+    Field.ON_TIME_LIST: Parameter.ON_TIME_LIST_1,
+    Field.REPETITIONS: Parameter.REPETITIONS,
+}
+_LOGGER: Final = logging.getLogger(__name__)
+
+
+@inspector(scope=ServiceScope.INTERNAL)
+def create_data_points_and_events(*, device: DeviceProtocol) -> 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.parameter_visibility_provider.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.parameter_visibility_provider.parameter_is_un_ignored(
+                    channel=channel,
+                    paramset_key=paramset_key,
+                    parameter=parameter,
+                )
+                if channel.device.parameter_visibility_provider.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: ChannelProtocol,
+    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.values()
+            and not parameter_is_un_ignored
+        )
+    )

aiohomematic/model/availability.py

@@ -0,0 +1,65 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2026
+"""
+Availability information for Homematic devices.
+
+This module provides the AvailabilityInfo dataclass that bundles
+device reachability, battery state, and signal strength information
+into a single unified view for external consumers.
+
+Public API of this module is defined by __all__.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Final
+
+__all__: Final = ["AvailabilityInfo"]
+
+
+@dataclass(frozen=True, slots=True)
+class AvailabilityInfo:
+    """
+    Bundled availability information for a Homematic device.
+
+    Provides a unified view of device connectivity and health status,
+    combining reachability, battery state, and signal strength.
+
+    This dataclass is immutable (frozen) to ensure thread-safety when
+    passed between components.
+
+    Example:
+        >>> info = device.availability
+        >>> if not info.is_reachable:
+        ...     print(f"Device unreachable since {info.last_updated}")
+        >>> if info.low_battery:
+        ...     print(f"Battery low: {info.battery_level}%")
+
+    """
+
+    is_reachable: bool
+    """Device is reachable (inverse of UNREACH parameter)."""
+
+    last_updated: datetime | None
+    """Most recent data point modification time across all channels."""
+
+    battery_level: int | None = None
+    """Battery level percentage (0-100), from OperatingVoltageLevel or BATTERY_STATE."""
+
+    low_battery: bool | None = None
+    """Low battery indicator from LOW_BAT parameter."""
+
+    signal_strength: int | None = None
+    """Signal strength in dBm from RSSI_DEVICE (negative values, e.g., -65)."""
+
+    @property
+    def has_battery(self) -> bool:
+        """Return True if any battery information is available."""
+        return self.battery_level is not None or self.low_battery is not None
+
+    @property
+    def has_signal_info(self) -> bool:
+        """Return True if signal strength information is available."""
+        return self.signal_strength is not None

aiohomematic/model/calculated/__init__.py

@@ -0,0 +1,89 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2026
+"""
+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.const import ServiceScope
+from aiohomematic.decorators import inspector
+from aiohomematic.interfaces.model import ChannelProtocol
+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__ = [
+    # Base
+    "CalculatedDataPoint",
+    # Climate
+    "ApparentTemperature",
+    "DewPoint",
+    "DewPointSpread",
+    "Enthalpy",
+    "FrostPoint",
+    "VaporConcentration",
+    # Factory
+    "create_calculated_data_points",
+    # Voltage
+    "OperatingVoltageLevel",
+]
+
+_CALCULATED_DATA_POINTS: Final = (
+    ApparentTemperature,
+    DewPoint,
+    DewPointSpread,
+    Enthalpy,
+    FrostPoint,
+    OperatingVoltageLevel,
+    VaporConcentration,
+)
+_LOGGER: Final = logging.getLogger(__name__)
+
+
+@inspector(scope=ServiceScope.INTERNAL)
+def create_calculated_data_points(*, channel: ChannelProtocol) -> 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))