diff --git a/README.md b/README.md index 1932ef1..7d7f4f0 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,7 @@ Async Python library for Thermia heat pumps on the **Genesis** platform (Atlas, Calibra E, Calibra Cool, Calibra RXT, Diplomat Inverter), using Modbus via [`modbus-connection`](https://home-assistant-libs.github.io/modbus-connection/). -> **Status:** early development. Only Genesis firmware 17.1 is targeted. +> **Status:** early development. Genesis firmware 17.1 is targeted; 18.0 reads the same. This library powers the [Thermia Genesis Home Assistant integration](https://github.com/klconsultancy/ha-thermia-genesis). diff --git a/docs/design.md b/docs/design.md index 1ead7dc..07af7ba 100644 --- a/docs/design.md +++ b/docs/design.md @@ -10,9 +10,11 @@ Domain terms are defined in [`CONTEXT.md`](../CONTEXT.md). - Thermia heat pumps on the **Genesis** platform (Atlas, Calibra, Calibra E, Calibra Cool, Calibra RXT, Diplomat Inverter), controlled over **Modbus**. - Only firmware **17.1** is implemented. The register map lives in a per-version module - (`v17_1`) so other versions can be added side by side later. -- Reference hardware: Calibra 7, firmware 17.1.11, Modbus TCP, EM3 extension module with - passive cooling. + (`v17_1`) so other versions can be added side by side later. Firmware **18.0** uses the + same map: the reference pump's dump on 18.0.1 matched it address for address (errata), and + no protocol document for 18.0 is available yet. +- Reference hardware: Calibra 7, Modbus TCP, EM3 extension module with passive cooling; + firmware 17.1.11 until November 2026, then 18.0.1 (it updated itself). - Modbus TCP first. RTU is not excluded: `modbus-connection` already supports serial and RTU-over-TCP, so adding it is mostly config-flow work in the integration. - Read first, then writes: the write API (#19, see Public API) covers a few settings so @@ -231,7 +233,7 @@ await pump.status.write(Status.operational_mode, OperationalMode.STANDBY) - The firmware version is read from input registers 311–313 (major, minor, micro), with every update. `pump.firmware_version` is a `FirmwareVersion` named tuple (`str()` gives "17.1.11", it compares as a tuple), or `None` until an update has read it. -- On a major/minor version other than 17.1 the library still uses the 17.1 map; +- On a major/minor version other than 17.1 or 18.0 the library still uses the 17.1 map; `FirmwareVersion.supported` is then `False`, and the caller decides how to warn (the Home Assistant integration raises a repair issue). - Optional subsystems are detected from their "Enable ..." coils: mix valve 1 coil 11, HGW diff --git a/docs/errata.md b/docs/errata.md index 4882499..68c97b2 100644 --- a/docs/errata.md +++ b/docs/errata.md @@ -31,6 +31,7 @@ field report from another pump. | Scale 100 (chapter 2.1) | The scale table says the transmitted value is "a tenfold larger"; the worked example in the same section transmits -5 °C as -500. | Hundredfold (the worked example; the reference pump's discharge pipe reads 2667: 26.67 °C, not 266.7 °C). | | Footnote \*5 "Should always be set to 1 i auto mode" | Printed under the coil table of chapter 3 and with the footnotes of chapter 9, but no register refers to it. | Not applied to any register. To be verified which register it belongs to. | | Footnotes | Printed at the end of chapter 9 instead of in their own chapter (as in 17.0). | Treated as document-wide footnotes. | +| Firmware 18.0 | No protocol document for 18.0 is available. The reference pump updated itself from 17.1.11 to 18.0.1 (noticed 2026-11-18). Its dump (`tests/fixtures/calibra7-18.0.1.json`) reads the same addresses as on 17.1.11, with no failed read and no change in any holding register; the input registers that differ follow from the compressor running during the 18.0.1 dump and idle during the 17.1.11 one. | 18.0 uses the 17.1 map and counts as supported. A register 18.0 adds, or a changed meaning behind an equal value, would not show in a dump. | ## Undocumented behaviour diff --git a/src/thermia_genesis/firmware.py b/src/thermia_genesis/firmware.py index 8782e4a..2de6560 100644 --- a/src/thermia_genesis/firmware.py +++ b/src/thermia_genesis/firmware.py @@ -2,8 +2,9 @@ from typing import NamedTuple -# The firmware the register map is written for; docs/design.md (Scope). -SUPPORTED = (17, 1) +# The firmware versions the register map is written for or checked against; +# docs/design.md (Scope). +SUPPORTED = frozenset({(17, 1), (18, 0)}) class FirmwareVersion(NamedTuple): @@ -19,5 +20,5 @@ def __str__(self) -> str: @property def supported(self) -> bool: - """Whether the register map is written for this major.minor version (17.1).""" - return (self.major, self.minor) == SUPPORTED + """Whether the register map applies to this major.minor version (17.1 or 18.0).""" + return (self.major, self.minor) in SUPPORTED diff --git a/tests/fixtures/calibra7-18.0.1.json b/tests/fixtures/calibra7-18.0.1.json new file mode 100644 index 0000000..c52a37b --- /dev/null +++ b/tests/fixtures/calibra7-18.0.1.json @@ -0,0 +1,514 @@ +{ + "firmware": "18.0.1", + "parts": { + "mix_valve_1": false, + "hgw": false, + "cooling": true, + "pool": false, + "electric_meter": false + }, + "registers": { + "coil": { + "3": false, + "5": false, + "6": false, + "7": false, + "8": true, + "9": true, + "10": false, + "11": false, + "14": false, + "20": false, + "21": false, + "22": false, + "25": false, + "26": false, + "28": false, + "33": true, + "34": false, + "35": true, + "39": false, + "40": false, + "41": false, + "42": false, + "59": true, + "60": false, + "61": false + }, + "discrete": { + "0": false, + "1": false, + "2": false, + "3": false, + "9": false, + "10": false, + "11": false, + "12": false, + "13": false, + "14": false, + "15": false, + "16": false, + "22": false, + "23": false, + "24": false, + "25": false, + "26": false, + "27": false, + "28": false, + "29": false, + "30": false, + "31": false, + "32": false, + "33": false, + "34": false, + "35": false, + "47": false, + "49": false, + "50": false, + "55": false, + "56": false, + "57": false, + "66": false, + "67": false, + "74": false, + "75": false, + "78": false, + "79": true, + "83": false, + "84": false, + "85": false, + "86": false, + "87": false, + "199": true, + "201": false, + "202": false, + "204": false, + "206": false, + "210": true, + "211": false, + "218": true, + "219": false, + "220": true, + "221": false, + "224": false, + "225": true, + "236": false, + "238": false, + "240": false, + "242": false, + "246": false + }, + "input": { + "1": 4, + "2": 8, + "4": 900, + "5": 1200, + "6": 0, + "7": 4058, + "8": 2382, + "9": 2504, + "10": 898, + "11": 736, + "12": 20000, + "13": 929, + "15": 5055, + "16": 4979, + "17": 5006, + "18": 2437, + "19": 3000, + "20": 1700, + "21": 1000, + "22": 500, + "23": 0, + "24": 65036, + "25": 64036, + "26": 63036, + "27": 20000, + "30": 39, + "36": 65386, + "39": 10000, + "41": 20000, + "44": 5000, + "47": 0, + "48": 0, + "49": 11064, + "50": 0, + "51": 1539, + "52": 0, + "53": 0, + "54": 2791, + "55": 99, + "56": 99, + "60": 0, + "61": 100, + "62": 4, + "63": 99, + "64": 99, + "65": 99, + "66": 99, + "67": 0, + "68": 0, + "82": 4, + "106": 2356, + "121": 230, + "122": 2575, + "123": 2587, + "124": 666, + "125": 283, + "126": 170, + "127": 881, + "128": 1590, + "129": 2405, + "130": 949, + "131": 65386, + "137": 0, + "139": 0, + "140": 1, + "141": 0, + "143": 0, + "145": 1, + "146": 1, + "157": 268, + "158": 36, + "160": 0, + "161": 0, + "162": 0, + "163": 0, + "311": 18, + "312": 0, + "313": 1, + "315": 3443, + "319": 26, + "348": 0, + "349": 0, + "350": 71, + "351": 1, + "352": 156, + "353": 7, + "354": 67, + "355": 170, + "356": 6, + "357": 41, + "358": 0, + "359": 622, + "360": 0, + "361": 982, + "362": 1, + "363": 32, + "364": 396, + "365": 1, + "380": 0, + "381": 0, + "382": 208, + "383": 1, + "384": 986, + "385": 7, + "386": 66, + "387": 908, + "388": 6, + "389": 39, + "390": 0, + "391": 664, + "392": 0, + "393": 63, + "394": 2, + "395": 31, + "396": 448, + "397": 1 + }, + "holding": { + "0": 3, + "3": 4000, + "4": 2000, + "5": 2200, + "6": 2300, + "7": 2700, + "8": 2900, + "9": 3100, + "10": 3200, + "11": 3700, + "12": 4100, + "16": 2100, + "22": 4500, + "23": 5500, + "26": 1, + "27": 9, + "28": 7, + "29": 5, + "30": 1800, + "49": 0, + "50": 10000, + "61": 300, + "63": 60, + "67": 2000, + "68": 65036, + "69": 64036, + "70": 600, + "75": 65530, + "76": 3300, + "77": 5000, + "78": 400, + "79": 10000, + "80": 10000, + "81": 10000, + "82": 5000, + "87": 1, + "88": 9, + "105": 1800, + "106": 1300, + "116": 2500, + "117": 0, + "118": 20000, + "119": 16, + "120": 2, + "124": 0, + "125": 0, + "304": 1000, + "321": 2 + } + }, + "values": { + "heat_pump": { + "reset_all_alarms": false, + "enable_external_additional_heater": false, + "enable_flow_pressure_switch": false, + "enable_tap_water": true, + "enable_heat": true, + "enable_brine_out_monitoring": false, + "enable_brine_pump_continuous_operation": false, + "enable_system_circulation_pump": false, + "enable_additional_heater_only": false, + "enable_variable_speed_condenser_pump": false, + "enable_variable_speed_brine_pump": true, + "enable_outdoor_temperature_dependent_external_heater": false, + "enable_brine_in_monitoring": false, + "enable_evaporator_freeze_protection": false, + "enable_continuous_condenser_pump": true, + "current_limiter_restricts_external_additional_heater": false, + "current_limiter_restricts_secondary_units": false, + "alarm_class_a": false, + "alarm_class_b": false, + "alarm_class_c": false, + "alarm_class_d": false, + "high_pressure_switch_alarm": false, + "low_pressure_level_alarm": false, + "high_discharge_pipe_temperature_alarm": false, + "operating_pressure_limit_indication": false, + "discharge_pipe_sensor_alarm": false, + "liquid_line_sensor_alarm": false, + "suction_gas_sensor_alarm": false, + "flow_pressure_switch_alarm": false, + "power_input_phase_detection_alarm": false, + "inverter_unit_alarm": false, + "compressor_low_speed_alarm": false, + "low_super_heat_alarm": false, + "pressure_ratio_out_of_range_alarm": false, + "compressor_pressure_outside_envelope_alarm": false, + "brine_temperature_out_of_range_alarm": false, + "brine_in_sensor_alarm": false, + "brine_out_sensor_alarm": false, + "condenser_in_sensor_alarm": false, + "condenser_out_sensor_alarm": false, + "outdoor_sensor_alarm": false, + "brine_delta_out_of_range_alarm": false, + "brine_in_high_temperature_alarm": false, + "brine_in_low_temperature_alarm": false, + "brine_out_low_temperature_alarm": false, + "sum_alarm": false, + "inverter_unit_communication_alarm": false, + "secondary_unit_communication_alarm": false, + "other_primary_units_alarm": false, + "missing_secondary_units_alarm": false, + "tap_water_top_sensor_alarm": false, + "external_alarm_input": false, + "external_relay_brine_ground_water_pump": true, + "oil_boost_in_progress": false, + "compressor_control_signal": true, + "smart_grid_1_evu_input": false, + "smart_grid_2": false, + "external_additional_heater_control_signal": false, + "condenser_pump_on": true, + "brine_pump_on": true, + "external_heater_circulation_pump_control_signal": false, + "external_additional_heater_active": false, + "stopping": false, + "ok_to_start": true, + "compressor_unable_to_speed_up": false, + "compressor_available_gears": 9.0, + "compressor_speed": 1200, + "compressor_speed_percent": 27.91, + "compressor_start_restriction_timer": 0, + "compressor_current_gear": 1.0, + "compressor_operating_hours": 11064, + "expansion_valve_opening_degree": 34.43, + "inverter_temperature": 26, + "discharge_pipe_temperature": 40.58, + "condenser_in_temperature": 23.82, + "condenser_out_temperature": 25.04, + "brine_in_temperature": 8.98, + "brine_out_temperature": 7.36, + "outdoor_temperature": 9.29, + "room_temperature": 23.0, + "liquid_line_temperature": 24.05, + "suction_gas_temperature": 9.49, + "bubble_point_high_pressure_temperature": 25.75, + "dew_point_high_pressure_temperature": 25.87, + "dew_point_low_pressure_temperature": 6.66, + "superheat_temperature": 2.83, + "sub_cooling_temperature": 1.7, + "low_pressure_side_pressure": 8.81, + "high_pressure_side_pressure": 15.9, + "condenser_circulation_pump_speed": 100.0, + "brine_circulation_pump_speed": 50.0, + "external_additional_heater_current_demand": 0.0, + "external_additional_heater_operating_hours": 0, + "internal_immersion_heater_active_step": 0, + "current_power_output": 2.68, + "current_consumed_power": 0.36, + "cooling_season_integral_value": -150, + "heating_season_integral_value": -150, + "smart_grid_mode": "NORMAL", + "available_secondaries": 0, + "total_distributed_gears": 1, + "maximum_requested_gear": 1, + "secondaries_class_d_alarm": 0, + "secondaries_communication_alarm": 0, + "secondaries_class_a_alarm": 0, + "secondaries_class_b_alarm": 0, + "software_version_major": 18, + "software_version_minor": 0, + "software_version_micro": 1, + "minimum_allowed_gear_in_heating": 1, + "maximum_allowed_gear_in_heating": 9, + "gear_shift_delay_heating": 300, + "brine_in_high_alarm_limit": 20.0, + "brine_in_low_alarm_limit": -5.0, + "brine_out_low_alarm_limit": -15.0, + "brine_max_delta_limit": 6.0, + "external_additional_heater_start": -6, + "external_additional_heater_stop": 4.0, + "external_heater_outdoor_temperature_limit": 10.0, + "enabled_immersion_heater": "INTERNAL", + "condenser_pump_lowest_allowed_speed": 33.0, + "brine_pump_lowest_allowed_speed": 50.0, + "condenser_pump_highest_allowed_speed": 100.0, + "brine_pump_highest_allowed_speed": 100.0, + "condenser_pump_standby_speed": 100.0, + "brine_pump_standby_speed": 50.0, + "outdoor_temperature_source": "PT1000_SENSOR", + "bms_outdoor_temperature": null, + "maximum_phase_current": 16, + "compressor_current_hysteresis": 2, + "power_consumption_control_mode": 0, + "input_power_limit": 0.0 + }, + "heat": { + "enable_fixed_system_supply_set_point": false, + "system_supply_low_temperature_alarm": false, + "system_supply_line_sensor_alarm": false, + "room_temperature_sensor_alarm": false, + "system_circulation_pump_control_signal": false, + "heating_season_active": true, + "system_supply_line_temperature": null, + "system_supply_line_calculated_set_point": 24.37, + "system_return_line_temperature": null, + "calculated_demand": 0.39, + "desired_gear": 1, + "selected_heat_curve_supply_line": 30.0, + "heat_curve_x_1": 17.0, + "heat_curve_x_2": 10.0, + "heat_curve_x_3": 5.0, + "heat_curve_x_4": 0.0, + "heat_curve_x_5": -5.0, + "heat_curve_x_6": -15.0, + "heat_curve_x_7": -25.0, + "buffer_tank_temperature": null, + "buffer_tank_charge_set_point": 0.0, + "max_limitation_set_point_curve": 40.0, + "min_limitation_set_point_curve": 20.0, + "comfort_wheel_setting": 22.0, + "heating_season_stop_temperature": 21.0, + "fixed_system_supply_set_point": 25.0, + "heat_curve_y_1": 23.0, + "heat_curve_y_2": 27.0, + "heat_curve_y_3": 29.0, + "heat_curve_y_4": 31.0, + "heat_curve_y_5": 32.0, + "heat_curve_y_6": 37.0, + "heat_curve_y_7": 41.0 + }, + "tap_water": { + "enable_hot_gas_pump": false, + "mid_sensor_alarm": false, + "top_temperature": 50.55, + "lower_temperature": 49.79, + "weighted_temperature": 50.06, + "valve_position": 0, + "operating_hours": 1539, + "desired_gear": 0, + "start_temperature": 45.0, + "stop_temperature": 55.0, + "maximum_allowed_gear": 7, + "minimum_allowed_gear": 5 + }, + "cooling": { + "enable_active_cooling": false, + "enable_passive_cooling": true, + "supply_line_sensor_alarm": false, + "circuit_supply_line_temperature_deviation_alarm": false, + "external_start_brine_pump": false, + "circuit_circulation_pump_control_signal": false, + "surplus_heat_directional_valve_position": false, + "circuit_regulation_control_signal": false, + "active_cooling_directional_valve_position": false, + "circuit_supply_line_temperature": 23.56, + "mix_valve_opening_degree": 0.0, + "desired_gear": 0, + "start_temperature": 18.0, + "stop_temperature": 13.0, + "gear_shift_delay": 60, + "minimum_allowed_gear": 1, + "maximum_allowed_gear": 9, + "mix_valve_set_point": 18.0, + "supply_line_mix_valve_lowest_allowed_opening_degree": 0.0, + "supply_line_mix_valve_highest_allowed_opening_degree": 100.0 + }, + "status": { + "running_demand_1": "HEAT", + "running_demand_2": "NO_DEMAND", + "running_demand_3": "NO_DEMAND", + "running_demands": [ + "HEAT" + ], + "queued_demand_1": "HEAT", + "queued_demand_2": "NO_DEMAND", + "queued_demand_3": "NO_DEMAND", + "queued_demand_4": "NO_DEMAND", + "queued_demand_5": "NO_DEMAND", + "operational_mode": "ON_AUTO" + }, + "energy_statistics": { + "heating_aux_heater_months_1_to_12": 0, + "heating_consumed_months_1_to_12": 1071, + "heating_delivered_months_1_to_12": 7156, + "heating_cop_months_1_to_12": 6.7, + "heating_natural_source_months_1_to_12": 6170, + "tap_water_aux_heater_months_1_to_12": 41, + "tap_water_consumed_months_1_to_12": 622, + "tap_water_delivered_months_1_to_12": 1982, + "tap_water_cop_months_1_to_12": 3.2, + "tap_water_natural_source_months_1_to_12": 1396, + "heating_aux_heater_months_13_to_24": 0, + "heating_consumed_months_13_to_24": 1208, + "heating_delivered_months_13_to_24": 7986, + "heating_cop_months_13_to_24": 6.6, + "heating_natural_source_months_13_to_24": 6908, + "tap_water_aux_heater_months_13_to_24": 39, + "tap_water_consumed_months_13_to_24": 664, + "tap_water_delivered_months_13_to_24": 2063, + "tap_water_cop_months_13_to_24": 3.1, + "tap_water_natural_source_months_13_to_24": 1448 + } + }, + "failed": {} +} diff --git a/tests/test_firmware.py b/tests/test_firmware.py index f5a3bfe..391c2f0 100644 --- a/tests/test_firmware.py +++ b/tests/test_firmware.py @@ -21,6 +21,17 @@ async def test_reads_the_firmware_version(mock_modbus_unit: MockModbusUnit) -> N assert version >= (17, 1) +async def test_reports_firmware_18_0_as_supported(mock_modbus_unit: MockModbusUnit) -> None: + # The reference pump updated itself to 18.0.1; its dump matches the 17.1 map (errata). + mock_modbus_unit.input[311] = [18, 0, 1] + pump = ThermiaGenesis(mock_modbus_unit) + + await pump.async_update() + + assert pump.firmware_version == FirmwareVersion(18, 0, 1) + assert pump.firmware_version.supported + + def test_has_no_firmware_version_before_the_first_update( mock_modbus_unit: MockModbusUnit, ) -> None: @@ -31,14 +42,14 @@ def test_has_no_firmware_version_before_the_first_update( async def test_reports_another_firmware_as_unsupported(mock_modbus_unit: MockModbusUnit) -> None: # The 17.1 map is still used; the caller decides how to warn. - mock_modbus_unit.input[311] = [18, 0, 2] + mock_modbus_unit.input[311] = [19, 0, 2] mock_modbus_unit.input[13] = 905 pump = ThermiaGenesis(mock_modbus_unit) await pump.async_update() version = pump.firmware_version - assert version == FirmwareVersion(18, 0, 2) + assert version == FirmwareVersion(19, 0, 2) assert not version.supported assert pump.heat_pump.outdoor_temperature == 9.05