pybls21 5.1.0__tar.gz → 5.2.0__tar.gz

{pybls21-5.1.0/pybls21.egg-info → pybls21-5.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pybls21
-Version: 5.1.0
+Version: 5.2.0
 Summary: Async Modbus TCP client for Blauberg S21 ventilation devices
 Author-email: Julius Vitkauskas <zadintuvas@gmail.com>
 License-Expression: MIT
@@ -159,6 +159,38 @@ a successful poll. Connection and communication failures mark
 successful subsequent poll restores it. Previously returned models are immutable
 snapshots, so read `client.device` for the updated availability.
 
+## Heater and cooler activity
+
+```python
+snapshot = await client.poll()
+print(snapshot.is_heating, snapshot.is_cooling)
+```
+
+`is_heating` and `is_cooling` expose the controller's operation indications at
+**DI7 (`DI_StatusHEATER`)** and **DI8 (`DI_StatusCOOLER`)**, respectively. Every poll
+reads both in one additional Modbus request, regardless of mode or alarm state.
+These booleans come directly from the controller; temperature differences,
+selected HVAC mode, and unit power do not override them. If both bits are set,
+both fields remain true rather than arbitrarily selecting one action.
+They indicate controller-reported operation, not independently measured power
+consumption or proof that the attached heater/cooler is functioning.
+
+A successful poll populates both fields. Failed, erroneous, or short responses
+fail the poll and mark the cached snapshot unavailable, like other required
+reads; they never silently report inactive equipment. The new fields default to
+`None` only for manually constructed snapshots that omit them, preserving
+compatibility with existing callers constructing `ClimateDevice`.
+
+The reads were verified on a physical S21 running firmware `0.36 (2019-05-08)`:
+both flags were false in fan-only mode while the fans ran. In a controlled test,
+heating mode with a 15 °C target left DI7 false; raising the target to 25 °C
+made DI7 true after about six seconds. Restoring fan-only mode and 15 °C made
+DI7 false again, with fan level and alarm codes unchanged. No cooler was
+configured, so active cooling is covered by the Modbus test server rather than
+a physical cooling test. The legacy `hvac_action` field remains inferred for compatibility. Use the
+new activity flags when actual heater/cooler status is needed; downstream
+integrations must not treat the inferred field as measured activity.
+
 ## Bypass control
 
 ```python

{pybls21-5.1.0 → pybls21-5.2.0}/README.md

@@ -135,6 +135,38 @@ a successful poll. Connection and communication failures mark
 successful subsequent poll restores it. Previously returned models are immutable
 snapshots, so read `client.device` for the updated availability.
 
+## Heater and cooler activity
+
+```python
+snapshot = await client.poll()
+print(snapshot.is_heating, snapshot.is_cooling)
+```
+
+`is_heating` and `is_cooling` expose the controller's operation indications at
+**DI7 (`DI_StatusHEATER`)** and **DI8 (`DI_StatusCOOLER`)**, respectively. Every poll
+reads both in one additional Modbus request, regardless of mode or alarm state.
+These booleans come directly from the controller; temperature differences,
+selected HVAC mode, and unit power do not override them. If both bits are set,
+both fields remain true rather than arbitrarily selecting one action.
+They indicate controller-reported operation, not independently measured power
+consumption or proof that the attached heater/cooler is functioning.
+
+A successful poll populates both fields. Failed, erroneous, or short responses
+fail the poll and mark the cached snapshot unavailable, like other required
+reads; they never silently report inactive equipment. The new fields default to
+`None` only for manually constructed snapshots that omit them, preserving
+compatibility with existing callers constructing `ClimateDevice`.
+
+The reads were verified on a physical S21 running firmware `0.36 (2019-05-08)`:
+both flags were false in fan-only mode while the fans ran. In a controlled test,
+heating mode with a 15 °C target left DI7 false; raising the target to 25 °C
+made DI7 true after about six seconds. Restoring fan-only mode and 15 °C made
+DI7 false again, with fan level and alarm codes unchanged. No cooler was
+configured, so active cooling is covered by the Modbus test server rather than
+a physical cooling test. The legacy `hvac_action` field remains inferred for compatibility. Use the
+new activity flags when actual heater/cooler status is needed; downstream
+integrations must not treat the inferred field as measured activity.
+
 ## Bypass control
 
 ```python

{pybls21-5.1.0 → pybls21-5.2.0}/pybls21/_decoder.py

@@ -78,6 +78,7 @@ def _decode_hvac_action(
 def decode_device(
     *,
     coils: list[bool],
+    activity: list[bool],
     holding_registers: list[int],
     input_registers: list[int],
     alarm_codes: list[int],
@@ -126,6 +127,8 @@ def decode_device(
 
     return ClimateDevice(
         available=True,
+        is_heating=activity[0],
+        is_cooling=activity[reg.DI_StatusCOOLER - reg.DI_StatusHEATER],
         name="Blauberg S21",
         temperature_unit=TEMP_CELSIUS,
         precision=1,

{pybls21-5.1.0 → pybls21-5.2.0}/pybls21/client.py

@@ -176,7 +176,7 @@ class S21Client:
         bits = self._validate_modbus_response(response, operation).bits
         if not isinstance(bits, list) or len(bits) < count:
             raise ModbusCommunicationException(
-                f"Modbus {operation} failed: expected {count} coil bits"
+                f"Modbus {operation} failed: expected {count} bits"
             )
         return bits
 
@@ -218,11 +218,12 @@ class S21Client:
             response, count, f"read input registers at {address}"
         )
 
+    async def _read_discrete_inputs(self, address: int, count: int) -> list[bool]:
+        response = await self._client.read_discrete_inputs(address, count=count)
+        return self._get_bits(response, count, f"read discrete inputs at {address}")
+
     async def _read_alarm_codes(self) -> list[int]:
-        response = await self._client.read_discrete_inputs(
-            reg.DI_ALARM_START, count=reg.DI_ALARM_COUNT
-        )
-        bits = self._get_bits(response, reg.DI_ALARM_COUNT, "read alarm codes")
+        bits = await self._read_discrete_inputs(reg.DI_ALARM_START, reg.DI_ALARM_COUNT)
         # Modbus pads bit responses to whole bytes; ignore bits beyond code 52.
         return [code for code in range(reg.DI_ALARM_COUNT) if bits[code]]
 
@@ -274,6 +275,9 @@ class S21Client:
         coils = await self._read_coils(0, count=4)
         holding_registers = await self._read_holding_registers(0, count=76)
         input_registers = await self._read_input_registers(0, count=39)
+        activity = await self._read_discrete_inputs(
+            reg.DI_StatusHEATER, count=reg.DI_StatusCOOLER - reg.DI_StatusHEATER + 1
+        )
         alarm_codes = (
             await self._read_alarm_codes() if input_registers[reg.IR_ALARM] else []
         )
@@ -288,6 +292,7 @@ class S21Client:
         try:
             return decode_device(
                 coils=coils,
+                activity=activity,
                 holding_registers=holding_registers,
                 input_registers=input_registers,
                 alarm_codes=alarm_codes,

{pybls21-5.1.0 → pybls21-5.2.0}/pybls21/constants.py

@@ -47,6 +47,10 @@ IR_StatusBpsRotor = 51
 IR_CurSuFanSpeed = 52  # Actual supply fan performance, percent
 IR_CurExFanSpeed = 53  # Actual extract fan performance, percent
 
+# Discrete inputs: controller-reported heating/cooling activity
+DI_StatusHEATER = 7
+DI_StatusCOOLER = 8
+
 # Discrete inputs: alarm codes 0 through 52
 DI_ALARM_START = 19
 DI_ALARM_COUNT = 53

{pybls21-5.1.0 → pybls21-5.2.0}/pybls21/models.py

@@ -178,3 +178,11 @@ class ClimateDevice:
         default=None,
         doc="Actual extract fan performance in percent (0–100); None for unsupported or invalid readings.",
     )
+    is_heating: bool | None = field(
+        default=None,
+        doc="Controller heater-operation indication (DI7), independent of the selected mode; None if not populated.",
+    )
+    is_cooling: bool | None = field(
+        default=None,
+        doc="Controller cooler-operation indication (DI8), independent of the selected mode; None if not populated.",
+    )

{pybls21-5.1.0 → pybls21-5.2.0/pybls21.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pybls21
-Version: 5.1.0
+Version: 5.2.0
 Summary: Async Modbus TCP client for Blauberg S21 ventilation devices
 Author-email: Julius Vitkauskas <zadintuvas@gmail.com>
 License-Expression: MIT
@@ -159,6 +159,38 @@ a successful poll. Connection and communication failures mark
 successful subsequent poll restores it. Previously returned models are immutable
 snapshots, so read `client.device` for the updated availability.
 
+## Heater and cooler activity
+
+```python
+snapshot = await client.poll()
+print(snapshot.is_heating, snapshot.is_cooling)
+```
+
+`is_heating` and `is_cooling` expose the controller's operation indications at
+**DI7 (`DI_StatusHEATER`)** and **DI8 (`DI_StatusCOOLER`)**, respectively. Every poll
+reads both in one additional Modbus request, regardless of mode or alarm state.
+These booleans come directly from the controller; temperature differences,
+selected HVAC mode, and unit power do not override them. If both bits are set,
+both fields remain true rather than arbitrarily selecting one action.
+They indicate controller-reported operation, not independently measured power
+consumption or proof that the attached heater/cooler is functioning.
+
+A successful poll populates both fields. Failed, erroneous, or short responses
+fail the poll and mark the cached snapshot unavailable, like other required
+reads; they never silently report inactive equipment. The new fields default to
+`None` only for manually constructed snapshots that omit them, preserving
+compatibility with existing callers constructing `ClimateDevice`.
+
+The reads were verified on a physical S21 running firmware `0.36 (2019-05-08)`:
+both flags were false in fan-only mode while the fans ran. In a controlled test,
+heating mode with a 15 °C target left DI7 false; raising the target to 25 °C
+made DI7 true after about six seconds. Restoring fan-only mode and 15 °C made
+DI7 false again, with fan level and alarm codes unchanged. No cooler was
+configured, so active cooling is covered by the Modbus test server rather than
+a physical cooling test. The legacy `hvac_action` field remains inferred for compatibility. Use the
+new activity flags when actual heater/cooler status is needed; downstream
+integrations must not treat the inferred field as measured activity.
+
 ## Bypass control
 
 ```python

{pybls21-5.1.0 → pybls21-5.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pybls21"
-version = "5.1.0"
+version = "5.2.0"
 description = "Async Modbus TCP client for Blauberg S21 ventilation devices"
 readme = "README.md"
 requires-python = ">=3.14.2"

{pybls21-5.1.0 → pybls21-5.2.0}/tests/test_client.py

@@ -228,6 +228,8 @@ class TestClient(unittest.IsolatedAsyncioTestCase):
                 model="S21",
                 sw_version="0.36 (2019-05-08)",
                 is_boosting=False,
+                is_heating=False,
+                is_cooling=False,
                 current_intake_temperature=10.8,
                 manual_fan_speed_percent=100,
                 max_fan_level=3,
@@ -333,6 +335,79 @@ class TestClient(unittest.IsolatedAsyncioTestCase):
         self.assertEqual(device.fan_level_timer_mode, 1)
         self.assertEqual(device.fan_level_schedule_mode, 0)
 
+    async def test_activity_bits_are_independent_of_mode_and_temperature(self):
+        client = S21Client(self.server.host, self.server.port)
+        bank = self.server.data_bank
+        bank.set_input_registers(reg.IR_ALARM, [0])
+        bank.set_input_registers(reg.IR_CurTEMP_SuAirIn, [100, 300])
+        for powered in (False, True):
+            bank.set_coils(reg.CL_POWER, [powered])
+            for mode in range(4):
+                bank.set_holding_registers(reg.HR_OPERATION_MODE, [mode])
+                for heating, cooling in (
+                    (False, False),
+                    (True, False),
+                    (False, True),
+                    (True, True),
+                ):
+                    with self.subTest(
+                        powered=powered, mode=mode, heating=heating, cooling=cooling
+                    ):
+                        bank.set_discrete_inputs(
+                            reg.DI_StatusHEATER, [heating, cooling]
+                        )
+                        snapshot = await client.poll()
+                        self.assertIs(snapshot.is_heating, heating)
+                        self.assertIs(snapshot.is_cooling, cooling)
+        # An unsupported temperature sensor does not invalidate operation bits.
+        bank.set_input_registers(reg.IR_CurTEMP_SuAirIn, [0x8000, 0x7FFF])
+        self.assertTrue((await client.poll()).is_heating)
+
+    async def test_activity_fields_default_to_unknown_for_older_constructors(self):
+        from dataclasses import fields
+
+        snapshot = await S21Client(self.server.host, self.server.port).poll()
+        old_arguments = {
+            field.name: getattr(snapshot, field.name)
+            for field in fields(snapshot)
+            if field.name not in {"is_heating", "is_cooling"}
+        }
+        constructed = ClimateDevice(**old_arguments)
+        self.assertIsNone(constructed.is_heating)
+        self.assertIsNone(constructed.is_cooling)
+
+    async def test_activity_byte_padding_does_not_report_cooling(self):
+        self.server.data_bank.set_input_registers(reg.IR_ALARM, [0])
+        client = S21Client(self.server.host, self.server.port)
+        client._client.read_discrete_inputs = AsyncMock(
+            return_value=SuccessResponse(bits=[True, False] + [True] * 6)
+        )
+        snapshot = await client.poll()
+        self.assertTrue(snapshot.is_heating)
+        self.assertFalse(snapshot.is_cooling)
+        client._client.read_discrete_inputs.assert_awaited_once_with(7, count=2)
+
+    async def test_activity_read_failures_invalidate_cache_and_recover(self):
+        client = S21Client(self.server.host, self.server.port)
+        read = client._client.read_discrete_inputs
+        for response in (
+            None,
+            ErrorResponse(),
+            SuccessResponse(bits=[]),
+            SuccessResponse(bits=[True]),
+        ):
+            with self.subTest(response=response):
+                client._client.read_discrete_inputs = read
+                snapshot = await client.poll()
+                client._client.read_discrete_inputs = AsyncMock(return_value=response)
+                with self.assertRaises(ModbusCommunicationException):
+                    await client.poll()
+                self.assertFalse(client.device.available)
+                self.assertTrue(snapshot.available)
+                self.assertFalse(client._client.connected)
+        client._client.read_discrete_inputs = read
+        self.assertTrue((await client.poll()).available)
+
     async def test_alarm_codes_are_read_only_for_active_alarms_or_warnings(self):
         client = S21Client(self.server.host, self.server.port)
         client._client.read_discrete_inputs = Mock(
@@ -345,8 +420,14 @@ class TestClient(unittest.IsolatedAsyncioTestCase):
             with self.subTest(state=state):
                 bank.set_input_registers(reg.IR_ALARM, [state])
                 self.assertEqual((await client.poll()).alarm_codes, tuple(expected))
-        self.assertEqual(client._client.read_discrete_inputs.call_count, 2)
-        client._client.read_discrete_inputs.assert_called_with(19, count=53)
+        self.assertEqual(client._client.read_discrete_inputs.call_count, 6)
+        self.assertEqual(
+            [
+                (call.args[0], call.kwargs["count"])
+                for call in client._client.read_discrete_inputs.call_args_list
+            ],
+            [(7, 2), (7, 2), (19, 53), (7, 2), (19, 53), (7, 2)],
+        )
 
     async def test_alarm_code_byte_padding_is_ignored(self):
         self.server.data_bank.set_input_registers(reg.IR_ALARM, [1])
@@ -363,7 +444,13 @@ class TestClient(unittest.IsolatedAsyncioTestCase):
                 client = S21Client(self.server.host, self.server.port)
                 await client.poll()
                 self.server.data_bank.set_input_registers(reg.IR_ALARM, [1])
-                client._client.read_discrete_inputs = AsyncMock(return_value=response)
+                client._client.read_discrete_inputs = AsyncMock(
+                    side_effect=lambda address, *, count: (
+                        response
+                        if address == reg.DI_ALARM_START
+                        else SuccessResponse(bits=[False] * 8)
+                    )
+                )
                 with self.assertRaises(ModbusCommunicationException):
                     await client.poll()
                 self.assertFalse(client.device.available)

{pybls21-5.1.0 → pybls21-5.2.0}/tests/test_decoder.py

@@ -17,6 +17,7 @@ class TestDecoder(unittest.TestCase):
     def decode(self):
         return decode_device(
             coils=self.coils,
+            activity=[False, False],
             holding_registers=self.holding,
             input_registers=self.inputs,
             alarm_codes=[1, 52],