python-qube-heatpump 1.13.0__tar.gz → 1.14.0__tar.gz

{python_qube_heatpump-1.13.0 → python_qube_heatpump-1.14.0}/.github/workflows/ci.yml

@@ -19,7 +19,7 @@ jobs:
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
-        pip install ".[test]" ruff
+        pip install ".[test]" ruff==0.14.14
     - name: Lint with ruff
       run: |
         ruff check .

{python_qube_heatpump-1.13.0 → python_qube_heatpump-1.14.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: python-qube-heatpump
-Version: 1.13.0
+Version: 1.14.0
 Summary: Async Modbus client for Qube Heat Pumps
 Project-URL: Homepage, https://github.com/MattieGit/python-qube-heatpump
 Project-URL: Bug Tracker, https://github.com/MattieGit/python-qube-heatpump/issues
@@ -53,6 +53,7 @@ asyncio.run(main())
 - **Entity definitions** for sensors, binary sensors, and switches
 - **FLOAT32 decoding** with big endian (ABCD) byte order
 - **Type-safe dataclasses** for entity definitions
+- **Monotonic clamping with reset detection** for the energy totals: sub-kWh jitter is clamped, while a drop of more than 1 kWh that persists for 3 consecutive reads is accepted as a counter reset (logged as a warning); `clear_monotonic_cache()` forgets all baselines
 
 ## Entity Definitions
 

{python_qube_heatpump-1.13.0 → python_qube_heatpump-1.14.0}/README.md

@@ -34,6 +34,7 @@ asyncio.run(main())
 - **Entity definitions** for sensors, binary sensors, and switches
 - **FLOAT32 decoding** with big endian (ABCD) byte order
 - **Type-safe dataclasses** for entity definitions
+- **Monotonic clamping with reset detection** for the energy totals: sub-kWh jitter is clamped, while a drop of more than 1 kWh that persists for 3 consecutive reads is accepted as a counter reset (logged as a warning); `clear_monotonic_cache()` forgets all baselines
 
 ## Entity Definitions
 

{python_qube_heatpump-1.13.0 → python_qube_heatpump-1.14.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "python-qube-heatpump"
-version = "1.13.0"
+version = "1.14.0"
 authors = [
   { name="MattieGit", email="6250046+MattieGit@users.noreply.github.com" },
 ]

{python_qube_heatpump-1.13.0 → python_qube_heatpump-1.14.0}/src/python_qube_heatpump/client.py

@@ -149,6 +149,9 @@ class QubeClient:
         self._next_connect_at: float = 0.0
         # Monotonic clamping for total_increasing counters
         self._monotonic_cache: dict[str, float] = {}
+        # Per-key count of consecutive reads that fell below the cached
+        # maximum by more than the reset threshold (see clamp_monotonic)
+        self._monotonic_reset_pending: dict[str, int] = {}
         # Reads that already produced a WARNING (transient failures are
         # logged once per target, then at DEBUG to avoid log spam)
         self._read_failures_warned: set[str] = set()
@@ -254,17 +257,48 @@ class QubeClient:
     def monotonic_cache(self, value: dict[str, float]) -> None:
         """Set the monotonic clamping cache (e.g. restored from disk)."""
         self._monotonic_cache = dict(value)
+        self._monotonic_reset_pending.clear()
 
-    def clamp_monotonic(self, key: str, value: float | None) -> float | None:
+    def clear_monotonic_cache(self) -> None:
+        """Forget all monotonic baselines.
+
+        The next reading of every counter is accepted as-is. Use this when
+        the controller's counters were reset on purpose and the clamped
+        values in the cache are known to be stale.
+        """
+        self._monotonic_cache.clear()
+        self._monotonic_reset_pending.clear()
+
+    # A drop below the cached maximum larger than this (in the counter's own
+    # unit: kWh for the energy totals) is treated as a counter reset rather
+    # than float32 jitter or a transient glitch...
+    MONOTONIC_RESET_THRESHOLD: float = 1.0
+    # ...but only after it has been seen on this many consecutive reads, so a
+    # single glitched zero read never drops a total_increasing counter.
+    MONOTONIC_RESET_CONFIRM_READS: int = 3
+
+    def clamp_monotonic(
+        self,
+        key: str,
+        value: float | None,
+        reset_threshold: float | None = None,
+    ) -> float | None:
         """Clamp a value to prevent decreases for total_increasing counters.
 
-        Returns the clamped value. If the new value is lower than the
-        previously seen value for this key, the previous value is returned.
-        None and non-finite values pass through unchanged.
+        If the new value is lower than the previously seen value for this
+        key by less than ``reset_threshold``, the previous value is returned
+        (jitter suppression). A larger drop is a counter-reset candidate: it
+        is still clamped until it has persisted for
+        ``MONOTONIC_RESET_CONFIRM_READS`` consecutive reads, after which the
+        low value is accepted as the new baseline and a warning is logged.
+        None and non-finite values pass through unchanged and do not affect
+        the reset detection.
 
         Args:
             key: Identifier for this counter (e.g. entity unique_id).
             value: The current reading.
+            reset_threshold: Drop size that counts as a reset; defaults to
+                ``MONOTONIC_RESET_THRESHOLD``.
 
         Returns:
             The clamped value, or None if input was None/non-finite.
@@ -272,8 +306,35 @@ class QubeClient:
         if value is None or not math.isfinite(value):
             return value
         previous = self._monotonic_cache.get(key)
-        if previous is not None and value < previous:
+        if previous is None or value >= previous:
+            self._monotonic_cache[key] = value
+            self._monotonic_reset_pending.pop(key, None)
+            return value
+
+        threshold = (
+            self.MONOTONIC_RESET_THRESHOLD
+            if reset_threshold is None
+            else reset_threshold
+        )
+        if previous - value < threshold:
+            # Sub-threshold jitter: clamp and forget any pending reset
+            self._monotonic_reset_pending.pop(key, None)
             return previous
+
+        pending = self._monotonic_reset_pending.get(key, 0) + 1
+        if pending < self.MONOTONIC_RESET_CONFIRM_READS:
+            self._monotonic_reset_pending[key] = pending
+            return previous
+
+        _LOGGER.warning(
+            "Counter reset detected for %s: value dropped from %s to %s on %d "
+            "consecutive reads; accepting it as the new baseline",
+            key,
+            previous,
+            value,
+            pending,
+        )
+        self._monotonic_reset_pending.pop(key, None)
         self._monotonic_cache[key] = value
         return value
 

{python_qube_heatpump-1.13.0 → python_qube_heatpump-1.14.0}/src/python_qube_heatpump/entities/sensors.py

@@ -51,7 +51,7 @@ _SENSOR_DEFS: tuple[EntityDef, ...] = (
     ),
     EntityDef(
         key="tapw_timeprogram_dhws",
-        name="Minimum temperature DHW",
+        name="DHW setpoint (user)",
         address=44,
         input_type=InputType.HOLDING_REGISTER,
         data_type=DataType.FLOAT32,
@@ -60,7 +60,7 @@ _SENSOR_DEFS: tuple[EntityDef, ...] = (
     ),
     EntityDef(
         key="tapw_timeprogram_dhws_prog",
-        name="DHW temperature (active program)",
+        name="DHW setpoint (time program, Linq min.)",
         address=46,
         input_type=InputType.HOLDING_REGISTER,
         data_type=DataType.FLOAT32,
@@ -107,7 +107,7 @@ _SENSOR_DEFS: tuple[EntityDef, ...] = (
     ),
     EntityDef(
         key="tapw_timeprogram_dhwsetp_nolinq",
-        name="User-defined DHW setpoint",
+        name="DHW setpoint (Modbus)",
         address=173,
         input_type=InputType.HOLDING_REGISTER,
         data_type=DataType.FLOAT32,
@@ -299,7 +299,7 @@ _SENSOR_DEFS: tuple[EntityDef, ...] = (
     ),
     EntityDef(
         key="dhw_setp",
-        name="DHW calculated setpoint",
+        name="Active DHW setpoint",
         address=47,
         input_type=InputType.INPUT_REGISTER,
         data_type=DataType.FLOAT32,
@@ -453,7 +453,7 @@ _SENSOR_DEFS: tuple[EntityDef, ...] = (
     ),
     EntityDef(
         key="setpoint_dhw",
-        name="User-defined DHW setpoint",
+        name="DHW setpoint (Modbus)",
         address=173,
         input_type=InputType.HOLDING_REGISTER,
         data_type=DataType.FLOAT32,

{python_qube_heatpump-1.13.0 → python_qube_heatpump-1.14.0}/tests/test_client.py

@@ -1,5 +1,6 @@
 """Test the Qube Heat Pump client."""
 
+import logging
 from unittest.mock import AsyncMock, MagicMock
 
 import pytest
@@ -591,3 +592,102 @@ async def test_read_entity_warns_again_per_entity(mock_modbus_client, caplog):
 
     warnings = [r for r in caplog.records if r.levelno == logging.WARNING]
     assert len(warnings) == 2
+
+
+@pytest.mark.asyncio
+async def test_clamp_monotonic_reset_detected_after_confirmation(mock_modbus_client):
+    """A drop larger than the reset threshold becomes the new baseline once confirmed."""
+    client = QubeClient("1.2.3.4", 502)
+    assert client.clamp_monotonic("energy", 1000.0) == 1000.0
+
+    # First two low reads are still clamped (could be a transient glitch)
+    assert client.clamp_monotonic("energy", 3.0) == 1000.0
+    assert client.clamp_monotonic("energy", 3.1) == 1000.0
+    # Third consecutive low read confirms the reset
+    assert client.clamp_monotonic("energy", 3.2) == 3.2
+    assert client.monotonic_cache["energy"] == 3.2
+    # Counting resumes from the new baseline
+    assert client.clamp_monotonic("energy", 3.5) == 3.5
+
+
+@pytest.mark.asyncio
+async def test_clamp_monotonic_reset_logs_warning(mock_modbus_client, caplog):
+    """Confirming a reset logs a warning naming the key."""
+    client = QubeClient("1.2.3.4", 502)
+    client.clamp_monotonic("energy_total_thermic", 500.0)
+    with caplog.at_level(logging.WARNING):
+        for _ in range(QubeClient.MONOTONIC_RESET_CONFIRM_READS):
+            client.clamp_monotonic("energy_total_thermic", 0.0)
+    assert "Counter reset detected" in caplog.text
+    assert "energy_total_thermic" in caplog.text
+
+
+@pytest.mark.asyncio
+async def test_clamp_monotonic_transient_glitch_does_not_reset(mock_modbus_client):
+    """A single low read followed by recovery must not become a new baseline."""
+    client = QubeClient("1.2.3.4", 502)
+    client.clamp_monotonic("energy", 1000.0)
+
+    assert client.clamp_monotonic("energy", 0.0) == 1000.0
+    assert client.clamp_monotonic("energy", 0.0) == 1000.0
+    # Recovery cancels the pending reset
+    assert client.clamp_monotonic("energy", 1000.2) == 1000.2
+    # A fresh low read starts counting from scratch again
+    assert client.clamp_monotonic("energy", 0.0) == 1000.2
+    assert client.clamp_monotonic("energy", 0.0) == 1000.2
+    assert client.monotonic_cache["energy"] == 1000.2
+
+
+@pytest.mark.asyncio
+async def test_clamp_monotonic_sub_threshold_jitter_still_clamped(mock_modbus_client):
+    """Drops smaller than the threshold are jitter and stay clamped forever."""
+    client = QubeClient("1.2.3.4", 502)
+    client.clamp_monotonic("energy", 1000.0)
+    for _ in range(10):
+        assert client.clamp_monotonic("energy", 999.5) == 1000.0
+    assert client.monotonic_cache["energy"] == 1000.0
+    # Jitter reads do not count towards reset confirmation
+    assert client.clamp_monotonic("energy", 0.0) == 1000.0
+    assert client.clamp_monotonic("energy", 0.0) == 1000.0
+    assert client.clamp_monotonic("energy", 999.5) == 1000.0
+    assert client.clamp_monotonic("energy", 0.0) == 1000.0
+    assert client.clamp_monotonic("energy", 0.0) == 1000.0
+    assert client.monotonic_cache["energy"] == 1000.0
+
+
+@pytest.mark.asyncio
+async def test_clamp_monotonic_custom_threshold(mock_modbus_client):
+    """The reset threshold can be overridden per call."""
+    client = QubeClient("1.2.3.4", 502)
+    client.clamp_monotonic("hours", 100.0, reset_threshold=10.0)
+    # A 5-unit drop is below the custom threshold: clamped, never a reset
+    for _ in range(5):
+        assert client.clamp_monotonic("hours", 95.0, reset_threshold=10.0) == 100.0
+    # A 50-unit drop is a reset
+    for _ in range(QubeClient.MONOTONIC_RESET_CONFIRM_READS - 1):
+        assert client.clamp_monotonic("hours", 50.0, reset_threshold=10.0) == 100.0
+    assert client.clamp_monotonic("hours", 50.0, reset_threshold=10.0) == 50.0
+
+
+@pytest.mark.asyncio
+async def test_clear_monotonic_cache(mock_modbus_client):
+    """Clearing the cache forgets baselines and pending resets."""
+    client = QubeClient("1.2.3.4", 502)
+    client.clamp_monotonic("energy", 1000.0)
+    client.clamp_monotonic("energy", 0.0)  # pending reset
+    client.clear_monotonic_cache()
+    assert client.monotonic_cache == {}
+    # Next read is accepted as a fresh baseline
+    assert client.clamp_monotonic("energy", 5.0) == 5.0
+
+
+@pytest.mark.asyncio
+async def test_monotonic_cache_setter_discards_pending_resets(mock_modbus_client):
+    """Restoring a cache from disk resets the reset-confirmation counters."""
+    client = QubeClient("1.2.3.4", 502)
+    client.clamp_monotonic("energy", 1000.0)
+    client.clamp_monotonic("energy", 0.0)
+    client.clamp_monotonic("energy", 0.0)
+    client.monotonic_cache = {"energy": 1000.0}
+    # Only one low read so far after the restore: still clamped
+    assert client.clamp_monotonic("energy", 0.0) == 1000.0