Repository navigation
Devices and entities
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.
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-modbusdetermines what exists and what it means.
trovis-modbus-hassdetermines how it appears in Home Assistant.
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.
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, 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.
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 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.
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.
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.
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:
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.
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.
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.
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 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.
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.
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-modbusdecides what the controller data means.trovis-modbus-hassdecides how that data appears in Home Assistant.
- Your-TROVIS-in-Home-Assistant — visual/user-facing view of devices
- Config-flow-and-reconfiguration — probing, reconfiguration and config entries
- Coordinator-and-runtime-updates — polling, availability and recovery
- Writing-and-write-access — technical write path
- Changing-settings-safely — user-facing write safety
- Architecture-and-internals — overall architecture and project boundaries
- Development-and-Testing — integration development workflow
Disclaimer: Any information on this wiki is informal advice only. It is not supported nor endorsed by Samson, Sauter, YADOS, Pewo or any other equipment maker or OEM. There is no warranty expressed or implied: you take sole responsibility for everything you do with your heating controller.
-
Wozu dieses Projekt?
What is this project about?
-
Wie funktioniert das?
How does it work?
- Was wird benötigt? Kosten?
What's required? Costs?
- Supported controllers
- Connecting your TROVIS
- Installation and setup
- Current limits and migration
- Troubleshooting
- Architecture and internals
- Connections and transports
- Config flow and reconfiguration
- Coordinator and runtime updates
- Devices and entities
- Writing and write access
- Development and testing
- LAN/WLAN
USR-TCP232-T2, USR-TCP232-410S, USR-K7, USR-DR301 (Hutschiene), Elfin-EE10 (WLAN) - USB
AZDelivery FT232RL, Waveshare USB 2 RS232/485/TTL - ESP
ESP-01, Wemos D1 - SPS
S7 1200, Wago 750-889 - KNX
Masifi Modbus Gateway
- Edomi
- espHome/HomeAssitant
- FHEM
- HomeAssistant
- ioBroker
- KNX
- Loxone
- NodeRed
- openHAB
- SIMATIC Step7
- smarthomeNG
- Tasmota/MQTT
- Wago CODESYS
Wiki - Start