diff --git a/CONTEXT.md b/CONTEXT.md index 319581a..f33907b 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -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. diff --git a/docs/design.md b/docs/design.md index 07af7ba..ff9f2f0 100644 --- a/docs/design.md +++ b/docs/design.md @@ -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. diff --git a/docs/errata.md b/docs/errata.md index 68c97b2..be7b802 100644 --- a/docs/errata.md +++ b/docs/errata.md @@ -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. | +| 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. | diff --git a/src/thermia_genesis/v17_1/enums.py b/src/thermia_genesis/v17_1/enums.py index 70ea22e..c3a5f65 100644 --- a/src/thermia_genesis/v17_1/enums.py +++ b/src/thermia_genesis/v17_1/enums.py @@ -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 class OutdoorTemperatureSource(IntEnum): diff --git a/src/thermia_genesis/v17_1/heat_pump_unit.py b/src/thermia_genesis/v17_1/heat_pump_unit.py index a02bac0..fb17fa2 100644 --- a/src/thermia_genesis/v17_1/heat_pump_unit.py +++ b/src/thermia_genesis/v17_1/heat_pump_unit.py @@ -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="%")) diff --git a/tests/test_v17_1_decoding.py b/tests/test_v17_1_decoding.py index c1a1835..964bf42 100644 --- a/tests/test_v17_1_decoding.py +++ b/tests/test_v17_1_decoding.py @@ -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). diff --git a/tests/test_v17_1_register_map.py b/tests/test_v17_1_register_map.py index 6527c04..311e134 100644 --- a/tests/test_v17_1_register_map.py +++ b/tests/test_v17_1_register_map.py @@ -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()}