Panasonic H, J, K & L Series Aquarea air-water heat pump protocol

This project makes it possible to read information from Panasonic Aquarea heat pump and report the data either to an MQTT server or as JSON format over HTTP.

Eine deutschsprachige README_DE.md findest du hier.
Een nederlandse vertaling README_NL.md vind je hier.
Suomen kielellä README_FI.md luettavissa täällä.

Help on translation to other languages is welcome.

Current releases

Latest release is available here. The ESP8266 compiled binary can be installed on a Wemos D1 mini, on the HeishaMon PCB and generally on any ESP8266 based board compatible with Wemos build settings (at least 4MB flash). You can also download the code and compile it yourself (see required libraries below). The ESP32-S3 binary is for the newer, large, version of heishamon.

Using the software

HeishaMon is able to communicate with the Panasonic Aquarea H, J, K and L&series. Confirmed by users types of HP you can find here
If you want to compile this image yourself be sure to use the mentioned libraries and support for a filesystem on the esp8266 so select the correct flash option in arduino ide for that.

When starting, without a configured wifi, an open-wifi-hotspot will be visible allowing you to configure your wifi network and your MQTT server. Configuration page will be located at http://192.168.4.1 . \

After configuring and booting the image will be able to read and talk to your heatpump. The GPIO13/GPIO15 connection will be used for communications so you can keep your computer/uploader connected to the board if you want.
Serial 1 (GPIO2) can be used to connect another serial line (GND and TX from the board only) to read some debugging data.

All received data will be sent to different MQTT topics (see below for topic descriptions). There is also a 'panasonic_heat_pump/log' MQTT topic which provides debug logging and a hexdump of the received packets (if enabled in the web portal).

You can connect a 1wire network on GPIO4 which will report in seperate MQTT topics (panasonic_heat_pump/1wire/sensorid).

The software is also able to measure Watt on a S0 port of two kWh meters. You only need to connect GPIO12 and GND to the S0 of one kWh meter and if you need a second kWh meter use GPIO14 and GND. It will report on MQTT topic panasonic_heat_pump/s0/Watt/1 and panasonic_heat_pump/s0/Watt/2 and also in the JSON output. You can replace 'Watt' in the previous topic with 'Watthour' to get consumption counter in WattHour (per mqtt message) or to 'WatthourTotal' to get the total consumption measured in WattHour. To sync the WatthourTotal with your kWh-meter, publish the correct value to MQTT to the panasonic_heat_pump/s0/WatthourTotal/1 or panasonic_heat_pump/s0/WatthourTotal/2 topic with the 'retain' option while heishamon is rebooting. Upon reboot, heishamon reads this value as the last known value to you can sync using this method.

Updating the firmware is as easy as going to the firmware menu and, after authentication with username 'admin' and password 'heisha' (or other provided during setup), uploading the binary there.

A json output of all received data (heatpump and 1wire) is available at the url http://heishamon.local/json (replace heishamon.local with the ip address of your heishamon device if MDNS is not working for you).

Within the 'integrations' folder you can find examples how to connect your automation platform to the HeishaMon.

Rules functionality

The rules functionality allows you to control the heatpump from within the HeishaMon itself. Which makes it much more reliable then having to deal with external domotica over WiFi. When posting a new ruleset, it is immidiatly validated and when valid used. When a new ruleset is invalid it will be ignored and the old ruleset will be loaded again. You can check the console for feedback on this. If somehow a new valid ruleset crashes the HeishaMon, it will be automatically disabled the next reboot, allowing you to make changes. This prevents the HeishaMon getting into a boot loop.

The techniques used in the rule library allows you to work with very large rulesets, but best practice is to keep it below 10.000 bytes.

Notice that sending commands to the heatpump is done asynced. So, commands sent to the heatpump at the beginning of your syntax will not immediatly be reflected in the values from the heatpump later on. Therefor, heatpump values should be read from the heatpump itself instead of those based on the values you keep yourself.

Syntax

Two general rules are that spaces are mandatory and semicolons are used as end-of-line character.

