Provide high level interface

[kbabioch]

Currently this module focuses on providing low level data as reported back from the heat pump itself. While there are different categories of data (parameters, visibilities and calculations), they are essentially reported back as-is with only a simple mapping that is done by the available datatypes. For instance values like 0, 1, 2 might be mapped to some string representation:

    codes = {
        0: "Automatic",
        1: "Second heatsource",
        2: "Party",
        3: "Holidays",
        4: "Off",
    }

As it turns out there are some issues with this, though:

For instance, Betriebszustand reports EVU, while the heat pump is not allowed to run, while it doesnt reportcooling` when it is actually cooling without the compressor running (see #112). There are more such glitches discussed / reported in #84.

For now @BenPru has dealt with these complexities in this Home Assistant integration. However it would be nice if those could actually be handled by this module, so that consumers of this module don't have to implement this on their own.

For this a high level interface is needed that represents the current state of the heat pump by interpreting the low level values itself.

Besides that the high level interface could also provide services / functions to the user, so that the user of the module does not need to deal with the low level details.

This could include:

• Setting the room temperature (admittedly this is essentially writing only a single value, but still its an improvement if you don't need to know anything about parameters, etc.)
• Enabling the heating rod to heat up some water (e.g. this could be used to get rid of excess power produced by PV)
• Turn on the HUP (Heizungsumwälzpumpe) to get some water flow in the heating system
• Turn on the ZIP (Zirkulationspumpe) to get some water flow in the water installation (e.g. when presense is detected by a motion sensor, etc.)

The exact details and additional functionality that might be needed/useful can be discussed in this issue, since I'm interested in the point of view from other users of this module also.

@gerw @Bouni @BenPru What are your thoughts about this?

[gerw]

In principle, this is a good idea. But (of course) the user has to take care, that the things are also turned off later. The heat pump itself is not able to do it (e.g. you cannot tell the heat pump to turn on the ZWE for 30 minutes).

I am also developing (or trying to develop) a small python application (currently intended only for personal use) which should run on a RaspberryPi and which (one day should)

• regularly fetches the status of the heat pump
• sends messages (containing the measurements of the heat pump) to MQTT
• has a small web server with a REST API (e.g. to request changes for the heat pump)
• controls the heat pump (e.g. on a regular schedule beyond the capabilities of the heat pump)

This application could also help to assist with your respect to your ideas, e.g., one could send a message to the REST API and then the ZIP is turned on for 10 minutes.

[kbabioch]

In principle, this is a good idea. But (of course) the user has to take care, that the things are also turned off later. The heat pump itself is not able to do it (e.g. you cannot tell the heat pump to turn on the ZWE for 30 minutes).

I would expect that there are some additional security mechanisms in the firmware and/or implemented by hardware. Of course ZWE needs to be turned off again (or you have to put the heat somewhere). The high level interface will provide such functionality, but in the end, you never can be sure that it will be turned off by external software, since the software (or computer it runs on, etc.) might crash.

I am also developing (or trying to develop) a small python application (currently intended only for personal use) which should run on a RaspberryPi and which (one day should)

When thinking about layers / black boxes, this module will provide the possibility to interact with the heat pump (status and control / scheduling). Everything else (MQTT, REST API) sits on top of that and uses this Python module.

But to be honest: Most of what you're after (status of heat pump, MQTT, schedules) is already implemented / doable with Home Assistant (and probably other things like Node Red / ioBroker) also.

[gerw]

For the "reading" part, we have at least two possibilities:

• Design a new class (in lack of a better name) HigherLevelReading (similar to Calculations), which will be filled and returned by read()
• Include functions like get_hot_water_temperature() to Luxtronik. [In this case, an instance of Luxtronik needs to cache the last reading, cf. #85]

I think that I favor the second option.

For the "writing" part, it seems reasonable to have something like set_hot_water_parameters(bar, foo). Again, there are two possibilities:

• These methods directly write the changes to the heat pump.
• These methods cache the changes, which are consequently written by a call to write(). Optionally, each set_* method could have a parameter write_immediately (default value False), with the obvious implication.

[Guzz-T]

• Include functions like get_hot_water_temperature() to Luxtronik. [In this case, an instance of Luxtronik needs to cache the last reading, cf.

Why do you need to cache the last reading? You have no certainty that the saved value still corresponds to the current value on the heat pump. (https://en.wikipedia.org/wiki/Time-of-check_to_time-of-use)

[Guzz-T]

• These methods cache the changes, which are consequently written by a call to write(). Optionally, each set_* method could have a parameter write_immediately (default value False), with the obvious implication.

Currently the user is already able to cache changes using the Parameters()dictionary:

params = Paramters()
params.set(3, 'Automatic')
params.set(4, '50 degree')
...
luxtronik.write(params)

It would also be legitimate to store the parameter queue (just the queue!) inside the Luxtronik object and provide functions like write_hot_water_temp(temp, write_immediatly) and write_cached()