python-stiebel-eltron

Python API for interacting with the STIEBEL ELTRON ISG web gateway via modbus for controlling integral ventilation units and heat pumps.

This module is based on the STIEBEL ELTRON modbus user manual, but is not official, developed, supported or endorsed by Stiebel Eltron GmbH & Co. KG. For questions and other inquiries, use the issue tracker in this repo please.

Requirements

You need to have Python installed.

• STIEBEL ELTRON Internet-Service Gateway ISG WEB with enabled modbus module
  • You can call the STIEBEL ELTRON support, if your ISG does not have the modbus module enabled. They upgraded mine for free.
• STIEBEL ELTRON heatpumpt (compatible). Successfully used devices:
  • LWZ504e
  • LWZ304
  • Tecalor THZ 7.1 IBC Topline with ISG Connect (reported as LWZ_R290, WPM register map). Ventilation registers (WpmVentilationValues, WpmVentilationParameters) read only so far; writing the ventilation stages is untested
• Network connection to the ISG WEB

Installation

The package is available in the Python Package Index.

Base install:

    $ pip install pystiebeleltron

Install with the optional tmodbus backend used in the example below:

    $ pip install "pystiebeleltron[tmodbus]"

Example usage of the module

The examples/ directory contains runnable examples for WPM and LWZ heat pumps. They use the optional tmodbus backend, so install pystiebeleltron[tmodbus] first.

The API takes a ModbusUnit. You own the connection: build it, hand a unit to the API, and close it when done. Building it performs no I/O — the first read establishes the link, and a link that drops later is re-established on the next request, over the same unit handle. Each register block is a component exposed on the API, and values are read as typed attributes (None when the register is unavailable).

Pass the IP address of the ISG gateway to the selected example:

./examples/wpm-example.py 192.168.1.10
./examples/lwz-example.py 192.168.1.10

The WPM example also demonstrates writing and restoring the DHW comfort temperature. The LWZ example reads room and outside temperatures and the current operating mode.

For a read-only WPM library check outside Home Assistant, use examples/wpm-readonly-check.py in a separate virtual environment. Select --family wpm, wpm3 or wpm3i, and pass --confirm-read-only. It performs one poll by default (--polls accepts at most three); --raw exercises raw reads without printing register values. The output contains package versions, a retry-module fingerprint and request outcomes, excluding host addresses and register values. The wrapper permits only input and holding reads and rejects all write operations. This checks the library, not Home Assistant compatibility.

WPM API polls retry an illegal-address input or holding read at most once from a lower start answered directly in the same register space and poll, when the expanded read fits within 125 registers. Healthy reads and writes are unchanged; LWZ does not opt in. A rejected block costs one failed original request and at most one additional read on every poll. A successful retry does not establish that the target registers exist; unavailable words still decode as None.

Errors a caller sees

• get_controller_model raises StiebelEltronModbusError when the identification register cannot be read or comes back empty, and UnknownControllerModelError (with .model_id) for an id this library does not know.
• async_update and async_read_raw raise the modbus_connection errors unchanged: ModbusError and its subclasses such as ModbusConnectionError, ModbusTimeoutError or an IllegalDataAddressError naming the refused block. The one exception is an optional block a controller refuses with illegal data address before it ever answered it; that block is dropped and the poll goes on, as described above.
• write raises ValueError from the field's validator for a value outside its documented range, AttributeError for an unknown or read-only field, and the modbus_connection errors for a failed transfer.

License

python-stiebel-eltron is licensed under MIT, for more details check LICENSE.