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

{python_qube_heatpump-1.13.0 → python_qube_heatpump-1.15.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.15.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.15.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.15.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.15.0}/pyproject.toml

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

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

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import contextlib
 import logging
 import math
 import struct
@@ -10,6 +11,7 @@ from collections.abc import Iterable
 from typing import Any
 
 from pymodbus.client import AsyncModbusTcpClient
+from pymodbus.exceptions import ConnectionException, ModbusIOException
 
 from . import const
 from .entities import BINARY_SENSORS, SENSORS, SWITCHES, EntityDef
@@ -18,6 +20,22 @@ from .models import QubeState
 
 _LOGGER = logging.getLogger(__name__)
 
+# Exceptions meaning the TCP link (or the device behind it) stopped answering,
+# as opposed to a Modbus error reply to one request. pymodbus raises
+# ConnectionException when it cannot connect and ModbusIOException when a
+# request got no response after its retries. OSError covers socket errors
+# and TimeoutError.
+_LINK_ERRORS: tuple[type[Exception], ...] = (
+    ConnectionException,
+    ModbusIOException,
+    OSError,
+)
+
+
+class _BlockReadError(Exception):
+    """A block read got a Modbus error reply or a short response."""
+
+
 # Entities read by get_all_data() (used by the official HA core integration).
 # These mirror the register definitions in `const` exactly (address, scale,
 # offset) so batching cannot change any value get_all_data() returns.
@@ -149,6 +167,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()
@@ -165,10 +186,29 @@ class QubeClient:
             self._read_failures_warned.add(target)
             _LOGGER.warning("Exception reading %s: %s", target, exc)
 
+    def _log_read_ok(self, target: str) -> None:
+        """Re-arm the warn-once log for a target that reads fine again."""
+        if target in self._read_failures_warned:
+            self._read_failures_warned.discard(target)
+            _LOGGER.info("Reading %s recovered", target)
+
+    def _mark_disconnected(self) -> None:
+        """Drop the connection after a link failure so the next poll reconnects.
+
+        pymodbus' connect() replaces the transport without closing the old
+        one, so the transport is closed here before any reconnect.
+        """
+        self._connected = False
+        with contextlib.suppress(Exception):
+            self._client.close()
+
     async def connect(self) -> bool:
         """Connect to the Modbus server."""
         if not self._connected:
             self._connected = await self._client.connect()
+            if self._connected:
+                self._backoff_seconds = 0.0
+                self._next_connect_at = 0.0
         return self._connected
 
     @property
@@ -207,7 +247,8 @@ class QubeClient:
         """Fetch all definition data and return a state object.
 
         This fetches core sensors for the official HA integration.
-        Returns None if not connected and reconnection fails.
+        Returns None if not connected and reconnection fails, or if the
+        connection was lost during this poll.
         """
         await self._ensure_connected()
         if not self._connected:
@@ -222,6 +263,8 @@ class QubeClient:
         # handful of block transactions instead of ~59 per-field reads.
         entities = [*_CORE_STATE_ENTITIES, *BINARY_SENSORS.values()]
         results = await self.read_entities_batched(entities)
+        if not self._connected:
+            return None
 
         for ent in _CORE_STATE_ENTITIES:
             setattr(state, ent.key, results.get(ent.key))
@@ -254,17 +297,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 clear_monotonic_cache(self) -> None:
+        """Forget all monotonic baselines.
 
-    def clamp_monotonic(self, key: str, value: float | None) -> float | None:
+        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 +346,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
 
@@ -389,10 +490,13 @@ class QubeClient:
             if offset is not None:
                 val += offset
 
+            self._log_read_ok(f"address {address}")
             return val
 
         except Exception as e:
             self._log_read_failure(f"address {address}", e)
+            if isinstance(e, _LINK_ERRORS):
+                self._mark_disconnected()
             return None
 
     @staticmethod
@@ -481,51 +585,32 @@ class QubeClient:
 
         Groups entities into a handful of Modbus block reads instead of
         one transaction per entity. If a block read fails, its entities
-        are read individually as a fallback.
+        are read individually as a fallback. If one of those single reads
+        hits a link failure (no connection, no response), the device is
+        treated as unreachable: the client is marked disconnected and the
+        remaining reads are skipped.
 
         Returns:
-            Dictionary mapping entity keys to their values (None on error).
+            Dictionary mapping every requested entity key to its value
+            (None on error).
         """
         results: dict[str, Any] = {}
-        for input_type_str, start, count, members in self._plan_blocks(entities):
+        blocks = self._plan_blocks(entities)
+        for input_type_str, start, count, members in blocks:
+            target = f"block {input_type_str}@{start} (count {count})"
             try:
