Reworked handling of GLT / Rk1..Rk4 Operating Modes / Pumps and Valves

• Hardened controller probing against partial Modbus read failures and excluded the invalid CL59/UP3 gap on 2-circuit controllers.
• Reworked operating-mode handling with effective active_mode state, direct mode writes, separate AUTARK release and settling-aware verification.
• Added detailed operating-mode transition logging for field testing and diagnostics.
• Added Night mode support for Rk4 / DHW and corrected adjustable DHW temperature limits to 5–90 °C.
• Added per-circuit and controller-wide GLT operating-mode ownership states.
• Added explicit pump control modes (Auto / On / Off) using pump output and ownership coils without invalid GLT pre-writes.
• Added regression tests for delayed mode changes, normalized command readback, Rk4 Night and pump-control ownership/write behavior.

fix for modbus-connection 4.12.1 not being in core yet

quick fix - the lib is now checking if the new features of modbus-connection 4.12.1 are available

Maintenance release

trovis-modbus 3.1.1

Maintenance release following the repository and documentation reorganization.

Changed

• Renamed the GitHub repository to trovis-modbus_python-library.
• Moved central project documentation, support, issue reporting, and discussions to
  samson_trovis_557x.
• Updated repository links and documentation accordingly.
• Updated readme.md accordingly..

No functional changes to the Python library are included in this release.

trovis-modbus 3.1.0

trovis-modbus 3.1.0

This release improves Modbus write reliability and updates the library for the
current modbus-connection 4.12.x API.

Write reliability

• Add verified writes for normal state-setting registers and coils.
• After a write, read back the affected datapoint and update the local cache
  only after successful verification.
• On a lost write response, perform a targeted readback first instead of
  immediately repeating the write, avoiding unnecessary duplicate writes when
  the controller has already accepted the value.
• Retry failed or mismatching normal writes up to two times.
• Add the public TrovisWriteVerificationError for writes that cannot be
  verified successfully.
• Apply the same write/readback verification to the TROVIS write-access
  register.

Safety

• Explicitly mark one-shot command/trigger datapoints as non-retryable where
  repeating the command could have unintended effects.
• In particular, forced_charging remains non-retryable because the exact
  controller behavior of repeated trigger writes is not sufficiently defined.

Modbus connection

• Require modbus-connection >= 4.12.1, <5.
• Use the current ModbusUnit timing-requirement API.
• Request a 5 s connection timeout and 0 s connect delay for TROVIS
  communication.
• Update tests and mocks for the current modbus-connection API.

No intentional breaking changes are introduced to the public TROVIS device
model.

Feature parity with YAML version and shNG Plugin, richer control-circuit model and advanced diagnostics

Version 3.0.0 - Major milestone
Feature parity reached, base functionality completed, registers/coils audits completed
All known Trovis models are auto-detected and auto-configured

With this release, trovis-modbus has reached and in several areas surpassed the functional scope previously provided by the legacy Home Assistant YAML configuration and the SmartHomeNG plugin.

The library now provides a substantially more complete, model-aware and reusable representation of SAMSON TROVIS 557x controllers while remaining independent of Home Assistant and of the underlying Modbus transport.

What's new

Expanded heating-circuit support

• Added and refined model-, hydronic-system- and control-circuit-aware datapoint availability.
• Improved handling of Rk1-Rk3 roles and controller-specific capabilities.
• Added additional heating-circuit functions and parameters required for practical controller monitoring and adjustment.
• Added PI/PID and two-point control parameters where supported.
• Added support for the configured control type and related controller functions.
• Refined room-unit / remote-transmitter semantics, including correct handling of FG inputs depending on their configured role.
• Added model- and circuit-aware support for TROVIS 5570 room control units.
• Added and refined Optimization and Adaptation related capabilities.

Heating-curve calculation

• Added a common, transport-independent heating-curve calculation backend.
• Supports all three TROVIS setpoint-generation modes:
  • gradient characteristic,
  • four-point characteristic,
  • fixed setpoint.
