python-qube-heatpump 1.11.2__tar.gz → 1.12.0__tar.gz

{python_qube_heatpump-1.11.2 → python_qube_heatpump-1.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-qube-heatpump
-Version: 1.11.2
+Version: 1.12.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

{python_qube_heatpump-1.11.2 → python_qube_heatpump-1.12.0}/pyproject.toml

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

{python_qube_heatpump-1.11.2 → python_qube_heatpump-1.12.0}/src/python_qube_heatpump/client.py

@@ -6,6 +6,7 @@ import logging
 import math
 import struct
 import time
+from collections.abc import Iterable
 from typing import Any
 
 from pymodbus.client import AsyncModbusTcpClient
@@ -21,6 +22,14 @@ _LOGGER = logging.getLogger(__name__)
 class QubeClient:
     """Qube Modbus Client."""
 
+    # Block-read planning limits. Small address gaps within a block are
+    # read along and discarded; a failed block falls back to individual
+    # entity reads, so gap registers can never break a value.
+    _MAX_BLOCK_REGISTERS = 100  # Modbus allows at most 125 per request
+    _MAX_BLOCK_BITS = 256
+    _MAX_GAP_REGISTERS = 8
+    _MAX_GAP_BITS = 16
+
     def __init__(self, host: str, port: int = 502, unit_id: int = 1):
         """Initialize."""
         self.host = host
@@ -34,6 +43,21 @@ class QubeClient:
         self._next_connect_at: float = 0.0
         # Monotonic clamping for total_increasing counters
         self._monotonic_cache: dict[str, float] = {}
+        # 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()
+
+    def _log_read_failure(self, target: str, exc: Exception) -> None:
+        """Log a read failure: WARNING on first occurrence per target, DEBUG after.
+
+        Transient Modbus timeouts recover on the next poll cycle, so
+        repeated occurrences should not flood the log at high severity.
+        """
+        if target in self._read_failures_warned:
+            _LOGGER.debug("Exception reading %s: %s", target, exc)
+        else:
+            self._read_failures_warned.add(target)
+            _LOGGER.warning("Exception reading %s: %s", target, exc)
 
     async def connect(self) -> bool:
         """Connect to the Modbus server."""
@@ -205,33 +229,12 @@ class QubeClient:
         Returns:
             Dictionary mapping entity keys to their values.
         """
-        results: dict[str, Any] = {}
-
-        # Read all sensors
-        for key, entity in SENSORS.items():
-            try:
-                results[key] = await self.read_entity(entity)
-            except Exception as exc:
-                _LOGGER.debug("Error reading sensor %s: %s", key, exc)
-                results[key] = None
-
-        # Read all binary sensors
-        for key, entity in BINARY_SENSORS.items():
-            try:
-                results[key] = await self.read_entity(entity)
-            except Exception as exc:
-                _LOGGER.debug("Error reading binary sensor %s: %s", key, exc)
-                results[key] = None
-
-        # Read all switches
-        for key, entity in SWITCHES.items():
-            try:
-                results[key] = await self.read_entity(entity)
-            except Exception as exc:
-                _LOGGER.debug("Error reading switch %s: %s", key, exc)
-                results[key] = None
-
-        return results
+        all_entities = [
+            *SENSORS.values(),
+            *BINARY_SENSORS.values(),
+            *SWITCHES.values(),
+        ]
+        return await self.read_entities_batched(all_entities)
 
     async def read_value(self, definition: tuple) -> float | None:
         """Read a single value based on the constant definition."""
@@ -309,9 +312,141 @@ class QubeClient:
             return val
 
         except Exception as e:
-            _LOGGER.error("Exception reading address %s: %s", address, e)
+            self._log_read_failure(f"address {address}", e)
             return None
 
+    @staticmethod
+    def _register_count(entity: EntityDef) -> int:
+        """Return the number of registers an entity occupies."""
+        data_type_str = entity.data_type.value if entity.data_type else None
+        return 2 if data_type_str in ("float32", "uint32", "int32") else 1
+
+    @staticmethod
+    def _decode_registers(data_type_str: str | None, regs: list[int]) -> float | int:
+        """Decode raw registers based on data type.
+
+        Qube uses big endian word order (ABCD): regs[0]=MSW, regs[1]=LSW.
+        """
+        val: float | int = 0
+        if data_type_str == "float32":
+            int_val = (regs[0] << 16) | regs[1]
+            val = struct.unpack(">f", struct.pack(">I", int_val))[0]
+        elif data_type_str == "int16":
+            val = regs[0]
+            if val > 32767:
+                val -= 65536
+        elif data_type_str == "uint16":
+            val = regs[0]
+        elif data_type_str == "uint32":
+            int_val = (regs[0] << 16) | regs[1]
+            val = int_val
+        elif data_type_str == "int32":
+            int_val = (regs[0] << 16) | regs[1]
+            val = int_val
+            if val > 2147483647:
+                val -= 4294967296
+        return val
+
+    @staticmethod
+    def _apply_scaling(entity: EntityDef, val: float | int) -> float | int:
+        """Apply an entity's scale, offset and precision to a raw value."""
+        if entity.scale is not None:
+            val = val * entity.scale
+        if entity.offset is not None:
+            val = val + entity.offset
+        if entity.precision is not None and isinstance(val, float):
+            val = round(val, entity.precision)
+        return val
+
+    def _plan_blocks(
+        self, entities: Iterable[EntityDef]
+    ) -> list[tuple[str, int, int, list[EntityDef]]]:
+        """Group entities into contiguous block reads per input type.
+
+        Returns a list of (input_type, start_address, count, entities)
+        tuples. Entities within _MAX_GAP_* of each other share a block.
+        """
+        groups: dict[str, list[EntityDef]] = {}
+        for ent in entities:
+            input_type_str = ent.input_type.value if ent.input_type else "holding"
+            groups.setdefault(input_type_str, []).append(ent)
+
+        blocks: list[tuple[str, int, int, list[EntityDef]]] = []
+        for input_type_str, ents in groups.items():
+            is_bits = input_type_str in ("coil", "discrete_input")
+            max_gap = self._MAX_GAP_BITS if is_bits else self._MAX_GAP_REGISTERS
+            max_block = self._MAX_BLOCK_BITS if is_bits else self._MAX_BLOCK_REGISTERS
+            start: int | None = None
+            end = 0
+            members: list[EntityDef] = []
+            for ent in sorted(ents, key=lambda e: e.address):
+                count = 1 if is_bits else self._register_count(ent)
+                ent_end = ent.address + count
+                if start is None:
+                    start, end, members = ent.address, ent_end, [ent]
+                elif ent.address <= end + max_gap and ent_end - start <= max_block:
+                    end = max(end, ent_end)
+                    members.append(ent)
+                else:
+                    blocks.append((input_type_str, start, end - start, members))
+                    start, end, members = ent.address, ent_end, [ent]
+            if start is not None:
+                blocks.append((input_type_str, start, end - start, members))
+        return blocks
+
+    async def read_entities_batched(
+        self, entities: Iterable[EntityDef]
+    ) -> dict[str, Any]:
+        """Read entities using contiguous block reads.
+
+        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.
+
+        Returns:
+            Dictionary mapping entity keys to their values (None on error).
+        """
+        results: dict[str, Any] = {}
+        for input_type_str, start, count, members in self._plan_blocks(entities):
+            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}")
+            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)
+                continue
+
+            for ent in members:
+                offset = ent.address - start
+                if input_type_str in ("coil", "discrete_input"):
+                    results[ent.key] = bool(result.bits[offset])
+                else:
+                    reg_count = self._register_count(ent)
+                    regs = result.registers[offset : offset + reg_count]
+                    data_type_str = ent.data_type.value if ent.data_type else None
+                    val = self._decode_registers(data_type_str, regs)
+                    results[ent.key] = self._apply_scaling(ent, val)
+        return results
+
     async def read_entity(self, entity: EntityDef) -> Any:
         """Read a single entity value based on EntityDef.
 
@@ -324,10 +459,7 @@ class QubeClient:
         # 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
-        if data_type_str in ("float32", "uint32", "int32"):
-            count = 2
-        else:
-            count = 1
+        count = self._register_count(entity)
 
         try:
             # Read based on input type (use string comparison for safety)
@@ -364,43 +496,11 @@ class QubeClient:
                 _LOGGER.warning("Error reading address %s", entity.address)
                 return None
 
-            regs = result.registers
-            val: float | int = 0
-
-            # Decode based on data type (use string comparison for safety)
-            # Qube uses big endian word order (ABCD): regs[0]=MSW, regs[1]=LSW
-            if data_type_str == "float32":
-                int_val = (regs[0] << 16) | regs[1]
-                val = struct.unpack(">f", struct.pack(">I", int_val))[0]
-            elif data_type_str == "int16":
-                val = regs[0]
-                if val > 32767:
-                    val -= 65536
-            elif data_type_str == "uint16":
-                val = regs[0]
-            elif data_type_str == "uint32":
-                int_val = (regs[0] << 16) | regs[1]
-                val = int_val
-            elif data_type_str == "int32":
-                int_val = (regs[0] << 16) | regs[1]
-                val = int_val
-                if val > 2147483647:
-                    val -= 4294967296
-
-            # Apply scale and offset
-            if entity.scale is not None:
-                val = val * entity.scale
-            if entity.offset is not None:
-                val = val + entity.offset
-
-            # Apply precision rounding if specified
-            if entity.precision is not None and isinstance(val, float):
-                val = round(val, entity.precision)
-
-            return val
+            val = self._decode_registers(data_type_str, result.registers)
+            return self._apply_scaling(entity, val)
 
         except Exception as e:
-            _LOGGER.error("Exception reading entity %s: %s", entity.key, e)
+            self._log_read_failure(f"entity {entity.key}", e)
             return None
 
     async def read_sensor(self, key: str) -> float | int | None:

{python_qube_heatpump-1.11.2 → python_qube_heatpump-1.12.0}/tests/test_client.py

@@ -529,3 +529,54 @@ async def test_set_sg_ready_mode_unknown(mock_modbus_client):
     client = QubeClient("1.2.3.4", 502)
     result = await client.set_sg_ready_mode("turbo")
     assert result is False
+
+
+@pytest.mark.asyncio
+async def test_read_entity_failure_logs_warning_once_then_debug(
+    mock_modbus_client, caplog
+):
+    """Transient read failures log WARNING on first occurrence, DEBUG after."""
+    import logging
+
+    from python_qube_heatpump.entities import BINARY_SENSORS
+
+    client = QubeClient("1.2.3.4", 502)
+    mock_instance = mock_modbus_client.return_value
+    mock_instance.read_discrete_inputs = AsyncMock(
+        side_effect=OSError("No response received after 3 retries")
+    )
+    client._client = mock_instance
+
+    entity = BINARY_SENSORS["dout_srcpmp_val"]
+
+    with caplog.at_level(logging.DEBUG, logger="python_qube_heatpump.client"):
+        assert await client.read_entity(entity) is None
+        assert await client.read_entity(entity) is None
+
+    records = [r for r in caplog.records if "dout_srcpmp_val" in r.getMessage()]
+    assert len(records) == 2
+    assert records[0].levelno == logging.WARNING
+    assert records[1].levelno == logging.DEBUG
+    assert not any(r.levelno == logging.ERROR for r in records)
+
+
+@pytest.mark.asyncio
+async def test_read_entity_warns_again_per_entity(mock_modbus_client, caplog):
+    """The warn-once tracking is per entity, not global."""
+    import logging
+
+    from python_qube_heatpump.entities import BINARY_SENSORS
+
+    client = QubeClient("1.2.3.4", 502)
+    mock_instance = mock_modbus_client.return_value
+    mock_instance.read_discrete_inputs = AsyncMock(
+        side_effect=OSError("No response received after 3 retries")
+    )
+    client._client = mock_instance
+
+    with caplog.at_level(logging.DEBUG, logger="python_qube_heatpump.client"):
+        await client.read_entity(BINARY_SENSORS["dout_srcpmp_val"])
+        await client.read_entity(BINARY_SENSORS["dout_usrpmp_val"])
+
+    warnings = [r for r in caplog.records if r.levelno == logging.WARNING]
+    assert len(warnings) == 2

python_qube_heatpump-1.12.0/tests/test_client_batching.py

@@ -0,0 +1,174 @@
+"""Tests for batched block reads in QubeClient."""
+
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+
+from python_qube_heatpump import QubeClient
+from python_qube_heatpump.entities import BINARY_SENSORS, SENSORS, SWITCHES
+from python_qube_heatpump.entities.base import (
+    DataType,
+    EntityDef,
+    InputType,
+    Platform,
+)
+
+
+def _bit_response(bits):
+    resp = MagicMock()
+    resp.isError.return_value = False
+    resp.bits = bits
+    return resp
+
+
+def _register_response(registers):
+    resp = MagicMock()
+    resp.isError.return_value = False
+    resp.registers = registers
+    return resp
+
+
+def _float32_regs(value):
+    import struct
+
+    int_val = struct.unpack(">I", struct.pack(">f", value))[0]
+    return [(int_val >> 16) & 0xFFFF, int_val & 0xFFFF]
+
+
+@pytest.mark.asyncio
+async def test_batched_discrete_inputs_single_transaction(mock_modbus_client):
+    """Adjacent discrete inputs are read in one block transaction."""
+    client = QubeClient("1.2.3.4", 502)
+    mock_instance = mock_modbus_client.return_value
+    mock_instance.read_discrete_inputs = AsyncMock(
+        return_value=_bit_response([True, False, True])
+    )
+    client._client = mock_instance
+
+    entities = [
+        BINARY_SENSORS["dout_srcpmp_val"],  # address 0
+        BINARY_SENSORS["dout_usrpmp_val"],  # address 1
+        BINARY_SENSORS["dout_fourwayvlv_val"],  # address 2
+    ]
+    results = await client.read_entities_batched(entities)
+
+    assert mock_instance.read_discrete_inputs.call_count == 1
+    call = mock_instance.read_discrete_inputs.call_args
+    assert call.args[0] == 0
+    assert call.kwargs["count"] >= 3
+    assert results == {
+        "dout_srcpmp_val": True,
+        "dout_usrpmp_val": False,
+        "dout_fourwayvlv_val": True,
+    }
+
+
+@pytest.mark.asyncio
+async def test_batched_input_registers_decode_float32(mock_modbus_client):
+    """Adjacent float32 input registers decode correctly from one block."""
+    client = QubeClient("1.2.3.4", 502)
+    mock_instance = mock_modbus_client.return_value
+    regs = _float32_regs(24.5) + _float32_regs(25.0)
+    mock_instance.read_input_registers = AsyncMock(
+        return_value=_register_response(regs)
+    )
+    client._client = mock_instance
+
+    entities = [
+        SENSORS["temp_supply"],  # address 20, float32
+        SENSORS["temp_return"],  # address 22, float32
+    ]
+    results = await client.read_entities_batched(entities)
+
+    assert mock_instance.read_input_registers.call_count == 1
+    call = mock_instance.read_input_registers.call_args
+    assert call.args[0] == 20
+    assert call.kwargs["count"] == 4
+    assert round(results["temp_supply"], 1) == 24.5
+    assert round(results["temp_return"], 1) == 25.0
+
+
+@pytest.mark.asyncio
+async def test_batched_far_apart_registers_split_into_blocks(mock_modbus_client):
+    """Registers far apart are read in separate block transactions."""
+    client = QubeClient("1.2.3.4", 502)
+    mock_instance = mock_modbus_client.return_value
+    mock_instance.read_holding_registers = AsyncMock(
+        return_value=_register_response(_float32_regs(1.0))
+    )
+    client._client = mock_instance
+
+    ent_a = EntityDef(
+        key="a",
+        name="A",
+        address=0,
+        input_type=InputType.HOLDING_REGISTER,
+        platform=Platform.SENSOR,
+        data_type=DataType.FLOAT32,
+    )
+    ent_b = EntityDef(
+        key="b",
+        name="B",
+        address=500,
+        input_type=InputType.HOLDING_REGISTER,
+        platform=Platform.SENSOR,
+        data_type=DataType.FLOAT32,
+    )
+    await client.read_entities_batched([ent_a, ent_b])
+
+    assert mock_instance.read_holding_registers.call_count == 2
+
+
+@pytest.mark.asyncio
+async def test_batched_block_failure_falls_back_to_individual_reads(
+    mock_modbus_client,
+):
+    """If a block read fails, entities in it are read individually."""
+    client = QubeClient("1.2.3.4", 502)
+    mock_instance = mock_modbus_client.return_value
+    mock_instance.read_input_registers = AsyncMock(
+        side_effect=[
+            OSError("No response received after 3 retries"),  # block read
+            _register_response(_float32_regs(24.5)),  # individual read
+            _register_response(_float32_regs(25.0)),  # individual read
+        ]
+    )
+    client._client = mock_instance
+
+    entities = [SENSORS["temp_supply"], SENSORS["temp_return"]]
+    results = await client.read_entities_batched(entities)
+
+    assert mock_instance.read_input_registers.call_count == 3
+    assert round(results["temp_supply"], 1) == 24.5
+    assert round(results["temp_return"], 1) == 25.0
+
+
+@pytest.mark.asyncio
+async def test_get_all_entities_uses_batched_reads(mock_modbus_client):
+    """get_all_entities reads all entities in a handful of transactions."""
+    client = QubeClient("1.2.3.4", 502)
+    mock_instance = mock_modbus_client.return_value
+
+    def _bits(address, count=1, **kwargs):
+        return _bit_response([False] * count)
+
+    def _regs(address, count=1, **kwargs):
+        return _register_response([0] * count)
+
+    mock_instance.read_coils = AsyncMock(side_effect=_bits)
+    mock_instance.read_discrete_inputs = AsyncMock(side_effect=_bits)
+    mock_instance.read_input_registers = AsyncMock(side_effect=_regs)
+    mock_instance.read_holding_registers = AsyncMock(side_effect=_regs)
+    client._client = mock_instance
+
+    results = await client.get_all_entities()
+
+    expected_keys = set(SENSORS) | set(BINARY_SENSORS) | set(SWITCHES)
+    assert set(results) == expected_keys
+    total_calls = (
+        mock_instance.read_coils.call_count
+        + mock_instance.read_discrete_inputs.call_count
+        + mock_instance.read_input_registers.call_count
+        + mock_instance.read_holding_registers.call_count
+    )
+    assert total_calls <= 15