Skip to content

Devices and entities

Tom-Bom-badil edited this page Sep 15, 2026 · 1 revision

This page explains how the SAMSON TROVIS 557x integration turns a detected controller into Home Assistant devices and entities.

It focuses on the Home Assistant side of that job. Controller semantics — register and coil definitions, hydronic topology, Rk roles, datapoint metadata and controller-specific rules — belong to trovis-modbus.

For the overall integration and Modbus stack, see Architecture-and-internals.

For a user-facing visual tour of the integration, see Your-TROVIS-in-Home-Assistant.


🧭 Representation at a glance

The integration does not expose the TROVIS as one flat device containing every possible datapoint.

Instead, it maps the detected controller model and hydronic structure to a main controller device plus linked functional devices:

SAMSON TROVIS 557x
├── Controller
├── Measurements
├── Rk1 – role-dependent
├── Rk2 – role-dependent
├── Rk3 – role-dependent
├── Rk4 – Domestic hot water, when present
└── Solar – when present

Not every controller shows every device.

Optional devices and entities are created only when they are meaningful for the detected controller and hydronic configuration.

The basic ownership rule is:

trovis-modbus determines what exists and what it means.

trovis-modbus-hass determines how it appears in Home Assistant.


🏠 Device model

Controller

The physical TROVIS controller is represented by the main Home Assistant device.

Controller-wide entities belong here rather than to one particular hydronic circuit.

Examples can include controller information, controller-wide status, date/time functions and the Home Assistant Write access safety switch, depending on the supported controller model and configuration.

The main controller device is also the parent for the linked functional devices.


Measurements

Physical inputs are grouped under the linked Measurements device.

They are intentionally kept separate from Rk1 through Rk4 because a physical input can have different hydronic meanings depending on the controller model, wiring, system code, active functions and input assignments.

Typical TROVIS sensor/input abbreviations include:

AF1
VF1
RüF1
RF1
SF1
FG1
IMP

The physical sensor identity remains stable even if another hydronic configuration gives that measured value a different role.

Entity IDs remain ASCII-safe. For example, the visible manufacturer notation RüF can use ruef in an entity ID.


Rk1 through Rk3

Rk1, Rk2 and Rk3 are technical controller slots.

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

The hydronic model supplied by trovis-modbus determines the role of each slot. A slot can, for example, represent:

  • a heating circuit,
  • a pre-control / primary circuit,
  • a buffer-tank circuit,
  • or an unused slot.

The integration keeps the technical Rk identity stable and maps the resolved role to the Home Assistant representation.

A role that is not a room-heating circuit must not receive a misleading heating-only entity merely because it occupies an Rk slot.


Buffer-tank role

When Rk1 is resolved as a supported buffer-tank circuit, buffer-tank-specific entities are associated with that functional Rk1 representation.

The buffer-tank extension does not create a duplicate copy of the common Rk1 state merely because additional buffer-specific datapoints are available.

The exact controller-side buffer-tank model and datapoints are owned by trovis-modbus.


Rk4 – Domestic hot water

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

The linked Rk4 device is therefore conditional: it is not created merely because the controller model is capable of DHW.

Where supported, Home Assistant can expose both normal entities and a water_heater convenience entity for the same underlying library-backed datapoints.


Solar

A dedicated Solar device is created only when the detected controller and hydronic configuration contain a supported solar circuit.

Solar is kept as its own functional representation rather than being attached to Rk4 merely because some hydronic systems combine solar operation with domestic hot water.

The exact solar functions and datapoints are defined in trovis-modbus.


🧩 Entity platforms

The integration currently uses these Home Assistant entity platforms:

Platform Typical role in the integration
sensor Read-only measurements, states and derived values
binary_sensor Read-only boolean states
number Writable numeric settings
select Writable enumerated settings
switch Boolean controls and integration safety controls
date Date values and settings
time Time values and settings
climate Convenience view for supported heating circuits running in heating-curve mode
water_heater Convenience view for supported DHW circuits

Not every datapoint is writable, and not every platform is present on every controller.

climate and water_heater are convenience views over the same underlying library-backed datapoints. They are not separate controller-side data sources.


🧠 Metadata-driven entity mapping

Home Assistant entity descriptions should not contain a second TROVIS controller model.

The integration consumes neutral metadata from trovis-modbus and maps it to the appropriate Home Assistant entity representation.

