pybls21 4.2.2__tar.gz → 4.3.0__tar.gz

pybls21-4.3.0/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: pybls21
+Version: 4.3.0
+Summary: An api allowing control of AC state (temperature, on/off, speed) of an Blauberg S21 device locally over TCP
+Home-page: https://github.com/jvitkauskas/pybls21
+Author: Julius Vitkauskas
+Author-email: zadintuvas@gmail.com
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pymodbus<4.0,>=3.13.1
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# Blauberg S21 Asynchronous Python API
+An api allowing control of AC state (temperature, on/off, speed) of an Blauberg S21 device locally over TCP.
+
+## Usage
+To initialize:
+`client = S21Client("192.168.0.125")`
+
+To load:
+`await client.poll()`
+
+The following functions are available:
+`turn_on()`
+`turn_off()`
+`set_hvac_mode(hvac_mode: HVACMode)`
+`set_fan_mode(mode: int)`
+`set_manual_fan_speed_percent(speed_percent: int)`
+`set_temperature(temp_celsius: int)`
+`reset_filter_change_timer()`
+`reset_alarm()`
+`boost_on()`
+`boost_off()`
+`set_bypass_mode(mode: BypassMode)`
+`set_bypass_position(position_percent: int)`
+
+
+## Additional readings
+
+`await client.poll()` also returns extract and exhaust air temperatures
+(`current_extract_temperature`, `current_exhaust_temperature`), supply and
+extract duct pressure in Pa (`supply_pressure`, `extract_pressure`), and whole
+days remaining until filter replacement (`filter_countdown_days`).
+
+Missing or short-circuited temperature sensors are reported as `None`, including
+`current_temperature` and `current_intake_temperature`. In AUTO mode,
+`hvac_action` is also `None` when either temperature needed to infer the action
+is unavailable. Other readings remain usable and `available` stays true after
+a successful poll. Connection and communication failures mark
+`client.device.available` false if a previous poll populated the device; a
+successful subsequent poll restores it. Previously returned models are immutable
+snapshots, so read `client.device` for the updated availability.
+
+## Bypass control
+
+```python
+from pybls21.models import BypassMode
+
+# AUTO lets the device control its bypass or rotary heat exchanger.
+await client.set_bypass_mode(BypassMode.AUTO)
+
+# For analogue control, set the manual percentage and select manual mode.
+await client.set_bypass_position(60)
+await client.set_bypass_mode(BypassMode.OPEN)
+```
+
+`CLOSED` closes the bypass or starts the rotor. `OPEN` opens the bypass or stops
+the rotor for discrete control; with analogue control it selects the percentage
+set by `set_bypass_position()`. That setter alone does not change the mode.
+A value of 0 means closed bypass / maximum rotor speed; 100 means open bypass /
+stopped rotor. Choose controls appropriate to the reported `bypass_type`.
+
+The model exposes `bypass_type`, `bypass_mode`, `manual_bypass_position`, and
+`bypass_position`. Position is read separately from optional input register 51.
+On older firmware that rejects this address, `bypass_position` is `None` and
+polling the other readings still succeeds. Other communication errors are
+propagated. When no bypass/rotor is fitted, its mode and positions are `None`
+and the optional read is skipped.
+
+New model fields have defaults, preserving construction with the original
+positional or keyword arguments. The tuple now contains additional fields;
+consumers should access readings by attribute rather than unpacking a fixed
+number of values.

pybls21-4.3.0/README.md

@@ -0,0 +1,71 @@
+# Blauberg S21 Asynchronous Python API
+An api allowing control of AC state (temperature, on/off, speed) of an Blauberg S21 device locally over TCP.
+
+## Usage
+To initialize:
+`client = S21Client("192.168.0.125")`
+
+To load:
+`await client.poll()`
+
+The following functions are available:
+`turn_on()`
+`turn_off()`
+`set_hvac_mode(hvac_mode: HVACMode)`
+`set_fan_mode(mode: int)`
+`set_manual_fan_speed_percent(speed_percent: int)`
+`set_temperature(temp_celsius: int)`
+`reset_filter_change_timer()`
+`reset_alarm()`
+`boost_on()`
+`boost_off()`
+`set_bypass_mode(mode: BypassMode)`
+`set_bypass_position(position_percent: int)`
+
+
+## Additional readings
+
+`await client.poll()` also returns extract and exhaust air temperatures
+(`current_extract_temperature`, `current_exhaust_temperature`), supply and
+extract duct pressure in Pa (`supply_pressure`, `extract_pressure`), and whole
+days remaining until filter replacement (`filter_countdown_days`).
+
+Missing or short-circuited temperature sensors are reported as `None`, including
+`current_temperature` and `current_intake_temperature`. In AUTO mode,
+`hvac_action` is also `None` when either temperature needed to infer the action
+is unavailable. Other readings remain usable and `available` stays true after
+a successful poll. Connection and communication failures mark
+`client.device.available` false if a previous poll populated the device; a
+successful subsequent poll restores it. Previously returned models are immutable
+snapshots, so read `client.device` for the updated availability.
+
+## Bypass control
+
+```python
+from pybls21.models import BypassMode
+
+# AUTO lets the device control its bypass or rotary heat exchanger.
+await client.set_bypass_mode(BypassMode.AUTO)
+
+# For analogue control, set the manual percentage and select manual mode.
+await client.set_bypass_position(60)
+await client.set_bypass_mode(BypassMode.OPEN)
+```
+
+`CLOSED` closes the bypass or starts the rotor. `OPEN` opens the bypass or stops
+the rotor for discrete control; with analogue control it selects the percentage
+set by `set_bypass_position()`. That setter alone does not change the mode.
+A value of 0 means closed bypass / maximum rotor speed; 100 means open bypass /
+stopped rotor. Choose controls appropriate to the reported `bypass_type`.
+
+The model exposes `bypass_type`, `bypass_mode`, `manual_bypass_position`, and
+`bypass_position`. Position is read separately from optional input register 51.
+On older firmware that rejects this address, `bypass_position` is `None` and
+polling the other readings still succeeds. Other communication errors are
+propagated. When no bypass/rotor is fitted, its mode and positions are `None`
+and the optional read is skipped.
+
+New model fields have defaults, preserving construction with the original
+positional or keyword arguments. The tuple now contains additional fields;
+consumers should access readings by attribute rather than unpacking a fixed
+number of values.

