aiohomematic 2026.1.29__py3-none-any.whl

aiohomematic/rega_scripts/trigger_firmware_update.fn

@@ -0,0 +1,67 @@
+!# name: trigger_firmware_update.fn
+!#
+!# This script triggers an unattended firmware update.
+!# Only supported on OpenCCU (uses checkFirmwareUpdate.sh).
+!#
+!# The script validates:
+!# 1. checkFirmwareUpdate.sh exists and is executable
+!# 2. Script supports required flags (-a, -r) via -h output
+!#
+!# Then runs the update with nohup in background:
+!# -a = apply update (download and stage)
+!# -r = reboot immediately after staging
+!#
+!# Note: Backup (-b) is NOT used here. Use create_backup_and_download()
+!# before triggering the firmware update to download a backup.
+!#
+!# The script is started with nohup to ensure it continues running
+!# even if the connection is lost during the update/reboot process.
+!#
+
+string sResult = "";
+boolean bScriptAvailable = false;
+boolean bSuccess = false;
+string sMessage = "";
+
+!# Check if checkFirmwareUpdate.sh is available and supports required flags
+system.Exec("test -x /bin/checkFirmwareUpdate.sh && /bin/checkFirmwareUpdate.sh -h 2>&1", &sResult);
+if (sResult) {
+    !# Verify script supports required flags: -a (apply), -r (reboot)
+    boolean bHasApply = (sResult.Find("-a") >= 0);
+    boolean bHasReboot = (sResult.Find("-r") >= 0);
+
+    if (bHasApply && bHasReboot) {
+        bScriptAvailable = true;
+    }
+}
+
+if (bScriptAvailable) {
+    !# Save system state before update
+    system.Save();
+
+    !# Run checkFirmwareUpdate.sh with nohup in background
+    !# -a = apply update (download and stage)
+    !# -r = reboot immediately after staging
+    !# Note: Use create_backup_and_download() before this for backup
+    sResult = "";
+    system.Exec("nohup /bin/checkFirmwareUpdate.sh -a -r >/dev/null 2>&1 &", &sResult);
+
+    bSuccess = true;
+    sMessage = "Firmware update triggered, system will reboot when ready";
+} else {
+    sMessage = "checkFirmwareUpdate.sh not available or missing required flags (only supported on OpenCCU)";
+}
+
+Write('{"success":');
+if (bSuccess) {
+    Write('true,');
+} else {
+    Write('false,');
+}
+Write('"script_available":');
+if (bScriptAvailable) {
+    Write('true,');
+} else {
+    Write('false,');
+}
+Write('"message":"' # sMessage # '"}');

aiohomematic/schemas.py

@@ -0,0 +1,256 @@
+"""
+Validation and normalization schemas for API data structures.
+
+Uses voluptuous to validate and normalize data received from Homematic backends.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Any, Final
+
+import voluptuous as vol
+
+if TYPE_CHECKING:
+    from aiohomematic.const import DeviceDescription, ParameterData
+
+_LOGGER: Final = logging.getLogger(__name__)
+
+# ============================================================================
+# DeviceDescription Schema
+# ============================================================================
+
+
+def _normalize_children(*, value: Any) -> list[str]:
+    """Normalize CHILDREN field to always be a list."""
+    if value is None:
+        return []
+    if isinstance(value, str):
+        return [] if value == "" else [value]
+    if isinstance(value, (list, tuple)):
+        return list(value)
+    return []
+
+
+def _normalize_paramsets(*, value: Any) -> list[str]:
+    """Normalize PARAMSETS field to always be a list."""
+    if value is None:
+        return ["MASTER", "VALUES"]
+    if isinstance(value, (list, tuple)):
+        return list(value)
+    return ["MASTER", "VALUES"]
+
+
+DEVICE_DESCRIPTION_SCHEMA = vol.Schema(
+    {
+        # Required fields per API spec
+        vol.Required("TYPE"): vol.Coerce(str),
+        vol.Required("ADDRESS"): vol.Coerce(str),
+        vol.Required("PARAMSETS", default=["MASTER", "VALUES"]): lambda x: _normalize_paramsets(value=x),
+        # Optional fields with normalization
+        vol.Optional("CHILDREN", default=[]): lambda x: _normalize_children(value=x),
+        vol.Optional("PARENT"): vol.Any(None, str),
+        vol.Optional("PARENT_TYPE"): vol.Any(None, str),
+        vol.Optional("SUBTYPE"): vol.Any(None, str),
+        vol.Optional("FIRMWARE"): vol.Any(None, str),
+        vol.Optional("AVAILABLE_FIRMWARE"): vol.Any(None, str),
+        vol.Optional("UPDATABLE"): vol.Coerce(bool),
+        vol.Optional("FIRMWARE_UPDATE_STATE"): vol.Any(None, str),
+        vol.Optional("FIRMWARE_UPDATABLE"): vol.Any(None, bool),
+        vol.Optional("INTERFACE"): vol.Any(None, str),
+        # Per API spec: RX_MODE is Integer (bitmask)
+        vol.Optional("RX_MODE"): vol.Any(None, vol.Coerce(int)),
+        vol.Optional("LINK_SOURCE_ROLES"): vol.Any(None, str),
+        vol.Optional("LINK_TARGET_ROLES"): vol.Any(None, str),
+        # Additional fields from spec (currently commented in const.py)
+        vol.Optional("RF_ADDRESS"): vol.Any(None, vol.Coerce(int)),
+        vol.Optional("INDEX"): vol.Any(None, vol.Coerce(int)),
+        vol.Optional("AES_ACTIVE"): vol.Any(None, vol.Coerce(int)),
+        vol.Optional("VERSION"): vol.Any(None, vol.Coerce(int)),
+        vol.Optional("FLAGS"): vol.Any(None, vol.Coerce(int)),
+        vol.Optional("DIRECTION"): vol.Any(None, vol.Coerce(int)),
+        vol.Optional("GROUP"): vol.Any(None, str),
+        vol.Optional("TEAM"): vol.Any(None, str),
+        vol.Optional("TEAM_TAG"): vol.Any(None, str),
+        vol.Optional("TEAM_CHANNELS"): vol.Any(None, list),
+        vol.Optional("ROAMING"): vol.Any(None, vol.Coerce(int)),
+    },
+    extra=vol.ALLOW_EXTRA,  # Allow backend-specific extra fields
+)
+
+
+# ============================================================================
+# ParameterData Schema (ParameterDescription in API)
+# ============================================================================
+
+# Parameter TYPE values per API spec
+VALID_PARAMETER_TYPES = {
+    "FLOAT",
+    "INTEGER",
+    "BOOL",
+    "ENUM",
+    "STRING",
+    "ACTION",
+    # Additional types found in practice
+    "DUMMY",
+    "",
+}
+
+
+def _normalize_parameter_type(*, value: Any) -> str:
+    """Normalize and validate parameter TYPE field."""
+    if value is None:
+        return ""
+    str_val = str(value).upper()
+    return str_val if str_val in VALID_PARAMETER_TYPES else ""
+
+
+def _normalize_operations(*, value: Any) -> int:
+    """Normalize OPERATIONS to integer bitmask."""
+    if value is None:
+        return 0
+    try:
+        return int(value)
+    except (ValueError, TypeError):
+        return 0
+
+
+def _normalize_flags(*, value: Any) -> int:
+    """Normalize FLAGS to integer bitmask."""
+    if value is None:
+        return 0
+    try:
+        return int(value)
+    except (ValueError, TypeError):
+        return 0
+
+
+def _normalize_value_list(*, value: Any) -> list[str]:
+    """Normalize VALUE_LIST to list of strings."""
+    if value is None:
+        return []
+    if not isinstance(value, (list, tuple)):
+        return []
+    # Convert all items to strings
+    return [str(item) for item in value]
+
+
+PARAMETER_DATA_SCHEMA = vol.Schema(
+    {
+        vol.Optional("TYPE"): lambda x: _normalize_parameter_type(value=x),
+        vol.Optional("OPERATIONS", default=0): lambda x: _normalize_operations(value=x),
+        vol.Optional("FLAGS", default=0): lambda x: _normalize_flags(value=x),
+        vol.Optional("DEFAULT"): vol.Any(None, str, int, float, bool),
+        vol.Optional("MAX"): vol.Any(None, str, int, float),
+        vol.Optional("MIN"): vol.Any(None, str, int, float),
+        vol.Optional("UNIT"): vol.Any(None, str),
+        vol.Optional("ID"): vol.Any(None, str),
+        # Per API spec: TAB_ORDER is Integer (display ordering)
+        vol.Optional("TAB_ORDER"): vol.Any(None, vol.Coerce(int)),
+        # Per API spec: CONTROL is String (UI hint)
+        vol.Optional("CONTROL"): vol.Any(None, str),
+        # Per API spec: VALUE_LIST is Array of String (for ENUM type)
+        vol.Optional("VALUE_LIST", default=[]): lambda x: _normalize_value_list(value=x),
+        # Per API spec: SPECIAL is Array of Struct {ID: String, VALUE: <TYPE>}
+        # In practice: Dict with special value IDs as keys (e.g., {"NOT_USED": 111600.0})
+        vol.Optional("SPECIAL"): vol.Any(None, list, dict),
+    },
+    extra=vol.ALLOW_EXTRA,
+)
+
+
+# ============================================================================
+# ParamsetDescription Schema
+# ============================================================================
+
+
+def normalize_paramset_description(
+    *,
+    paramset: dict[str, Any] | None,
+) -> dict[str, ParameterData]:
+    """
+    Normalize a paramset description dict.
+
+    A ParamsetDescription is a Struct where each key is a parameter name
+    and each value is a ParameterDescription (ParameterData).
+    """
+    if paramset is None:
+        return {}
+    result: dict[str, ParameterData] = {}
+    for param_name, param_data in paramset.items():
+        try:
+            result[param_name] = PARAMETER_DATA_SCHEMA(param_data)
+        except vol.Invalid as err:
+            # Log validation failures for debugging
+            _LOGGER.debug(
+                "Parameter validation failed for %s: %s. Using raw data.",
+                param_name,
+                err,
+            )
+            # Keep original data if validation fails
+            result[param_name] = param_data
+    return result
+
+
+# ============================================================================
+# Public API
+# ============================================================================
+
+
+def normalize_device_description(*, device_description: dict[str, Any] | DeviceDescription) -> DeviceDescription:
+    """
+    Normalize a device description dict.
+
+    Should be called at all ingestion points:
+    - After receiving from list_devices()
+    - After receiving from get_device_description()
+    - After receiving from newDevices() callback
+    - After loading from cache
+
+    Args:
+        device_description: Raw device description from backend or cache.
+
+    Returns:
+        Normalized DeviceDescription dict with guaranteed field types.
+
+    """
+    try:
+        return dict(DEVICE_DESCRIPTION_SCHEMA(device_description))  # type: ignore[return-value]
+    except vol.Invalid as err:
+        # Log validation failures for debugging
+        address = device_description.get("ADDRESS", "UNKNOWN")
+        _LOGGER.debug(
+            "Device description validation failed for %s: %s. Applying fallback normalization.",
+            address,
+            err,
+        )
+        # On validation failure, at minimum ensure CHILDREN is a list
+        result = dict(device_description)
+        children = result.get("CHILDREN")
+        if children is None or isinstance(children, str):
+            result["CHILDREN"] = []
+        return result  # type: ignore[return-value]
+
+
+def normalize_parameter_data(*, parameter_data: dict[str, Any]) -> ParameterData:
+    """
+    Normalize a parameter data dict (ParameterDescription).
+
+    Args:
+        parameter_data: Raw parameter data from backend or cache.
+
+    Returns:
+        Normalized ParameterData dict with guaranteed field types.
+
+    """
+    try:
+        return dict(PARAMETER_DATA_SCHEMA(parameter_data))  # type: ignore[return-value]
+    except vol.Invalid as err:
+        # Log validation failures for debugging
+        param_id = parameter_data.get("ID", "UNKNOWN")
+        _LOGGER.debug(
+            "Parameter data validation failed for %s: %s. Using raw data.",
+            param_id,
+            err,
+        )
+        return dict(parameter_data)  # type: ignore[return-value]

aiohomematic/store/__init__.py

@@ -0,0 +1,55 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2026
+"""
+Store packages for AioHomematic.
+
+This package groups store implementations used throughout the library:
+- persistent: Long-lived on-disk registries for device and paramset descriptions.
+- dynamic: Short-lived in-memory caches/trackers for runtime values and connection health.
+- visibility: Parameter visibility rules to decide which parameters are relevant.
+- storage: Abstraction layer for file persistence with factory pattern.
+
+Package structure
+-----------------
+- storage.py: Storage abstraction with factory pattern for HA Store integration
+- persistent/: DeviceDescriptionRegistry, ParamsetDescriptionRegistry, SessionRecorder
+- dynamic/: CommandCache, DeviceDetailsCache, CentralDataCache, PingPongTracker
+- visibility/: ParameterVisibilityRegistry
+- types.py: Shared type definitions (CachedCommand, PongTracker, type aliases)
+- serialization.py: Freeze/unfreeze utilities for session recording
+
+"""
+
+from __future__ import annotations
+
+from aiohomematic.store.serialization import cleanup_params_for_session, freeze_params, unfreeze_params
+from aiohomematic.store.storage import (
+    LocalStorageFactory,
+    MigrateFunc,
+    Storage,
+    StorageError,
+    StorageFactoryProtocol,
+    StorageProtocol,
+)
+from aiohomematic.store.types import CacheName, CacheStatistics, IncidentSeverity, IncidentSnapshot, IncidentType
+
+__all__ = [
+    # Cache
+    "CacheName",
+    "CacheStatistics",
+    # Incident types
+    "IncidentSeverity",
+    "IncidentSnapshot",
+    "IncidentType",
+    # Serialization
+    "cleanup_params_for_session",
+    "freeze_params",
+    "unfreeze_params",
+    # Storage abstraction
+    "LocalStorageFactory",
+    "MigrateFunc",
+    "Storage",
+    "StorageError",
+    "StorageFactoryProtocol",
+    "StorageProtocol",
+]

aiohomematic/store/dynamic/__init__.py

@@ -0,0 +1,43 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2026
+"""
+Dynamic store used at runtime by the central unit and clients.
+
+This package provides short-lived, in-memory stores that support robust and efficient
+communication with Homematic interfaces.
+
+Package structure
+-----------------
+- command: CommandTracker for tracking sent commands
+- details: DeviceDetailsCache for device metadata
+- data: CentralDataCache for parameter values
+- ping_pong: PingPongTracker for connection health monitoring
+
+Key behaviors
+-------------
+- Stores are intentionally ephemeral and cleared/aged according to rules
+- Memory footprint is kept predictable while improving responsiveness
+
+Public API
+----------
+- CommandTracker: Tracks recently sent commands per data point
+- DeviceDetailsCache: Device names, rooms, functions, interfaces
+- CentralDataCache: Stores recently fetched parameter values
+- PingPongTracker: Connection health monitoring via ping/pong
+"""
+
+from __future__ import annotations
+
+from aiohomematic.store.dynamic.command import CommandTracker
+from aiohomematic.store.dynamic.data import CentralDataCache
+from aiohomematic.store.dynamic.details import DeviceDetailsCache
+from aiohomematic.store.dynamic.ping_pong import PingPongTracker
+
+__all__ = [
+    # Caches
+    "CentralDataCache",
+    "DeviceDetailsCache",
+    # Trackers
+    "CommandTracker",
+    "PingPongTracker",
+]

aiohomematic/store/dynamic/command.py

@@ -0,0 +1,250 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2026
+"""
+Command tracker for tracking recently sent commands.
+
+This module provides CommandTracker which tracks recently sent commands per data point
+with automatic expiry and configurable size limits to prevent unbounded memory growth.
+
+Memory management strategy (three-tier approach):
+    1. Lazy cleanup: When tracker exceeds CLEANUP_THRESHOLD, remove expired entries
+    2. Warning threshold: Log warning when approaching MAX_SIZE (hysteresis prevents spam)
+    3. Hard limit eviction: When MAX_SIZE reached, remove oldest 20% of entries
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+import logging
+from typing import Any, Final
+
+from aiohomematic.const import (
+    COMMAND_TRACKER_MAX_SIZE,
+    COMMAND_TRACKER_WARNING_THRESHOLD,
+    DP_KEY_VALUE,
+    LAST_COMMAND_SEND_STORE_TIMEOUT,
+    LAST_COMMAND_SEND_TRACKER_CLEANUP_THRESHOLD,
+    DataPointKey,
+    ParamsetKey,
+)
+from aiohomematic.converter import CONVERTABLE_PARAMETERS, convert_combined_parameter_to_paramset
+from aiohomematic.store.types import CachedCommand, TrackerStatistics
+from aiohomematic.support import changed_within_seconds
+
+_LOGGER: Final = logging.getLogger(__name__)
+
+
+class CommandTracker:
+    """
+    Tracker for sent commands with resource limits.
+
+    Tracks recently sent commands per data point with automatic expiry
+    and configurable size limits to prevent unbounded memory growth.
+
+    Memory management strategy (three-tier approach):
+        1. Lazy cleanup: When tracker exceeds CLEANUP_THRESHOLD, remove expired entries
+        2. Warning threshold: Log warning when approaching MAX_SIZE (hysteresis prevents spam)
+        3. Hard limit eviction: When MAX_SIZE reached, remove oldest 20% of entries
+
+    The 20% eviction rate balances memory reclamation against the cost of repeated
+    evictions (avoiding evicting just 1 entry repeatedly).
+    """
+
+    __slots__ = (
+        "_interface_id",
+        "_last_send_command",
+        "_stats",
+        "_warning_logged",
+    )
+
+    def __init__(self, *, interface_id: str) -> None:
+        """Initialize command tracker."""
+        self._interface_id: Final = interface_id
+        self._stats: Final = TrackerStatistics()
+        # Maps DataPointKey to CachedCommand for tracking recent commands.
+        # Used to detect duplicate sends and for unconfirmed value tracking.
+        self._last_send_command: Final[dict[DataPointKey, CachedCommand]] = {}
+        # Hysteresis flag to prevent repeated warning logs
+        self._warning_logged: bool = False
+
+    @property
+    def size(self) -> int:
+        """Return the current tracker size."""
+        return len(self._last_send_command)
+
+    @property
+    def statistics(self) -> TrackerStatistics:
+        """Return the tracker statistics."""
+        return self._stats
+
+    def add_combined_parameter(
+        self, *, parameter: str, channel_address: str, combined_parameter: str
+    ) -> set[DP_KEY_VALUE]:
+        """Add data from combined parameter."""
+        if values := convert_combined_parameter_to_paramset(parameter=parameter, value=combined_parameter):
+            return self.add_put_paramset(
+                channel_address=channel_address,
+                paramset_key=ParamsetKey.VALUES,
+                values=values,
+            )
+        return set()
+
+    def add_put_paramset(
+        self, *, channel_address: str, paramset_key: ParamsetKey, values: dict[str, Any]
+    ) -> set[DP_KEY_VALUE]:
+        """Add data from put paramset command."""
+        # Cleanup expired entries when tracker size exceeds threshold
+        if len(self._last_send_command) > LAST_COMMAND_SEND_TRACKER_CLEANUP_THRESHOLD:
+            self.cleanup_expired()
+
+        # Enforce hard size limit
+        self._enforce_size_limit()
+
+        dpk_values: set[DP_KEY_VALUE] = set()
+        now_ts = datetime.now()
+        for parameter, value in values.items():
+            dpk = DataPointKey(
+                interface_id=self._interface_id,
+                channel_address=channel_address,
+                paramset_key=paramset_key,
+                parameter=parameter,
+            )
+            self._last_send_command[dpk] = CachedCommand(value=value, sent_at=now_ts)
+            dpk_values.add((dpk, value))
+        return dpk_values
+
+    def add_set_value(
+        self,
+        *,
+        channel_address: str,
+        parameter: str,
+        value: Any,
+    ) -> set[DP_KEY_VALUE]:
+        """Add data from set value command."""
+        if parameter in CONVERTABLE_PARAMETERS:
+            return self.add_combined_parameter(
+                parameter=parameter, channel_address=channel_address, combined_parameter=value
+            )
+
+        # Cleanup expired entries when tracker size exceeds threshold
+        if len(self._last_send_command) > LAST_COMMAND_SEND_TRACKER_CLEANUP_THRESHOLD:
+            self.cleanup_expired()
+
+        # Enforce hard size limit
+        self._enforce_size_limit()
+
+        now_ts = datetime.now()
+        dpk = DataPointKey(
+            interface_id=self._interface_id,
+            channel_address=channel_address,
+            paramset_key=ParamsetKey.VALUES,
+            parameter=parameter,
+        )
+        self._last_send_command[dpk] = CachedCommand(value=value, sent_at=now_ts)
+        return {(dpk, value)}
+
+    def cleanup_expired(self, *, max_age: int = LAST_COMMAND_SEND_STORE_TIMEOUT) -> int:
+        """
+        Remove expired command tracker entries.
+
+        Return the number of entries removed.
+
+        Two-pass algorithm (safer than deleting during iteration):
+            1. First pass: Collect keys of expired entries into a list
+            2. Second pass: Delete collected keys from the dictionary
+
+        This avoids "dictionary changed size during iteration" errors.
+        """
+        # Pass 1: Identify expired entries without modifying the dict
+        expired_keys = [
+            dpk
+            for dpk, cached in self._last_send_command.items()
+            if not changed_within_seconds(last_change=cached.sent_at, max_age=max_age)
+        ]
+        # Pass 2: Delete expired entries
+        for dpk in expired_keys:
+            del self._last_send_command[dpk]
+        # Track evictions via local counter
+        if expired_keys:
+            self._stats.record_eviction(count=len(expired_keys))
+        return len(expired_keys)
+
+    def clear(self) -> None:
+        """Clear all tracked command entries."""
+        self._last_send_command.clear()
+
+    def get_last_value_send(self, *, dpk: DataPointKey, max_age: int = LAST_COMMAND_SEND_STORE_TIMEOUT) -> Any:
+        """Return the last send values."""
+        if cached := self._last_send_command.get(dpk):
+            if cached.sent_at and changed_within_seconds(last_change=cached.sent_at, max_age=max_age):
+                return cached.value
+            self.remove_last_value_send(
+                dpk=dpk,
+                max_age=max_age,
+            )
+        return None
+
+    def remove_last_value_send(
+        self,
+        *,
+        dpk: DataPointKey,
+        value: Any = None,
+        max_age: int = LAST_COMMAND_SEND_STORE_TIMEOUT,
+    ) -> None:
+        """Remove the last send value."""
+        if (cached := self._last_send_command.get(dpk)) is not None and (
+            not changed_within_seconds(last_change=cached.sent_at, max_age=max_age)
+            or (value is not None and cached.value == value)
+        ):
+            del self._last_send_command[dpk]
+
+    def _enforce_size_limit(self) -> None:
+        """
+        Enforce size limits on the tracker to prevent unbounded growth.
+
+        LRU-style eviction algorithm:
+            When tracker reaches MAX_SIZE, evict the oldest 20% of entries.
+            The 20% threshold is a heuristic that balances:
+            - Memory reclamation (enough entries removed to be meaningful)
+            - Performance (not called too frequently)
+            - Data retention (most recent entries are preserved)
+
+        Warning hysteresis:
+            The _warning_logged flag prevents log spam when tracker size oscillates
+            near the warning threshold. Warning is logged once when threshold is
+            exceeded, then reset only when size drops below threshold.
+        """
+        current_size = len(self._last_send_command)
+
+        # Warning with hysteresis: log once when crossing threshold, reset when below
+        if current_size >= COMMAND_TRACKER_WARNING_THRESHOLD and not self._warning_logged:
+            _LOGGER.warning(  # i18n-log: ignore
+                "CommandTracker for %s approaching size limit: %d/%d entries",
+                self._interface_id,
+                current_size,
+                COMMAND_TRACKER_MAX_SIZE,
+            )
+            self._warning_logged = True
+        elif current_size < COMMAND_TRACKER_WARNING_THRESHOLD:
+            # Reset warning flag when tracker shrinks below threshold
+            self._warning_logged = False
+
+        # Hard limit enforcement with LRU eviction
+        if current_size >= COMMAND_TRACKER_MAX_SIZE:
+            # Sort entries by timestamp (oldest first) for LRU eviction
+            sorted_entries = sorted(
+                self._last_send_command.items(),
+                key=lambda item: item[1].sent_at,
+            )
+            # Remove oldest 20% of entries (at least 1)
+            remove_count = max(1, current_size // 5)
+            for dpk, _ in sorted_entries[:remove_count]:
+                del self._last_send_command[dpk]
+            # Track evictions via local counter
+            self._stats.record_eviction(count=remove_count)
+            _LOGGER.debug(
+                "CommandTracker for %s evicted %d oldest entries (size was %d)",
+                self._interface_id,
+                remove_count,
+                current_size,
+            )