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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-qube-heatpump
-Version: 1.11.2
+Version: 1.13.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.13.0}/pyproject.toml

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

{python_qube_heatpump-1.11.2 → python_qube_heatpump-1.13.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
@@ -17,10 +18,124 @@ from .models import QubeState
 
 _LOGGER = logging.getLogger(__name__)
 
+# 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.
+# Note: some of these intentionally differ from the corresponding entries in
+# entities/sensors.py (e.g. compressor_speed has a x60 RPM scale here but not
+# there; cop_calc is unrounded here but rounded to 1 decimal there) — reusing
+# SENSORS would silently change get_all_data()'s output, so a dedicated table
+# is kept instead.
+# Format: (key, address, input_type, data_type, scale, offset)
+_CORE_STATE_REGISTERS: tuple[
+    tuple[str, int, InputType, DataType, float | None, float | None], ...
+] = (
+    ("temp_supply", 20, InputType.INPUT_REGISTER, DataType.FLOAT32, None, None),
+    ("temp_return", 22, InputType.INPUT_REGISTER, DataType.FLOAT32, None, None),
+    ("temp_source_in", 24, InputType.INPUT_REGISTER, DataType.FLOAT32, None, None),
+    ("temp_source_out", 26, InputType.INPUT_REGISTER, DataType.FLOAT32, None, None),
+    ("temp_room", 28, InputType.INPUT_REGISTER, DataType.FLOAT32, None, None),
+    ("temp_dhw", 30, InputType.INPUT_REGISTER, DataType.FLOAT32, None, None),
+    ("temp_outside", 32, InputType.INPUT_REGISTER, DataType.FLOAT32, None, None),
+    ("power_thermic", 36, InputType.INPUT_REGISTER, DataType.FLOAT32, None, None),
+    ("power_electric", 61, InputType.INPUT_REGISTER, DataType.FLOAT32, None, None),
+    (
+        "energy_total_electric",
+        69,
+        InputType.INPUT_REGISTER,
+        DataType.FLOAT32,
+        None,
+        None,
+    ),
+    (
+        "energy_total_thermic",
+        71,
+        InputType.INPUT_REGISTER,
+        DataType.FLOAT32,
+        None,
+        None,
+    ),
+    ("cop_calc", 34, InputType.INPUT_REGISTER, DataType.FLOAT32, None, None),
+    ("status_code", 38, InputType.INPUT_REGISTER, DataType.UINT16, None, None),
+    ("compressor_speed", 45, InputType.INPUT_REGISTER, DataType.FLOAT32, 60, None),
+    ("flow_rate", 18, InputType.INPUT_REGISTER, DataType.FLOAT32, None, None),
+    (
+        "setpoint_room_heat_day",
+        27,
+        InputType.HOLDING_REGISTER,
+        DataType.FLOAT32,
+        None,
+        None,
+    ),
+    (
+        "setpoint_room_heat_night",
+        29,
+        InputType.HOLDING_REGISTER,
+        DataType.FLOAT32,
+        None,
+        None,
+    ),
+    (
+        "setpoint_room_cool_day",
+        31,
+        InputType.HOLDING_REGISTER,
+        DataType.FLOAT32,
+        None,
+        None,
+    ),
+    (
+        "setpoint_room_cool_night",
+        33,
+        InputType.HOLDING_REGISTER,
+        DataType.FLOAT32,
+        None,
+        None,
+    ),
+    ("setpoint_dhw", 173, InputType.HOLDING_REGISTER, DataType.FLOAT32, None, None),
+    (
+        "usr_pid_heatsetp",
+        101,
+        InputType.HOLDING_REGISTER,
+        DataType.FLOAT32,
+        None,
+        None,
+    ),
+    (
+        "usr_pid_coolsetp",
+        103,
+        InputType.HOLDING_REGISTER,
+        DataType.FLOAT32,
+        None,
+        None,
+    ),
+    ("modbus_roomtemp", 75, InputType.INPUT_REGISTER, DataType.FLOAT32, None, None),
+)
+
+_CORE_STATE_ENTITIES: tuple[EntityDef, ...] = tuple(
+    EntityDef(
+        key=key,
+        name=key,
+        address=address,
+        input_type=input_type,
+        data_type=data_type,
+        scale=scale,
+        offset=offset,
+    )
+    for key, address, input_type, data_type, scale, offset in _CORE_STATE_REGISTERS
+)
+
 
 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 +149,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."""
@@ -85,53 +215,27 @@ class QubeClient:
 
         state = QubeState()
 
-        # Helper to read and assign
-        async def _read(const_def):
-            return await self.read_value(const_def)
-
-        # Fetch temperature sensors
-        state.temp_supply = await _read(const.TEMP_SUPPLY)
-        state.temp_return = await _read(const.TEMP_RETURN)
-        state.temp_source_in = await _read(const.TEMP_SOURCE_IN)
-        state.temp_source_out = await _read(const.TEMP_SOURCE_OUT)
-        state.temp_room = await _read(const.TEMP_ROOM)
-        state.temp_dhw = await _read(const.TEMP_DHW)
-        state.temp_outside = await _read(const.TEMP_OUTSIDE)
-
-        # Fetch power and energy sensors
-        state.power_thermic = await _read(const.POWER_THERMIC)
-        state.power_electric = await _read(const.POWER_ELECTRIC_CALC)
-        state.energy_total_electric = await _read(const.ENERGY_ELECTRIC_TOTAL)
-        state.energy_total_thermic = await _read(const.ENERGY_THERMIC_TOTAL)
-        state.cop_calc = await _read(const.COP_CALC)
-
-        # Fetch operation sensors
-        state.status_code = await _read(const.STATUS_CODE)
-        state.compressor_speed = await _read(const.COMPRESSOR_SPEED)
-        flow_rate = await _read(const.FLOW_RATE)
+        # Batch-read the core sensor fields plus all binary sensors together.
+        # _plan_blocks groups by input type (input/holding/discrete_input/coil)
+        # regardless of which list an entity came from, so combining both
+        # tables into a single read_entities_batched() call still yields one
+        # handful of block transactions instead of ~59 per-field reads.
+        entities = [*_CORE_STATE_ENTITIES, *BINARY_SENSORS.values()]
+        results = await self.read_entities_batched(entities)
+
+        for ent in _CORE_STATE_ENTITIES:
+            setattr(state, ent.key, results.get(ent.key))
+
+        flow_rate = state.flow_rate
         if flow_rate is not None and flow_rate < 0:
             flow_rate = 0.0
         state.flow_rate = flow_rate
 
-        # Fetch setpoints (holding registers)
-        state.setpoint_room_heat_day = await _read(const.SETPOINT_HEAT_DAY)
-        state.setpoint_room_heat_night = await _read(const.SETPOINT_HEAT_NIGHT)
-        state.setpoint_room_cool_day = await _read(const.SETPOINT_COOL_DAY)
-        state.setpoint_room_cool_night = await _read(const.SETPOINT_COOL_NIGHT)
-        state.setpoint_dhw = await _read(const.USER_DHW_SETPOINT)
-        state.usr_pid_heatsetp = await _read(const.USER_HEAT_SETPOINT)
-        state.usr_pid_coolsetp = await _read(const.USER_COOL_SETPOINT)
-
-        # LinQ thermostat room temperature (optional)
-        state.modbus_roomtemp = await _read(const.TEMP_ROOM_MODBUS)
-
         self._apply_monotonic_clamping(state)
 
-        # Fetch binary sensors
-        binary_data = await self.read_all_binary_sensors()
-        for key, value in binary_data.items():
+        for key in BINARY_SENSORS:
             if hasattr(state, key):
-                setattr(state, key, value)
+                setattr(state, key, results.get(key))
 
         # Compute unified status (status_code + anti-legionella override)
         state.status = const.resolve_status(state.status_code, state.req_antileg_1)
@@ -205,33 +309,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 +392,152 @@ 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}")
+                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})"
+                    )
+            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 +550,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 +587,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.13.0}/tests/test_client.py

@@ -331,12 +331,18 @@ async def test_get_all_data_auto_reconnects(mock_modbus_client):
     client._client = mock_instance
     client._connected = False
 
-    # Mock successful register reads
-    mock_resp = MagicMock()
-    mock_resp.isError.return_value = False
-    mock_resp.registers = [0, 0]
-    mock_instance.read_input_registers = AsyncMock(return_value=mock_resp)
-    mock_instance.read_holding_registers = AsyncMock(return_value=mock_resp)
+    # Mock successful register reads. Batched block reads request a
+    # variable number of registers per block, so the mock must honor the
+    # requested `count` (a real Modbus server would too), unlike a fixed
+    # 2-register response.
+    def _resp(address, count=1, **kwargs):
+        resp = MagicMock()
+        resp.isError.return_value = False
+        resp.registers = [0] * count
+        return resp
+
+    mock_instance.read_input_registers = AsyncMock(side_effect=_resp)
+    mock_instance.read_holding_registers = AsyncMock(side_effect=_resp)
 
     state = await client.get_all_data()
     assert state is not None
@@ -424,11 +430,16 @@ async def test_get_all_data_applies_clamping(mock_modbus_client):
     client._client = mock_instance
     client._connected = True
 
-    mock_resp = MagicMock()
-    mock_resp.isError.return_value = False
-    mock_resp.registers = [0, 0]
-    mock_instance.read_input_registers = AsyncMock(return_value=mock_resp)
-    mock_instance.read_holding_registers = AsyncMock(return_value=mock_resp)
+    # Batched block reads request a variable `count` of registers per
+    # block, so the mock must honor it (a real Modbus server would too).
+    def _resp(address, count=1, **kwargs):
+        resp = MagicMock()
+        resp.isError.return_value = False
+        resp.registers = [0] * count
+        return resp
+
+    mock_instance.read_input_registers = AsyncMock(side_effect=_resp)
+    mock_instance.read_holding_registers = AsyncMock(side_effect=_resp)
 
     state = await client.get_all_data()
     assert state is not None
@@ -529,3 +540,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.13.0/tests/test_client_batching.py

@@ -0,0 +1,249 @@
+"""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_batched_short_successful_response_falls_back_to_individual_reads(
+    mock_modbus_client,
+):
+    """A well-formed but too-short block response degrades gracefully.
+
+    A device can return isError()==False with fewer registers/bits than the
+    requested count (a malformed-but-"successful" response). Previously this
+    slipped past the isError() check and crashed with an uncaught IndexError
+    while decoding, instead of falling back to individual reads like a failed
+    block does. Since get_all_data() is now polled by HA core every 15s via
+    this same batching path, such a response must degrade the same way a
+    failed block does, not raise.
+    """
+    client = QubeClient("1.2.3.4", 502)
+    mock_instance = mock_modbus_client.return_value
+    mock_instance.read_input_registers = AsyncMock(
+        side_effect=[
+            # Block read: isError() is False, but only 2 registers came back
+            # for a block that needs 4 (two float32 entities).
+            _register_response(_float32_regs(24.5)),
+            _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
+
+
+@pytest.mark.asyncio
+async def test_get_all_data_uses_batched_reads(mock_modbus_client):
+    """get_all_data (used by HA core, polled every 15s) reads via block reads.
+
+    Previously get_all_data() performed one Modbus transaction per field
+    (~59 transactions: 23 core sensors + 37 binary sensors). It should now
+    use the same batched block-read infrastructure as get_all_entities(),
+    landing in a handful of transactions instead.
+    """
+    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
+    client._connected = True
+
+    state = await client.get_all_data()
+
+    assert state is not None
+    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
+    )
+    # Old per-register/per-entity path made ~59 transactions (23 core
+    # fields + 37 binary sensors). Batched block reads should collapse
+    # this into a handful of transactions.
+    assert total_calls <= 15