Gets information from the Kronoterm heat pump connected to Modbus TEX interface. While this should work for all Kronoterm heat pumps the software was verified to run on ETERA ground source heat pump with Heat pump manager V3.13-1 and WPG-10-K2 HT ground source heat pump with Heat pump manager V2.12-1 (19200 baud rate). From the Kronoterm modbus specification the registers are the same for all Kronoterm heat pumps.
While reading Modbus registers from the pump the kronoterm2mqtt sends MQTT discovery events from KRONOTERM to MQTT broker (Mosquito) that Home Assistant then reads and the sensor readings appear therein automatically.
Optionally, the MQTT loop can also control custom (DIY) IO expander to be added to heat pump controlling additional heating loops and pumps for solar DHW pre-heat boiler. This expander board is using Arduino nano MCU to provide serial (UART) interface for Raspberry Pi control. See Etera UART GPIO expander project for help on the protocol and interface. By default, this module functionality is disabled so that only Kronoterm Heat Pump MQTT can still be used without having this hardware module.
Clone the sources and just call the CLI to create a Python Virtualenv, e.g.:
~$ git clone --recursive https://github.com/kosl/kronoterm2mqtt.git
~$ cd kronoterm2mqtt
~/kronoterm2mqtt$ ./cli.py --helpThe output of ./cli.py --help looks like:
kronoterm2mqtt v0.1.8 bed9746 (/home/leon/kronoterm2mqtt)
Usage: ./cli.py [OPTIONS] COMMAND [ARGS]...
╭─ Options ────────────────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────────────────╮
│ edit-settings Edit the settings file. On first call: Create the default one. │
│ print-registers Print RAW modbus register data │
│ print-settings Display (anonymized) MQTT server username and password │
│ print-values Print all values from the definition │
│ probe-usb-ports Probe through the USB ports and print the values from definition │
│ publish-loop Publish KRONOTERM registers to Home Assistant MQTT │
│ systemd-debug Print Systemd service template + context + rendered file content. │
│ systemd-remove Remove Systemd service file. (May need sudo) │
│ systemd-setup Write Systemd service file, enable it and (re-)start the service. │
│ (May need sudo) │
│ systemd-status Display status of systemd service. (May need sudo) │
│ systemd-stop Stops the systemd service. (May need sudo) │
│ test-mqtt-connection Test connection to MQTT Server │
│ version Print version and exit │
╰──────────────────────────────────────────────────────────────────────────────────────────╯
Project Homepage: https://github.com/kosl/kronoterm2mqttOnce having hardware (Modbus wiring) correctly installed the steps to get running are:
./cli-app.py edit-settingto configure MQTT host and credentials, heat pump model and RS485 port../cli-app.py test-mqtt-connectionto check that Mosquitto broker accepts connections../cli-app.py print-valuesto see the actual registers from the heat pump converted to correct units.- Install and configure MQTT integration in Home assistant
./cli-app.py publish-loopto see the heat pump under Home Assistant -> Settings -> Devices & Services -> MQTT.sudo ./cli-app.py systemd-setupto create permanent service (enable) and (re-)start itsudo ./cli-app.py systemd-statusto see thekronoterm2mqtt.servicestatus
There are some other useful commands to debug (-v switch) and
develop it further. Unwanted registers can be commented out by
changing kronoterm2mqtt/definitions/kronoterm_ksm.toml individual
[[sensor]] entries to something like [[sensor_disabled]] so that
it will be skipped during definitions scan. There are quite some
number of disabled sensors that can be shown and the TOML file can get
more sensors if required. Note that you need to have at least one of
each sensor type enabled in your TOML file ([[enum_sensor]],
[[sensor]]], [[binary_sensor]]). Switches are harcoded and can
only be commented out or expanded in the mqtt_handler.py
./cli.py print-values
+ /home/leon/kronoterm2mqtt/.venv-app/bin/kronoterm2mqtt_app print-values
kronoterm2mqtt v0.1.8 ab9d6f5 (/home/leon/kronoterm2mqtt)
Connect to /dev/ttyUSB0...
Desired DHW temperature 45.0 °C
Current desired DHW temperature 45.0 °C
Loop 1 temperature offset in ECO mode -6550.7 °C
HP inlet temperature 30.5 °C
DHW temperature 52.3 °C
Outside temperature 33.6 °C
HP outlet temperature 31.0 °C
Evaporating temperature 30.9 °C
Compressor temperature 30.4 °C
Current power consumption 0.0 W
Loop 1 temperature 30.8 °C
Loop 2 temperature 28.7 °C
Loop 2 thermostat temperature 25.4 °C
Heating system pressure 1.4 bar
Current HP load 0 %
Source pressure 1.8 bar
SCOP 0.00 kronoterm2mqtt is released under PyPi so that it is easier to install it in a virtual environment such as:
python -m venv venv
venv/bin/pip install kronoterm2mqtt
venv/bin/kronoterm2mqtt_app edit-settings
venv/bin/kronoterm2mqtt_app print-valuesIf we are interested in some additional info derived from the heat pump then it is useful to add some derived sensors. The following example calculates difference between source inlet and outlet (evaporating and compressor) temperatures.
In Homeassistant select Settings -> Devices -> Helpers -> + Add Helper -> Template -> Template a Sensor and enter
- Name: Heat Pump Source temperature difference
- State template:
{{ states('sensor.heat_pump_evaporating_temperature')|float(default=0)
- states('sensor.heat_pump_compressor_temperature')|float(default=0) }}- Unit of measurement: C
- Device class: Temperature
- State class: Measurement
- Add this helper under Heat Pump
Integral of power is energy consumend.
- Select Settings -> Devices -> Helpers -> + Add Helper-> Integral
- Name: Heat Pump Energy consumption
- Metric prefix:
- Time unit: h
- Input Sensor: sensor.heat_pump_current_power_consumption
- Integration method: trapezoidal
- Add this helper under Heat Pump
- Add Utility Meter integration
- Select Settings -> Devices -> Helpers -> + Add Helper-> Template
- Name: Heat Pump Energy consumption (yearly reset)
- Input sensor: sensor.heat_pump_energy_consumption
- Meter reset cycle: yearly
- Meter reset offset: 0
- Add this helper under Heat Pump
Raspberry Pi3B (running Home Assistant) and a small 5-port ethernet switch below are powered by a buckle step down (12->5V) converters.
Note that bitrate needs to be changed to 19200 for WPG heat pumps within [connection] section.
~/kronoterm2mqtt/kronoterm2mqtt/definitions/kronoterm_ksm.toml
[connection]
#baudrate = 115200
baudrate = 19200
bytesize = 8
parity = "N"
stopbits = 1Home Assistant -> Settings -> Devices & Services -> MQTT screenshot
Dashboard raw sources for above cards is under kronoterm2mqtt/examples/dashboard-overview.yaml. It requires custom apexcharts-card to be installed. Create new dashboard with Home Assistant -> Settings -> Dashboard -> Add Dashboard and then Edit -> Edit raw sources. While the sensor names are in English, you may always rename the names to your local language.
The connection to TEX port is done with RS485 dongle using 3 wires (A,
B, GND). The cheapest "USB to RS485 Converter" with GND will work when
connected to TEX (Modbus) port located in the Kronoterm heat pump
processor board (KSM). I recommend Raspberry Pi 3B+ with Home
Assistant to be used inside the heat pump. Otherwise, you will need to
have a long 3-wire twisted cable to it or some dongle. Before running
kronoterm2mqtt it is advisable to run simple example provided to
debug and test the communication as shown below.
$ python -m venv venv
$ venv/bin/pip install pymodbus pyserial
$ venv/bin/python kronoterm2mqtt/examples/print-temperatures.py
2024-08-09 10:11:35,553 DEBUG logging:103 Current transaction state - IDLE
2024-08-09 10:11:35,554 DEBUG logging:103 Running transaction 1
2024-08-09 10:11:35,554 DEBUG logging:103 SEND: 0x14 0x3 0x8 0x34 0x0 0xa 0x84 0xa6
2024-08-09 10:11:35,555 DEBUG logging:103 Resetting frame - Current Frame in buffer -
2024-08-09 10:11:35,556 DEBUG logging:103 New Transaction state "SENDING"
2024-08-09 10:11:35,557 DEBUG logging:103 Changing transaction state from "SENDING" to "WAITING FOR REPLY"
2024-08-09 10:11:35,579 DEBUG logging:103 Changing transaction state from "WAITING FOR REPLY" to "PROCESSING REPLY"
2024-08-09 10:11:35,579 DEBUG logging:103 RECV: 0x14 0x3 0x14 0x1 0x20 0x1 0xe3 0x0 0xf7 0x1 0x25 0x1 0x2f 0x1 0x2a 0xfd 0xa8 0x0 0x0 0xfd 0xa8 0x1 0xc 0x8d 0x77
2024-08-09 10:11:35,580 DEBUG logging:103 Processing: 0x14 0x3 0x14 0x1 0x20 0x1 0xe3 0x0 0xf7 0x1 0x25 0x1 0x2f 0x1 0x2a 0xfd 0xa8 0x0 0x0 0xfd 0xa8 0x1 0xc 0x8d 0x77
2024-08-09 10:11:35,580 DEBUG logging:103 Getting Frame - 0x3 0x14 0x1 0x20 0x1 0xe3 0x0 0xf7 0x1 0x25 0x1 0x2f 0x1 0x2a 0xfd 0xa8 0x0 0x0 0xfd 0xa8 0x1 0xc
2024-08-09 10:11:35,580 DEBUG logging:103 Factory Response[ReadHoldingRegistersResponse': 3]
2024-08-09 10:11:35,581 DEBUG logging:103 Frame advanced, resetting header!!
2024-08-09 10:11:35,581 DEBUG logging:103 Adding transaction 0
2024-08-09 10:11:35,581 DEBUG logging:103 Getting transaction 0
2024-08-09 10:11:35,581 DEBUG logging:103 Changing transaction state from "PROCESSING REPLY" to "TRANSACTION_COMPLETE"
KRONOTERM Temperatures: ['28.8°C', '48.3°C', '24.7°C', '29.3°C', '30.3°C', '29.8°C', '6493.6°C', '0.0°C', '6493.6°C', '26.8°C']If the test above fails, try to change port or baudrate to 19200 by editing kronoterm2mqtt/examples/print-temperatures.py.
- Lovelace HTML Jinja2 Template card (html-template-card)
- Numberbox Card (numberbox-card)
- fold-entity-row
-
enum_sensorto convert status registers to more meaningfull text readings instead of float sensor -
switchto turn on at least DHW circulation pump manually in Home Assistant and then programatically since 6 transitions provided by the heat pump is too limited -
binary_sensorto show some two-state states -
binary_sensorto decode binary statuses inenumlike manner combined. For example error messages or "additional activations". - Upgrade ha-services with
numbercomponent allowing change of some numeric parameters (set temperatures, etc.). - Display the heat pump state using ThermIQ as an example.
Navodila za priklop in uporabo CNS sistema.pdfKronoterm Modbus RTU description (in Slovene) obtained from Kronoterm supportInstallation and Operating Manual for BMS System.pdfKronoterm Modbus V3.13-1 RTU description obtained from Kronoterm support1122-16-17-4021-05_Modbus_BMS_TT3000web.pdfModbus naslovi za BMS; Regulacija TT3000 (in Slovene) obtained from Kronoterm support