• Day and night curves are calculated separately.
• Four-point characteristics are linearly interpolated between the configured points and keep the P1/P4 boundary values outside the configured point range.
• Fixed-setpoint mode returns constant day/night curves.
• The same calculation backend is available to applications such as the Home Assistant simulation helpers, avoiding duplicate heating-curve implementations.

Pumps, valves and overall controller state

• Added/refined canonical pump and valve state information.
• Added SystemOverallStatus, an 8-bit actuator-status matrix covering:
  • Rk1 valve,
  • Rk2 valve,
  • Rk3 valve,
  • storage tank charging pump,
  • circulation pumps UP1/UP2/UP3,
  • DHW circulation pump.

The existing SystemActivity logic remains unchanged and separate.

Improved controller diagnostics

• Added the raw controller model code as diagnostic information.
• Expanded metadata and availability information for model-, circuit- and configuration-dependent datapoints.
• Improved handling of physical sensor / input semantics and unsupported combinations.

Manual read exclusions

A new per-device support mechanism allows applications to exclude individual zero-based Modbus register or coil addresses from reading.

This is intended primarily as a troubleshooting tool for controller models, hardware revisions or firmware versions where individual addresses are known to reject Modbus reads.

Excluded addresses are removed from the actual readable ranges, so no generated block read will span across them.

Example: 22,33-47,119

This is deliberately a runtime/device-specific override; the normal model address maps remain unchanged.

Architecture

trovis-modbus remains transport-independent.

Applications provide a modbus_connection.ModbusUnit, while the library handles:

• controller and hydronic-system discovery,
• controller-specific datapoint availability,
• neutral metadata,
• grouped reads,
• validated writes,
• write-access handling,
• derived controller states,
• heating-curve calculation.

Compatibility

Supported SAMSON TROVIS 557x controllers and compatible OEM variants continue to use their corresponding TROVIS model profiles.

This release does not attempt to reproduce every controller menu or commissioning function. Its scope remains operational monitoring and fine adjustment of already commissioned heating systems.

Ongoing audit of registers/coils, support modbus-connection 4.8.1

trovis-modbus 2.2.0

This release contains a set of datapoint, metadata and development-tooling
improvements following the current TROVIS register/entity audit.

Added

• Add support for the global thermal-disinfection function for domestic hot
  water (CO4-F14 / CL414).
• Add the writable disinfection_enabled datapoint to the Rk4 / domestic-hot-water
  subsystem.

Changed

• Update the minimum modbus-connection dependency to 4.8.1.
• Use a conservative default step of 1 °C/K for writable temperature datapoints,
  while keeping non-temperature factors and steps unchanged.
• Correct hardware revision handling (HR40004) to use the unscaled integer value
  reported by real TROVIS hardware.
• Update query/CLI tests for the modbus-connection 4.8.1 behavior where
  field_rows() respects restrict_fields() and omits unavailable fields.
• Update canonical-parity tests with hardware-verified metadata exceptions.
• Simplify the local development/test workflow so project dependencies are
  installed from the package itself instead of requiring a local
  modbus-connection source checkout.
• Rename the development scripts to the common project naming:
  • script/format_code.sh
  • script/run_checks.sh
• Consolidate the previous separate library test script into run_checks.sh.
• Add the common _local_dev_overrides path to .gitignore.

Compatibility

• Python >= 3.12
• modbus-connection >= 4.8.1
• CLI extra: modbus-connection[pymodbus] >= 4.8.1

No public TROVIS identities or existing datapoint names have been removed in this
release.

trovis-modbus 2.1.0

** trovis-modbus 2.1.0 **

• Add fixed-setpoint, weather-compensated heating-curve and four-point control mode detection for Rk1–Rk3.
• Add four-point characteristic values and calculated day/night heating curves, including return-flow curves where available.
• Add public HeatingCircuitControlMode support and related circuit helpers.
• Migrate to modbus-connection >= 4.2 and its current connection/model APIs.
• Update the CLI to ModbusTcpParams / ModbusSerialParams.
• Update tests for the new modbus-connection 4.2 lifecycle and mock APIs.

