.todo

--- stripped from trovis-modbus-hass to avoid redundant information

Extracted trovis-modbus library internals

Important

Temporary migration document.

This file contains library-owned material extracted from the trovis-modbus-hass Architecture and internals page. It should not become a second permanent copy of the same documentation.

The sections below should later be merged into the existing trovis-modbus wiki pages and then this staging file can be deleted.

The Home Assistant integration should keep only enough information to explain its dependency on trovis-modbus and to tell contributors which repository owns a change. The detailed controller model belongs here, in the library documentation.

Suggested destinations in the trovis-modbus wiki

Extracted topic	Suggested target page
Library responsibility boundary and ModbusUnit contract	Architecture and scope
TROVIS device model, Rk roles, sensor/input model	Controller profiles and hydronic model
modbus_connection.model, addressing, grouped reads, metadata	Datapoints, reading, and writing
Library-side write validation and access handling	Datapoints, reading, and writing
Library tests	Development and contributions

Note

Some of this information is already present in those pages. When integrating this staging document, merge and improve existing sections instead of adding duplicate paragraphs.

---

1. Responsibility boundary and backend-neutral contract

trovis-modbus

Repository:

https://github.com/Tom-Bom-badil/trovis-modbus

This is the backend-neutral TROVIS device library and the authoritative source for controller-specific knowledge.

It owns:

• supported SAMSON and compatible OEM controller profiles,
• controller probing,
• hydronic system definitions,
• Rk roles and optional subsystems,
• physical sensor/input definitions,
• holding-register and coil definitions,
• manufacturer-reference to zero-based Modbus/PDU address conversion,
• model-specific readable ranges,
• grouped-read planning constraints,
• data types,
• units,
• scaling,
• invalid/sentinel values,
• neutral datapoint metadata,
• enum options,
• numeric limits and steps,
• derived TROVIS values and states,
• validated reads and writes,
• TROVIS write-access handling,
• controller-specific write preconditions.

It does not own:

• Home Assistant devices,
• Home Assistant entity IDs,
• config entries,
• Home Assistant translations,
• physical connection creation,
• a concrete Modbus backend.

The library receives a modbus_connection.ModbusUnit from its caller.

That dependency direction is intentional:

application
    │
    ├── creates a connection using any supported backend
    │
    └── passes ModbusUnit
              │
              ▼
         trovis-modbus

The same TROVIS model can therefore be used by Home Assistant, the command-line query tool, automated tests, or another application without changing the controller model.

---

2. Controller and datapoint model

🏗️ TROVIS device model

The TROVIS device is not represented as one flat list of thousands of registers.

The library separates controller-wide data from functional subsystems.

A typical logical structure is:

Trovis557x
├── controller-wide data
├── Measurements
├── Rk1
├── Rk2
├── Rk3
├── Rk4 / domestic hot water
├── Solar
├── Buffer-tank extensions
├── date/time
└── other supported functional components

The exact structure depends on controller model and hydronic configuration.

Rk identity versus hydronic role

Rk1, Rk2, and Rk3 are technical controller slots.

They are not simply aliases for "heating circuit 1", "heating circuit 2", and "heating circuit 3".

Depending on the configured hydronic system, a slot can have a role such as:

• heating circuit,
• pre-control/primary circuit,
• buffer-tank circuit,
• unused.

Rk4 is reserved for domestic hot water where the hydronic configuration uses it.

The Rk number remains stable even when the role differs.

This is important for both the library and Home Assistant identity model: entities are built around the technical controller structure, while visible names can describe the resolved role.

---

🌡️ Physical sensors and Measurements

Physical sensor inputs are deliberately kept separate from hydronic circuit devices.

For example:

AF1
VF1
RüF1
RF1
SF1
FG1
IMP

The same physical input can have different hydronic meaning depending on:

• controller model,
• wiring,
• selected system code,
• active functions,
• input assignments.

Therefore the integration does not permanently rename a physical sensor based on the current role of an Rk circuit.

ASCII-safe entity IDs use forms such as ruef, while visible names can retain the manufacturer's RüF notation.

---

🧱 modbus_connection.model inside trovis-modbus

trovis-modbus builds on the backend-neutral modelling framework supplied by modbus_connection.model.

Fields are declared as typed register or coil descriptors and then exposed as normal Python attributes after an update.

Conceptually:

class ExampleComponent(Component):
    temperature = gauge(...)
    operating_mode = enum(...)
    enabled = coil(...)

The TROVIS wrappers add controller-specific behavior around those generic field types, including:

