pybls21 4.3.0__tar.gz → 5.0.0__tar.gz

pybls21-5.0.0/MANIFEST.in

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

pybls21-5.0.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.0.0/PKG-INFO

@@ -0,0 +1,232 @@
+Metadata-Version: 2.4
+Name: pybls21
+Version: 5.0.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` and `ModbusCommunicationException`; the latter
+includes transport errors and timeouts, retaining the original cause.
+
+## 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.0.0/README.md

@@ -0,0 +1,208 @@
+# 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` and `ModbusCommunicationException`; the latter
+includes transport errors and timeouts, retaining the original cause.
+
+## 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.0.0/THIRD_PARTY_NOTICES

@@ -0,0 +1,41 @@
+Third-party notices
+===================
+
+Ported S21 controls and telemetry
+--------------------------------
+
+This project includes code adapted from marni-xyz/pybls21 for timer and
+weekly-schedule activation, alarm details, timer and filter countdowns,
+airflow, operating time, and fan-performance readings. This notice applies
+to those incorporated portions and their adaptations.
+
+Source: https://github.com/marni-xyz/pybls21
+Revision: 4bbd1189811d7e96ec501a632aac7824e2ad907d
+
+The upstream fork attributes the operating-time, airflow, and fan-performance
+additions to birdie1. Contributor acknowledgements are also recorded in the
+README and Git commit history.
+
+The source project's copyright notice and MIT license follow:
+
+MIT License
+
+Copyright (c) 2026 marni-xyz / 2021 Julius Vitkauskas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pybls21-5.0.0/pybls21/__init__.py

@@ -0,0 +1,21 @@
+"""Public API for the asynchronous Blauberg S21 client."""
+
+from .client import S21Client
+from .exceptions import (
+    ModbusCommunicationException,
+    S21Error,
+    UnsupportedDeviceException,
+)
+from .models import BypassMode, BypassType, ClimateDevice, HVACAction, HVACMode
+
+__all__ = [
+    "S21Client",
+    "S21Error",
+    "ModbusCommunicationException",
+    "UnsupportedDeviceException",
+    "BypassMode",
+    "BypassType",
+    "ClimateDevice",
+    "HVACAction",
+    "HVACMode",
+]