Compatibility: modbus-connection >= 4.2; CLI extra requires modbus-connection[pymodbus] >= 4.2.

Update docs

This is a pure documentation-based release:

• update readme.md
• restructure Wiki
• update Wiki pages

Modelling controllers, hydronic systems, control circuits with roles, connected sensors / inputs

List of changes

• Add model definitions and all 94 currently known hydronic systems for all TROVIS models (5573, 5573-1, 5575, 5576, 5578, 5578-E, 5579).

• Improve model specific and hydronic system specific sensor discovery, including configurable multi-purpose, analog and pulse inputs. Additional sensors will also be detected and added, even if not required by the specific hydronic system in use.

• Introduce role-aware Rk1-Rk4 control circuits for heating, pre-control, buffer-tank and domestic-hot-water functions.

• Add dedicated solar circuit and buffer-tank subsystems with relevant status and control datapoints.

• Reorganize configuration and subsystem modules and significantly expand matrix, regression and live-controller coverage.

• Breaking: replace the former hk1-hk3 and ww public identities with rk1-rk4.

The Code has been tested successfully with 3 different Trovis controller models: 5578 (testing device; hydronic system 6.1); 5579 (testing device; hydronic system 5.1); 5576 ('live' device connected to my heating system). All 3 controller models, hydronic systems and attached sensors have been auto-detetected; the expected datapoints were created automatically in accordance to their functions of each circuit; plausible readings of all connected sensors and inputs were made available.

Consistent, type-safe and range-aware datapoint definitions

This maintenance release completes and unifies the value-range metadata used by
the expanded TROVIS 557x datapoint model.

The datapoint catalog introduced with 1.1.0 already covered the large majority
of the required controller values. Version 1.1.1 makes this coverage
consistently usable by applications such as the Home Assistant integration by
providing complete and type-safe limits for writable values.

Changes

• Unified value-range metadata across numeric and temporal datapoints.
• Numeric, date, time, and MonthDay values now consistently use
  min_value and max_value in their native Python type.
• Removed the special min_year / max_year metadata fields.
• Added raw_min and raw_max metadata to distinguish Modbus transfer ranges
  from application-facing value ranges.
• Completed missing minimum, maximum, step, precision, and unit metadata for
  writable controller, heating-circuit, and domestic-hot-water values.
• Completed the ranges required to expose the affected datapoints safely as
  Home Assistant number entities.
• Added explicit temporal limits for controller time, controller date, yearless
  dates, and thermal-disinfection times.
• Preserved the hardware-verified HR40118 exception:
  • scale: 0.1
  • application range: 1..6 K/h
  • raw register range: 10..60
• Expanded metadata consistency and temporal-value tests.
• Reordered datapoint definition blocks for improved readability.
• Improved the explanation of TROVIS manufacturer references and zero-based
  Modbus addresses.
• Cleaned up and standardized import ordering.
• Configured Ruff to keep aliased imports grouped for better readability.

Datapoint coverage

• 121 / 121 legacy direct datapoints are functionally modeled.
• 108 additional datapoints beyond the previous Standard-Modbus configuration
  are modeled.
• The current catalog covers the large majority of the most important TROVIS 5578
  and 5579 controller values.
• Remaining larger feature areas include time-program editing, complete
  heat-meter modeling, and full error-bit decoding.

Validation

• 300 tests collected
• 283 tests passed
• 17 expected tests skipped
• script/libtest.sh completed successfully
• script/libcheck.sh completed successfully
• Ruff formatting check passed
• Ruff lint check passed
• Python compileall passed
• Source distribution build passed
• Wheel build passed
• Home Assistant started without TROVIS integration errors
• Testing devices (TROVIS 5578 + 5579) both operated successfully
  (2x6 = 12 devices with 466 entities in total)
• Expanded primary Home Assistant entities were created successfully
• Controller date was read and written successfully through Home Assistant
• Existing polling and write-access handling remained functional

Developer note

Consumers of temporal metadata should now use:

• min_value
• max_value
• raw_min
• raw_max

instead of the previous date-specific min_year and max_year attributes.