Controller-side information such as:

  • datapoint availability,
  • data type,
  • unit,
  • scaling,
  • valid range,
  • step,
  • enum options,
  • writable state,
  • invalid/sentinel handling,
  • controller-specific write rules,

belongs to trovis-modbus.

The Home Assistant side owns the mapping of that information to:

  • entity platform,
  • device placement,
  • visible name and translation,
  • Home Assistant device class/state class where applicable,
  • entity availability and enabled/disabled behavior,
  • stable Home Assistant identity.

This boundary is important because it prevents controller knowledge from being maintained twice.

For the library-side model, see:


🔎 What determines whether a device or entity exists?

The integration builds its Home Assistant representation from the result of controller probing and the model subsequently constructed by trovis-modbus.

Relevant inputs include:

  • detected controller model,
  • applicable controller profile,
  • physical sensor/input availability,
  • hydronic system,
  • resolved Rk roles,
  • optional subsystems,
  • datapoints meaningful for the detected installation.

The important distinction is:

Capability is not the same as presence.

A controller model may support a function in general while the currently configured installation does not use it.

The integration therefore avoids creating devices or entities only because a register exists somewhere in the controller family.


🧱 Static entity topology

The integration uses a deliberately static entity-discovery model.

setup / reconfiguration
        │
        ▼
probe + build controller model
        │
        ▼
create applicable HA devices/entities
        │
        ▼
normal polling updates values only

Normal coordinator polling does not create or remove Home Assistant entities.

This keeps:

  • entity identity predictable,
  • the entity registry stable,
  • dashboards and automations from changing underneath the user,
  • controller I/O separate from Home Assistant platform setup.

If controller-side configuration changes the static model, run Reconfigure.

Examples include changes to:

  • hydronic system code,
  • sensor/input assignments,
  • relevant function blocks,
  • connection type,
  • Modbus unit ID.

🌡️ Sensor retention during reconfiguration

Physical sensors discovered during a later probe are added to the known sensor set.

Previously known sensors are retained rather than immediately removed because a single later probe returned no usable value.

This avoids unnecessary entity churn caused by temporary sensor faults or transiently invalid readings.

Newly connected or newly configured physical inputs therefore require a reconfiguration probe before new Home Assistant entities can be added.


🪪 Entity identity and the config-entry slug

Each controller receives an entity-ID prefix/slug during initial setup.

Example:

t5578

which can result in IDs such as:

sensor.t5578_rk1_flow_temp
number.t5578_rk1_room_setpoint_day

The slug is intentionally treated as stable identity data.

Changing the controller display name, connection endpoint or access code should not silently rename the existing Home Assistant entities.

This is especially important for:

  • dashboards,
  • automations,
  • scripts,
  • statistics,
  • long-term history.

The entity-ID prefix therefore remains stable during reconfiguration.


✍️ Writable entities

Writable controller datapoints can be represented through normal Home Assistant platforms such as:

  • number,
  • select,
  • switch,
  • date,
  • time,
  • climate,
  • water_heater.

The presence of a writable Home Assistant entity does not bypass the integration or controller safety rules.

Writes still pass through the controller-level Write access safety gate and then through the public trovis-modbus write API.

The detailed write architecture is documented in Writing-and-write-access.

For user-facing information, see Changing-settings-safely.


🚦 Availability and polling

Entities do not communicate with the controller independently.

All entities belonging to one TROVIS config entry consume the state refreshed by the shared DataUpdateCoordinator.

A normal communication failure therefore affects the shared controller update rather than one entity opening its own Modbus connection.

Polling, communication errors and recovery are documented in Coordinator-and-runtime-updates and are intentionally not duplicated here.


🧑‍💻 Development boundaries

The project-level ownership rules are maintained in one place: Architecture-and-internals#%EF%B8%8F-where-should-a-change-be-implemented.

For this page, the simple rule is enough:

trovis-modbus decides what the controller data means. trovis-modbus-hass decides how that data appears in Home Assistant.


📚 Related documentation

Home Assistant integration

TROVIS device library

german Wiki - Start english


english Bauanleitungen

Schritt 1 - Kabel

Schritt 2 - Adapter

Schritt 3 - Schnittstelle

Schritt 4 - Regler

Schritt 5 - Erster Test

🔥 Update: Weitere Adapter


english Home Assistant Integration

🚀 Getting started

🔌 Using the integration

🧑‍💻 Technical reference

🔢 Related projects


english SmartHomeNG Plugin


german2 Anhang: Info-Sammlung

Clone this wiki locally