{pybls21-4.2.2 → pybls21-4.3.0}/pybls21/client.py

@@ -2,11 +2,14 @@ import asyncio
 from typing import Any, Awaitable, Callable, List, Optional
 
 from pymodbus.client import AsyncModbusTcpClient
+from pymodbus.pdu import ExceptionResponse
 
 from .constants import *
 from .exceptions import *
 from .models import (
     TEMP_CELSIUS,
+    BypassMode,
+    BypassType,
     ClimateDevice,
     ClimateEntityFeature,
     HVACAction,
@@ -27,6 +30,13 @@ def _to_signed_16bit(value: int) -> int:
     return value - 0x10000 if value > 0x7FFF else value
 
 
+def _parse_temperature(value: int) -> Optional[float]:
+    # The S21 reserves these values for a missing or short-circuited sensor.
+    if value in (0x8000, 0x7FFF):
+        return None
+    return _to_signed_16bit(value) / 10
+
+
 class S21Client:
     def __init__(self, host: str, port: int = 502):
         self.host = host
@@ -73,6 +83,16 @@ class S21Client:
     async def boost_off(self) -> None:
         await self._do_with_connection(self._set_boost_off)
 
+    async def set_bypass_mode(self, mode: BypassMode) -> None:
+        mode = BypassMode(mode)
+        await self._do_with_connection(lambda: self._set_bypass_mode(mode))
+
+    async def set_bypass_position(self, position_percent: int) -> None:
+        self._validate_bypass_position(position_percent)
+        await self._do_with_connection(
+            lambda: self._set_bypass_position(position_percent)
+        )
+
     @staticmethod
     def _validate_modbus_response(response: Any, operation: str) -> Any:
         if response is None:
@@ -117,10 +137,23 @@ class S21Client:
         if not isinstance(temp_celsius, int) or not 15 <= temp_celsius <= 30:
             raise ValueError("Temperature must be between 15 and 30 °C")
 
+    @staticmethod
+    def _validate_bypass_position(position_percent: int) -> None:
+        if not isinstance(position_percent, int) or not 0 <= position_percent <= 100:
+            raise ValueError("Bypass position percent must be between 0 and 100")
+
     async def _read_input_registers(self, address: int, count: int) -> List[int]:
         response = await self.client.read_input_registers(address, count=count)
         return self._get_registers(response, count, f"read input registers at {address}")
 
+    async def _read_bypass_position(self) -> Optional[int]:
+        response = await self.client.read_input_registers(IR_StatusBpsRotor, count=1)
+        # Older firmware has no IR51. Only Illegal Data Address is optional;
+        # timeouts, malformed replies and other device errors must still surface.
+        if isinstance(response, ExceptionResponse) and response.exception_code == 2:
+            return None
+        return self._get_registers(response, 1, "read bypass position")[0]
+
     async def _read_holding_registers(self, address: int, count: int) -> List[int]:
         response = await self.client.read_holding_registers(address, count=count)
         return self._get_registers(response, count, f"read holding registers at {address}")
@@ -139,14 +172,17 @@ class S21Client:
 
     async def _do_with_connection(self, func: Callable[[], Awaitable[Any]]) -> Any:
         async with self.lock:  # Device does not support multiple connections
-            if not await self.client.connect():
-                raise ModbusCommunicationException("Failed to open Modbus TCP connection")
-
             try:
+                if not await self.client.connect():
+                    raise ModbusCommunicationException(
+                        "Failed to open Modbus TCP connection"
+                    )
                 return await func()
             except Exception:
                 if isinstance(self.device, ClimateDevice):
-                    self.device.available = False
+                    # ClimateDevice is a NamedTuple and therefore immutable,
+                    # so the flag has to be replaced instead of assigned.
+                    self.device = self.device._replace(available=False)
                 raise
             finally:
                 self.client.close()  # Also, long connections break over time and become unusable
@@ -156,7 +192,7 @@ class S21Client:
             raise UnsupportedDeviceException("Unsupported device (IR_DeviceTYPE != 1)")
 
         coils = await self._read_coils(0, count=4)
-        holding_registers = await self._read_holding_registers(0, count=45)
+        holding_registers = await self._read_holding_registers(0, count=76)
         input_registers = await self._read_input_registers(0, count=39)
 
         is_on: bool = coils[CL_POWER]
@@ -167,10 +203,10 @@ class S21Client:
         alarm_state: int = input_registers[IR_ALARM]
         max_fan_level: int = holding_registers[HR_MaxSPEED_MODE]
         current_fan_level: int = holding_registers[HR_SPEED_MODE]  # 255 - manual
-        temp_before_heating_x10: int = _to_signed_16bit(
+        temp_before_heating = _parse_temperature(
             input_registers[IR_CurTEMP_SuAirIn]
         )
-        temp_after_heating_x10: int = _to_signed_16bit(
+        temp_after_heating = _parse_temperature(
             input_registers[IR_CurTEMP_SuAirOut]
         )
         supply_fan_speed: int = input_registers[IR_SuRPM]
@@ -180,6 +216,22 @@ class S21Client:
         ]
         operation_mode: int = holding_registers[HR_OPERATION_MODE]
         manual_fan_speed_percent: int = holding_registers[HR_ManualSPEED]
+        bypass_type: BypassType = BypassType(holding_registers[HR_BPS_ROTOR_TYPE])
+        bypass_mode = (
+            BypassMode(holding_registers[HR_BPS_ROTOR_MODE])
+            if bypass_type != BypassType.NOT_AVAILABLE
+            else None
+        )
+        manual_bypass_position = (
+            holding_registers[HR_SetBpsRotorMANUAL]
+            if bypass_type != BypassType.NOT_AVAILABLE
+            else None
+        )
+        bypass_position = (
+            await self._read_bypass_position()
+            if bypass_type != BypassType.NOT_AVAILABLE
+            else None
+        )
 
         self.device = ClimateDevice(
             available=True,
@@ -187,7 +239,7 @@ class S21Client:
             unique_id=f"S21_{self.host}_{self.port}",
             temperature_unit=TEMP_CELSIUS,  # Seems like no Fahrenheit option is available
             precision=1,
-            current_temperature=temp_after_heating_x10 / 10,
+            current_temperature=temp_after_heating,
             target_temperature=set_temperature,
             target_temperature_step=1,
             min_temp=15,
@@ -210,10 +262,12 @@ class S21Client:
             if operation_mode == 1
             else HVACAction.COOLING
             if operation_mode == 2
+            else None
+            if temp_before_heating is None or temp_after_heating is None
             else HVACAction.HEATING
-            if temp_before_heating_x10 < temp_after_heating_x10
+            if temp_before_heating < temp_after_heating
             else HVACAction.COOLING
-            if temp_before_heating_x10 > temp_after_heating_x10
+            if temp_before_heating > temp_after_heating
             else HVACAction.IDLE,
             hvac_modes=[
                 HVACMode.OFF,
@@ -230,13 +284,26 @@ class S21Client:
             model="S21",
             sw_version=_parse_firmware_version(firmware_info),
             is_boosting=is_boosting,
-            current_intake_temperature=temp_before_heating_x10 / 10,
+            current_intake_temperature=temp_before_heating,
             manual_fan_speed_percent=manual_fan_speed_percent,
             max_fan_level=max_fan_level,
             filter_state=filter_state,
             alarm_state=alarm_state,
             supply_fan_speed=supply_fan_speed,
             extract_fan_speed=extract_fan_speed,
+            current_extract_temperature=_parse_temperature(
+                input_registers[IR_CurTEMP_ExAirIn]
+            ),
+            current_exhaust_temperature=_parse_temperature(
+                input_registers[IR_CurTEMP_ExAirOut]
+            ),
+            supply_pressure=input_registers[IR_CurSuPRESS],
+            extract_pressure=input_registers[IR_CurExPRESS],
+            filter_countdown_days=input_registers[IR_CurFILTER_TIMER_DAYS],
+            bypass_type=bypass_type,
+            bypass_mode=bypass_mode,
+            bypass_position=bypass_position,
+            manual_bypass_position=manual_bypass_position,
         )
 
         return self.device
@@ -283,3 +350,9 @@ class S21Client:
 
     async def _set_boost_off(self) -> None:
         await self._write_coil(CL_BoostSWITCH_CTRL, False)
+
+    async def _set_bypass_mode(self, mode: BypassMode) -> None:
+        await self._write_register(HR_BPS_ROTOR_MODE, int(mode))
+
+    async def _set_bypass_position(self, position_percent: int) -> None:
+        await self._write_register(HR_SetBpsRotorMANUAL, position_percent)

pybls21-4.3.0/pybls21/constants.py

@@ -0,0 +1,36 @@
+# Coils
+CL_POWER = 0
+CL_Boost_MODE = 3
+CL_BoostSWITCH_CTRL = 13
+CL_RESET_FILTER_TIMER = 17
+CL_RESET_ALARM = 18
+
+# Holding registers
+HR_MaxSPEED_MODE = 1
+HR_SPEED_MODE = 2
+HR_ManualSPEED = 17
+HR_OPERATION_MODE = 43
+HR_SetTEMP = 44
+HR_BPS_ROTOR_TYPE = 57
+HR_BPS_ROTOR_MODE = 74
+HR_SetBpsRotorMANUAL = 75
+
+# Input registers
+IR_CurTEMP_SuAirIn = 1
+IR_CurTEMP_SuAirOut = 2
+IR_CurTEMP_ExAirIn = 3  # Extract air from the rooms, at the unit inlet
+IR_CurTEMP_ExAirOut = 4  # Exhaust air to the outside, at the unit outlet
+IR_CurRH_Int = 10
+IR_CurSuPRESS = 21  # Supply duct pressure, Pa
+IR_CurExPRESS = 22  # Extract duct pressure, Pa
+IR_SuRPM = 23
+IR_ExRPM = 24
+IR_CurFILTER_TIMER_HOURS_MINUTES = 27  # High byte: hours, low byte: minutes
+IR_CurFILTER_TIMER_DAYS = 28
+IR_StateFILTER = 31
+IR_VerMAIN_FMW_start = 34
+IR_VerMAIN_FMW_end = 36
+IR_DeviceTYPE = 37
+IR_ALARM = 38
+IR_BPS_ROTOR_U = 45
+IR_StatusBpsRotor = 51

pybls21-4.3.0/pybls21/models.py

@@ -0,0 +1,80 @@
+from enum import Enum
+from typing import List, NamedTuple, Optional
+
+TEMP_CELSIUS: str = "°C"
+
+
+class ClimateEntityFeature(int, Enum):
+    TARGET_TEMPERATURE = 1
+    FAN_MODE = 8
+
+
+class HVACMode(str, Enum):
+    OFF = "off"
+    HEAT = "heat"
+    COOL = "cool"
+    AUTO = "auto"
+    FAN_ONLY = "fan_only"
+
+
+class HVACAction(str, Enum):
+    COOLING = "cooling"
+    FAN = "fan"
+    HEATING = "heating"
+    IDLE = "idle"
+    OFF = "off"
+
+
+class BypassType(int, Enum):
+    NOT_AVAILABLE = 0
+    BYPASS_TWO_POINT = 1  # Discrete open/closed bypass damper control
+    BYPASS_ANALOGUE = 2  # Bypass damper position controlled 0-100%
+    ROTOR_DISCRETE = 3  # Discrete on/off rotary heat exchanger control
+    ROTOR_ANALOGUE = 4  # Rotary heat exchanger speed controlled 0-100%
+    BYPASS_THREE_POINT = 5  # Bypass damper driven open/closed via timed pulses
+
+
+class BypassMode(int, Enum):
+    CLOSED = 0  # Close the bypass / start the rotor
+    OPEN = 1  # Open the bypass / stop the rotor (discrete), or manual % (analogue)
+    AUTO = 2  # Device controls bypass/rotor automatically based on temperature
+
+
+class ClimateDevice(NamedTuple):
+    available: bool
+    name: str
+    unique_id: str
+    temperature_unit: str
+    precision: float
+    current_temperature: Optional[float]
+    target_temperature: float
+    target_temperature_step: float
+    max_temp: float
+    min_temp: float
+    current_humidity: Optional[float]
+    hvac_mode: str
+    hvac_action: Optional[str]
+    hvac_modes: List[str]
+    fan_mode: Optional[int]
+    fan_modes: Optional[List[int]]
+    supported_features: int
+    manufacturer: str
+    model: Optional[str]
+    sw_version: Optional[str]
+    is_boosting: bool
+    current_intake_temperature: Optional[float]
+    manual_fan_speed_percent: int
+    max_fan_level: int
+    filter_state: int
+    alarm_state: int
+    supply_fan_speed: int
+    extract_fan_speed: int
+    current_extract_temperature: Optional[float] = None
+    current_exhaust_temperature: Optional[float] = None
+    supply_pressure: Optional[int] = None
+    extract_pressure: Optional[int] = None
+    filter_countdown_days: Optional[int] = None
+    bypass_type: BypassType = BypassType.NOT_AVAILABLE
+    bypass_mode: Optional[BypassMode] = None
+    bypass_position: Optional[int] = None
+    manual_bypass_position: Optional[int] = None

pybls21-4.3.0/pybls21.egg-info/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: pybls21
+Version: 4.3.0
+Summary: An api allowing control of AC state (temperature, on/off, speed) of an Blauberg S21 device locally over TCP
+Home-page: https://github.com/jvitkauskas/pybls21
+Author: Julius Vitkauskas
+Author-email: zadintuvas@gmail.com
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pymodbus<4.0,>=3.13.1
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# Blauberg S21 Asynchronous Python API
+An api allowing control of AC state (temperature, on/off, speed) of an Blauberg S21 device locally over TCP.
+
+## Usage
+To initialize:
+`client = S21Client("192.168.0.125")`
+
+To load:
+`await client.poll()`
+
+The following functions are available:
+`turn_on()`
+`turn_off()`
+`set_hvac_mode(hvac_mode: HVACMode)`
+`set_fan_mode(mode: int)`
+`set_manual_fan_speed_percent(speed_percent: int)`
+`set_temperature(temp_celsius: int)`
+`reset_filter_change_timer()`
+`reset_alarm()`
+`boost_on()`
+`boost_off()`
+`set_bypass_mode(mode: BypassMode)`
+`set_bypass_position(position_percent: int)`
+
+
+## Additional readings
+
+`await client.poll()` also returns extract and exhaust air temperatures
+(`current_extract_temperature`, `current_exhaust_temperature`), supply and
+extract duct pressure in Pa (`supply_pressure`, `extract_pressure`), and whole
+days remaining until filter replacement (`filter_countdown_days`).
+
+Missing or short-circuited temperature sensors are reported as `None`, including
+`current_temperature` and `current_intake_temperature`. In AUTO mode,
+`hvac_action` is also `None` when either temperature needed to infer the action
+is unavailable. Other readings remain usable and `available` stays true after
+a successful poll. Connection and communication failures mark
+`client.device.available` false if a previous poll populated the device; a
+successful subsequent poll restores it. Previously returned models are immutable
+snapshots, so read `client.device` for the updated availability.
+
+## Bypass control
+
+```python
+from pybls21.models import BypassMode
+
+# AUTO lets the device control its bypass or rotary heat exchanger.
+await client.set_bypass_mode(BypassMode.AUTO)
+
+# For analogue control, set the manual percentage and select manual mode.
+await client.set_bypass_position(60)
+await client.set_bypass_mode(BypassMode.OPEN)
+```
+
+`CLOSED` closes the bypass or starts the rotor. `OPEN` opens the bypass or stops
+the rotor for discrete control; with analogue control it selects the percentage
+set by `set_bypass_position()`. That setter alone does not change the mode.
+A value of 0 means closed bypass / maximum rotor speed; 100 means open bypass /
+stopped rotor. Choose controls appropriate to the reported `bypass_type`.
+
+The model exposes `bypass_type`, `bypass_mode`, `manual_bypass_position`, and
+`bypass_position`. Position is read separately from optional input register 51.
+On older firmware that rejects this address, `bypass_position` is `None` and
+polling the other readings still succeeds. Other communication errors are
+propagated. When no bypass/rotor is fitted, its mode and positions are `None`
+and the optional read is skipped.
+
+New model fields have defaults, preserving construction with the original
+positional or keyword arguments. The tuple now contains additional fields;
+consumers should access readings by attribute rather than unpacking a fixed
+number of values.

pybls21-4.3.0/pybls21.egg-info/requires.txt

@@ -0,0 +1 @@
+pymodbus<4.0,>=3.13.1

{pybls21-4.2.2 → pybls21-4.3.0}/setup.py

@@ -5,7 +5,7 @@ with open("README.md", "r") as fh:
 
 setuptools.setup(
     name="pybls21",
-    version="4.2.2",
+    version="4.3.0",
     author="Julius Vitkauskas",
     author_email="zadintuvas@gmail.com",
     description="An api allowing control of AC state (temperature, on/off, speed) of an Blauberg S21 device locally over TCP",
@@ -13,7 +13,7 @@ setuptools.setup(
     long_description_content_type="text/markdown",
     url="https://github.com/jvitkauskas/pybls21",
     packages=setuptools.find_packages(exclude=["tests"]),
-    install_requires=["pymodbus>=3.11.2,<4.0"],
+    install_requires=["pymodbus>=3.13.1,<4.0"],
     classifiers=[
         "Programming Language :: Python :: 3",
         "License :: OSI Approved :: MIT License",

{pybls21-4.2.2 → pybls21-4.3.0}/tests/test_client.py

@@ -2,11 +2,19 @@ import unittest
 from unittest.mock import AsyncMock, Mock
 
 from pyModbusTCP.server import DataBank, ModbusServer
+from pymodbus.pdu import ExceptionResponse
 
 from pybls21.client import S21Client
 from pybls21.constants import *
 from pybls21.exceptions import *
-from pybls21.models import ClimateDevice, ClimateEntityFeature, HVACAction, HVACMode
+from pybls21.models import (
+    BypassMode,
+    BypassType,
+    ClimateDevice,
+    ClimateEntityFeature,
+    HVACAction,
+    HVACMode,
+)
 
 
 class ErrorResponse:
@@ -56,6 +64,38 @@ class TestClient(unittest.IsolatedAsyncioTestCase):
         with self.assertRaises(ModbusCommunicationException):
             await client.poll()
 
+        client.client.close.assert_called_once_with()
+
+    async def test_failed_reconnect_invalidates_device_and_can_recover(self):
+        client = S21Client(host=self.server.host, port=self.server.port)
+        await client.poll()
+        connect = client.client.connect
+        close = client.client.close
+        client.client.connect = AsyncMock(return_value=False)
+        client.client.close = Mock(wraps=close)
+
+        with self.assertRaises(ModbusCommunicationException):
+            await client.poll()
+
+        self.assertFalse(client.device.available)
+        client.client.close.assert_called_once_with()
+        client.client.connect = connect
+        self.assertTrue((await client.poll()).available)
+
+    async def test_connect_exception_invalidates_device_and_preserves_error(self):
+        client = S21Client(host=self.server.host, port=self.server.port)
+        await client.poll()
+        error = OSError("Connection failed")
+        client.client.connect = AsyncMock(side_effect=error)
+        client.client.close = Mock(wraps=client.client.close)
+
+        with self.assertRaises(OSError) as raised:
+            await client.turn_on()
+
+        self.assertIs(raised.exception, error)
+        self.assertFalse(client.device.available)
+        client.client.close.assert_called_once_with()
+
     async def test_poll_when_modbus_returns_error_raises_exception(self):
         client = S21Client(host=self.server.host, port=self.server.port)
         client.client.connect = AsyncMock(return_value=True)
@@ -91,6 +131,25 @@ class TestClient(unittest.IsolatedAsyncioTestCase):
         with self.assertRaises(ModbusCommunicationException):
             await client.poll()
 
+    async def test_poll_when_it_fails_after_a_successful_poll_marks_device_unavailable(
+        self,
+    ):
+        client = S21Client(host=self.server.host, port=self.server.port)
+
+        # A device has to be present first - the failure path below is only
+        # reached once self.device holds a ClimateDevice.
+        await client.poll()
+        self.assertTrue(client.device.available)
+
+        client.client.connect = AsyncMock(return_value=True)
+        client.client.close = Mock()
+        client.client.read_input_registers = AsyncMock(return_value=ErrorResponse())
+
+        with self.assertRaises(ModbusCommunicationException):
+            await client.poll()
+
+        self.assertFalse(client.device.available)
+
     async def test_turn_on_when_write_fails_raises_exception(self):
         client = S21Client(host=self.server.host, port=self.server.port)
         client.client.connect = AsyncMock(return_value=True)
@@ -115,6 +174,11 @@ class TestClient(unittest.IsolatedAsyncioTestCase):
         self.server.data_bank.set_input_registers(IR_ALARM, [2])
         self.server.data_bank.set_input_registers(IR_CurTEMP_SuAirIn, [108])
         self.server.data_bank.set_input_registers(IR_CurTEMP_SuAirOut, [192])
+        self.server.data_bank.set_input_registers(IR_CurTEMP_ExAirIn, [236])
+        self.server.data_bank.set_input_registers(IR_CurTEMP_ExAirOut, [227])
+        self.server.data_bank.set_input_registers(IR_CurSuPRESS, [45])
+        self.server.data_bank.set_input_registers(IR_CurExPRESS, [50])
+        self.server.data_bank.set_input_registers(IR_CurFILTER_TIMER_DAYS, [69])
         self.server.data_bank.set_input_registers(
             IR_VerMAIN_FMW_start, [36, 2053, 2019]
         )
@@ -159,10 +223,76 @@ class TestClient(unittest.IsolatedAsyncioTestCase):
                 filter_state=3,
                 alarm_state=2,
                 supply_fan_speed=10,
-                extract_fan_speed=20
+                extract_fan_speed=20,
+                current_extract_temperature=23.6,
+                current_exhaust_temperature=22.7,
+                supply_pressure=45,
+                extract_pressure=50,
+                filter_countdown_days=69,
+                bypass_type=BypassType.NOT_AVAILABLE,
+                bypass_mode=None,
+                bypass_position=None,
+                manual_bypass_position=None,
             ),
         )
 
+    async def test_original_climate_device_constructor_remains_supported(self):
+        client = S21Client(host=self.server.host, port=self.server.port)
+        device = await client.poll()
+        # The public model originally contained these first 28 fields.
+        original_values = device[:28]
+        positional = ClimateDevice(*original_values)
+        keyword = ClimateDevice(**dict(zip(device._fields[:28], original_values)))
+        self.assertEqual(positional, keyword)
+        self.assertEqual(positional[:28], original_values)
+        self.assertIsNone(positional.current_extract_temperature)
+        self.assertIsNone(positional.current_exhaust_temperature)
+        self.assertIsNone(positional.supply_pressure)
+        self.assertIsNone(positional.extract_pressure)
+        self.assertIsNone(positional.filter_countdown_days)
+        self.assertEqual(positional.bypass_type, BypassType.NOT_AVAILABLE)
+        self.assertIsNone(positional.bypass_mode)
+        self.assertIsNone(positional.bypass_position)
+        self.assertIsNone(positional.manual_bypass_position)
+
+    async def test_temperature_faults_are_unknown_and_recover(self):
+        client = S21Client(host=self.server.host, port=self.server.port)
+        sensors = (
+            (IR_CurTEMP_SuAirIn, "current_intake_temperature"),
+            (IR_CurTEMP_SuAirOut, "current_temperature"),
+            (IR_CurTEMP_ExAirIn, "current_extract_temperature"),
+            (IR_CurTEMP_ExAirOut, "current_exhaust_temperature"),
+        )
+        for address, field in sensors:
+            for raw in (0x8000, 0x7FFF):
+                with self.subTest(address=address, raw=raw):
+                    self.server.data_bank.reset()
+                    self.server.data_bank.set_holding_registers(HR_OPERATION_MODE, [3])
+                    self.server.data_bank.set_input_registers(address, [raw])
+                    device = await client.poll()
+                    self.assertIsNone(getattr(device, field))
+                    self.assertTrue(device.available)
+                    if address in (IR_CurTEMP_SuAirIn, IR_CurTEMP_SuAirOut):
+                        self.assertIsNone(device.hvac_action)
+                    else:
+                        self.assertEqual(device.hvac_action, HVACAction.IDLE)
+                    self.server.data_bank.set_input_registers(address, [100])
+                    self.assertEqual(getattr(await client.poll(), field), 10.0)
+
+    async def test_extract_and_exhaust_temperatures_support_negative_and_zero(self):
+        self.server.data_bank.set_input_registers(IR_CurTEMP_ExAirIn, [0xFFF6])
+        self.server.data_bank.set_input_registers(IR_CurTEMP_ExAirOut, [0])
+        device = await S21Client(self.server.host, self.server.port).poll()
+        self.assertEqual(device.current_extract_temperature, -1.0)
+        self.assertEqual(device.current_exhaust_temperature, 0.0)
+
+    async def test_missing_temperatures_preserve_off_and_fan_actions(self):
+        self.server.data_bank.set_input_registers(IR_CurTEMP_SuAirOut, [0x8000])
+        client = S21Client(self.server.host, self.server.port)
+        self.assertEqual((await client.poll()).hvac_action, HVACAction.FAN)
+        self.server.data_bank.set_coils(CL_POWER, [False])
+        self.assertEqual((await client.poll()).hvac_action, HVACAction.OFF)
+
     async def test_poll_when_device_is_off(self):
         self.server.data_bank.set_coils(CL_POWER, [False])
 
@@ -492,13 +622,130 @@ class TestClient(unittest.IsolatedAsyncioTestCase):
 
         self.assertEqual(self.server.data_bank.get_coils(CL_BoostSWITCH_CTRL, 1), [False])
 
+    async def test_poll_reads_bypass_state(self):
+        self.server.data_bank.set_holding_registers(HR_BPS_ROTOR_TYPE, [2])
+        self.server.data_bank.set_holding_registers(HR_BPS_ROTOR_MODE, [2])
+        self.server.data_bank.set_holding_registers(HR_SetBpsRotorMANUAL, [75])
+        self.server.data_bank.set_input_registers(IR_StatusBpsRotor, [42])
+
+        client = S21Client(host=self.server.host, port=self.server.port)
+        device = await client.poll()
+
+        self.assertEqual(device.bypass_type, BypassType.BYPASS_ANALOGUE)
+        self.assertEqual(device.bypass_mode, BypassMode.AUTO)
+        self.assertEqual(device.manual_bypass_position, 75)
+        self.assertEqual(device.bypass_position, 42)
+
+    async def test_poll_supports_older_input_register_map(self):
+        bank = DataBank(coils_size=25, h_regs_size=182, i_regs_size=51)
+        bank.set_input_registers(IR_DeviceTYPE, [1])
+        bank.set_input_registers(IR_CurTEMP_SuAirOut, [215])
+        bank.set_holding_registers(HR_BPS_ROTOR_TYPE, [2])
+        bank.set_holding_registers(HR_BPS_ROTOR_MODE, [2])
+        server = ModbusServer(host="localhost", port=5503, no_block=True, data_bank=bank)
+        server.start()
+        self.addCleanup(server.stop)
+        client = S21Client(server.host, server.port)
+        for _ in range(2):
+            device = await client.poll()
+            self.assertTrue(device.available)
+            self.assertEqual(device.current_temperature, 21.5)
+            self.assertEqual(device.bypass_mode, BypassMode.AUTO)
+            self.assertIsNone(device.bypass_position)
+
+    async def test_no_bypass_skips_optional_position_read(self):
+        client = S21Client(self.server.host, self.server.port)
+        client.client.read_input_registers = Mock(
+            wraps=client.client.read_input_registers
+        )
+        device = await client.poll()
+        self.assertEqual(device.bypass_type, BypassType.NOT_AVAILABLE)
+        self.assertIsNone(device.bypass_position)
+        self.assertIsNone(device.bypass_mode)
+        self.assertIsNone(device.manual_bypass_position)
+        self.assertEqual(client.client.read_input_registers.call_count, 2)
+
+    async def test_optional_position_does_not_hide_communication_errors(self):
+        self.server.data_bank.set_holding_registers(HR_BPS_ROTOR_TYPE, [2])
+        for response in (
+            None,
+            ErrorResponse(),
+            ExceptionResponse(4, 4),
+            SuccessResponse(registers=[]),
+            TimeoutError("Timed out"),
+        ):
+            with self.subTest(response=response):
+                client = S21Client(self.server.host, self.server.port)
+                await client.poll()
+                read_input_registers = client.client.read_input_registers
+
+                async def read(address, *, count):
+                    if address == IR_StatusBpsRotor:
+                        if isinstance(response, Exception):
+                            raise response
+                        return response
+                    return await read_input_registers(address, count=count)
+
+                client.client.read_input_registers = AsyncMock(side_effect=read)
+                expected = (
+                    TimeoutError
+                    if isinstance(response, TimeoutError)
+                    else ModbusCommunicationException
+                )
+                with self.assertRaises(expected):
+                    await client.poll()
+                self.assertFalse(client.device.available)
+                self.assertFalse(client.client.connected)
+
+    async def test_set_bypass_mode(self):
+        self.server.data_bank.set_holding_registers(HR_BPS_ROTOR_MODE, [2])
+
+        client = S21Client(host=self.server.host, port=self.server.port)
+        await client.set_bypass_mode(BypassMode.CLOSED)
+
+        self.assertEqual(
+            self.server.data_bank.get_holding_registers(HR_BPS_ROTOR_MODE, 1), [0]
+        )
+
+    async def test_set_bypass_mode_when_value_is_invalid_raises_exception(self):
+        client = S21Client(host=self.server.host, port=self.server.port)
+        client.client.connect = AsyncMock(return_value=True)
+
+        for invalid_mode in (-1, 3):
+            with self.subTest(mode=invalid_mode):
+                with self.assertRaises(ValueError):
+                    await client.set_bypass_mode(invalid_mode)
+
+        client.client.connect.assert_not_called()
+
+    async def test_set_bypass_position(self):
+        self.server.data_bank.set_holding_registers(HR_SetBpsRotorMANUAL, [0])
+
+        client = S21Client(host=self.server.host, port=self.server.port)
+        await client.set_bypass_position(60)
+
+        self.assertEqual(
+            self.server.data_bank.get_holding_registers(HR_SetBpsRotorMANUAL, 1), [60]
+        )
+
+    async def test_set_bypass_position_when_value_is_invalid_raises_exception(self):
+        client = S21Client(host=self.server.host, port=self.server.port)
+        client.client.connect = AsyncMock(return_value=True)
+
+        for invalid_position in (-1, 101):
+            with self.subTest(position=invalid_position):
+                with self.assertRaises(ValueError):
+                    await client.set_bypass_position(invalid_position)
+
+        client.client.connect.assert_not_called()
+
 
 class TestDataBank(DataBank):
     __test__ = False
 
     def __init__(self):
         super().__init__(
-            coils_size=25, d_inputs_size=72, h_regs_size=182, i_regs_size=51
+            coils_size=25, d_inputs_size=72, h_regs_size=182, i_regs_size=54
         )
         self.reset()
 

pybls21-4.2.2/PKG-INFO

@@ -1,43 +0,0 @@
-Metadata-Version: 2.4
-Name: pybls21
-Version: 4.2.2
-Summary: An api allowing control of AC state (temperature, on/off, speed) of an Blauberg S21 device locally over TCP
-Home-page: https://github.com/jvitkauskas/pybls21
-Author: Julius Vitkauskas
-Author-email: zadintuvas@gmail.com
-Classifier: Programming Language :: Python :: 3
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: OS Independent
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: pymodbus<4.0,>=3.11.2
-Dynamic: author
-Dynamic: author-email
-Dynamic: classifier
-Dynamic: description
-Dynamic: description-content-type
-Dynamic: home-page
-Dynamic: license-file
-Dynamic: requires-dist
-Dynamic: requires-python
-Dynamic: summary
-
-# Blauberg S21 Asynchronous Python API
-An api allowing control of AC state (temperature, on/off, speed) of an Blauberg S21 device locally over TCP.
-
-## Usage
-To initialize:
-`client = S21Client("192.168.0.125")`
-
-To load:
-`await client.poll()`
-
-The following functions are available:
-`turn_on()`
-`turn_off()`
-`set_hvac_mode(hvac_mode: HVACMode)`
-`set_fan_mode(mode: int)`
-`set_manual_fan_speed_percent(speed_percent: int)`
-`set_temperature(temp_celsius: int)`
-`reset_filter_change_timer()`

pybls21-4.2.2/README.md

@@ -1,18 +0,0 @@
-# Blauberg S21 Asynchronous Python API
-An api allowing control of AC state (temperature, on/off, speed) of an Blauberg S21 device locally over TCP.
-
-## Usage
-To initialize:
-`client = S21Client("192.168.0.125")`
-
-To load:
-`await client.poll()`
-
-The following functions are available:
-`turn_on()`
-`turn_off()`
-`set_hvac_mode(hvac_mode: HVACMode)`
-`set_fan_mode(mode: int)`
-`set_manual_fan_speed_percent(speed_percent: int)`
-`set_temperature(temp_celsius: int)`
-`reset_filter_change_timer()`

pybls21-4.2.2/pybls21/constants.py

@@ -1,25 +0,0 @@
-# Coils
-CL_POWER = 0
-CL_Boost_MODE = 3
-CL_BoostSWITCH_CTRL = 13
-CL_RESET_FILTER_TIMER = 17
-CL_RESET_ALARM = 18
-
-# Holding registers
-HR_MaxSPEED_MODE = 1
-HR_SPEED_MODE = 2
-HR_ManualSPEED = 17
-HR_OPERATION_MODE = 43
-HR_SetTEMP = 44
-
-# Input registers
-IR_CurTEMP_SuAirIn = 1
-IR_CurTEMP_SuAirOut = 2
-IR_CurRH_Int = 10
-IR_SuRPM = 23
-IR_ExRPM = 24
-IR_StateFILTER = 31
-IR_VerMAIN_FMW_start = 34
-IR_VerMAIN_FMW_end = 36
-IR_DeviceTYPE = 37
-IR_ALARM = 38

pybls21-4.2.2/pybls21/models.py

@@ -1,56 +0,0 @@
-from enum import Enum
-from typing import List, NamedTuple, Optional
-
-TEMP_CELSIUS: str = "°C"
-
-
-class ClimateEntityFeature(int, Enum):
-    TARGET_TEMPERATURE = 1
-    FAN_MODE = 8
-
-
-class HVACMode(str, Enum):
-    OFF = "off"
-    HEAT = "heat"
-    COOL = "cool"
-    AUTO = "auto"
-    FAN_ONLY = "fan_only"
-
-
-class HVACAction(str, Enum):
-    COOLING = "cooling"
-    FAN = "fan"
-    HEATING = "heating"
-    IDLE = "idle"
-    OFF = "off"
-
-
-class ClimateDevice(NamedTuple):
-    available: bool
-    name: str
-    unique_id: str
-    temperature_unit: str
-    precision: float
-    current_temperature: float
-    target_temperature: float
-    target_temperature_step: float
-    max_temp: float
-    min_temp: float
-    current_humidity: Optional[float]
-    hvac_mode: str
-    hvac_action: str
-    hvac_modes: List[str]
-    fan_mode: Optional[int]
-    fan_modes: Optional[List[int]]
-    supported_features: int
-    manufacturer: str
-    model: Optional[str]
-    sw_version: Optional[str]
-    is_boosting: bool
-    current_intake_temperature: float
-    manual_fan_speed_percent: int
-    max_fan_level: int
-    filter_state: int
-    alarm_state: int
-    supply_fan_speed: int
-    extract_fan_speed: int

pybls21-4.2.2/pybls21.egg-info/PKG-INFO

@@ -1,43 +0,0 @@
-Metadata-Version: 2.4
-Name: pybls21
-Version: 4.2.2
-Summary: An api allowing control of AC state (temperature, on/off, speed) of an Blauberg S21 device locally over TCP
-Home-page: https://github.com/jvitkauskas/pybls21
-Author: Julius Vitkauskas
-Author-email: zadintuvas@gmail.com
-Classifier: Programming Language :: Python :: 3
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: OS Independent
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: pymodbus<4.0,>=3.11.2
-Dynamic: author
-Dynamic: author-email
-Dynamic: classifier
-Dynamic: description
-Dynamic: description-content-type
-Dynamic: home-page
-Dynamic: license-file
-Dynamic: requires-dist
-Dynamic: requires-python
-Dynamic: summary
-
-# Blauberg S21 Asynchronous Python API
-An api allowing control of AC state (temperature, on/off, speed) of an Blauberg S21 device locally over TCP.
-
-## Usage
-To initialize:
-`client = S21Client("192.168.0.125")`
-
-To load:
-`await client.poll()`
-
-The following functions are available:
-`turn_on()`
-`turn_off()`
-`set_hvac_mode(hvac_mode: HVACMode)`
-`set_fan_mode(mode: int)`
-`set_manual_fan_speed_percent(speed_percent: int)`
-`set_temperature(temp_celsius: int)`
-`reset_filter_change_timer()`

pybls21-4.2.2/pybls21.egg-info/requires.txt

@@ -1 +0,0 @@
-pymodbus<4.0,>=3.11.2