Datapoints, reading, and writing

This page describes the declarative datapoint model, metadata, grouped polling, invalid-value handling, write access, operating modes, native date/time values, and selected derived values.

Datapoint catalog and metadata

The library uses declarative datapoint definitions rather than scattering raw Modbus addresses throughout the code.

A catalog entry describes the technical and semantic properties of a holding register or coil.

Typical metadata includes:

• manufacturer reference such as HR40145 or CL137,
• zero-based Modbus address,
• holding-register or coil type,
• signed or unsigned encoding,
• scale,
• unit,
• minimum and maximum,
• write step,
• enum type and options,
• invalid raw values,
• writable state,
• model applicability,
• read-grouping information.

Manufacturer-style references remain visible in source because they are easier to compare with TROVIS documentation. Conversion to zero-based Modbus addresses is centralized in the library.

Why metadata belongs in the library

The library is the authoritative source for controller-specific facts. A consuming application should not need to duplicate:

• whether a value is writable,
• which value range is valid,
• how the raw value is scaled,
• whether the raw value is signed,
• which enum values are valid,
• which controller models support the value,
• which write preconditions apply.

Applications may decide presentation details, but should not redefine controller behavior.

Functional parity

The catalog covers the direct datapoints required by the project reference and adds model-specific values where verified.

Parity is functional rather than entity-count based. For example, one native date value can replace several raw words and display templates, and one enum can replace a raw number plus application-specific formatting logic.

Reading and polling

Grouped reads

The library groups adjacent fields into bounded Modbus reads. The planning limit is deliberately conservative:

maximum span: approximately 50 registers or coils

This reduces protocol overhead without creating very large or fragile requests.

The planner respects:

• holding-register versus coil separation,
• known manufacturer block boundaries,
• catalog gaps,
• controller-model restrictions,
• active Rk1-Rk3 slot count,
• configured readable ranges.

Update cycle

A normal application refreshes the device with:

await device.async_update()

The library then:

1. builds the required read plan,
2. performs grouped requests,
3. decodes raw values,
4. handles invalid-value sentinels,
5. updates component properties,
6. refreshes configuration-dependent and derived values.

The complete device update is coordinated through one component group so that subsystems can share efficient reads.

Invalid values

TROVIS controllers use special raw values for missing sensors or unavailable data. The library converts these sentinels centrally rather than exposing them as plausible temperatures, percentages, or numbers.

This is especially important for:

• optional physical sensors,
• configurable inputs,
• model-dependent registers,
• values that are valid only for selected functions or systems.

An unavailable value is represented as an unavailable Python value, normally None, rather than as the manufacturer's sentinel.

Writing and write access

TROVIS controllers require explicit write access before protected values can be changed.

A typical sequence is:

await device.async_enable_writing()

try:
    await device.rk1.set_room_setpoint_day(21.5)
finally:
    await device.async_disable_writing()

The default write-access code is provided by the library and may be overridden by the application.

The top-level object also exposes:

is_enabled = await device.async_read_writing_enabled()

The local device.writing_enabled property represents whether writing was enabled through the current library object. It is not a substitute for a direct controller read when another client may change the state.

Generic datapoint writes

Components support metadata-driven writes:

await component.async_write_datapoint(field, value)

Before writing, the library can perform:

• writable-state checks,
• type conversion,
• enum conversion,
• range validation,
• step validation,
• signed and scaled encoding,
• TROVIS write-access refresh,
• field-specific preconditions,
• one or more ordered register or coil writes.

This keeps application code free from raw address calculations.

Write safety

Not every readable datapoint should automatically become writable. A field is marked writable only when the controller documentation and implementation support a verified write path.

Special command registers that may trigger controller actions, firmware operations, resets, or restarts remain read-only until their command values, ordering, and consequences are fully understood.

Applications should still provide their own user-facing safety controls. The library validates controller rules; it does not decide who is authorized to change a building system.

Operating modes and control levels

A TROVIS control circuit is not a conventional on/off thermostat. Its behavior is split across:

• an operating-mode register,
• a control-level coil,
• room and flow setpoints,
• heating curves,
• setback behavior,
• pumps and valves,
• controller-wide states.

Operating modes

The shared operating-mode enum models:

Raw value	Meaning
0	Program
1	Automatic
2	Standby
3	Manual
4	Day
5	Night

A complete shared enum is used even when a specific physical selector exposes only a subset of these positions.

Automatic mode

Automatic has special TROVIS semantics:

• it changes the corresponding control-level coil to autonomous operation,
• it does not overwrite the stored operating-mode register.

Other operating modes use the supervisory or control level before writing the mode register.

This behavior belongs in the library because it is a controller rule, not a presentation detail.

Readable control state

Control-level coils are also available as readable state so applications can show whether a circuit or domestic-hot-water function is operating autonomously or under supervisory control.

Native date and time values

Raw DDMM and HHMM registers are converted to native Python types.

Controller time

The controller time is exposed as:

datetime.time

The controller has minute resolution.

Controller date

The complete controller date is composed from:

• the DDMM register,
• the year register.

It is exposed as:

datetime.date

When writing a complete date, the library writes the year first and then the day/month value. This ordering avoids transient invalid combinations around month lengths and leap years.

Recurring month/day values

Some controller dates are year-independent recurring dates. They are represented by the library's MonthDay type instead of inventing an arbitrary year.

MonthDay(month=5, day=15)

The application decides how to present a yearless recurring date in its user interface.

Thermal disinfection times

Domestic-hot-water disinfection start and stop values are native datetime.time objects and are validated against the documented controller range.

Derived values

Some useful values do not correspond to one physical register. The library may derive them when the calculation is controller-specific and broadly useful.

System activity

device.system_activity combines heating and domestic-hot-water operation into a single enum-like state:

State	Meaning
IDLE	Neither heating nor domestic-hot-water charging is active
HEATING	At least one built-in Rk1-Rk3 pump is active
DOMESTIC_HOT_WATER	Domestic-hot-water charging is active
HEATING_AND_DOMESTIC_HOT_WATER	Both are active

The value is None when none of the required pump states is available.

Domestic-hot-water temperature ranges

The library exposes calculated day and night temperature ranges based on the relevant setpoints, switching differential, and hold values.

These replace presentation templates while keeping the calculation close to the controller semantics.

Prefer direct values when available

A derived estimate should not duplicate a better direct register. For example, a direct active charging setpoint should be preferred over reconstructing the same information from a sensor value and configured elevation.

Exceptions

Controller-specific validation and write failures use library exceptions so an application can distinguish them from transport errors. Important categories include:

• write access disabled,
• write access rejected,
• unsupported or unimplemented writes,
• invalid values.

Transport and connection failures remain the responsibility of the selected modbus-connection backend.