Architecture and scope

This page describes the responsibilities of trovis-modbus, its position in a Modbus application, the current package structure, and the documentation sources used for controller-specific behavior.

Project scope

trovis-modbus is an asynchronous Python library for SAMSON TROVIS 557x heating and district-heating controllers.

The library provides:

• controller-model detection,
• physical sensor detection,
• model-specific register and coil catalogs,
• scaling and signed-value conversion,
• invalid-value handling,
• neutral datapoint metadata,
• grouped and range-aware reads,
• TROVIS-specific write access,
• type-safe and validated writes,
• enum, date, time, and year-independent month/day values,
• controller, sensor, Rk1-Rk4, heating, domestic-hot-water, solar, and buffer-tank abstractions,
• hydronic system definitions selected by the controller's system code number,
• sensor-variant resolution based on controller configuration,
• selected derived operating values.

The library intentionally does not provide application-specific entities or user interfaces. For example, an application decides whether a datapoint is shown as a sensor, number, select, switch, date, or time value.

This separation keeps the controller knowledge reusable outside Home Assistant.

Architecture

The library sits between an application and a transport-neutral modbus_connection.ModbusUnit.

flowchart LR
    APP["Application<br/>Home Assistant, CLI, custom service"]
    LIB["trovis-modbus<br/>Controller model, metadata, reads, writes"]
    MC["modbus-connection<br/>Connection and unit abstraction"]
    BACKEND["Backend<br/>tmodbus, pymodbus, other"]
    DEVICE["SAMSON TROVIS 557x"]

    APP --> LIB
    LIB --> MC
    MC --> BACKEND
    BACKEND --> DEVICE

Loading

The application owns the connection lifecycle. The library receives a unit object and performs only controller-specific operations through that object.

This design provides:

• no dependency on one concrete Modbus implementation,
• no duplicate connection management,
• support for shared connections used by several consumers,
• controller logic independent of Home Assistant,
• transport changes without rewriting the TROVIS model,
• a clear boundary between generic Modbus behavior and controller semantics.

Responsibility boundaries

The application is responsible for

• choosing and configuring the Modbus backend,
• opening and closing the connection,
• choosing the unit or station address,
• defining polling intervals and retry behavior,
• deciding how library values are presented,
• deciding which optional subsystems are exposed to users,
• storing application-specific configuration.

modbus-connection is responsible for

• connection and unit abstractions,
• backend integration,
• generic register and coil field behavior,
• shared connection handling,
• the in-memory pytest backend used by the test suite.

trovis-modbus is responsible for

• TROVIS model and system interpretation,
• manufacturer register and coil references,
• data types, scaling, limits, and enums,
• model- and configuration-specific availability,
• read grouping within documented boundaries,
• TROVIS write-access handling and write preconditions,
• controller-specific derived values.

Current package structure

The source is organized around controller configuration and functional subsystems.

src/trovis_modbus/
├── trovis.py
├── device_info.py
├── data_model.py
├── metadata.py
├── addresses.py
├── enums.py
├── exceptions.py
├── utils.py
├── configurations/
│   ├── address_ranges.py
│   ├── hydronic_systems.py
│   ├── sensor_variants.py
│   ├── settings.py
│   └── trovis_models.py
└── subsystems/
    ├── controller.py
    ├── date_time.py
    ├── sensors.py
    ├── circuit_heating.py
    ├── circuit_dhw.py
    ├── circuit_buffer_tank.py
    ├── circuit_solar.py
    └── heat_meters.py

Main modules

Module or package	Purpose
trovis.py	Top-level Trovis557x object, probing, component grouping, hydronic availability, and derived device properties
device_info.py	Device identity, firmware, hardware, serial, and system code number
data_model.py	Shared TROVIS field behavior and write-access helpers
metadata.py	Neutral datapoint metadata exposed to applications
addresses.py	Conversion from manufacturer references to zero-based Modbus addresses
enums.py	Shared typed values such as operating modes, Rk roles, and system activity
configurations/address_ranges.py	Conservative readable register and coil ranges by controller family
configurations/trovis_models.py	Per-model logical capabilities and sensor variants
configurations/hydronic_systems.py	System-code definitions, model support, topology, Rk roles, and optional hydronic features
configurations/sensor_variants.py	Resolution of configurable or shared physical inputs
configurations/settings.py	Controller functions and parameters used by the model and resolvers
subsystems/	Functional controller areas exposed as Python objects

The internal file layout may evolve, but the public application-facing API should remain stable unless a breaking change is explicitly released.

Source hierarchy

Several official and historical sources exist for TROVIS behavior. They do not always answer the same question and may occasionally disagree.

Current model-specific manuals

The current model-specific manuals are authoritative for:

• system code numbers and hydronic diagrams,
• Rk1-Rk4 roles,
• function blocks and parameters,
• sensor assignments and electrical connections,
• model-specific availability,
• controller terminology.

The supported manual set covers TROVIS 5573, 5573-1, 5575, 5576, 5578, 5578-E, and 5579. When a maintained controller receives a newer manual, the newest verified edition replaces the previous edition as the project source.

Register and coil semantics

For raw Modbus semantics, the project follows this priority:

1. Final controller firmware register and coil tables
   Authoritative for addresses, ranges, scaling, units, invalid values, and writeability.
2. Current model-specific controller manuals
   Authoritative for model behavior, system topology, functions, parameters, sensor roles, and terminology.
3. Manufacturer application layout definitions
   Useful for function-block dependencies, visibility rules, and plant configurations.
4. Manufacturer application override definitions
   Useful for enum labels, formatting, and special conversions.
5. Older expert-value definitions
   Supplemental reference only when they do not conflict with current official documentation.
6. Existing working configurations and live-controller tests
   Important validation sources, but not a replacement for official controller documentation.

When sources conflict, the source that is authoritative for the affected type of information wins. A live observation may reveal a documentation problem, but it must not silently replace a documented rule without an explicit and tested project decision.

Design principles

• Keep manufacturer references such as HR40145 and CL137 visible in source.
• Centralize conversion to zero-based Modbus addresses.
• Prefer native typed values over display-oriented strings.
• Keep model, address-range, system-code, and function restrictions explicit.
• Do not infer hydronic meaning solely from a plausible measured value.
• Prefer direct controller values over reconstructed estimates.
• Keep presentation decisions outside the library.
• Treat writes more conservatively than reads.
• Add controller knowledge once in the library instead of duplicating it in every consuming application.

Related projects

• modbus-connection provides the transport-neutral connection and unit abstraction.
• trovis-modbus-hass maps library data to Home Assistant devices and entities.