weider-modbus 0.1.0__py3-none-any.whl

weider_modbus/__init__.py

@@ -0,0 +1,36 @@
+"""Async Python library for the Modbus TCP interface of Weider WT16 heat pumps."""
+
+from .components import DigitalInputs, Measurements, Settings
+from .const import (
+    HOT_WATER_TARGET_MAX,
+    HOT_WATER_TARGET_MIN,
+    MANUFACTURER,
+    MAX_PLAUSIBLE_TEMPERATURE,
+    MIN_PLAUSIBLE_TEMPERATURE,
+    MODEL,
+    ROOM_TARGET_MAX,
+    ROOM_TARGET_MIN,
+    TARGET_STEP,
+)
+from .device import WeiderWT16
+from .helpers import SgReadyMode, clean_error_text, plausible_temperature, sg_ready_mode
+
+__all__ = [
+    "HOT_WATER_TARGET_MAX",
+    "HOT_WATER_TARGET_MIN",
+    "MANUFACTURER",
+    "MAX_PLAUSIBLE_TEMPERATURE",
+    "MIN_PLAUSIBLE_TEMPERATURE",
+    "MODEL",
+    "ROOM_TARGET_MAX",
+    "ROOM_TARGET_MIN",
+    "TARGET_STEP",
+    "DigitalInputs",
+    "Measurements",
+    "Settings",
+    "SgReadyMode",
+    "WeiderWT16",
+    "clean_error_text",
+    "plausible_temperature",
+    "sg_ready_mode",
+]

weider_modbus/components.py

