pybls21 4.4.0__tar.gz → 5.1.0__tar.gz

pybls21-5.1.0/MANIFEST.in

@@ -0,0 +1 @@
+include MIGRATION.md

pybls21-5.1.0/MIGRATION.md

@@ -0,0 +1,132 @@
+# Migrating from 4.4 to 5.0
+
+Version 5 keeps the async control methods and Modbus mappings, but changes the
+state model, error contract, and packaging. Update the Home Assistant component
+before changing its pinned dependency to `pybls21==5.0.0`.
+
+## Python requirement
+
+Version 5 requires Python 3.14.2 or newer, matching Home Assistant 2026.9.4.
+Python 3.10–3.13 and Python 3.14.0–3.14.1 are no longer supported. Update the
+runtime before upgrading; older Home Assistant installations may need an update.
+
+## Device snapshots
+
+`ClimateDevice` is now a frozen, keyword-only dataclass with slots. Attribute
+access is unchanged. Tuple indexing, unpacking, `_fields`, `_asdict()`, and
+`_replace()` are removed. Use the standard dataclass helpers when needed:
+
+```python
+from dataclasses import asdict, replace
+
+values = asdict(snapshot)
+updated = replace(snapshot, available=False)
+```
+
+`asdict()` is a Python mapping, not a JSON serialization contract: enum and
+`timedelta` values may need conversion for diagnostics or storage.
+
+`hvac_modes`, `fan_modes`, and `alarm_codes` are tuples. `alarm_codes` is an empty
+tuple when no alarms are reported. `hvac_mode` and `hvac_action` are annotated
+with their enum types. Both enums now use `StrEnum`: string conversion and
+formatting return the value, so `str(HVACMode.HEAT)` and `f"{HVACMode.HEAT}"`
+produce `"heat"` instead of `"HVACMode.HEAT"`. String equality and value-based
+construction remain supported. `BypassMode` and `BypassType` are now `IntEnum`
+classes. Snapshot fields include Python 3.14 `field(doc=...)` documentation
+for their meaning, units, and unavailable values.
+
+`timer_countdown` is a `datetime.timedelta` rather than an `HH:MM:SS` string.
+Use `snapshot.timer_countdown.total_seconds()` for a Home Assistant duration
+sensor; handle `None` for an unknown value. A zero duration is a valid value.
+
+## Home Assistant identity and features
+
+The IP-derived `unique_id` is removed. The protocol mapping implemented by this
+library does not expose a stable hardware identifier. The integration must own
+identity: use a device-provided identifier if available, or a config-entry ID
+as a last resort. Do not rebuild entity IDs from the current host address.
+
+For existing installations, explicitly migrate the entity/device registry
+identifiers while preserving the registered entities and their user settings;
+simply assigning new identifiers can create duplicates. Inspect the component's
+existing identifier format before implementing that migration.
+
+`ClimateEntityFeature` and `snapshot.supported_features` are removed. Set the
+feature flags in the component using Home Assistant's own `ClimateEntityFeature`.
+Other descriptive fields, including manufacturer, model, temperature unit, and
+supported modes, remain available.
+
+## Optional percentage readings
+
+`bypass_position`, `supply_fan_speed_percent`, and `extract_fan_speed_percent`
+now report `None` for values outside 0–100, including the `65535` observed on
+physical hardware. Valid readings remain usable even if another optional
+percentage is unknown; the device is still available after a successful poll.
+
+## Errors and inputs
+
+Catch `S21Error` for all library device/communication failures, or its subclasses:
+
+- `UnsupportedDeviceException`: the device type is not S21.
+- `ModbusCommunicationException`: connection failure, timeout, pymodbus failure,
+  error response, or invalid response data.
+
+`OSError`, `TimeoutError`, and pymodbus transport exceptions are now wrapped in
+`ModbusCommunicationException`, with the original error in `__cause__`.
+Unexpected programming errors are not wrapped. Task cancellation propagates as
+`asyncio.CancelledError`; cleanup still runs and cached state becomes unavailable.
+
+Invalid control arguments raise `ValueError` before connecting. An unknown HVAC
+mode no longer silently selects AUTO. Booleans are rejected for numeric controls.
+An unknown operating mode in a powered-on device response is a communication
+error rather than an assumed AUTO state.
+
+## Client ownership
+
+`client.device` remains readable but is now a read-only property. Before the
+first successful poll it is `None`. Successful writes do not optimistically
+change the snapshot: poll to read confirmed state. A failed operation replaces
+the cached snapshot with an unavailable one; previously returned snapshots remain
+unchanged.
+
+The underlying pymodbus client and lock are private implementation details;
+`client.client` and `client.lock` are removed. All public control methods are
+still async. No persistent connection or explicit public `close()` is needed:
+each operation connects, performs its work, and closes under one shared lock.
+
+Optional keyword arguments `timeout` (seconds per Modbus request) and `retries`
+(request retry count) are now available. Defaults remain 3 seconds and 3 retries.
+They are not a total poll deadline. Callers can bound an entire operation with
+`asyncio.timeout()`, including time waiting for the client lock:
+
+```python
+try:
+    async with asyncio.timeout(10):
+        snapshot = await client.poll()
+except TimeoutError:
+    # The caller's total deadline expired; handle outside the timeout block.
+    ...
+except S21Error:
+    # A device/transport failure occurred, including per-request timeouts.
+    ...
+```
+
+An expired outer deadline cancels the operation and raises `TimeoutError` to
+the caller. An operation that acquired the lock closes its connection and marks
+cached state unavailable; one cancelled while waiting for the lock has not
+started I/O and leaves the active operation and cached state untouched.
+
+## Development and releases
+
+Metadata now lives in `pyproject.toml`; `setup.py` is removed. Install with
+`pip install -e '.[dev]'` or `pip install -r requirements.txt` (the latter pins
+pymodbus to the minimum supported version).
+
+Pushes and pull requests run validation only. To publish, merge the version bump
+and changes, then publish a GitHub release with the matching tag, such as
+`v5.0.0`. A bare tag push or a draft release does not publish to PyPI. The release
+workflow reruns tests, typing, lint, coverage, and packaging checks, verifies the
+tag against the built package version, and uploads those same validated artifacts
+using the existing `pypi` environment and Trusted Publisher configuration.
+Published prereleases also trigger publishing; use a matching PEP 440 prerelease
+version/tag (for example `5.1.0rc1` / `v5.1.0rc1`).

