Skip to content

Config flow and reconfiguration

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

This page explains how a TROVIS controller moves from connection details entered by the user to a stable Home Assistant config entry and runtime device.

The controller model itself stays in trovis-modbus. The integration is responsible for collecting the connection data, probing the controller and storing the Home Assistant-specific identity.

For connection details, see Connections-and-transports.


🧭 The three stages

There are three related but separate paths:

  1. Initial setup — collect connection data, probe the controller and create the config entry.
  2. Runtime setup — rebuild the connection and controller object from the stored config entry when Home Assistant loads it.
  3. Reconfiguration — probe again when connection or controller settings change, while keeping stable Home Assistant identity where possible.

Runtime setup sequence

Conceptually, async_setup_entry() does this:

flowchart TD
    ENTRY["TROVIS config entry"]
    PARAMS["Build Modbus connection parameters"]
    CONN["Create ModbusConnection"]
    UNIT["Select unit ID"]
    DEVICE["Create Trovis557x"]
    COORD["Create coordinator"]
    REFRESH["First controller refresh"]
    PLATFORMS["Load HA entity platforms"]

    ENTRY --> PARAMS
    PARAMS --> CONN
    CONN --> UNIT
    UNIT --> DEVICE
    DEVICE --> COORD
    COORD --> REFRESH
    REFRESH --> PLATFORMS
Loading

The connection object belongs to the config-entry lifetime.

When the entry is unloaded, the integration closes the connection.




🔎 Controller setup and probing

The setup flow does not ask the user to manually select the TROVIS model or hydronic system.

Instead, the integration first establishes a temporary communication path and uses:

await Trovis557x.async_probe(unit)

The probe determines the controller information required to build the final device model.

The setup path is conceptually:

flowchart TD
    USER["Connection data + unit ID"]
    TEMP["Temporary Modbus connection"]
    UNIT["ModbusUnit"]
    PROBE["Trovis557x.async_probe"]
    MODEL["Controller model"]
    SENSORS["Detected physical inputs"]
    FINAL["Name + entity prefix + access code"]
    ENTRY["Home Assistant config entry"]

    USER --> TEMP
    TEMP --> UNIT
    UNIT --> PROBE
    PROBE --> MODEL
    PROBE --> SENSORS
    MODEL --> FINAL
    SENSORS --> FINAL
    FINAL --> ENTRY
Loading

The final config entry stores enough information to reconstruct the runtime device without forcing every entity platform to probe the controller again.

Depending on the current implementation and library version, the probe and subsequent model construction determine or resolve:

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



🔄 Reconfiguration

Reconfiguration is more than editing a hostname.

The controller is probed again because changes to the connection, unit ID, or controller configuration can affect the discovered device model.

A reconfiguration can therefore refresh:

  • connection data,
  • Modbus unit ID,
  • controller display name,
  • write-access code,
  • detected model,
  • physical sensors,
  • hydronic topology and supported subsystems.

The entity-ID prefix remains stable.

Normal polling only refreshes the existing model. Run Reconfigure after changing controller-side configuration that can affect the static structure, for example:

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

Entity-topology rules, including sensor retention and stable entity identity, are documented in Devices-and-entities.




💾 Config-entry boundaries

The current config entry conceptually contains two categories of information.

Connection data

Depending on transport:

connection type
host / port / framing
or
serial target / serial parameters
unit ID

TROVIS identity and probe data

display name
stable entity-ID prefix
write-access code
detected controller model
detected physical sensors

The exact field names are implementation details and can evolve with config-entry schema migrations.

The important architectural rule is:

The config entry stores enough transport information to recreate the connection and enough probe information to reconstruct the same stable Home Assistant representation.




🪪 Stable identity

Reconfiguration may update connection details, the detected model or physical sensor information, but it should not casually rename an existing Home Assistant installation.

The detailed entity-ID, sensor-retention and static-topology rules are kept in one place:

➡️ Devices-and-entities

Normal coordinator polling does not run the setup flow again and does not create new entities. Runtime behavior is documented in Coordinator-and-runtime-updates.


📚 Related pages

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