-                if input_type_str == "coil":
-                    result = await self._client.read_coils(
-                        start, count=count, device_id=self.unit
-                    )
-                elif input_type_str == "discrete_input":
-                    result = await self._client.read_discrete_inputs(
-                        start, count=count, device_id=self.unit
-                    )
-                elif input_type_str == "input":
-                    result = await self._client.read_input_registers(
-                        start, count=count, device_id=self.unit
-                    )
-                else:  # holding
-                    result = await self._client.read_holding_registers(
-                        start, count=count, device_id=self.unit
-                    )
-                if result.isError():
-                    raise OSError(f"Modbus error response for block @{start}")
-                if input_type_str in ("coil", "discrete_input"):
-                    if len(result.bits) < count:
-                        raise OSError(
-                            f"Short bit response for block {input_type_str}@{start} "
-                            f"(got {len(result.bits)}, expected {count})"
-                        )
-                elif len(result.registers) < count:
-                    raise OSError(
-                        f"Short register response for block {input_type_str}@{start} "
-                        f"(got {len(result.registers)}, expected {count})"
-                    )
+                result = await self._read_block(input_type_str, start, count)
             except Exception as exc:
-                self._log_read_failure(
-                    f"block {input_type_str}@{start} (count {count})", exc
-                )
-                for ent in members:
-                    results[ent.key] = await self.read_entity(ent)
+                self._log_read_failure(target, exc)
+                if not await self._read_individually(members, results):
+                    self._mark_disconnected()
+                    for _, _, _, block_members in blocks:
+                        for ent in block_members:
+                            results.setdefault(ent.key, None)
+                    return results
                 continue
 
+            self._log_read_ok(target)
             for ent in members:
                 offset = ent.address - start
                 if input_type_str in ("coil", "discrete_input"):
@@ -538,6 +623,63 @@ class QubeClient:
                     results[ent.key] = self._apply_scaling(ent, val)
         return results
 
+    async def _read_block(self, input_type_str: str, start: int, count: int) -> Any:
+        """Read one block and validate the response.
+
+        Raises:
+            _BlockReadError: On a Modbus error reply or a short response.
+            Any of _LINK_ERRORS: When the device could not be reached.
+        """
+        if input_type_str == "coil":
+            result = await self._client.read_coils(
+                start, count=count, device_id=self.unit
+            )
+        elif input_type_str == "discrete_input":
+            result = await self._client.read_discrete_inputs(
+                start, count=count, device_id=self.unit
+            )
+        elif input_type_str == "input":
+            result = await self._client.read_input_registers(
+                start, count=count, device_id=self.unit
+            )
+        else:  # holding
+            result = await self._client.read_holding_registers(
+                start, count=count, device_id=self.unit
+            )
+        if result.isError():
+            raise _BlockReadError(f"Modbus error response for block @{start}")
+        if input_type_str in ("coil", "discrete_input"):
+            if len(result.bits) < count:
+                raise _BlockReadError(
+                    f"Short bit response for block {input_type_str}@{start} "
+                    f"(got {len(result.bits)}, expected {count})"
+                )
+        elif len(result.registers) < count:
+            raise _BlockReadError(
+                f"Short register response for block {input_type_str}@{start} "
+                f"(got {len(result.registers)}, expected {count})"
+            )
+        return result
+
+    async def _read_individually(
+        self, members: list[EntityDef], results: dict[str, Any]
+    ) -> bool:
+        """Read a failed block's entities one by one into ``results``.
+
+        Returns False as soon as a read hits a link failure, so a dead
+        device costs one extra transaction instead of one per entity.
+        """
+        for ent in members:
+            try:
+                results[ent.key] = await self._read_entity_or_raise(ent)
+            except _LINK_ERRORS as exc:
+                self._log_read_failure(f"entity {ent.key}", exc)
+                return False
+            except Exception as exc:
+                self._log_read_failure(f"entity {ent.key}", exc)
+                results[ent.key] = None
+        return True
+
     async def read_entity(self, entity: EntityDef) -> Any:
         """Read a single entity value based on EntityDef.
 
@@ -547,33 +689,41 @@ class QubeClient:
         Returns:
             The read value (float, int, or bool depending on entity type).
         """
+        try:
+            return await self._read_entity_or_raise(entity)
+        except Exception as e:
+            self._log_read_failure(f"entity {entity.key}", e)
+            if isinstance(e, _LINK_ERRORS):
+                self._mark_disconnected()
+            return None
+
+    async def _read_entity_or_raise(self, entity: EntityDef) -> Any:
+        """Read a single entity; return None on an error reply, raise otherwise."""
         # Determine register count based on data type
         # Use string comparison to handle potential enum class differences
         data_type_str = entity.data_type.value if entity.data_type else None
         count = self._register_count(entity)
 