pybls21-5.1.0/PKG-INFO

@@ -0,0 +1,278 @@
+Metadata-Version: 2.4
+Name: pybls21
+Version: 5.1.0
+Summary: Async Modbus TCP client for Blauberg S21 ventilation devices
+Author-email: Julius Vitkauskas <zadintuvas@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/jvitkauskas/pybls21
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Typing :: Typed
+Requires-Python: >=3.14.2
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: THIRD_PARTY_NOTICES
+Requires-Dist: pymodbus<4.0,>=3.13.1
+Provides-Extra: dev
+Requires-Dist: pyModbusTCP==0.3.0; extra == "dev"
+Requires-Dist: coverage[toml]>=7.6; extra == "dev"
+Requires-Dist: mypy>=1.19; extra == "dev"
+Requires-Dist: ruff>=0.14; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=6; extra == "dev"
+Dynamic: license-file
+
+# 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
+
+Requires Python 3.14.2+ and `pymodbus>=3.13.1,<4.0`.
+
+```python
+import asyncio
+
+from pybls21 import HVACMode, S21Client, S21Error
+
+
+async def main():
+    client = S21Client("192.168.0.125", timeout=3.0, retries=3)
+    try:
+        snapshot = await client.poll()
+        print(snapshot.current_temperature)
+        await client.set_hvac_mode(HVACMode.AUTO)
+        await client.set_temperature(21)
+    except S21Error as error:
+        print(f"Device unavailable: {error}")
+
+
+asyncio.run(main())
+```
+
+Each operation opens and closes its connection. Calls on the same client are
+serialized because the unit supports one connection. Reuse one client per unit.
+`timeout` applies per Modbus request, not to the full poll. Writes do not update
+cached readings; call `poll()` to get confirmed state.
+
+To limit the whole poll, including waiting for the client lock, use an outer
+`asyncio.timeout()` context. Handle its `TimeoutError` outside the block:
+
+```python
+try:
+    async with asyncio.timeout(10):
+        snapshot = await client.poll()
+except TimeoutError:
+    print("The total poll deadline expired")
+except S21Error as error:
+    print(f"Device communication failed: {error}")
+```
+
+The outer deadline also limits time spent on retries. A per-request timeout is
+reported as `ModbusCommunicationException` (a subclass of `S21Error`); expiry of
+the outer deadline raises `TimeoutError`. Cancellation cleans up an operation
+that has started I/O. Cancelling while waiting for the lock leaves the operation
+already using the connection unaffected.
+
+Upgrading from v4? See [the migration guide](MIGRATION.md) for the changed model,
+identity, exceptions, and Home Assistant component migration.
+
+| Async method | Input / behavior |
+| --- | --- |
+| `poll()` | Return an immutable `ClimateDevice` snapshot |
+| `turn_on()`, `turn_off()` | Enable/disable the unit |
+| `set_hvac_mode(mode)` | `HVACMode` or its string value; invalid values raise `ValueError` |
+| `set_fan_mode(mode)` | Level 1–5, or 255 for manual; use levels supported by the device |
+| `set_manual_fan_speed_percent(value)` | Integer 0–100; does not select manual mode |
+| `set_temperature(value)` | Integer 15–30 °C |
+| `reset_filter_change_timer()` | Restart the configured filter interval |
+| `reset_alarm()` | Request alarm reset |
+| `boost_on()`, `boost_off()` | Enable/disable boost |
+| `set_bypass_mode(mode)` | `BypassMode` or its integer value |
+| `set_bypass_position(value)` | Integer 0–100; does not change bypass mode |
+| `set_timer_on()`, `set_timer_off()` | Enable/disable the configured timer |
+| `set_scheduler_mode_on()`, `set_scheduler_mode_off()` | Enable/disable the configured weekly schedule |
+
+Booleans are not accepted as numeric control values. Bad arguments raise
+`ValueError` before network I/O. `S21Error` is the base for
+`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
+(`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.
+If the device rejects this address with Illegal Data 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.
+
+Snapshots are frozen dataclasses; access readings by attribute. Collections of
+modes and alarm codes are immutable tuples. The component owns entity identity
+and Home Assistant feature flags; the library does not generate a unique ID
+from the network address.
+
+## Timer, scheduler, and telemetry
+
+`set_timer_on()` / `set_timer_off()` enable or disable the device's existing
+main timer. `set_scheduler_mode_on()` / `set_scheduler_mode_off()` enable or
+disable its existing weekly schedule. Configure the timer duration and weekly
+schedule on the device; these methods only toggle their activation.
+
+The following fields are available after `await client.poll()`:
+
+| Field | Meaning |
+| --- | --- |
+| `is_timer` | Whether the main timer is active |
+| `timer_countdown` | Remaining main timer time as `datetime.timedelta` |
+| `is_schedule_mode` | Whether the weekly schedule is enabled |
+| `fan_level_schedule_mode` | Current scheduled fan level; 0 means standby |
+| `fan_level_timer_mode` | Configured timer fan level; 0 means standby |
+| `alarm_codes` | Active numeric alarm codes (0–52); empty tuple when no alarm or warning is reported |
+| `supply_airflow`, `extract_airflow` | Airflow in m³/h |
+| `operating_time_minutes` | Total device operating time in minutes |
+| `filter_countdown_hours`, `filter_countdown_minutes` | Remaining hours and minutes in addition to `filter_countdown_days` |
+| `supply_fan_speed_percent`, `extract_fan_speed_percent` | Actual fan performance in percent, or `None` when unavailable |
+
+`fan_mode` remains the configured normal fan level and `set_fan_mode(mode)`
+still takes one argument. Timer and schedule levels are separate readings, not
+an inferred effective fan level during overrides. The existing
+`supply_fan_speed` and `extract_fan_speed` fields continue to report **RPM**.
+
+The timer, schedule, airflow, operating time, and filter readings use the blocks
+already fetched by polling. Detailed alarm codes add a discrete-input read only
+when an alarm or warning is active. Fan percentages add a separate read of
+IR52–53; an Illegal Data Address response leaves both percentages unknown without
+interrupting other readings. Successful reads containing percentages outside
+0–100 (including `65535` / `0xFFFF`) are also reported as `None`, individually
+for bypass position and each fan percentage. Timeouts and other errors still propagate and
+invalidate cached availability.
+
+There is no verified firmware-version cutoff for these optional readings. The
+bundled protocol table ends at IR50; a physical device reporting firmware
+`0.36 (2019-05-08)` accepted IR51–53 reads but returned `0xFFFF` for all three.
+It also returned `0xFFFF` at IR54–55. Those replies are not usable measurements
+and do not establish that the corresponding features are implemented. Its full
+DI0–71 range, including the 53 alarm bits, was readable.
+
+These additions are adapted from [marni-xyz's fork](https://github.com/marni-xyz/pybls21),
+including its operating-time, airflow, and fan-performance work attributed to
+[birdie1](https://github.com/birdie1).
+
+The copyright and MIT terms for these ported portions are retained in
+[THIRD_PARTY_NOTICES](THIRD_PARTY_NOTICES), included in both source and wheel
+distributions.
+
+## Interpretation limits
+
+`current_temperature` is the supply outlet temperature, not necessarily room
+temperature. `hvac_action` is inferred: HEAT and COOL report their configured
+action; AUTO compares supply temperatures before/after heating. It is not a
+measurement of heater/compressor activity. Missing temperature sensors produce
+`None`; zero remains a valid temperature. Optional unsupported registers also
+produce `None`, while communication failures fail the poll.
+
+## Development
+
+```sh
+python -m pip install -r requirements.txt
+ruff check .
+ruff format --check .
+mypy
+python -m coverage run -m unittest -v
+python -m coverage report
+python -m build
+python -m twine check dist/*
+```
+
+CI tests Python 3.14.2 with minimum pymodbus and the latest Python 3.14 patch
+with the newest allowed pymodbus, and requires at least 95% combined
+statement/branch coverage. The Python minimum matches
+[Home Assistant 2026.9.4](https://github.com/home-assistant/core/blob/2026.9.4/pyproject.toml#L22). The package ships
+`py.typed` for downstream type checking.
+
+## Releasing
+
+Merges to `main` validate changes without publishing. Set the package version in
+`pyproject.toml`, merge the change, and publish a GitHub release with its matching
+`vVERSION` tag. The release workflow repeats validation, checks the tag/version
+match, and publishes the validated wheel and source distribution to PyPI.
+See [the release details](MIGRATION.md#development-and-releases).

pybls21-5.1.0/README.md

@@ -0,0 +1,254 @@
+# 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
+
+Requires Python 3.14.2+ and `pymodbus>=3.13.1,<4.0`.
+
+```python
+import asyncio
+
+from pybls21 import HVACMode, S21Client, S21Error
+
+
+async def main():
+    client = S21Client("192.168.0.125", timeout=3.0, retries=3)
+    try:
+        snapshot = await client.poll()
+        print(snapshot.current_temperature)
+        await client.set_hvac_mode(HVACMode.AUTO)
+        await client.set_temperature(21)
+    except S21Error as error:
+        print(f"Device unavailable: {error}")
+
+
+asyncio.run(main())
+```
+
+Each operation opens and closes its connection. Calls on the same client are
+serialized because the unit supports one connection. Reuse one client per unit.
+`timeout` applies per Modbus request, not to the full poll. Writes do not update
+cached readings; call `poll()` to get confirmed state.
+
+To limit the whole poll, including waiting for the client lock, use an outer
+`asyncio.timeout()` context. Handle its `TimeoutError` outside the block:
+
+```python
+try:
+    async with asyncio.timeout(10):
+        snapshot = await client.poll()
+except TimeoutError:
+    print("The total poll deadline expired")
+except S21Error as error:
+    print(f"Device communication failed: {error}")
+```
+
+The outer deadline also limits time spent on retries. A per-request timeout is
+reported as `ModbusCommunicationException` (a subclass of `S21Error`); expiry of
+the outer deadline raises `TimeoutError`. Cancellation cleans up an operation
+that has started I/O. Cancelling while waiting for the lock leaves the operation
+already using the connection unaffected.
+
+Upgrading from v4? See [the migration guide](MIGRATION.md) for the changed model,
+identity, exceptions, and Home Assistant component migration.
+
+| Async method | Input / behavior |
+| --- | --- |
+| `poll()` | Return an immutable `ClimateDevice` snapshot |
+| `turn_on()`, `turn_off()` | Enable/disable the unit |
+| `set_hvac_mode(mode)` | `HVACMode` or its string value; invalid values raise `ValueError` |
+| `set_fan_mode(mode)` | Level 1–5, or 255 for manual; use levels supported by the device |
+| `set_manual_fan_speed_percent(value)` | Integer 0–100; does not select manual mode |
+| `set_temperature(value)` | Integer 15–30 °C |
+| `reset_filter_change_timer()` | Restart the configured filter interval |
+| `reset_alarm()` | Request alarm reset |
+| `boost_on()`, `boost_off()` | Enable/disable boost |
+| `set_bypass_mode(mode)` | `BypassMode` or its integer value |
+| `set_bypass_position(value)` | Integer 0–100; does not change bypass mode |
+| `set_timer_on()`, `set_timer_off()` | Enable/disable the configured timer |
+| `set_scheduler_mode_on()`, `set_scheduler_mode_off()` | Enable/disable the configured weekly schedule |
+
+Booleans are not accepted as numeric control values. Bad arguments raise
+`ValueError` before network I/O. `S21Error` is the base for
+`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
+(`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.
+If the device rejects this address with Illegal Data 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.
+
+Snapshots are frozen dataclasses; access readings by attribute. Collections of
+modes and alarm codes are immutable tuples. The component owns entity identity
+and Home Assistant feature flags; the library does not generate a unique ID
+from the network address.
+
+## Timer, scheduler, and telemetry
+
+`set_timer_on()` / `set_timer_off()` enable or disable the device's existing
+main timer. `set_scheduler_mode_on()` / `set_scheduler_mode_off()` enable or
+disable its existing weekly schedule. Configure the timer duration and weekly
+schedule on the device; these methods only toggle their activation.
+
+The following fields are available after `await client.poll()`:
+
+| Field | Meaning |
+| --- | --- |
+| `is_timer` | Whether the main timer is active |
+| `timer_countdown` | Remaining main timer time as `datetime.timedelta` |
+| `is_schedule_mode` | Whether the weekly schedule is enabled |
+| `fan_level_schedule_mode` | Current scheduled fan level; 0 means standby |
+| `fan_level_timer_mode` | Configured timer fan level; 0 means standby |
+| `alarm_codes` | Active numeric alarm codes (0–52); empty tuple when no alarm or warning is reported |
+| `supply_airflow`, `extract_airflow` | Airflow in m³/h |
+| `operating_time_minutes` | Total device operating time in minutes |
+| `filter_countdown_hours`, `filter_countdown_minutes` | Remaining hours and minutes in addition to `filter_countdown_days` |
+| `supply_fan_speed_percent`, `extract_fan_speed_percent` | Actual fan performance in percent, or `None` when unavailable |
+
+`fan_mode` remains the configured normal fan level and `set_fan_mode(mode)`
+still takes one argument. Timer and schedule levels are separate readings, not
+an inferred effective fan level during overrides. The existing
+`supply_fan_speed` and `extract_fan_speed` fields continue to report **RPM**.
+
+The timer, schedule, airflow, operating time, and filter readings use the blocks
+already fetched by polling. Detailed alarm codes add a discrete-input read only
+when an alarm or warning is active. Fan percentages add a separate read of
+IR52–53; an Illegal Data Address response leaves both percentages unknown without
+interrupting other readings. Successful reads containing percentages outside
+0–100 (including `65535` / `0xFFFF`) are also reported as `None`, individually
+for bypass position and each fan percentage. Timeouts and other errors still propagate and
+invalidate cached availability.
+
+There is no verified firmware-version cutoff for these optional readings. The
+bundled protocol table ends at IR50; a physical device reporting firmware
+`0.36 (2019-05-08)` accepted IR51–53 reads but returned `0xFFFF` for all three.
+It also returned `0xFFFF` at IR54–55. Those replies are not usable measurements
+and do not establish that the corresponding features are implemented. Its full
+DI0–71 range, including the 53 alarm bits, was readable.
+
+These additions are adapted from [marni-xyz's fork](https://github.com/marni-xyz/pybls21),
+including its operating-time, airflow, and fan-performance work attributed to
+[birdie1](https://github.com/birdie1).
+
+The copyright and MIT terms for these ported portions are retained in
+[THIRD_PARTY_NOTICES](THIRD_PARTY_NOTICES), included in both source and wheel
+distributions.
+
+## Interpretation limits
+
+`current_temperature` is the supply outlet temperature, not necessarily room
+temperature. `hvac_action` is inferred: HEAT and COOL report their configured
+action; AUTO compares supply temperatures before/after heating. It is not a
+measurement of heater/compressor activity. Missing temperature sensors produce
+`None`; zero remains a valid temperature. Optional unsupported registers also
+produce `None`, while communication failures fail the poll.
+
+## Development
+
+```sh
+python -m pip install -r requirements.txt
+ruff check .
+ruff format --check .
+mypy
+python -m coverage run -m unittest -v
+python -m coverage report
+python -m build
+python -m twine check dist/*
+```
+
+CI tests Python 3.14.2 with minimum pymodbus and the latest Python 3.14 patch
+with the newest allowed pymodbus, and requires at least 95% combined
+statement/branch coverage. The Python minimum matches
+[Home Assistant 2026.9.4](https://github.com/home-assistant/core/blob/2026.9.4/pyproject.toml#L22). The package ships
+`py.typed` for downstream type checking.
+
+## Releasing
+
+Merges to `main` validate changes without publishing. Set the package version in
+`pyproject.toml`, merge the change, and publish a GitHub release with its matching
+`vVERSION` tag. The release workflow repeats validation, checks the tag/version
+match, and publishes the validated wheel and source distribution to PyPI.
+See [the release details](MIGRATION.md#development-and-releases).