@@ -0,0 +1,246 @@
+"""Typed Modbus components of the Weider WT16."""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Awaitable, Callable
+from typing import ClassVar, Final
+
+from modbus_connection.exceptions import IllegalDataAddressError
+from modbus_connection.model import (
+    Component,
+    NumberField,
+    discrete_input,
+    gauge,
+    integer,
+    string,
+    uint32,
+)
+
+from .const import (
+    HOT_WATER_TARGET_MAX,
+    HOT_WATER_TARGET_MIN,
+    ROOM_TARGET_MAX,
+    ROOM_TARGET_MIN,
+)
+
+_LOGGER = logging.getLogger(__name__)
+
+
+def _temperature(address: int) -> NumberField[float]:
+    """Return the signed, 0.1-scaled WT16 temperature format.
+
+    Outdoor, source and refrigerant temperatures go below 0 °C, which the
+    device sends as two's complement (65516 is -2.0 °C).
+    """
+    return gauge(address, 0.1, unit="°C")
+
+
+def _range_validator(minimum: float, maximum: float) -> Callable[[float], float]:
+    """Return a write validator that rejects values outside [minimum, maximum]."""
+
+    def validate(value: float) -> float:
+        if not minimum <= value <= maximum:
+            raise ValueError(
+                f"{value} is outside the allowed range {minimum}..{maximum}"
+            )
+        return value
+
+    return validate
+
+
+def _target_temperature(
+    address: int, minimum: float, maximum: float
+) -> NumberField[float]:
+    """Return a writable, unsigned, 0.1-scaled target temperature.
+
+    The device only accepts function code 16 for these registers.
+    """
+    return gauge(
+        address,
+        0.1,
+        signed=False,
+        unit="°C",
+        writable=_range_validator(minimum, maximum),
+        force_fc16=True,
+    )
+
+
+_READERS: Final = {
+    "input": "read_input_registers",
+    "holding": "read_holding_registers",
+    "discrete": "read_discrete_inputs",
+    "coil": "read_coils",
+}
+
+
+async def _rejected_fields(
+    component: Component, space: str, names: set[str]
+) -> set[str]:
+    """Read each field on its own and return those the device rejects."""
+    read = getattr(component.modbus_unit, _READERS[space])
+    rejected = set()
+    for name in sorted(names):
+        field = component.resolved_fields[name]
+        try:
+            await read(field.address, field.count)
+        except IllegalDataAddressError:
+            rejected.add(name)
+    return rejected
+
+
+async def _update_skipping_unsupported(
+    component: Component,
+    update: Callable[..., Awaitable[None]],
+    space: str,
+    optional: frozenset[str] | None,
+    *,
+    notify: bool,
+) -> None:
+    """Refresh a component, dropping optional fields the device rejects.
+
+    If the device rejects a block of several fields, each field is read on its
+    own to find the unsupported ones. Unsupported fields are skipped only if
+    they are all optional (``optional=None`` treats all fields as optional).
+    Anything else is a real error and propagates, so it is reported instead of
+    hidden.
+    """
+    while True:
+        try:
+            await update(notify=notify)
+            return
+        except IllegalDataAddressError as err:
+            block = err.block
+            if block is None or block.space != space:
+                raise
+            unsupported = {
+                name
+                for name, field in component.resolved_fields.items()
+                if field.address < block.address + block.count
+                and block.address < field.address + field.count
+            }
+            if len(unsupported) > 1:
+                unsupported = await _rejected_fields(component, space, unsupported)
+            if not unsupported or (
+                optional is not None and not unsupported <= optional
+            ):
+                raise
+            addresses = sorted(
+                component.resolved_fields[name].address for name in unsupported
+            )
+            component.restrict_fields(set(component.resolved_fields) - unsupported)
+            _LOGGER.info(
+                "Skipping unsupported %s %s at %s %s",
+                "field" if len(unsupported) == 1 else "fields",
+                ", ".join(sorted(unsupported)),
+                "address" if len(addresses) == 1 else "addresses",
+                ", ".join(map(str, addresses)),
+            )
+
+
+class Measurements(Component):
+    """Read-only WT16 input registers (function code 04)."""
+
+    register_space = "input"
+    # max_gap = 1 merges directly adjacent registers only, never across a gap.
+    max_gap = 1
+    max_span = 50
+
+    hot_water_temperature = _temperature(13)
+    flow_target_temperature = _temperature(14)
+    outdoor_temperature = _temperature(15)
+    buffer_temperature = _temperature(16)
+    mixer_temperature = _temperature(17)
+    reserve_temperature_1 = _temperature(18)
+    reserve_temperature_2 = _temperature(19)
+    reserve_temperature_3 = _temperature(20)
+    defrost_temperature = _temperature(21)
+    flow_temperature = _temperature(25)
+    return_temperature = _temperature(26)
+    source_inlet_temperature = _temperature(27)
+    source_outlet_temperature = _temperature(28)
+    superheat = _temperature(29)
+    evaporation_temperature = _temperature(31)
+    condensation_temperature = _temperature(33)
+    evaporator_temperature = _temperature(35)
+    suction_gas_temperature = _temperature(36)
+    hot_gas_temperature = _temperature(37)
+    volume_flow = gauge(44, 0.001, signed=False, unit="m³/h")
+    room_temperature = _temperature(724)
+    mixer_position = integer(736, signed=False)
+    last_pump_runtime = uint32(60164, unit="min")
+    last_hot_water_runtime = uint32(60168, unit="min")
+    active_error = string(63000, 16)
+
+    # Registers that some firmware versions do not provide.
+    OPTIONAL_FIELDS: ClassVar[frozenset[str]] = frozenset(
+        {
+            "room_temperature",
+            "mixer_position",
+            "last_pump_runtime",
+            "last_hot_water_runtime",
+            "active_error",
+        }
+    )
+
+    async def async_update(self, *, notify: bool = True) -> None:
+        """Refresh measurements, skipping optional registers this device rejects."""
+        await _update_skipping_unsupported(
+            self, super().async_update, "input", self.OPTIONAL_FIELDS, notify=notify
+        )
+
+
+class Settings(Component):
+    """Writable WT16 holding registers (function codes 03/16)."""
+
+    max_gap = 0
+    max_span = 50
+
+    hot_water_target_temperature = _target_temperature(
+        1, HOT_WATER_TARGET_MIN, HOT_WATER_TARGET_MAX
+    )
+    room_target_temperature = _target_temperature(723, ROOM_TARGET_MIN, ROOM_TARGET_MAX)
+
+    # Installations without a room sensor may not provide the room target.
+    OPTIONAL_FIELDS: ClassVar[frozenset[str]] = frozenset({"room_target_temperature"})
+
+    async def async_update(self, *, notify: bool = True) -> None:
+        """Refresh settings, skipping optional registers this device rejects."""
+        await _update_skipping_unsupported(
+            self, super().async_update, "holding", self.OPTIONAL_FIELDS, notify=notify
+        )
+
+
+class DigitalInputs(Component):
+    """WT16 discrete inputs (function code 02)."""
+
+    # max_gap = 1 merges directly adjacent inputs only, never across a gap.
+    max_gap = 1
+    max_span = 50
+
+    flow_switch_1 = discrete_input(45)
+    flow_switch_2 = discrete_input(69)
+    compressor = discrete_input(679)
+    heating_pump = discrete_input(680)
+    source_pump = discrete_input(681)
+    mixer_pump = discrete_input(682)
+    hot_water_pump = discrete_input(685)
+    remote_fault = discrete_input(686)
+    four_way_valve = discrete_input(690)
+    reserve_1 = discrete_input(691)
+    reserve_2 = discrete_input(692)
+    reserve_3 = discrete_input(693)
+    cooling_output = discrete_input(694)
+    reserve_5 = discrete_input(695)
+    hot_water_block = discrete_input(703)
+    heating_block = discrete_input(704)
+    utility_block = discrete_input(705)
+    sg_ready_1 = discrete_input(706)
+    sg_ready_2 = discrete_input(707)
+    reserve = discrete_input(714)
+
+    async def async_update(self, *, notify: bool = True) -> None:
+        """Refresh supported inputs, excluding addresses rejected by this device."""
+        await _update_skipping_unsupported(
+            self, super().async_update, "discrete", None, notify=notify
+        )