-        try:
-            # Read based on input type (use string comparison for safety)
-            input_type_str = entity.input_type.value if entity.input_type else None
-
-            if input_type_str == "coil":
-                result = await self._client.read_coils(
-                    entity.address, count=1, device_id=self.unit
-                )
-                if result.isError():
-                    _LOGGER.warning("Error reading coil %s", entity.address)
-                    return None
-                return bool(result.bits[0])
-
-            if input_type_str == "discrete_input":
-                result = await self._client.read_discrete_inputs(
-                    entity.address, count=1, device_id=self.unit
-                )
-                if result.isError():
-                    _LOGGER.warning("Error reading discrete input %s", entity.address)
-                    return None
-                return bool(result.bits[0])
+        # Read based on input type (use string comparison for safety)
+        input_type_str = entity.input_type.value if entity.input_type else None
 
+        if input_type_str == "coil":
+            result = await self._client.read_coils(
+                entity.address, count=1, device_id=self.unit
+            )
+            if result.isError():
+                _LOGGER.warning("Error reading coil %s", entity.address)
+                return None
+            value: Any = bool(result.bits[0])
+        elif input_type_str == "discrete_input":
+            result = await self._client.read_discrete_inputs(
+                entity.address, count=1, device_id=self.unit
+            )
+            if result.isError():
+                _LOGGER.warning("Error reading discrete input %s", entity.address)
+                return None
+            value = bool(result.bits[0])
+        else:
             if input_type_str == "input":
                 result = await self._client.read_input_registers(
                     entity.address, count=count, device_id=self.unit
@@ -588,11 +738,10 @@ class QubeClient:
                 return None
 
             val = self._decode_registers(data_type_str, result.registers)
-            return self._apply_scaling(entity, val)
+            value = self._apply_scaling(entity, val)
 
-        except Exception as e:
-            self._log_read_failure(f"entity {entity.key}", e)
-            return None
+        self._log_read_ok(f"entity {entity.key}")
+        return value
 
     async def read_sensor(self, key: str) -> float | int | None:
         """Read a sensor value by key.
@@ -639,16 +788,18 @@ class QubeClient:
             return None
         return await self.read_entity(entity)
 
+    async def _read_table(self, table: dict[str, EntityDef]) -> dict[str, Any]:
+        """Batch-read every entity in a table, keeping the table's key order."""
+        results = await self.read_entities_batched(table.values())
+        return {key: results.get(key) for key in table}
+
     async def read_all_sensors(self) -> dict[str, Any]:
         """Read all sensor values.
 
         Returns:
             Dictionary mapping sensor keys to their values.
         """
-        result: dict[str, Any] = {}
-        for key, entity in SENSORS.items():
-            result[key] = await self.read_entity(entity)
-        return result
+        return await self._read_table(SENSORS)
 
     async def read_all_binary_sensors(self) -> dict[str, bool | None]:
         """Read all binary sensor values.
@@ -656,10 +807,7 @@ class QubeClient:
         Returns:
             Dictionary mapping binary sensor keys to their values.
         """
-        result: dict[str, bool | None] = {}
-        for key, entity in BINARY_SENSORS.items():
-            result[key] = await self.read_entity(entity)
-        return result
+        return await self._read_table(BINARY_SENSORS)
 
     async def read_all_switches(self) -> dict[str, bool | None]:
         """Read all switch states.
@@ -667,10 +815,7 @@ class QubeClient:
         Returns:
             Dictionary mapping switch keys to their states.
         """
-        result: dict[str, bool | None] = {}
-        for key, entity in SWITCHES.items():
-            result[key] = await self.read_entity(entity)
-        return result
+        return await self._read_table(SWITCHES)
 
     async def write_switch(self, key: str, value: bool) -> bool:
         """Write a switch state by key.
@@ -701,6 +846,8 @@ class QubeClient:
             return True
         except Exception as e:
             _LOGGER.error("Exception writing switch %s: %s", key, e)
+            if isinstance(e, _LINK_ERRORS):
+                self._mark_disconnected()
             return False
 
     # SG Ready mode API
@@ -721,8 +868,11 @@ class QubeClient:
         Returns:
             Mode string ("off", "block", "plus", "max"), or None on error.
         """
-        bit_a = await self.read_switch("bms_sgready_a")
-        bit_b = await self.read_switch("bms_sgready_b")
+        results = await self.read_entities_batched(
+            [SWITCHES["bms_sgready_a"], SWITCHES["bms_sgready_b"]]
+        )
+        bit_a = results.get("bms_sgready_a")
+        bit_b = results.get("bms_sgready_b")
         if bit_a is None or bit_b is None:
             return None
         return self._SGREADY_BITS_TO_MODE.get((bool(bit_a), bool(bit_b)))
@@ -730,16 +880,41 @@ class QubeClient:
     async def set_sg_ready_mode(self, mode: str) -> bool:
         """Set the SG Ready mode.
 
+        Both coils are written in one request so the heat pump never sees
+        a half-applied mode. If the device rejects the multi-coil write,
+        the coils are written one after the other instead.
+
         Args:
             mode: One of "off", "block", "plus", "max".
 
         Returns:
-            True if both writes succeeded, False otherwise.
+            True if both coils were written, False otherwise.
         """
         bits = self._SGREADY_MODE_TO_BITS.get(mode)
         if bits is None:
             _LOGGER.warning("Unknown SG Ready mode: %s", mode)
             return False
+
+        coil_a = SWITCHES["bms_sgready_a"]
+        coil_b = SWITCHES["bms_sgready_b"]
+        if coil_b.address == coil_a.address + 1:
+            try:
+                result = await self._client.write_coils(
+                    coil_a.address, list(bits), device_id=self.unit
+                )
+            except Exception as e:
+                _LOGGER.error("Exception writing SG Ready mode %s: %s", mode, e)
+                if isinstance(e, _LINK_ERRORS):
+                    self._mark_disconnected()
+                return False
+            if not result.isError():
+                return True
+            _LOGGER.debug(
+                "Multi-coil write rejected for SG Ready mode %s; "
+                "falling back to single writes",
+                mode,
+            )
+
         success_a = await self.write_switch("bms_sgready_a", bits[0])
         success_b = await self.write_switch("bms_sgready_b", bits[1])
         return success_a and success_b
@@ -767,6 +942,24 @@ class QubeClient:
             _LOGGER.warning("Sensor %s is not a holding register", key)
             return False
 
+        if not isinstance(value, int | float) or not math.isfinite(value):
+            _LOGGER.warning(
+                "Refusing to write %r to %s: not a finite number", value, key
+            )
+            return False
+
+        if (entity.min_value is not None and value < entity.min_value) or (
+            entity.max_value is not None and value > entity.max_value
+        ):
+            _LOGGER.warning(
+                "Refusing to write %s to %s: outside allowed range %s..%s",
+                value,
+                key,
+                entity.min_value,
+                entity.max_value,
+            )
+            return False
+
         try:
             # Reverse scale/offset if needed
             write_value = value
@@ -785,15 +978,25 @@ class QubeClient:
                 result = await self._client.write_registers(
                     entity.address, regs, device_id=self.unit
                 )
-            elif entity.data_type == DataType.INT16:
-                if write_value < 0:
-                    write_value = int(write_value) + 65536
-                result = await self._client.write_register(
-                    entity.address, int(write_value), device_id=self.unit
+            elif entity.data_type in (DataType.INT16, DataType.UINT16):
+                raw = round(write_value)
+                low, high = (
+                    (-32768, 32767)
+                    if entity.data_type == DataType.INT16
+                    else (0, 65535)
                 )
-            elif entity.data_type == DataType.UINT16:
+                if not low <= raw <= high:
+                    _LOGGER.warning(
+                        "Refusing to write %s to %s: does not fit in %s",
+                        value,
+                        key,
+                        entity.data_type.value,
+                    )
+                    return False
+                if raw < 0:
+                    raw += 65536
                 result = await self._client.write_register(
-                    entity.address, int(write_value), device_id=self.unit
+                    entity.address, raw, device_id=self.unit
                 )
             else:
                 _LOGGER.warning(
@@ -808,4 +1011,6 @@ class QubeClient:
 
         except Exception as e:
             _LOGGER.error("Exception writing setpoint %s: %s", key, e)
+            if isinstance(e, _LINK_ERRORS):
+                self._mark_disconnected()
             return False

{python_qube_heatpump-1.13.0 → python_qube_heatpump-1.15.0}/src/python_qube_heatpump/entities/base.py

@@ -79,3 +79,10 @@ class EntityDef:
     # Value precision
     precision: int | None = None
     """Number of decimal places to round to. None for no rounding."""
+
+    # Write limits
+    min_value: float | None = None
+    """Lowest value write_setpoint() accepts, in the entity's unit."""
+
+    max_value: float | None = None
+    """Highest value write_setpoint() accepts, in the entity's unit."""