pybls21 5.0.0__tar.gz → 5.2.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pybls21
-Version: 5.0.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
@@ -94,9 +94,55 @@ identity, exceptions, and Home Assistant component migration.
 
 Booleans are not accepted as numeric control values. Bad arguments raise
 `ValueError` before network I/O. `S21Error` is the base for
-`UnsupportedDeviceException` and `ModbusCommunicationException`; the latter
+`UnsupportedDeviceException`, `DiscoveryError`, and `ModbusCommunicationException`; the latter
 includes transport errors and timeouts, retaining the original cause.
 
+## Discovering devices
+
+```python
+from pybls21 import discover, S21Client
+
+# Broadcast one read-only UDP request and collect replies for three seconds.
+devices = await discover()
+for device in devices:
+    print(device.device_id, device.host)
+    snapshot = await S21Client(device.host).poll()
+
+# Optional: target a subnet, choose a local interface, or query a known host.
+devices = await discover(address="192.168.1.255", local_address="192.168.1.10")
+devices = await discover(address="192.168.1.149", timeout=1.0)
+```
+
+`discover()` returns a tuple of immutable `DiscoveredDevice` objects with `host`
+and `device_id`. It collects replies for the whole timeout, deduplicates by
+controller ID (keeping the first address received), and sorts results by ID.
+No replies means an empty tuple. Invalid arguments raise `ValueError`; socket
+failures raise `DiscoveryError`, a subclass of `S21Error`, retaining the cause.
+Cancellation propagates and closes the socket. No background tasks are left running.
+
+Discovery uses IPv4 UDP port **4000**, independently of Modbus TCP port **502**.
+It sends a parameter-read request for controller ID and device type using an
+empty password. Replies must have a valid checksum, matching controller IDs,
+and S21 device type 1. This was verified by unicast and broadcast against an S21
+running firmware `0.36 (2019-05-08)`; availability on other firmware is not yet
+verified. The packet format follows the manufacturer's
+[UDP protocol documentation](https://device.report/m/4ad7c8426973ad1157494cc5715f286e69d244ea3fa438d4b66851938bebf485);
+the [S21 manual](https://blaubergdata.de/Daten/Manual_S21.pdf) describes the app's
+network-search feature.
+
+The default broadcast address is `255.255.255.255`; it normally reaches only the
+local subnet. On a host with multiple network interfaces, call discovery for
+each desired interface using `local_address` and, if necessary, its subnet's
+broadcast address. Arguments accept IPv4 addresses, not hostnames or IPv6.
+Firewalls and network isolation can prevent replies; manual host configuration
+remains supported. Discovery does not automatically run when creating a client.
+
+The controller ID is a device-provided identifier that applications can use
+across IP changes. It is separate from `ClimateDevice` and does not change
+existing polling or entity IDs. UDP replies are not authenticated; validate a
+candidate with `S21Client.poll()` before setting up the device. No device settings
+are written and no password is needed for discovery on the tested unit.
+
 ## Additional readings
 
 `await client.poll()` also returns extract and exhaust air temperatures
@@ -113,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.0.0 → pybls21-5.2.0}/README.md

@@ -70,9 +70,55 @@ identity, exceptions, and Home Assistant component migration.
 
 Booleans are not accepted as numeric control values. Bad arguments raise
 `ValueError` before network I/O. `S21Error` is the base for
-`UnsupportedDeviceException` and `ModbusCommunicationException`; the latter
+`UnsupportedDeviceException`, `DiscoveryError`, and `ModbusCommunicationException`; the latter
 includes transport errors and timeouts, retaining the original cause.
 
+## Discovering devices
+
+```python
+from pybls21 import discover, S21Client
+
+# Broadcast one read-only UDP request and collect replies for three seconds.
+devices = await discover()
+for device in devices:
+    print(device.device_id, device.host)
+    snapshot = await S21Client(device.host).poll()
+
+# Optional: target a subnet, choose a local interface, or query a known host.
+devices = await discover(address="192.168.1.255", local_address="192.168.1.10")
+devices = await discover(address="192.168.1.149", timeout=1.0)
+```
+
+`discover()` returns a tuple of immutable `DiscoveredDevice` objects with `host`
+and `device_id`. It collects replies for the whole timeout, deduplicates by
+controller ID (keeping the first address received), and sorts results by ID.
+No replies means an empty tuple. Invalid arguments raise `ValueError`; socket
+failures raise `DiscoveryError`, a subclass of `S21Error`, retaining the cause.
+Cancellation propagates and closes the socket. No background tasks are left running.
+
+Discovery uses IPv4 UDP port **4000**, independently of Modbus TCP port **502**.
+It sends a parameter-read request for controller ID and device type using an
+empty password. Replies must have a valid checksum, matching controller IDs,
+and S21 device type 1. This was verified by unicast and broadcast against an S21
+running firmware `0.36 (2019-05-08)`; availability on other firmware is not yet
+verified. The packet format follows the manufacturer's
+[UDP protocol documentation](https://device.report/m/4ad7c8426973ad1157494cc5715f286e69d244ea3fa438d4b66851938bebf485);
+the [S21 manual](https://blaubergdata.de/Daten/Manual_S21.pdf) describes the app's
+network-search feature.
+
+The default broadcast address is `255.255.255.255`; it normally reaches only the
+local subnet. On a host with multiple network interfaces, call discovery for
+each desired interface using `local_address` and, if necessary, its subnet's
+broadcast address. Arguments accept IPv4 addresses, not hostnames or IPv6.
+Firewalls and network isolation can prevent replies; manual host configuration
+remains supported. Discovery does not automatically run when creating a client.
+
+The controller ID is a device-provided identifier that applications can use
+across IP changes. It is separate from `ClimateDevice` and does not change
+existing polling or entity IDs. UDP replies are not authenticated; validate a
+candidate with `S21Client.poll()` before setting up the device. No device settings
+are written and no password is needed for discovery on the tested unit.
+
 ## Additional readings
 
 `await client.poll()` also returns extract and exhaust air temperatures
@@ -89,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.0.0 → pybls21-5.2.0}/pybls21/__init__.py

@@ -1,7 +1,9 @@
 """Public API for the asynchronous Blauberg S21 client."""
 
 from .client import S21Client
+from .discovery import DiscoveredDevice, discover
 from .exceptions import (
+    DiscoveryError,
     ModbusCommunicationException,
     S21Error,
     UnsupportedDeviceException,
@@ -10,6 +12,9 @@ from .models import BypassMode, BypassType, ClimateDevice, HVACAction, HVACMode
 
 __all__ = [
     "S21Client",
+    "discover",
+    "DiscoveredDevice",
+    "DiscoveryError",
     "S21Error",
     "ModbusCommunicationException",
     "UnsupportedDeviceException",

{pybls21-5.0.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.0.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.0.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.2.0/pybls21/discovery.py

@@ -0,0 +1,133 @@
+"""Read-only IPv4 discovery using the controller's UDP protocol."""
+
+import asyncio
+import math
+import socket
+from dataclasses import dataclass, field
+from ipaddress import IPv4Address
+
+from .exceptions import DiscoveryError
+
+_DISCOVERY_PORT = 4000
+_MAX_PACKET_SIZE = 256
+# Read device ID (0x007c) and device type (0x00b9), with an empty password.
+_BODY = b"\x02\x10DEFAULT_DEVICEID\x00\x01\x7c\xb9"
+_REQUEST = b"\xfd\xfd" + _BODY + sum(_BODY).to_bytes(2, "little")
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class DiscoveredDevice:
+    """An S21 discovery reply; use host with S21Client's Modbus TCP port."""
+
+    host: str = field(doc="IPv4 address from which the reply was received.")
+    device_id: str = field(doc="16-character controller ID, independent of its IP.")
+
+
+def _parse_response(data: bytes, host: str) -> DiscoveredDevice | None:
+    """Ignore malformed packets and other products sharing the UDP protocol."""
+    if (
+        not 25 <= len(data) <= _MAX_PACKET_SIZE
+        or data[:4] != b"\xfd\xfd\x02\x10"
+        or sum(data[2:-2]) != int.from_bytes(data[-2:], "little")
+    ):
+        return None
+    identity = data[4:20]
+    if not identity.isalnum():
+        return None
+    password_size = data[20]
+    position = 21 + password_size
+    end = len(data) - 2
+    if password_size > 8 or position >= end or data[position] != 6:
+        return None
+    position += 1
+    parameters: dict[int, bytes] = {}
+    high_byte = 0
+    while position < end:
+        parameter = data[position]
+        position += 1
+        size = 1
+        if parameter == 0xFF:  # Change the high byte of subsequent parameter IDs.
+            if position >= end:
+                return None
+            high_byte = data[position] << 8
+            position += 1
+            continue
+        if parameter == 0xFE:  # Explicit length for the following parameter.
+            if position + 2 > end:
+                return None
+            size, parameter = data[position : position + 2]
+            position += 2
+        if parameter >= 0xFC or size == 0 or position + size > end:
+            return None
+        key = high_byte | parameter
+        if key in parameters:
+            return None
+        parameters[key] = data[position : position + size]
+        position += size
+    # S21 is type 1. Do not mistake VENTO and related products for an S21.
+    if parameters.get(0xB9) != b"\x01\x00" or parameters.get(0x7C) != identity:
+        return None
+    return DiscoveredDevice(host=host, device_id=identity.decode("ascii"))
+
+
+async def discover(
+    *,
+    timeout: float = 3.0,
+    address: str = "255.255.255.255",
+    local_address: str = "0.0.0.0",
+) -> tuple[DiscoveredDevice, ...]:
+    """Find S21 controllers without changing device settings.
+
+    Send one UDP broadcast and collect replies for ``timeout`` seconds. ``address``
+    may be a subnet broadcast or a known device's IPv4 address for unicast lookup.
+    Bind ``local_address`` to a local IPv4 address to select a network interface.
+    Hostnames and IPv6 are not supported. Broadcasts normally stay on the local
+    subnet; call separately for each desired interface on a multihomed host.
+
+    Return devices sorted by ID, retaining the first address seen for each ID.
+    Silence returns an empty tuple. Invalid arguments raise ValueError; socket
+    failures raise DiscoveryError. Cancellation propagates and closes the socket.
+    The timeout bounds sending and receiving, not just the first reply.
+    """
+    if (
+        isinstance(timeout, bool)
+        or not isinstance(timeout, (int, float))
+        or not math.isfinite(timeout)
+        or timeout <= 0
+    ):
+        raise ValueError("timeout must be a finite positive number")
+    if not isinstance(address, str) or not isinstance(local_address, str):
+        raise ValueError("address and local_address must be IPv4 address strings")
+    destination = str(IPv4Address(address))
+    interface = str(IPv4Address(local_address))
+    loop = asyncio.get_running_loop()
+    devices: dict[str, DiscoveredDevice] = {}
+    try:
+        with socket.socket(socket.AF_INET, socket.SOCK_DGRAM) as sock:
+            sock.setblocking(False)
+            sock.setsockopt(socket.SOL_SOCKET, socket.SO_BROADCAST, 1)
+            sock.bind((interface, 0))
+            deadline = asyncio.timeout(timeout)
+            try:
+                async with deadline:
+                    await loop.sock_sendto(
+                        sock, _REQUEST, (destination, _DISCOVERY_PORT)
+                    )
+                    while True:
+                        data, source = await loop.sock_recvfrom(
+                            sock, _MAX_PACKET_SIZE + 1
+                        )
+                        # Yield even if a busy socket has another packet ready,
+                        # so deadlines and cancellation cannot be starved.
+                        await asyncio.sleep(0)
+                        if source[1] != _DISCOVERY_PORT:
+                            continue
+                        device = _parse_response(data, source[0])
+                        if device is not None:
+                            devices.setdefault(device.device_id, device)
+            except TimeoutError:
+                if not deadline.expired():
+                    raise
+    except OSError as error:
+        raise DiscoveryError("UDP discovery failed") from error
+    return tuple(devices[key] for key in sorted(devices))

{pybls21-5.0.0 → pybls21-5.2.0}/pybls21/exceptions.py

@@ -14,3 +14,7 @@ class ModbusCommunicationException(S21Error):
 
     Transport exceptions are retained as ``__cause__`` when wrapped.
     """
+
+
+class DiscoveryError(S21Error):
+    """UDP discovery failed due to a socket error; the cause is retained."""

{pybls21-5.0.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.0.0 → pybls21-5.2.0/pybls21.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pybls21
-Version: 5.0.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
@@ -94,9 +94,55 @@ identity, exceptions, and Home Assistant component migration.
 
 Booleans are not accepted as numeric control values. Bad arguments raise
 `ValueError` before network I/O. `S21Error` is the base for
-`UnsupportedDeviceException` and `ModbusCommunicationException`; the latter
+`UnsupportedDeviceException`, `DiscoveryError`, and `ModbusCommunicationException`; the latter
 includes transport errors and timeouts, retaining the original cause.
 
+## Discovering devices
+
+```python
+from pybls21 import discover, S21Client
+
+# Broadcast one read-only UDP request and collect replies for three seconds.
+devices = await discover()
+for device in devices:
+    print(device.device_id, device.host)
+    snapshot = await S21Client(device.host).poll()
+
+# Optional: target a subnet, choose a local interface, or query a known host.
+devices = await discover(address="192.168.1.255", local_address="192.168.1.10")
+devices = await discover(address="192.168.1.149", timeout=1.0)
+```
+
+`discover()` returns a tuple of immutable `DiscoveredDevice` objects with `host`
+and `device_id`. It collects replies for the whole timeout, deduplicates by
+controller ID (keeping the first address received), and sorts results by ID.
+No replies means an empty tuple. Invalid arguments raise `ValueError`; socket
+failures raise `DiscoveryError`, a subclass of `S21Error`, retaining the cause.
+Cancellation propagates and closes the socket. No background tasks are left running.
+
+Discovery uses IPv4 UDP port **4000**, independently of Modbus TCP port **502**.
+It sends a parameter-read request for controller ID and device type using an
+empty password. Replies must have a valid checksum, matching controller IDs,
+and S21 device type 1. This was verified by unicast and broadcast against an S21
+running firmware `0.36 (2019-05-08)`; availability on other firmware is not yet
+verified. The packet format follows the manufacturer's
+[UDP protocol documentation](https://device.report/m/4ad7c8426973ad1157494cc5715f286e69d244ea3fa438d4b66851938bebf485);
+the [S21 manual](https://blaubergdata.de/Daten/Manual_S21.pdf) describes the app's
+network-search feature.
+
+The default broadcast address is `255.255.255.255`; it normally reaches only the
+local subnet. On a host with multiple network interfaces, call discovery for
+each desired interface using `local_address` and, if necessary, its subnet's
+broadcast address. Arguments accept IPv4 addresses, not hostnames or IPv6.
+Firewalls and network isolation can prevent replies; manual host configuration
+remains supported. Discovery does not automatically run when creating a client.
+
+The controller ID is a device-provided identifier that applications can use
+across IP changes. It is separate from `ClimateDevice` and does not change
+existing polling or entity IDs. UDP replies are not authenticated; validate a
+candidate with `S21Client.poll()` before setting up the device. No device settings
+are written and no password is needed for discovery on the tested unit.
+
 ## Additional readings
 
 `await client.poll()` also returns extract and exhaust air temperatures
@@ -113,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.0.0 → pybls21-5.2.0}/pybls21.egg-info/SOURCES.txt

@@ -8,6 +8,7 @@ pybls21/__init__.py
 pybls21/_decoder.py
 pybls21/client.py
 pybls21/constants.py
+pybls21/discovery.py
 pybls21/exceptions.py
 pybls21/models.py
 pybls21/py.typed
@@ -18,5 +19,6 @@ pybls21.egg-info/requires.txt
 pybls21.egg-info/top_level.txt
 tests/test_client.py
 tests/test_decoder.py
+tests/test_discovery.py
 tests/test_lifecycle.py
 tests/test_models.py

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pybls21"
-version = "5.0.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.0.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.0.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],

pybls21-5.2.0/tests/test_discovery.py

@@ -0,0 +1,233 @@
+"""UDP discovery framing, real loopback I/O, and resource lifecycle tests."""
+
+import asyncio
+import socket
+import unittest
+from dataclasses import FrozenInstanceError
+from unittest.mock import AsyncMock, Mock, patch
+
+from pybls21 import DiscoveredDevice, DiscoveryError, S21Error, discover
+from pybls21.discovery import _parse_response
+
+# Captured from the physical S21, firmware 0.36 (2019-05-08).
+CAPTURED = bytes.fromhex(
+    "fdfd0210303032343030353433333337353130370006"
+    "fe02b90100fe107c30303234303035343333333735313037b409"
+)
+IDENTITY = b"0024005433375107"
+
+
+def frame(body):
+    return b"\xfd\xfd" + body + sum(body).to_bytes(2, "little")
+
+
+def response(parameters=None, identity=IDENTITY, password=b"", function=6):
+    if parameters is None:
+        parameters = b"\xfe\x02\xb9\x01\x00\xfe\x10\x7c" + identity
+    return frame(
+        b"\x02\x10"
+        + identity
+        + bytes([len(password)])
+        + password
+        + bytes([function])
+        + parameters
+    )
+
+
+class TestDiscoveryParser(unittest.TestCase):
+    def test_hardware_capture(self):
+        self.assertEqual(response(), CAPTURED)
+        device = _parse_response(CAPTURED, "192.168.1.149")
+        self.assertEqual(
+            device,
+            DiscoveredDevice(host="192.168.1.149", device_id=IDENTITY.decode()),
+        )
+        with self.assertRaises(FrozenInstanceError):
+            device.host = "192.168.1.1"
+
+    def test_parameter_order_lengths_and_unknown_parameters(self):
+        parameters = (
+            b"\xfe\x10\x7c"
+            + IDENTITY
+            + b"\x42\x09"  # Unknown, default one-byte value.
+            + b"\xff\x01\xb9\x42"  # Different page, not device type.
+            + b"\xff\x00\xfe\x02\xb9\x01\x00"
+        )
+        self.assertIsNotNone(
+            _parse_response(response(parameters, password=b"1111"), "127.0.0.1")
+        )
+
+    def test_rejects_bad_header_checksum_identity_and_other_devices(self):
+        good_params = b"\xfe\x02\xb9\x01\x00\xfe\x10\x7c" + IDENTITY
+        bad_packets = [
+            b"",
+            CAPTURED[:-1],
+            CAPTURED + b"\x00",
+            b"\x00" * 257,
+            frame(b"\x03" + CAPTURED[3:-2]),
+            frame(b"\x02\x0f" + CAPTURED[4:-2]),
+            response(identity=b"DEFAULT_DEVICEID"),
+            response(identity=b"\xff" * 16),
+            response(password=b"123456789"),
+            frame(b"\x02\x10" + IDENTITY + b"\x08\x00\x00"),
+            response(function=1),
+            response(b"\xfe\x10\x7c" + IDENTITY),
+            response(b"\xfe\x02\xb9\x03\x00\xfe\x10\x7c" + IDENTITY),
+            response(b"\xb9\x01\xfe\x10\x7c" + IDENTITY),
+            response(good_params[:-1] + b"8"),
+            response(good_params + b"\xfe\x02\xb9\x01\x00"),
+        ]
+        for packet in bad_packets:
+            with self.subTest(packet=packet):
+                self.assertIsNone(_parse_response(packet, "127.0.0.1"))
+
+    def test_rejects_truncated_or_invalid_parameter_blocks(self):
+        for suffix in (
+            b"\xff",
+            b"\xfe",
+            b"\xfe\x10",
+            b"\xfe\x10\x7cshort",
+            b"\xfe\x00\x01",
+            b"\xfc",
+            b"\xfd\x7c",
+            b"\xfe\x01\xff\x00",
+        ):
+            with self.subTest(suffix=suffix):
+                self.assertIsNone(_parse_response(response(suffix), "127.0.0.1"))
+
+
+class TestDiscovery(unittest.IsolatedAsyncioTestCase):
+    async def asyncSetUp(self):
+        self.server = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+        self.server.setblocking(False)
+        self.server.bind(("127.0.0.1", 0))
+        self.addCleanup(self.server.close)
+        patcher = patch(
+            "pybls21.discovery._DISCOVERY_PORT", self.server.getsockname()[1]
+        )
+        patcher.start()
+        self.addCleanup(patcher.stop)
+        self.loop = asyncio.get_running_loop()
+
+    async def test_collects_multiple_devices_deduplicates_and_ignores_noise(self):
+        async def answer():
+            request, sender = await self.loop.sock_recvfrom(self.server, 1024)
+            # Exact wire contract: read only, empty password, ID and type queries.
+            self.assertEqual(
+                request,
+                bytes.fromhex("fdfd021044454641554c545f444556494345494400017cb9e905"),
+            )
+            for packet in (
+                b"garbage",
+                response(identity=b"0024005433379999"),
+                CAPTURED,
+                CAPTURED,
+            ):
+                await self.loop.sock_sendto(self.server, packet, sender)
+            with socket.socket(socket.AF_INET, socket.SOCK_DGRAM) as wrong_port:
+                wrong_port.sendto(response(identity=b"0024005433370000"), sender)
+
+        responder = asyncio.create_task(answer())
+        try:
+            devices = await discover(
+                address="127.0.0.1", local_address="127.0.0.1", timeout=0.1
+            )
+            await asyncio.wait_for(responder, 1)
+        finally:
+            responder.cancel()
+            await asyncio.gather(responder, return_exceptions=True)
+        self.assertEqual(
+            [d.device_id for d in devices], [IDENTITY.decode(), "0024005433379999"]
+        )
+        self.assertTrue(all(d.host == "127.0.0.1" for d in devices))
+
+    async def test_silence_returns_empty_tuple(self):
+        self.assertEqual(await discover(address="127.0.0.1", timeout=0.02), ())
+
+    async def test_cancellation_closes_socket(self):
+        original = socket.socket
+        sockets = []
+
+        def factory(*args, **kwargs):
+            sock = original(*args, **kwargs)
+            sockets.append(sock)
+            return sock
+
+        with patch("pybls21.discovery.socket.socket", side_effect=factory):
+            task = asyncio.create_task(discover(address="127.0.0.1", timeout=30))
+            try:
+                await asyncio.wait_for(self.loop.sock_recvfrom(self.server, 1024), 1)
+            finally:
+                task.cancel()
+                with self.assertRaises(asyncio.CancelledError):
+                    await task
+        self.assertEqual(sockets[0].fileno(), -1)
+
+    async def test_invalid_arguments_do_not_open_socket(self):
+        for kwargs in (
+            *(
+                {"timeout": value}
+                for value in (0, -1, True, float("nan"), float("inf"), "3", None)
+            ),
+            {"address": "example.org"},
+            {"address": "::1"},
+            {"local_address": "not-an-ip"},
+            {"address": 123},
+            {"local_address": None},
+        ):
+            with (
+                self.subTest(kwargs=kwargs),
+                patch("pybls21.discovery.socket.socket") as factory,
+            ):
+                with self.assertRaises(ValueError):
+                    await discover(**kwargs)
+                factory.assert_not_called()
+
+    async def test_socket_errors_are_wrapped_and_close_socket(self):
+        for stage in ("create", "bind", "send", "receive", "socket_timeout"):
+            error = (
+                TimeoutError("socket timeout")
+                if stage == "socket_timeout"
+                else OSError("network unavailable")
+            )
+            sock = Mock()
+            sock.__enter__ = Mock(return_value=sock)
+            sock.__exit__ = Mock(return_value=False)
+            factory = Mock(return_value=sock)
+            send = AsyncMock()
+            receive = AsyncMock()
+            if stage == "create":
+                factory.side_effect = error
+            elif stage == "bind":
+                sock.bind.side_effect = error
+            elif stage == "send":
+                send.side_effect = error
+            else:
+                receive.side_effect = error
+            with (
+                self.subTest(stage=stage),
+                patch("pybls21.discovery.socket.socket", factory),
+                patch.object(self.loop, "sock_sendto", send),
+                patch.object(self.loop, "sock_recvfrom", receive),
+            ):
+                with self.assertRaises(DiscoveryError) as caught:
+                    await discover()
+                self.assertIsInstance(caught.exception, S21Error)
+                self.assertIs(caught.exception.__cause__, error)
+                if stage != "create":
+                    sock.__exit__.assert_called_once()
+
+    async def test_deadline_includes_send_and_closes_socket(self):
+        sock = Mock()
+        sock.__enter__ = Mock(return_value=sock)
+        sock.__exit__ = Mock(return_value=False)
+
+        async def blocked_send(*args):
+            await asyncio.Event().wait()
+
+        with (
+            patch("pybls21.discovery.socket.socket", return_value=sock),
+            patch.object(self.loop, "sock_sendto", side_effect=blocked_send),
+        ):
+            self.assertEqual(await discover(timeout=0.01), ())
+        sock.__exit__.assert_called_once()