Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion CONTEXT.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,9 @@ marked "(EM)" only exist with an extension module.
: The user-selected mode of the pump: off, standby or on/auto.

**Smart grid mode**
: The external energy-tariff mode: EVU, normal, comfort or boost.
: The power consumption mode in force, as input 82 reports it: EVU, normal, comfort or boost
from an external tariff signal or the BMS, or power limit when the PL/LU power consumption
control caps the pump's input power.

**Primary / secondary unit**
: In cascaded installations one primary controller drives secondary heat pump units.
Expand Down
3 changes: 2 additions & 1 deletion docs/design.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,8 @@ Domain terms are defined in [`CONTEXT.md`](../CONTEXT.md).
transcribed in [`docs/protocol/17.1`](protocol/17.1/). It decides address, register space,
scale and unit, unless [`errata.md`](errata.md) records otherwise (for example the unit of
holding 58). Chapters 4–9 are only used to group registers per subsystem. Enum and
bit-flag values come from the footnotes.
bit-flag values come from the footnotes, plus the values the errata add (for example 10,
power limit, on input 82).
- Registers are **hand-written** with `modbus_connection.model` field types (`gauge`,
`integer`, `coil`, `discrete_input`, `enum`, ...). No CSV or code generator:
the map is small enough that readable, reviewable code wins.
Expand Down
6 changes: 4 additions & 2 deletions docs/errata.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,8 +13,10 @@ field report from another pump.
| Coil 25 "Enable additional heater only" | Scale 1 in chapter 3, scale 100 in chapter 4. | Scale 1 (chapter 3; coils are bits). |
| Holding registers 61–63 "Gear shift delay heating / pool / cooling" | Unit listed as `min`; the reference pump reads 300, 300 and 60. The display shows the heating delay (300) as "Schakelvertraging 0:05:00" (2026-10-25). | Seconds (`unit="s"`), as the display shows; the protocol document 17.0 and the Mega & Mega E edition of 17.1 ("Modbus protocol for Mega & Mega E, Genesis platform, Version 17.1", ACME01UG01202; PDF dated 2025-12-04) list all three in `s`. |
| Holding register 30 "Cooling mix valve set point (EM)" | Unit listed as `%`, but it is the display setting "Gewenste koelaanvoer min." (desired cooling supply minimum, 18 °C): on 2026-10-25, changing it on the display to 19 °C made holding 30 read 1900 while holding 105 "Start temp for cooling" stayed 1800, and no other holding register changed. | `°C` at scale 100, with `nan=ABSENT_SENSOR`; the protocol document 17.0 and the Mega & Mega E edition of 17.1 ("Modbus protocol for Mega & Mega E, Genesis platform, Version 17.1", ACME01UG01202; PDF dated 2025-12-04) list it in `°C`. |
| Holding register 125 "Input power limit during Power Limitation" | The description calls itself "defacto 40125", but its de facto address is 40126; 40125 is register 124, whose own description refers to 40126 for the power limit. | Address 125 (the Address column). |
| Holding register 124 "Desired Power Consumption Control, control mode" | The meaning of each value depends on the controller's power consumption control mode, which an installer sets and Modbus can't read: in SG-Ready mode 0 Normal, 1 Load-Up, 2 EVU, 3 Boost; in PL/LU mode 0 Normal, 1 and 3 Power Limit (holding 125), 2 Load-Up. So 2 blocks the compressor in one mode and asks for more heat in the other. The reference pump's installer menu shows "Verbruiksregeling: Geen" (2026-10-25): no mode is configured, so it presumably ignores 124 and 125 (not tested). | An unsigned integer, writable from 0 to 3, not an enum: the library can't tell which meaning applies. The active Smart Grid mode reads back on input 82 (`smart_grid_mode`). |
| Holding register 125 "Input power limit during Power Limitation" | The description calls itself "defacto 40125", but its de facto address is 40126; 40125 is register 124, whose own description refers to 40126 for the power limit. It reads 0.0 kW out of the box and is volatile: on 2026-11-18 (firmware 18.0.1) a power cycle of the controller reset a written 1.0 kW to 0.0 kW. The display shows it with six decimals. | Address 125 (the Address column). |
| Input register 60 "Compressor temporarily blocked, (start restriction timer)" | No unit. After the compressor stopped on 2026-11-18 (firmware 18.0.1), the display counted down from 5 minutes while input 60 read 123 and, 101 s later, 22; the brine pump started when it reached 0, the compressor some 45 s later. | Seconds (`unit="s"`). |
| Input register 82 "Current Smart Grid mode" | Footnote *4 lists 1 EVU, 4 Normal, 5 Comfort and 6 Boost. In PL/LU mode with holding 124 = 1 the reference pump reads 10 while its display shows "Huidige modus: Vermogensbegrenzing" (2026-11-18, firmware 18.0.1). | `SmartGridMode.POWER_LIMIT = 10`. The value for Load-Up in PL/LU mode is still unknown. |
Comment thread
kristoflemmens marked this conversation as resolved.
Resolved
| Holding register 124 "Desired Power Consumption Control, control mode" | The meaning of each value depends on the controller's power consumption control mode, which an installer sets and Modbus can't read: in SG-Ready mode 0 Normal, 1 Load-Up, 2 EVU, 3 Boost; in PL/LU mode 0 Normal, 1 and 3 Power Limit (holding 125), 2 Load-Up. So 2 blocks the compressor in one mode and asks for more heat in the other. The mode is set in the installer menu, *Installatie* page 6, "Verbruiksregeling" (power consumption control), whose own pages show "Invoermodus" (the mode), "Huidige modus" (the active value of 124) and "Vermogensbegrenzing – BMS" (holding 125). The reference pump came with "Geen" (none, 2026-10-25) and was set to PL/LU on 2026-11-18 (firmware 18.0.1): writing 124 = 1 made "Huidige modus" show "Vermogensbegrenzing" and input 82 read 10, and a limit of 0.3 kW in 125, below the 0.36 kW of the lowest gear, stopped the compressor about 1.5 minutes later (klconsultancy/ha-thermia-genesis#45). | An unsigned integer, writable from 0 to 3, not an enum: the library can't tell which meaning applies. The active Smart Grid mode reads back on input 82 (`smart_grid_mode`). |
| Write ranges | The document gives no range for any setting. | The validators use the ranges of CJNE/thermiagenesis, whose climate entities limit the comfort wheel (holding 5) to 10–40 °C and the tap water start and stop temperatures (holding 22, 23) to 35–60 °C; they are not Thermia's. The power limit (holding 125) takes 0 to 3276.7 kW, what its signed register holds: the document warns that a limit set too low stops the compressor, but gives no minimum and no maximum. To be checked against what the display allows. On 2026-11-10 the reference pump accepted a write of the comfort wheel (holding 5) from 22.0 to 21.5 °C: the next read returned 21.5, and writing 22.0 back restored it. |
| Input register 137 "Mix valve cooling opening degree (EM2/3)" | Chapter 7 lists the unit as `on/off` for an opening degree; chapter 3 lists `%` at scale 1. A Calibra Cool reads 0 to 10000 from a closed to a fully open valve (CJNE/thermiagenesis#284), so the scale is 100. The reference pump reads 0 outside the cooling season. | `%` at scale 100. To be verified on the reference pump while passive cooling runs. |
| Coil 14 "Enable hot gas pump" and the HGW registers: coil 6 "Enable HGW", discrete 52 "HGW sensor alarm", discrete 223 "HGW regulation control signal", input 45 "HGW supply line temperature" | Listed only in chapter 6 (coil 14 in 6.1, the others in 6.2), not in chapter 3. The reference pump has no HGW: the coils and discrete inputs read `False`, input 45 reads 20000. | Mapped from chapter 6. |
Expand Down
3 changes: 2 additions & 1 deletion src/thermia_genesis/v17_1/enums.py
Original file line number Diff line number Diff line change
Expand Up @@ -4,12 +4,13 @@


class SmartGridMode(IntEnum):
"""Current Smart Grid mode (footnote *4)."""
"""Current Smart Grid mode (footnote *4, and 10 from the errata)."""

EVU = 1
NORMAL = 4
COMFORT = 5
BOOST = 6
POWER_LIMIT = 10
Comment thread
kristoflemmens marked this conversation as resolved.
Resolved


class OutdoorTemperatureSource(IntEnum):
Expand Down
2 changes: 1 addition & 1 deletion src/thermia_genesis/v17_1/heat_pump_unit.py
Original file line number Diff line number Diff line change
Expand Up @@ -91,7 +91,7 @@ class HeatPumpUnit(Subsystem):
compressor_available_gears = input_register(gauge(4, 0.01))
compressor_speed = input_register(integer(5, signed=False, unit="rpm"))
compressor_speed_percent = input_register(gauge(54, 0.01, unit="%"))
compressor_start_restriction_timer = input_register(integer(60, signed=False))
compressor_start_restriction_timer = input_register(integer(60, signed=False, unit="s"))
compressor_current_gear = input_register(gauge(61, 0.01))
compressor_operating_hours = input_register(uint32(48, unit="h"))
expansion_valve_opening_degree = input_register(gauge(315, 0.01, unit="%"))
Expand Down
11 changes: 11 additions & 0 deletions tests/test_v17_1_decoding.py
Original file line number Diff line number Diff line change
Expand Up @@ -109,6 +109,17 @@ async def test_reads_enum_from_footnote(mock_modbus_unit: MockModbusUnit) -> Non
assert pump.heat_pump.smart_grid_mode is SmartGridMode.NORMAL


async def test_reads_the_power_limit_smart_grid_mode(mock_modbus_unit: MockModbusUnit) -> None:
# Not in footnote *4: in PL/LU mode with holding 124 = 1, the reference pump reads 10
# while its display shows "Vermogensbegrenzing" (errata).
mock_modbus_unit.input[82] = 10
pump = ThermiaGenesis(mock_modbus_unit)

await pump.async_update()

assert pump.heat_pump.smart_grid_mode is SmartGridMode.POWER_LIMIT


async def test_reads_enums_of_the_reference_pump(mock_modbus_unit: MockModbusUnit) -> None:
# The reference pump uses its own outdoor sensor (chapter 3.4, register 117: 0) and has
# the internal immersion heater enabled (footnote *7: 2).
Expand Down
2 changes: 2 additions & 0 deletions tests/test_v17_1_register_map.py
Original file line number Diff line number Diff line change
Expand Up @@ -113,6 +113,8 @@ def read_table(path: Path) -> dict[Key, DocumentedRegister]:
("holding", 61): "s",
("holding", 62): "s",
("holding", 63): "s",
# The display counts the restart down from 5 minutes; input 60 reads 123, then 22.
("input", 60): "s",
}
DOCUMENTED |= {key: DOCUMENTED[key]._replace(unit=unit) for key, unit in UNIT_ERRATA.items()}

Expand Down