weider_modbus/const.py

@@ -0,0 +1,22 @@
+"""Device facts for the Weider WT16."""
+
+from __future__ import annotations
+
+from typing import Final
+
+MANUFACTURER: Final = "Weider"
+MODEL: Final = "WT16"
+
+# Allowed write ranges for the target temperatures, in °C (inclusive).
+HOT_WATER_TARGET_MIN: Final = 15.0
+HOT_WATER_TARGET_MAX: Final = 55.0
+ROOM_TARGET_MIN: Final = 15.0
+ROOM_TARGET_MAX: Final = 35.0
+TARGET_STEP: Final = 0.5
+
+# The device reports a placeholder value, such as 3276.7, for a temperature
+# sensor that is not connected. Readings outside this range are treated as
+# unknown. The range covers outdoor temperatures down to -45 °C and the hot
+# gas temperature of the refrigerant circuit.
+MIN_PLAUSIBLE_TEMPERATURE: Final = -45.0
+MAX_PLAUSIBLE_TEMPERATURE: Final = 150.0

weider_modbus/device.py

@@ -0,0 +1,75 @@
+"""The top-level WT16 device object."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import TYPE_CHECKING, Final
+
+from modbus_connection.model import Device, Raw
+
+from .components import DigitalInputs, Measurements, Settings
+from .const import MANUFACTURER, MODEL
+from .helpers import SgReadyMode, sg_ready_mode
+
+if TYPE_CHECKING:
+    from modbus_connection import ModbusUnit
+
+# Attribute names of the components, in polling order.
+COMPONENTS: Final = ("measurements", "settings", "digital_inputs")
+
+
+class WeiderWT16(Device):
+    """One Weider WT16 heat pump, reached through a ``ModbusUnit``.
+
+    The consumer owns the connection and passes a unit. This library only
+    reads and writes registers, so it works over any modbus-connection backend.
+    """
+
+    manufacturer: Final = MANUFACTURER
+    model: Final = MODEL
+
+    def __init__(self, unit: ModbusUnit) -> None:
+        """Create the device and its components. No I/O happens here."""
+        super().__init__(unit)
+        self.measurements = Measurements(unit)
+        self.settings = Settings(unit)
+        self.digital_inputs = DigitalInputs(unit)
+
+    async def async_update(self) -> None:
+        """Refresh every component.
+
+        Optional registers the device rejects are dropped on the first poll
+        that hits them. Any other ``ModbusError`` propagates, so the caller can
+        retry or mark the device unavailable. Listeners fire once every read is
+        in, so they see a consistent poll.
+        """
+        await self.async_ensure_setup()
+        for name in COMPONENTS:
+            await getattr(self, name).async_update(notify=False)
+        for name in COMPONENTS:
+            getattr(self, name).notify()
+
+    async def async_set_hot_water_target(self, temperature: float) -> None:
+        """Write the hot water target temperature in °C.
+
+        Raises ``ValueError`` if the value is outside the allowed range.
+        """
+        await self.settings.write("hot_water_target_temperature", temperature)
+
+    async def async_set_room_target(self, temperature: float) -> None:
+        """Write the room target temperature in °C.
+
+        Raises ``ValueError`` if the value is outside the allowed range and
+        ``AttributeError`` if this device does not provide the register.
+        """
+        await self.settings.write("room_target_temperature", temperature)
+
+    @property
+    def sg_ready_mode(self) -> SgReadyMode | None:
+        """The SG Ready operating state, derived from the digital inputs."""
+        inputs = self.digital_inputs
+        return sg_ready_mode(inputs.utility_block, inputs.sg_ready_1, inputs.sg_ready_2)
+
+    async def async_read_raw(self, names: Iterable[str] = COMPONENTS) -> Raw:
+        """Return every register this device reads, undecoded, for diagnostics."""
+        return await super().async_read_raw(names)

weider_modbus/helpers.py

@@ -0,0 +1,60 @@
+"""Interpretation of WT16 values that the raw registers do not carry."""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+from .const import MAX_PLAUSIBLE_TEMPERATURE, MIN_PLAUSIBLE_TEMPERATURE
+
+
+def plausible_temperature(value: float | None) -> float | None:
+    """Return the temperature, or ``None`` if it is a placeholder value.
+
+    The device reports a placeholder (for example 3276.7) for a temperature
+    sensor that is not connected.
+    """
+    if value is None or MIN_PLAUSIBLE_TEMPERATURE <= value <= MAX_PLAUSIBLE_TEMPERATURE:
+        return value
+    return None
+
+
+def clean_error_text(value: str | None) -> str | None:
+    """Return the device's error text without padding, or ``None`` if no error.
+
+    The device pads the 16-register text with null characters or spaces, so
+    "no error" arrives as padding only.
+    """
+    if value is None:
+        return None
+    text = " ".join(value.replace("\x00", " ").split())
+    return text or None
+
+
+class SgReadyMode(StrEnum):
+    """SG Ready operating states (Betriebszustände)."""
+
+    UTILITY_BLOCK = "bz1_utility_block"
+    NORMAL = "bz2_normal"
+    INCREASED = "bz3_increased"
+    START = "bz4_start"
+
+
+def sg_ready_mode(
+    utility_block: bool | None, sg_ready_1: bool | None, sg_ready_2: bool | None
+) -> SgReadyMode | None:
+    """Return the SG Ready operating state for the given input states.
+
+    The utility company block always means BZ1. Otherwise SG Ready 1 and 2
+    select the state: only SG Ready 2 on is BZ3, only SG Ready 1 on is BZ4, and
+    anything else is BZ2. A missing utility block reading counts as no block;
+    missing SG Ready readings make the state unknown.
+    """
+    if utility_block:
+        return SgReadyMode.UTILITY_BLOCK
+    if sg_ready_1 is None or sg_ready_2 is None:
+        return None
+    if sg_ready_2 and not sg_ready_1:
+        return SgReadyMode.INCREASED
+    if sg_ready_1 and not sg_ready_2:
+        return SgReadyMode.START
+    return SgReadyMode.NORMAL

weider_modbus-0.1.0.dist-info/METADATA

@@ -0,0 +1,160 @@
+Metadata-Version: 2.5
+Name: weider-modbus
+Version: 0.1.0
+Summary: Async Python library for the Modbus TCP interface of Weider heat pumps, built on modbus-connection
+Project-URL: Homepage, https://github.com/schadom/weider-modbus
+Project-URL: Source, https://github.com/schadom/weider-modbus
+Project-URL: Issues, https://github.com/schadom/weider-modbus/issues
+Author: schadom
+License-Expression: MIT
+License-File: LICENSE
+Keywords: heat pump,home-assistant,modbus,weider,wt16
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Home Automation
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Requires-Dist: modbus-connection>=4.12.1
+Description-Content-Type: text/markdown
+
+# weider-modbus
+
+Async Python library for the Modbus TCP interface of Weider WT16 heat pumps,
+built on [modbus-connection](https://github.com/home-assistant-libs/modbus-connection).
+
+> [!IMPORTANT]
+> This library is not affiliated with Weider Wärmepumpen GmbH and is provided
+> as-is and without warranty.
+
+The library only reads and writes registers. It takes a `ModbusUnit` and never
+opens a connection itself, so it works over any modbus-connection backend
+(tmodbus, pymodbus, or the in-memory mock). It is used by the
+[Weider WT16 Home Assistant integration](https://github.com/schadom/hacs_weider).
+
+## Installation
+
+```bash
+pip install weider-modbus
+```
+
+The library depends only on the backend-neutral `modbus-connection`
+interface. To open a connection yourself, also install a backend:
+
+```bash
+pip install "modbus-connection[tmodbus]"
+```
+
+## Usage
+
+```python
+import asyncio
+
+from modbus_connection import ModbusTcpParams
+from modbus_connection.tmodbus import ModbusConnection
+
+from weider_modbus import WeiderWT16, plausible_temperature
+
+
+async def main() -> None:
+    connection = ModbusConnection(ModbusTcpParams(host="192.168.1.50", port=502))
+    try:
+        device = WeiderWT16(connection.for_unit(1))
+        await device.async_update()
+
+        print("Hot water:", device.measurements.hot_water_temperature)
+        outdoor = plausible_temperature(device.measurements.outdoor_temperature)
+        print("Outdoor:", outdoor)
+        print("Compressor running:", device.digital_inputs.compressor)
+        print("SG Ready mode:", device.sg_ready_mode)
+
+        await device.async_set_hot_water_target(47.5)
+    finally:
+        await connection.close()
+
+
+asyncio.run(main())
+```
+
+### Components
+
+| Attribute | Modbus space | Content |
+| --- | --- | --- |
+| `device.measurements` | Input registers (FC04) | Temperatures, volume flow, runtimes, mixer position, active error text |
+| `device.settings` | Holding registers (FC03/FC16) | Hot water and room target temperatures |
+| `device.digital_inputs` | Discrete inputs (FC02) | Compressor, pumps, valves, blocks, SG Ready inputs |
+
+A value reads as `None` until the first successful poll, or if the device
+does not provide the register.
+
+### Optional registers
+
+Some firmware versions do not provide every register. The room temperature,
+room target, mixer position, runtimes, active error text and any digital input
+are optional. If the device rejects one of them with an illegal data address,
+the library drops that register on the first poll and stops reading it. Any
+other register error still raises, so real problems are not hidden.
+
+### Errors
+
+`async_update()` raises a `modbus_connection.ModbusError` subclass (or
+`TimeoutError` / `OSError` from the transport) when a poll fails. The shared
+connection reopens on the next request, so the caller can simply retry.
+
+The target setters raise `ValueError` for a value outside the allowed range
+(hot water 15–55 °C, room 15–35 °C), before anything is written.
+
+### Helpers
+
+- `plausible_temperature(value)` returns `None` for the placeholder values the
+  device reports for an unconnected sensor (outside −45 to 150 °C).
+- `clean_error_text(value)` strips the padding from the active error text and
+  returns `None` when there is no error.
+- `sg_ready_mode(...)` and `device.sg_ready_mode` derive the SG Ready operating
+  state (BZ1–BZ4) from the digital inputs.
+
+## Hardware verification
+
+The register addresses, the signed 0.1 °C temperature format and the
+multi-register word order come from the existing integration. Confirm them
+against your WT16 documentation, especially for negative temperatures. The
+test simulator checks the software against this map, not the map against a
+real heat pump.
+
+## Development
+
+Requires Python 3.13 or newer and [uv](https://docs.astral.sh/uv/).
+
+```bash
+uv sync
+uv run pytest
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy
+```
+
+To run the synthetic WT16 on port 5020 for manual testing:
+
+```bash
+uv run python -m tests.simulator
+```
+
+## Releasing
+
+Releases are published to PyPI from GitHub Actions with
+[trusted publishing](https://docs.pypi.org/trusted-publishers/).
+
+1. Set the new `version` in `pyproject.toml` and merge it to `main`.
+2. Create a GitHub release with a tag equal to that version (for example
+   `0.1.0`).
+3. The `Publish` workflow builds the package and uploads it to PyPI.
+
+A version number can be published only once.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

weider_modbus-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+weider_modbus/__init__.py,sha256=h4jxlwvvQYMyHVxX2_LMMUNkqutusDDbmZg7vXZscS8,894
+weider_modbus/components.py,sha256=Md_uedNQval8jB8Tb9fo2VPEaU5WbZy0nq49UPoLnMs,8238
+weider_modbus/const.py,sha256=VOdpk4EZbBSDMgIU3h_yNNftL0dpJzxt6jyPPKGS5iE,741
+weider_modbus/device.py,sha256=Rbijwj8ddEtK4hku99iQyRY7pjB7NgTFCO2iuz8UYJQ,2879
+weider_modbus/helpers.py,sha256=evUQ4dGz7hpKIfSXJTAuOynYQAHtm2F0ik1bF54xdsE,1988
+weider_modbus/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+weider_modbus-0.1.0.dist-info/METADATA,sha256=wA4FrdIivRzn5EGPdPy3umB9chHQ0Z3P03ZjO4Dc9yY,5433
+weider_modbus-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+weider_modbus-0.1.0.dist-info/licenses/LICENSE,sha256=jnP_BOoMzchc9jaCzOEmdce4S2K1mouGtFl5Md0doCc,1064
+weider_modbus-0.1.0.dist-info/RECORD,,

weider_modbus-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

weider_modbus-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 schadom
+
+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.