• manufacturer HR/CL references,
• address conversion,
• TROVIS metadata,
• limits,
• units,
• steps,
• invalid values,
• write validation,
• packed date/time formats,
• documented readable ranges.

This is why Home Assistant entities can remain metadata-driven instead of carrying their own duplicate register map.

---

🔢 TROVIS addressing

Manufacturer documentation normally identifies datapoints using TROVIS references such as holding-register numbers and coil numbers.

Those are not copied directly into low-level Modbus requests.

The library converts the manufacturer reference to the zero-based address used on the Modbus PDU.

For example, the project consistently treats TROVIS coil numbering as manufacturer-facing one-based numbering and converts it centrally before the request is sent.

The rule is simple but important:

Address conversion belongs in trovis-modbus, never in a Home Assistant entity.

This prevents off-by-one fixes from being scattered across entity platforms and keeps documentation references readable in the device model.

---

📦 Read planning and grouped reads

Reading every field with a separate Modbus request would be unnecessarily slow and would put excessive load on older controllers and serial gateways.

modbus_connection.model therefore pools nearby fields into block reads.

The TROVIS layer further constrains that planner with its knowledge of the controller address space.

The read plan respects:

• model-specific readable ranges,
• known unsupported gaps,
• manufacturer block boundaries,
• the active component layout,
• register/coil separation,
• the maximum request span selected for TROVIS controllers.

The TROVIS implementation deliberately uses a conservative maximum block span rather than assuming every controller or gateway tolerates the full Modbus protocol maximum.

Historically, a maximum span of 50 registers/coils per request has been used for the TROVIS model.

This has two benefits:

1. fewer Modbus round trips than one-field-per-request,
2. no blind reads across known unsupported areas.

Static read layout

The field layout and grouped read plan are derived from the constructed component.

Once a component has been built and its plan cached, normal polling does not continually reshape the device model.

That matches the integration's static entity-discovery policy:

• setup/reconfiguration decides what exists,
• polling updates values,
• polling does not create new Home Assistant entities.

---

3. Library-side write semantics

2. TROVIS library validation and access handling

The library remains authoritative for:

• writable state,
• min/max values,
• steps,
• scaling,
• enum options,
• raw-value encoding,
• access-code handling,
• protected/special register sequences,
• controller-specific preconditions.

A typical integration write therefore ends in the library's generic path rather than writing a Modbus register directly from the entity:

await component.async_write_datapoint(
    field,
    value,
    access_code=access_code,
)

The default TROVIS access code is currently 1732, but the configured value is stored per controller.

The Home Assistant gate does not bypass the controller's own access rules.

---

4. Library testing

Library tests

trovis-modbus can be tested with a mock/in-memory ModbusUnit.

That allows tests for:

• register decoding,
• coil behavior,
• model ranges,
• grouped-read planning,
• write validation,
• hydronic roles,
• derived values,

without requiring Home Assistant or physical hardware.

---

Where should a library change be implemented?

A library contributor should be able to determine the repository boundary without reading the Home Assistant internals.

Change	Correct project/layer
TROVIS register or coil definition	trovis-modbus
Controller model/profile or readable range	trovis-modbus
Hydronic system, Rk role, subsystem or sensor resolver	trovis-modbus
TROVIS-specific metadata, scaling, limits, enums or invalid values	trovis-modbus
TROVIS-specific write rule or derived value	trovis-modbus
Generic Modbus model field or read-planning behavior	modbus-connection
Generic Modbus exception/connection abstraction	modbus-connection
Concrete tmodbus protocol/backend behavior	tmodbus
Serial transport behavior	serialx / selected backend
Home Assistant config flow, devices, entities or translations	trovis-modbus-hass
Home Assistant coordinator, entity availability or UI write gate	trovis-modbus-hass

A useful rule of thumb is:

If the behavior describes the TROVIS controller and should be identical for Home Assistant, a CLI tool, and another Python application, it belongs in trovis-modbus.

---

Cross-project boundary

The library may mention the Home Assistant integration as an important consumer, but it should not document Home Assistant implementation details such as config entries, entity platforms, DataUpdateCoordinator, translations, entity IDs, or the integration's user-facing write-access switch.

A concise cross-reference is enough:

trovis-modbus is used by the trovis-modbus-hass Home Assistant integration. The integration provides a ModbusUnit, consumes the neutral TROVIS model, and maps it to Home Assistant devices and entities.

Conversely, the Home Assistant wiki should point back to the library wiki for controller semantics rather than duplicating them.