To give users a way to interact with the heat pump we first want to add a modbus API. This gives users/installers a way to monitor and optimize the heat pump.
We support the following protocols:
Modbus TLS is enabled by default on the heat pump. You can discover the heat pump on the network using mDNS-SD, or connect directly if you already know its IP address. If you plan to connect via IP address, you can skip the Discovery section below.
You can discover the service using mDNS-SD. Devices advertise under their default service type, registered with IANA:
_mbap-s._tcp_mbap._tcpYou'll find a host named hpcb-xxxxxx.local and the port of the service (802 for TLS, 502 for TCP). This is the host and port you should connect to. You might find multiple heat pumps if you have a Duo (Cascade) setup.
To connect to the heat pump, you can simply use this hostname if mDNS is available on your system. On most systems, Windows, Mac, or Linux (with Avahi installed), you can check the connection using:
ping hpcb-xxxxxx.localTo connect using Modbus TLS, you first need to bootstrap (pair). See this page for details. We recommend using Modbus TLS when the network isn't isolated.
Modbus TLS is on port 802 and Modbus TCP on port 502.
The default settings are as follows:
Note that these settings can be changed, see the hardware settings below.
For the CoAP API we have numbered all settings/status items with Modbus in mind. Modbus addresses are 16 bit numbers, which is what we have used in the CoAP keys too. Therefore is should be quite straightforward to implement a Modbus API.
It is possible to directly control the heat pump via Modbus using the Control registers shown below. The control mode for heating/cooling needs to be set to Modbus in order for this to work. The heat pump will switch back off (and show that Modbus is disconnected) if there is no Modbus communication for 30 seconds. Note that just reading some status is enough to reset this timeout.
Power limitation can always be written and is always respected, even if the heat pump is not in Modbus control mode. Again, you need to keep writing this value, else it will be ignored and the heat pump will not restrict power consumption.
Address | Function | Format |
Space heating | ||
0x1101 | Enable function | 0 = disabled |
0x1108 | Profile | -1 = blocked 2 = comfort |
Space cooling | ||
0x2101 | Enable function | 0 = disabled 1 = enabled |
0x2102 | Profile | -1 = blocked 2 = comfort |
Domestic hot water | ||
0x3101 | Enable function | 0 = disabled 1 = enabled |
0x310A | Profile | -1 = blocked 2 = comfort |
DHW profile eco | ||
0x3601 | Tank setpoint | (10 ... 70)*10 |
0x3602 | Lower hysteresis | (0 ... 50)*10 |
0x3603 | Modulation percentage | (0 ... 100)*10 |
DHW profile normal | ||
0x3701 | Tank setpoint | (10 ... 70)*10 |
0x3702 | Lower hysteresis | (0 ... 50)*10 |
0x3703 | Modulation percentage | (0 ... 100)*10 |
DHW profile comfort | ||
0x3801 | Tank setpoint | (10 ... 70)*10 |
0x3802 | Lower hysteresis | (0 ... 50)*10 |
0x3803 | Modulation percentage | (0 ... 100)*10 |
Hardware | ||
0x520F | Modbus RTU address | 1 ... 247 (default 43) |
0x5210 | Modbus RTU baud rate | default 19200 |
0x5211 | Modbus RTU parity | 0 = none (default) |
Control | ||
0xB101 | Operating mode | 0 = off 1 = heating 2 = cooling |
0xB102 | Modulation level | 0 ... 100 |
0xB103 | Power budget (Watt) | 0 ... 65535 (0 means no limit) |
Address | Function | Format |
General info | ||
0x0 | Heat pump state | -1 = fault 0 = off |
0x1 ... 0x14 | First 20 active heat pump fault/warning/info messages | TODO: document fault format |
0x16 | Rated (max) power of all connected heat sources (Watt) | value |
DHW info | ||
0x20 | Status | -1 = fault state |
0x21 | Demand | 0 = no demand 1 = demand |
0x22 | Modulation percentage | value/10 |
0x25 | Tank temp | value/10 |
0x26 | Tank temp setpoint (in current profile) | value/10 |
0x27 | DHW valve is enabled | 0 = not enabled 1 = enabled |
0x28 | Current profile | -1 = blocked 2 = comfort |
Space heating info | ||
0x40 | Status | -1 = fault state |
0x41 | Demand | 0 = no demand 1 = demand |
0x42 | Modulation percentage | value/10 |
0x45 | Sink supply temp. (feed temp) | value/10 |
0x46 | Sink supply setp (in current control mode) | value/10 |
0x4A | Current profile | -1 = blocked 2 = comfort |
Space cooling | ||
0x60 | Status | -1 = fault state |
0x61 | Demand | 0 = no demand 1 = demand |
0x62 | Modulation percentage | value/10 |
0x65 | Sink supply temp. (feed temp) | value/10 |
0x66 | Sink supply setp (in current control mode) | value/10 |
0x69 | Modulation (power) percentage setpoint (OpenTherm control, optional) | value/10 |
Space conditioning input | ||
0x120 | Room temp. (optional) | value/10 |
0x121 | Ambient temp. (optional) | value/10 |
0x122 | Relative humidity. (optional) | value/10 |
0x123 | Room temp. setp. (optional) | value/10 |
0x124 | Modulation percentage (optional) | value/10 |
Heat pump module 1 / 2 | ||
General | ||
0x400 / 0x800 | State | -1 = fault state |
Compressor | ||
0x422 / 0x822 | Compressor freq | value/10 |
Source pump | ||
0x441 / 0x841 | Pump control percentage | value/10 |
Sink pump | ||
0x461 / 0x861 | Pump control percentage | value/10 |
Cooling valve | ||
0x4A1 / 0x8A1 | Cooling valve state | 0 = heating mode 1 = cooling mode |
Source circuit | ||
0x4C0 / 0x8C0 | Source return temp (from PVT to heat pump) | value/10 |
0x4C1 / 0x8C1 | Source supply temp (from heat pump to PVT) | value/10 |
Sink circuit | ||
0x500 / 0x900 | Sink return temp (from distribution to HP) | value/10 |
0x501 / 0x901 | Sink supply temp (from HP to distribution) | value/10 |
Performance | ||
0x680 / 0xA80 | Electric power consumption (Watts) | value |
0x681 / 0xA81 | Sink power generation (Watts), negative when cooling | value |
Statistics | ||
0x683 / 0xA83 | Compressor starts | value |
<end of table>