Variables

The ruleset uses the following variable structure:

• #: Globals These variables can be accessed throughout the ruleset but have to defined inside a rule block. Don't use globals for all your variables, because it will persistently use memory.

• $: Locals These variables live inside a rule block. When a rule block finishes, these variables will be cleaned up, freeing any memory used.

• @: Heatpump parameters These are the same as listed in the Manage Topics documentation page and as found on the HeishaMon homepage. The ruleset also follows the R/W logic as used through the MQTT and REST API. That means that the read topics differ from the write topics. So reading the heatpump state is done through @Heatpump_State, changing the heatpump state through @SetHeatpump.

• %: Datetime variables These can be used for date and time based rules. Currently %hour (0 - 23), %minute (0 - 59), %month (1 - 12), and day (1 - 7) are supported. All are plain integers. A proper NTP configuration is needed to set the correct system date and time on the HeishaMon.

• ?: Thermostat parameters These variables reflect parameters read from the connected thermostat when using the OpenTherm functionality. When OpenTherm is supported this documentation will be extended with more precise information. The can check the opentherm tab for the variables that can be used. The names are the same for reading and writing, but not all values support reading and/or writing. The opentherm tab also lists this.

• ds18b20#2800000000000000: Dallas 1-wire temperature values Use these variables to read the temperature of the connected sensors. These values are of course readonly. The id of the sensor should be placed after the hashtag.

• s0#watt[hour[total]]_?: The S0 values for port 1 and 2. Replace the question mark with the port number. For example s0#watt_1 to get watt from port 1 and s0#watthourtotal_2 to get total watthours from port 2

When a variable is called but not yet set to a value, the value will be NULL.

Variables can be of boolean (1 or 0), float (3.14), integer (10), and string type. Defining strings is done with single or double quotes.

Events or functions

Rules are written in event or function blocks. These are blocks that are triggered when something happened; either a new heatpump or thermostat value has been received or a timer fired. Or can be used as plain functions

on [event] then
  [...]
end

on [name] then
  [...]
end

Events can be Heatpump or thermostat parameters or timers:

on @Heatpump_State then
  [...]
end

on ?setpoint then
  [...]
end

on timer=1 then
  [...]
end

When defining functions, you just name your block and then you can call it from anywhere else:

on foobar then
  [...]
end

on @Heatpump_State then
  foobar();
end

Functions can have parameters which you can call:

on foobar($a, $b, $c) then
  [...]

on @Heatpump_State then
  foobar(1, 2, 3);
end

If you call a function less values then the function takes, all other parameters will have a NULL value.

There is currently one special function that calls when the system is booted on when a new ruleset is saved:

on System#Boot then
  [...]
end

This special function can be used to initially set your globals or certain timers.

Operators

Regular operators are supported with their standard associativity and precedence. This allows you to also use regular math.

• &&: And
• ||: Or
• ==: Equals`
• >=: Greater or equal then
• >: Greater then
• <: Lesser then
• <=: Lesser or equal then
• -: Minus
• %: Modulus
• *: Multiply
• /: Divide
• +: Plus
• ^: Power

Parenthesis can be used to prioritize operators as it would work in regular math.

Functions

• coalesce Returns the first value not NULL. E.g., $b = NULL; $a = coalesce($b, 1); will return 1. This function accepts an unlimited number of arguments.

• max Returns the maximum value of the input parameters.

• min Returns the minimum value of the input parameters.

• isset Return boolean true when the input variable is still NULL in any other cases it will return false.

• round Rounds the input float to the nearest integer.

• floor The largest integer value less than or equal to the input float.

• ceil The smallest integer value greater than or equal to the input float.

• setTimer Sets a timer to trigger in X seconds. The first parameter is the timer number and the second parameters the number of seconds before it fires. A timer only fires once so it has to be re-set for recurring events. When a timer triggers it will can the timer event as described above. E.g.

• print Prints a value to the console.

• concat Concatenates various values into a combined string. E.g.: `@S