htheatpump package¶

htheatpump.htheatpump¶

This module is responsible for the communication with the Heliotherm heat pump.

class htheatpump.htheatpump.VerifyAction[source]¶

Possible actions for the parameter verification:

NAME Verification of the parameter name.
MIN Verification of the minimal value of the parameter.
MAX Verification of the maximal value of the parameter.
VALUE Verification of the current parameter value.

The above enum entries can be used to specify the steps which should be performed during a parameter verification, e.g.:

hp = HtHeatpump("...", verify_param_action = {VerifyAction.NAME, VerifyAction.MAX})
temp = hp.get_param("Temp. Aussen")
...

or:

hp = HtHeatpump("/dev/ttyUSB0", baudrate=9600)
hp.verify_param_action = {VerifyAction.NAME, VerifyAction.MAX}
temp = hp.get_param("Temp. Aussen")
...

exception htheatpump.htheatpump.VerificationException(message: str)[source]¶

Exception which represents a verification error during parameter access.

Parameters:	message (str) – A detailed message describing the parameter verification failure.

class htheatpump.htheatpump.HtHeatpump(device: str, baudrate: int = 115200, bytesize: int = 8, parity: str = 'N', stopbits: Union[float, int] = 1, timeout: Union[float, int, None] = 5, xonxoff: bool = True, rtscts: bool = False, write_timeout: Union[float, int, None] = None, dsrdtr: bool = False, inter_byte_timeout: Union[float, int, None] = None, exclusive: Optional[bool] = None, verify_param_action: Optional[Set[VerifyAction]] = None, verify_param_error: bool = False)[source]¶

Object which encapsulates the communication with the Heliotherm heat pump.

Parameters:

device (str) – The serial device to attach to (e.g. /dev/ttyUSB0).
baudrate (int) – The baud rate to use for the serial device.
bytesize (int) – The bytesize of the serial messages.
parity (str) – Which kind of parity to use.
stopbits (float or int) – The number of stop bits to use.
timeout (None, float or int) – The read timeout value. Default is DEFAULT_SERIAL_TIMEOUT.
xonxoff (bool) – Software flow control enabled.
rtscts (bool) – Hardware flow control (RTS/CTS) enabled.
write_timeout (None, float or int) – The write timeout value.
dsrdtr (bool) – Hardware flow control (DSR/DTR) enabled.
inter_byte_timeout (None, float or int) – Inter-character timeout, None to disable (default).
exclusive (bool) – Exclusive access mode enabled (POSIX only).
verify_param_action (None or set) – Parameter verification actions.
verify_param_error (bool) – Interpretation of parameter verification failure as error enabled.

Example:

hp = HtHeatpump("/dev/ttyUSB0", baudrate=9600)
try:
    hp.open_connection()
    hp.login()
    # query for the outdoor temperature
    temp = hp.get_param("Temp. Aussen")
    print(temp)
    # ...
finally:
    hp.logout()  # try to logout for an ordinary cancellation (if possible)
    hp.close_connection()

DEFAULT_LOGIN_RETRIES = 2¶: Maximum number of retries for a login attempt; 1 regular try + DEFAULT_LOGIN_RETRIES retries.

DEFAULT_SERIAL_TIMEOUT = 5¶: Serial timeout value in seconds; normally no need to change it.

close_connection() → None[source]¶: Close the serial connection.

fast_query(*args) → Dict[str, Union[bool, int, float]][source]¶

Query for the current values of parameters from the heat pump the fast way.

Note

Only available for parameters representing a “MP” data point and no parameter verification possible!

Parameters:	args (str) – The parameter name(s) to request from the heat pump. If not specified all “known” parameters representing a “MP” data point are requested.
Returns:	A dict of the requested parameters with their values, e.g.: { "EQ Pumpe (Ventilator)": False, "FWS Stroemungsschalter": False, "Frischwasserpumpe": 0, "HKR_Sollwert": 26.8, # ... }
Return type:	`dict`
Raises:	KeyError – Will be raised when the parameter definition for a passed parameter is not found. ValueError – Will be raised when a passed parameter doesn’t represent a “MP” data point. IOError – Will be raised when the serial connection is not open or received an incomplete/invalid response (e.g. broken data stream, invalid checksum).

get_date_time() → Tuple[datetime.datetime, int][source]¶

Read the current date and time of the heat pump.

Returns:	The current date and time of the heat pump as a tuple with 2 elements, where the first element is of type `datetime.datetime` which represents the current date and time while the second element is the corresponding weekday in form of an `int` between 1 and 7, inclusive (Monday through Sunday). For example: ( datetime.datetime(...), 2 ) # 2 = Tuesday
Return type:	`tuple` ( datetime.datetime, int )
Raises:	IOError – Will be raised when the serial connection is not open or received an incomplete/invalid response (e.g. broken data stream, invalid checksum).

get_fault_list(*args) → List[Dict[str, object]][source]¶

Query for the fault list of the heat pump.

Parameters:	args (int) – The index number(s) to request from the fault list (optional). If not specified all fault list entries are requested.
Returns:	The requested entries of the fault list as `list`, e.g.: [ { "index" : 29, # fault list index "error" : 20, # error code "datetime": datetime.datetime(...), # date and time of the entry "message" : "EQ_Spreizung", # error message }, # ... ]
Return type:	`list`
Raises:	IOError – Will be raised when the serial connection is not open or received an incomplete/invalid response (e.g. broken data stream, invalid checksum).

get_fault_list_size() → int[source]¶

Query for the fault list size of the heat pump.

Returns:	The size of the fault list as `int`.
Return type:	`int`
Raises:	IOError – Will be raised when the serial connection is not open or received an incomplete/invalid response (e.g. broken data stream, invalid checksum).

get_last_fault() → Tuple[int, int, datetime.datetime, str][source]¶

Query for the last fault message of the heat pump.

Returns:	The last fault message of the heat pump as a tuple with 4 elements. The first element of the returned tuple represents the index as `int` of the message inside the fault list. The second element is (probably) the the error code as `int` defined by Heliotherm. The last two elements of the tuple are the date and time when the error occurred (as `datetime.datetime`) and the error message string itself. For example: ( 29, 20, datetime.datetime(...), "EQ_Spreizung" )
Return type:	`tuple` ( int, int, datetime.datetime, str )
Raises:	IOError – Will be raised when the serial connection is not open or received an incomplete/invalid response (e.g. broken data stream, invalid checksum).

get_param(name: str) → Union[bool, int, float][source]¶

Query for a specific parameter of the heat pump.

Parameters:	name (str) – The parameter name, e.g. `"Betriebsart"`.
Returns:	Returned value of the requested parameter. The type of the returned value is defined by the csv-table of supported heat pump parameters in `htparams.csv`.
Return type:	`bool`, `int` or `float`
Raises:	KeyError – Will be raised when the parameter definition for the passed parameter is not found. IOError – Will be raised when the serial connection is not open or received an incomplete/invalid response (e.g. broken data stream, invalid checksum). VerificationException – Will be raised if the parameter verification fails and the property `verify_param_error` is set to `True`. If property `verify_param_error` is set to `False` only a warning message will be emitted. The performed verification steps are defined by the property `verify_param_action`.

For example, the following call

temp = hp.get_param("Temp. Aussen")

will return the current measured outdoor temperature in °C.

get_serial_number() → int[source]¶

Query for the manufacturer’s serial number of the heat pump.

Returns:	The manufacturer’s serial number of the heat pump as `int` (e.g. `123456`).
Return type:	`int`
Raises:	IOError – Will be raised when the serial connection is not open or received an incomplete/invalid response (e.g. broken data stream, invalid checksum).

get_time_prog(idx: int, with_entries: bool = True) → htheatpump.httimeprog.TimeProgram[source]¶

Return a specific time program (specified by their index) together with their time program entries (if desired) from the heat pump.

Parameters:	idx (int) – The time program index. with_entries (bool) – Determines whether also the single time program entries should be requested or not. Default is `True`.
Returns:	The requested time program as `TimeProgram`.
Return type:	`TimeProgram`
Raises:	IOError – Will be raised when the serial connection is not open or received an incomplete/invalid response (e.g. broken data stream, invalid checksum).

get_time_prog_entry(idx: int, day: int, num: int) → htheatpump.httimeprog.TimeProgEntry[source]¶

Return a specific time program entry (specified by time program index, day and entry-of-day) of the heat pump.

Parameters:	idx (int) – The time program index. day (int) – The day of the time program entry (inside the specified time program). num (int) – The number of the time program entry (of the specified day).
Returns:	The requested time program entry as `TimeProgEntry`.
Return type:	`TimeProgEntry`
Raises:	IOError – Will be raised when the serial connection is not open or received an incomplete/invalid response (e.g. broken data stream, invalid checksum).

get_time_progs() → List[htheatpump.httimeprog.TimeProgram][source]¶

Return a list of all available time programs of the heat pump.

Returns:	A list of `TimeProgram` instances.
Return type:	`list`
Raises:	IOError – Will be raised when the serial connection is not open or received an incomplete/invalid response (e.g. broken data stream, invalid checksum).

get_version() → Tuple[str, int][source]¶

Query for the software version of the heat pump.

Returns:	The software version of the heat pump as a tuple with 2 elements. The first element inside the returned tuple represents the software version as a readable string in a common version number format (e.g. `"3.0.20"`). The second element (probably) contains a numerical representation as `int` of the software version returned by the heat pump. For example: ( "3.0.20", 2321 )
Return type:	`tuple` ( str, int )
Raises:	IOError – Will be raised when the serial connection is not open or received an incomplete/invalid response (e.g. broken data stream, invalid checksum).

in_error¶

Query whether the heat pump is malfunctioning.

Returns:	`True` if the heat pump is malfunctioning, `False` otherwise.
Return type:	`bool`
Raises:	IOError – Will be raised when the serial connection is not open or received an incomplete/invalid response (e.g. broken data stream, invalid checksum).

is_open¶

Return the state of the serial port, whether it’s open or not.

Returns:	The state of the serial port as `bool`.
Return type:	`bool`

login(update_param_limits: bool = False, max_retries: int = 2) → None[source]¶

Log in the heat pump. If update_param_limits is True an update of the parameter limits in HtParams will be performed. This will be done by requesting the current value together with their limits (MIN and MAX) for all “known” parameters directly after a successful login.

Parameters:	update_param_limits (bool) – Determines whether an update of the parameter limits in `HtParams` should be done or not. Default is `False`. max_retries (int) – Maximal number of retries for a successful login. One regular try plus `max_retries` retries. Default is `DEFAULT_LOGIN_RETRIES`.
Raises:	IOError – Will be raised when the serial connection is not open or received an incomplete/invalid response (e.g. broken data stream, invalid checksum).

logout() → None[source]¶: Log out from the heat pump session.

open_connection() → None[source]¶

Open the serial connection with the defined settings.

Raises:	IOError – When the serial connection is already open. ValueError – Will be raised when parameter are out of range, e.g. baudrate, bytesize. SerialException – In case the device can not be found or can not be configured.

query(*args) → Dict[str, Union[bool, int, float]][source]¶

Query for the current values of parameters from the heat pump.

Parameters:	args (str) – The parameter name(s) to request from the heat pump. If not specified all “known” parameters are requested.
Returns:	A dict of the requested parameters with their values, e.g.: { "HKR Soll_Raum": 21.0, "Stoerung": False, "Temp. Aussen": 8.8, # ... }
Return type:	`dict`
Raises:	KeyError – Will be raised when the parameter definition for a passed parameter is not found. IOError – Will be raised when the serial connection is not open or received an incomplete/invalid response (e.g. broken data stream, invalid checksum). VerificationException – Will be raised if the parameter verification fails and the property `verify_param_error` is set to `True`. If property `verify_param_error` is set to `False` only a warning message will be emitted. The performed verification steps are defined by the property `verify_param_action`.

read_response() → str[source]¶

Read the response message from the heat pump.

Returns:	The returned response message of the heat pump as `str`.
Return type:	`str`
Raises:	IOError – Will be raised when the serial connection is not open or received an incomplete/invalid (or unknown) response (e.g. broken data stream, unknown header, invalid checksum, …).

Note

There is a little bit strange behavior how the heat pump sometimes replies on some requests:

A response from the heat pump normally consists of the following header (the first 6 bytes) b"\x02\xfd\xe0\xd0\x00\x00" together with the payload and a computed checksum. But sometimes the heat pump replies with a different header (b"\x02\xfd\xe0\xd0\x04\x00" or b"\x02\xfd\xe0\xd0\x08\x00") together with the payload and a fixed value of 0x0 for the checksum (regardless of the content).

We have no idea about the reason for this behavior. But after analysing the communication between the Heliotherm home control Windows application and the heat pump, which simply accepts this kind of responses, we also decided to handle it as a valid answer to a request.

Furthermore, we have noticed another behavior, which is not fully explainable: For some response messages from the heat pump (e.g. for the error message "ERR,INVALID IDX") the transmitted payload length in the protocol is zero (0 bytes), although some payload follows. In this case we read until we will found the trailing b"\r\n" at the end of the payload to determine the payload of the message.

Additionally to the upper described facts, for some of the answers of the heat pump the payload length must be corrected (for the checksum computation) so that the received checksum fits with the computed one (e.g. for b"\x02\xfd\xe0\xd0\x01\x00" and b"\x02\xfd\xe0\xd0\x02\x00").

reconnect() → None[source]¶: Perform a reconnect of the serial connection. Flush the output and input buffer, close the serial connection and open it again.

send_request(cmd: str) → None[source]¶

Send a request to the heat pump.

Parameters:	cmd (str) – Command to send to the heat pump.
Raises:	IOError – Will be raised when the serial connection is not open.

set_date_time(dt: Optional[datetime.datetime] = None) → Tuple[datetime.datetime, int][source]¶

Set the current date and time of the heat pump.

Parameters:	dt (datetime.datetime) – The date and time to set. If `None` current date and time of the host will be used.
Returns:	A 2-elements tuple composed of a `datetime.datetime` which represents the sent date and time and an `int` between 1 and 7, inclusive, for the corresponding weekday (Monday through Sunday).
Return type:	`tuple` ( datetime.datetime, int )
Raises:	TypeError – Raised for an invalid type of argument `dt`. Must be `None` or of type `datetime.datetime`. IOError – Will be raised when the serial connection is not open or received an incomplete/invalid response (e.g. broken data stream, invalid checksum).

set_param(name: str, val: Union[bool, int, float], ignore_limits: bool = False) → Union[bool, int, float][source]¶

Set the value of a specific parameter of the heat pump. If ignore_limits is False and the passed value is beyond the parameter limits a ValueError will be raised.

Parameters:	name (str) – The parameter name, e.g. `"Betriebsart"`. val (bool, int or float) – The value to set. ignore_limits (bool) – Indicates if the parameter limits should be ignored or not.
Returns:	Returned value of the parameter set request. In case of success this value should be the same as the one passed to the function. The type of the returned value is defined by the csv-table of supported heat pump parameters in `htparams.csv`.
Return type:	`bool`, `int` or `float`
Raises:	KeyError – Will be raised when the parameter definition for the passed parameter is not found. ValueError – Will be raised if the passed value is beyond the parameter limits and argument `ignore_limits` is set to `False`. IOError – Will be raised when the serial connection is not open or received an incomplete/invalid response (e.g. broken data stream, invalid checksum). VerificationException – Will be raised if the parameter verification fails and the property `verify_param_error` is set to `True`. If property `verify_param_error` is set to `False` only a warning message will be emitted. The performed verification steps are defined by the property `verify_param_action`.

For example, the following call

hp.set_param("HKR Soll_Raum", 21.5)

will set the desired room temperature of the heating circuit to 21.5 °C.

set_time_prog(time_prog: htheatpump.httimeprog.TimeProgram) → htheatpump.httimeprog.TimeProgram[source]¶

Set all time program entries of a specific time program. Any non-specified entry (which is None) in the time program will be requested from the heat pump. The returned TimeProgram instance includes therefore all entries of this time program.

Parameters:	time_prog (TimeProgram) – The given time program as `TimeProgram`.
Returns:	The time program as `TimeProgram` including all time program entries.
Return type:	`TimeProgram`
Raises:	IOError – Will be raised when the serial connection is not open or received an incomplete/invalid response (e.g. broken data stream, invalid checksum).

set_time_prog_entry(idx: int, day: int, num: int, entry: htheatpump.httimeprog.TimeProgEntry) → htheatpump.httimeprog.TimeProgEntry[source]¶

Set a specific time program entry (specified by time program index, day and entry-of-day) of the heat pump.

Parameters:	idx (int) – The time program index. day (int) – The day of the time program entry (inside the specified time program). num (int) – The number of the time program entry (of the specified day). entry (TimeProgEntry) – The new time program entry as `TimeProgEntry`.
Returns:	The changed time program entry `TimeProgEntry`.
Return type:	`TimeProgEntry`
Raises:	IOError – Will be raised when the serial connection is not open or received an incomplete/invalid response (e.g. broken data stream, invalid checksum).

update_param_limits() → List[str][source]¶

Perform an update of the parameter limits in HtParams by requesting the limit values of all “known” parameters directly from the heat pump.

Returns:	The list of updated (changed) parameters.
Return type:	`list`
Raises:	VerificationException – Will be raised if the parameter verification fails and the property `verify_param_error` is set to `True`. If property `verify_param_error` is set to `False` only a warning message will be emitted. The performed verification steps are defined by the property `verify_param_action`.

verify_param_action¶

Property to specify the actions which should be performed during the parameter verification.

The possible actions for the parameter verification can be found in the enum VerifyAction. The default includes just a verification of the parameter name.

Param:	A set of `VerifyAction` enum values, which specify the actions which should be performed during the parameter verification, e.g. `{VerifyAction.NAME}`.
Returns:	The set of `VerifyAction` enum values, which specify the parameter verification actions.
Return type:	`set`

verify_param_error¶

Property to get or set whether a parameter verification failure should result in an error or not.

If True a failed parameter verification will result in an VerificationException exception. If False (default) only a warning message will be emitted.

Param:	Boolean value which indicates whether a parameter verification failure should result in an error or not.
Returns:	`True` if a verification failure should result in an error, `False` otherwise.
Return type:	`bool`

htheatpump.aiohtheatpump¶

This module provides an asynchronous communication with the Heliotherm heat pump.

class htheatpump.aiohtheatpump.AioHtHeatpump(device: str, baudrate: int = 115200, bytesize: int = 8, parity: str = 'N', stopbits: Union[float, int] = 1, timeout: Union[float, int, None] = 5, xonxoff: bool = True, rtscts: bool = False, write_timeout: Union[float, int, None] = None, dsrdtr: bool = False, inter_byte_timeout: Union[float, int, None] = None, exclusive: Optional[bool] = None, verify_param_action: Optional[Set[VerifyAction]] = None, verify_param_error: bool = False, loop: Optional[asyncio.events.AbstractEventLoop] = None, cancel_read_timeout: int = 1, cancel_write_timeout: int = 1)[source]¶

Object which encapsulates the asynchronous communication with the Heliotherm heat pump.

Parameters:

device (str) – The serial device to attach to (e.g. /dev/ttyUSB0).
baudrate (int) – The baud rate to use for the serial device.
bytesize (int) – The bytesize of the serial messages.
parity (str) – Which kind of parity to use.
stopbits (float or int) – The number of stop bits to use.
timeout (None, float or int) – The read timeout value. Default is DEFAULT_SERIAL_TIMEOUT.
xonxoff (bool) – Software flow control enabled.
rtscts (bool) – Hardware flow control (RTS/CTS) enabled.
write_timeout (None, float or int) – The write timeout value.
dsrdtr (bool) – Hardware flow control (DSR/DTR) enabled.
inter_byte_timeout (None, float or int) – Inter-character timeout, None to disable (default).
exclusive (bool) – Exclusive access mode enabled (POSIX only).
verify_param_action (None or set) – Parameter verification actions.
verify_param_error (bool) – Interpretation of parameter verification failure as error enabled.
loop (None or asyncio.AbstractEventLoop) – The event loop, None for the currently running event loop (default).
cancel_read_timeout (int) – TODO
cancel_write_timeout (int) – TODO

Example:

hp = AioHtHeatpump("/dev/ttyUSB0", baudrate=9600)
try:
    hp.open_connection()
    await hp.login_async()
    # query for the outdoor temperature
    temp = await hp.get_param_async("Temp. Aussen")
    print(temp)
    # ...
finally:
    await hp.logout_async()  # try to logout for an ordinary cancellation (if possible)
    hp.close_connection()

fast_query_async(*args) → Dict[str, Union[bool, int, float]][source]¶

Query for the current values of parameters from the heat pump the fast way.

Note

Only available for parameters representing a “MP” data point and no parameter verification possible!

Parameters:	args (str) – The parameter name(s) to request from the heat pump. If not specified all “known” parameters representing a “MP” data point are requested.
Returns:	A dict of the requested parameters with their values, e.g.: { "EQ Pumpe (Ventilator)": False, "FWS Stroemungsschalter": False, "Frischwasserpumpe": 0, "HKR_Sollwert": 26.8, # ... }
Return type:	`dict`
Raises:	KeyError – Will be raised when the parameter definition for a passed parameter is not found. ValueError – Will be raised when a passed parameter doesn’t represent a “MP” data point. IOError – Will be raised when the serial connection is not open or received an incomplete/invalid response (e.g. broken data stream, invalid checksum).

get_date_time_async() → Tuple[datetime.datetime, int][source]¶

Read the current date and time of the heat pump.

Returns:	The current date and time of the heat pump as a tuple with 2 elements, where the first element is of type `datetime.datetime` which represents the current date and time while the second element is the corresponding weekday in form of an `int` between 1 and 7, inclusive (Monday through Sunday). For example: ( datetime.datetime(...), 2 ) # 2 = Tuesday
Return type:	`tuple` ( datetime.datetime, int )
Raises:	IOError – Will be raised when the serial connection is not open or received an incomplete/invalid response (e.g. broken data stream, invalid checksum).

get_fault_list_async(*args) → List[Dict[str, object]][source]¶

Query for the fault list of the heat pump.

Parameters:	args (int) – The index number(s) to request from the fault list (optional). If not specified all fault list entries are requested.
Returns:	The requested entries of the fault list as `list`, e.g.: [ { "index" : 29, # fault list index "error" : 20, # error code "datetime": datetime.datetime(...), # date and time of the entry "message" : "EQ_Spreizung", # error message }, # ... ]
Return type:	`list`
Raises:	IOError – Will be raised when the serial connection is not open or received an incomplete/invalid response (e.g. broken data stream, invalid checksum).

get_fault_list_size_async() → int[source]¶

Query for the fault list size of the heat pump.

Returns:	The size of the fault list as `int`.
Return type:	`int`
Raises:	IOError – Will be raised when the serial connection is not open or received an incomplete/invalid response (e.g. broken data stream, invalid checksum).

get_last_fault_async() → Tuple[int, int, datetime.datetime, str][source]¶

Query for the last fault message of the heat pump.

Returns:	The last fault message of the heat pump as a tuple with 4 elements. The first element of the returned tuple represents the index as `int` of the message inside the fault list. The second element is (probably) the the error code as `int` defined by Heliotherm. The last two elements of the tuple are the date and time when the error occurred (as `datetime.datetime`) and the error message string itself. For example: ( 29, 20, datetime.datetime(...), "EQ_Spreizung" )
Return type:	`tuple` ( int, int, datetime.datetime, str )
Raises:	IOError – Will be raised when the serial connection is not open or received an incomplete/invalid response (e.g. broken data stream, invalid checksum).

get_param_async(name: str) → Union[bool, int, float][source]¶

Query for a specific parameter of the heat pump.

Parameters:	name (str) – The parameter name, e.g. `"Betriebsart"`.
Returns:	Returned value of the requested parameter. The type of the returned value is defined by the csv-table of supported heat pump parameters in `htparams.csv`.
Return type:	`bool`, `int` or `float`
Raises:	KeyError – Will be raised when the parameter definition for the passed parameter is not found. IOError – Will be raised when the serial connection is not open or received an incomplete/invalid response (e.g. broken data stream, invalid checksum). VerificationException – Will be raised if the parameter verification fails and the property `verify_param_error` is set to `True`. If property `verify_param_error` is set to `False` only a warning message will be emitted. The performed verification steps are defined by the property `verify_param_action`.

For example, the following call

temp = await hp.get_param_async("Temp. Aussen")

will return the current measured outdoor temperature in °C.

get_serial_number_async() → int[source]¶

Query for the manufacturer’s serial number of the heat pump.

Returns:	The manufacturer’s serial number of the heat pump as `int` (e.g. `123456`).
Return type:	`int`
Raises:	IOError – Will be raised when the serial connection is not open or received an incomplete/invalid response (e.g. broken data stream, invalid checksum).

get_time_prog_async(idx: int, with_entries: bool = True) → htheatpump.httimeprog.TimeProgram[source]¶

Return a specific time program (specified by their index) together with their time program entries (if desired) from the heat pump.

Parameters:	idx (int) – The time program index. with_entries (bool) – Determines whether also the single time program entries should be requested or not. Default is `True`.
Returns:	The requested time program as `TimeProgram`.
Return type:	`TimeProgram`
Raises:	IOError – Will be raised when the serial connection is not open or received an incomplete/invalid response (e.g. broken data stream, invalid checksum).

get_time_prog_entry_async(idx: int, day: int, num: int) → htheatpump.httimeprog.TimeProgEntry[source]¶

Return a specific time program entry (specified by time program index, day and entry-of-day) of the heat pump.

Parameters:	idx (int) – The time program index. day (int) – The day of the time program entry (inside the specified time program). num (int) – The number of the time program entry (of the specified day).
Returns:	The requested time program entry as `TimeProgEntry`.
Return type:	`TimeProgEntry`
Raises:	IOError – Will be raised when the serial connection is not open or received an incomplete/invalid response (e.g. broken data stream, invalid checksum).

get_time_progs_async() → List[htheatpump.httimeprog.TimeProgram][source]¶

Return a list of all available time programs of the heat pump.

Returns:	A list of `TimeProgram` instances.
Return type:	`list`
Raises:	IOError – Will be raised when the serial connection is not open or received an incomplete/invalid response (e.g. broken data stream, invalid checksum).

get_version_async() → Tuple[str, int][source]¶

Query for the software version of the heat pump.

Returns:	The software version of the heat pump as a tuple with 2 elements. The first element inside the returned tuple represents the software version as a readable string in a common version number format (e.g. `"3.0.20"`). The second element (probably) contains a numerical representation as `int` of the software version returned by the heat pump. For example: ( "3.0.20", 2321 )
Return type:	`tuple` ( str, int )
Raises:	IOError – Will be raised when the serial connection is not open or received an incomplete/invalid response (e.g. broken data stream, invalid checksum).

in_error_async¶

Query whether the heat pump is malfunctioning.

Returns:	`True` if the heat pump is malfunctioning, `False` otherwise.
Return type:	`bool`
Raises:	IOError – Will be raised when the serial connection is not open or received an incomplete/invalid response (e.g. broken data stream, invalid checksum).

login_async(update_param_limits: bool = False, max_retries: int = 2) → None[source]¶

Log in the heat pump. If update_param_limits is True an update of the parameter limits in HtParams will be performed. This will be done by requesting the current value together with their limits (MIN and MAX) for all “known” parameters directly after a successful login.

Parameters:	update_param_limits (bool) – Determines whether an update of the parameter limits in `HtParams` should be done or not. Default is `False`. max_retries (int) – Maximal number of retries for a successful login. One regular try plus `max_retries` retries. Default is `DEFAULT_LOGIN_RETRIES`.
Raises:	IOError – Will be raised when the serial connection is not open or received an incomplete/invalid response (e.g. broken data stream, invalid checksum).

logout_async() → None[source]¶: Log out from the heat pump session.

open_connection() → None[source]¶

Open the serial connection with the defined settings.

Raises:	IOError – When the serial connection is already open. ValueError – Will be raised when parameter are out of range, e.g. baudrate, bytesize. SerialException – In case the device can not be found or can not be configured.

query_async(*args) → Dict[str, Union[bool, int, float]][source]¶

Query for the current values of parameters from the heat pump.

Parameters:	args (str) – The parameter name(s) to request from the heat pump. If not specified all “known” parameters are requested.
Returns:	A dict of the requested parameters with their values, e.g.: { "HKR Soll_Raum": 21.0, "Stoerung": False, "Temp. Aussen": 8.8, # ... }
Return type:	`dict`
Raises:	KeyError – Will be raised when the parameter definition for a passed parameter is not found. IOError – Will be raised when the serial connection is not open or received an incomplete/invalid response (e.g. broken data stream, invalid checksum). VerificationException – Will be raised if the parameter verification fails and the property `verify_param_error` is set to `True`. If property `verify_param_error` is set to `False` only a warning message will be emitted. The performed verification steps are defined by the property `verify_param_action`.

read_response_async() → str[source]¶

Read the response message from the heat pump.

Returns:	The returned response message of the heat pump as `str`.
Return type:	`str`
Raises:	IOError – Will be raised when the serial connection is not open or received an incomplete/invalid (or unknown) response (e.g. broken data stream, unknown header, invalid checksum, …).

Note

There is a little bit strange behavior how the heat pump sometimes replies on some requests:

A response from the heat pump normally consists of the following header (the first 6 bytes) b"\x02\xfd\xe0\xd0\x00\x00" together with the payload and a computed checksum. But sometimes the heat pump replies with a different header (b"\x02\xfd\xe0\xd0\x04\x00" or b"\x02\xfd\xe0\xd0\x08\x00") together with the payload and a fixed value of 0x0 for the checksum (regardless of the content).

We have no idea about the reason for this behavior. But after analysing the communication between the Heliotherm home control Windows application and the heat pump, which simply accepts this kind of responses, we also decided to handle it as a valid answer to a request.

Furthermore, we have noticed another behavior, which is not fully explainable: For some response messages from the heat pump (e.g. for the error message "ERR,INVALID IDX") the transmitted payload length in the protocol is zero (0 bytes), although some payload follows. In this case we read until we will found the trailing b"\r\n" at the end of the payload to determine the payload of the message.

Additionally to the upper described facts, for some of the answers of the heat pump the payload length must be corrected (for the checksum computation) so that the received checksum fits with the computed one (e.g. for b"\x02\xfd\xe0\xd0\x01\x00" and b"\x02\xfd\xe0\xd0\x02\x00").

send_request_async(cmd: str) → None[source]¶

Send a request to the heat pump.

Parameters:	cmd (str) – Command to send to the heat pump.
Raises:	IOError – Will be raised when the serial connection is not open.

set_date_time_async(dt: Optional[datetime.datetime] = None) → Tuple[datetime.datetime, int][source]¶

Set the current date and time of the heat pump.

Parameters:	dt (datetime.datetime) – The date and time to set. If `None` current date and time of the host will be used.
Returns:	A 2-elements tuple composed of a `datetime.datetime` which represents the sent date and time and an `int` between 1 and 7, inclusive, for the corresponding weekday (Monday through Sunday).
Return type:	`tuple` ( datetime.datetime, int )
Raises:	TypeError – Raised for an invalid type of argument `dt`. Must be `None` or of type `datetime.datetime`. IOError – Will be raised when the serial connection is not open or received an incomplete/invalid response (e.g. broken data stream, invalid checksum).

set_param_async(name: str, val: Union[bool, int, float], ignore_limits: bool = False) → Union[bool, int, float][source]¶

Set the value of a specific parameter of the heat pump. If ignore_limits is False and the passed value is beyond the parameter limits a ValueError will be raised.

Parameters:	name (str) – The parameter name, e.g. `"Betriebsart"`. val (bool, int or float) – The value to set. ignore_limits (bool) – Indicates if the parameter limits should be ignored or not.
Returns:	Returned value of the parameter set request. In case of success this value should be the same as the one passed to the function. The type of the returned value is defined by the csv-table of supported heat pump parameters in `htparams.csv`.
Return type:	`bool`, `int` or `float`
Raises:	KeyError – Will be raised when the parameter definition for the passed parameter is not found. ValueError – Will be raised if the passed value is beyond the parameter limits and argument `ignore_limits` is set to `False`. IOError – Will be raised when the serial connection is not open or received an incomplete/invalid response (e.g. broken data stream, invalid checksum). VerificationException – Will be raised if the parameter verification fails and the property `verify_param_error` is set to `True`. If property `verify_param_error` is set to `False` only a warning message will be emitted. The performed verification steps are defined by the property `verify_param_action`.

For example, the following call

await hp.set_param_async("HKR Soll_Raum", 21.5)

will set the desired room temperature of the heating circuit to 21.5 °C.

set_time_prog_async(time_prog: htheatpump.httimeprog.TimeProgram) → htheatpump.httimeprog.TimeProgram[source]¶

Set all time program entries of a specific time program. Any non-specified entry (which is None) in the time program will be requested from the heat pump. The returned TimeProgram instance includes therefore all entries of this time program.

Parameters:	time_prog (TimeProgram) – The given time program as `TimeProgram`.
Returns:	The time program as `TimeProgram` including all time program entries.
Return type:	`TimeProgram`
Raises:	IOError – Will be raised when the serial connection is not open or received an incomplete/invalid response (e.g. broken data stream, invalid checksum).

set_time_prog_entry_async(idx: int, day: int, num: int, entry: htheatpump.httimeprog.TimeProgEntry) → htheatpump.httimeprog.TimeProgEntry[source]¶

Set a specific time program entry (specified by time program index, day and entry-of-day) of the heat pump.

Parameters:	idx (int) – The time program index. day (int) – The day of the time program entry (inside the specified time program). num (int) – The number of the time program entry (of the specified day). entry (TimeProgEntry) – The new time program entry as `TimeProgEntry`.
Returns:	The changed time program entry `TimeProgEntry`.
Return type:	`TimeProgEntry`
Raises:	IOError – Will be raised when the serial connection is not open or received an incomplete/invalid response (e.g. broken data stream, invalid checksum).

update_param_limits_async() → List[str][source]¶

Perform an update of the parameter limits in HtParams by requesting the limit values of all “known” parameters directly from the heat pump.

Returns:	The list of updated (changed) parameters.
Return type:	`list`
Raises:	VerificationException – Will be raised if the parameter verification fails and the property `verify_param_error` is set to `True`. If property `verify_param_error` is set to `False` only a warning message will be emitted. The performed verification steps are defined by the property `verify_param_action`.

htheatpump.httimeprog¶

Classes representing the time programs of the Heliotherm heat pump.

class htheatpump.httimeprog.TimeProgPeriod(start_hour: int, start_minute: int, end_hour: int, end_minute: int)[source]¶

Representation of a time program period defined by start- and end-time (HH:MM).

Parameters:	start_hour (int) – The hour value of the start-time (`HH`). start_minute (int) – The minute value of the start-time (`MM`). end_hour (int) – The hour value of the end-time (`HH`). end_minute (int) – The minute value of the end-time (`MM`).
Raises:	ValueError – Will be raised for any invalid argument.

as_dict() → Dict[str, object][source]¶

Create a dict representation of this time program period.

Returns:	A dict representing this time program period.
Return type:	`dict`

as_json() → Dict[str, object][source]¶

Create a json-readable dict representation of this time program period.

Returns:	A json-readable dict representing this time program period.
Return type:	`dict`

end¶

Return the end-time of this time program period as a tuple with 2 elements, where the first element represents the hours and the second one the minutes.

Returns:	The end-time of this time program period as tuple. For example: ( 16, 45 ) # -> 16:45
Return type:	`tuple` ( int, int )

end_hour¶

Return the hour value of the end-time of this time program period.

Returns:	The hour value of the end-time of this time program period.
Return type:	`int`

end_minute¶

Return the minute value of the end-time of this time program period.

Returns:	The minute value of the end-time of this time program period.
Return type:	`int`

end_str¶

Return the end-time of this time program period as str.

Returns:	The end-time of this time program period as `str`. For example: '16:45'
Return type:	`str`

classmethod from_json(json_dict: Dict[str, str]) → TimeProgPeriodT[source]¶

Create a TimeProgPeriod instance from a JSON representation.

Parameters:	json_dict (dict) – The JSON representation of the time program period as `dict`.
Return type:	`TimeProgPeriod`
Raises:	ValueError – Will be raised for any invalid argument.

classmethod from_str(start_str: str, end_str: str) → TimeProgPeriodT[source]¶

Create a TimeProgPeriod instance from string representations of the start- and end-time.

Parameters:	start_str (str) – The start-time of the time program entry as `str`. end_str (str) – The end-time of the time program entry as `str`.
Returns:	A `TimeProgPeriod` instance with the given properties.
Return type:	`TimeProgPeriod`
Raises:	ValueError – Will be raised for any invalid argument.

set(start_hour: int, start_minute: int, end_hour: int, end_minute: int) → None[source]¶

Set the start- and end-time of this time program period.

Parameters:	start_hour (int) – The hour value of the start-time. start_minute (int) – The minute value of the start-time. end_hour (int) – The hour value of the end-time. end_minute (int) – The minute value of the end-time.
Raises:	ValueError – Will be raised for any invalid argument.

start¶

Return the start-time of this time program period as a tuple with 2 elements, where the first element represents the hours and the second one the minutes.

Returns:	The start-time of this time program period as tuple. For example: ( 11, 0 ) # -> 11:00
Return type:	`tuple` ( int, int )

start_hour¶

Return the hour value of the start-time of this time program period.

Returns:	The hour value of the start-time of this time program period.
Return type:	`int`

start_minute¶

Return the minute value of the start-time of this time program period.

Returns:	The minute value of the start-time of this time program period.
Return type:	`int`

start_str¶

Return the start-time of this time program period as str.

Returns:	The start-time of this time program period as `str`. For example: '11:00'
Return type:	`str`

class htheatpump.httimeprog.TimeProgEntry(state: int, period: htheatpump.httimeprog.TimeProgPeriod)[source]¶

Representation of a single time program entry.

Parameters:	state (int) – The state of the time program entry. period (TimeProgPeriod) – The period of the time program entry.

as_dict() → Dict[str, object][source]¶

Create a dict representation of this time program entry.

Returns:	A dict representing this time program entry.
Return type:	`dict`

as_json() → Dict[str, object][source]¶

Create a json-readable dict representation of this time program entry.

Returns:	A json-readable dict representing this time program entry.
Return type:	`dict`

classmethod from_json(json_dict: Dict[str, Any]) → TimeProgEntryT[source]¶

Create a TimeProgEntry instance from a JSON representation.

Parameters:	json_dict (dict) – The JSON representation of the time program entry as `dict`.
Return type:	`TimeProgEntry`
Raises:	ValueError – Will be raised for any invalid argument.

classmethod from_str(state: str, start_str: str, end_str: str) → TimeProgEntryT[source]¶

Create a TimeProgEntry instance from string representations of the state, start- and end-time.

Parameters:	state (str) – The state of the time program entry as `str`. start_str (str) – The start-time of the time program entry as `str`. end_str (str) – The end-time of the time program entry as `str`.
Returns:	A `TimeProgEntry` instance with the given properties.
Return type:	`TimeProgEntry`

period¶

Property to get or set the period of this time program entry.

Param:	The new period of the time program entry as `TimeProgPeriod`.
Returns:	A copy of the current period of the time program entry as `TimeProgPeriod`.
Return type:	`TimeProgPeriod`

set(state: int, period: htheatpump.httimeprog.TimeProgPeriod) → None[source]¶

Set the state and period of this time program entry.

Parameters:	state (int) – The state of the time program entry. period (TimeProgPeriod) – The period of the time program entry.

state¶

Property to get or set the state of this time program entry.

Param:	The new state of the time program entry.
Returns:	The current state of the time program entry.
Return type:	`int`

class htheatpump.httimeprog.TimeProgram(idx: int, name: str, ead: int, nos: int, ste: int, nod: int)[source]¶

Representation of a time program of the Heliotherm heat pump.

Parameters:

idx (int) – The time program index.
name (str) – The name of the time program (e.g. “Warmwasser”).
ead (int) – The number of entries a day of the time program.
nos (int) – The number of states of the time program.
ste (int) – The step-size (in minutes) of the start- and end-times of the time program entries.
nod (int) – The number of days of the time program.

as_dict(with_entries: bool = True) → Dict[str, object][source]¶

Create a dict representation of this time program.

Parameters:	with_entries (bool) – Determines whether the single time program entries should be included or not. Default is `True`.
Returns:	A dict representing this time program.
Return type:	`dict`

as_json(with_entries: bool = True) → Dict[str, object][source]¶

Create a json-readable dict representation of this time program.

Parameters:	with_entries (bool) – Determines whether the single time program entries should be included or not. Default is `True`.
Returns:	A json-readable dict representing this time program.
Return type:	`dict`

entries_a_day¶

Return the number of entries a day of this time program.

Returns:	The number of entries a day of this time program.
Return type:	`int`

entries_of_day(day: int) → List[Optional[htheatpump.httimeprog.TimeProgEntry]][source]¶

Return a list of copies of time program entries of a specific day.

Parameters:	day (int) – The day of the time program entries.
Returns:	A list of `TimeProgEntry` instances or `None` if not set.
Return type:	`list` (TimeProgEntry)

entry(day: int, num: int) → Optional[htheatpump.httimeprog.TimeProgEntry][source]¶

Return a copy of a specific time program entry.

Parameters:	day (int) – The day of the time program entry. num (int) – The number of the time program entry.
Returns:	The time program entry as instance of `TimeProgEntry` or `None` if not set.
Return type:	`TimeProgEntry`

classmethod from_json(json_dict: Dict[str, Any]) → TimeProgramT[source]¶

Create a TimeProgram instance from a JSON representation.

Parameters:	json_dict (dict) – The JSON representation of the time program as `dict`.
Return type:	`TimeProgram`
Raises:	ValueError – Will be raised for any invalid argument.

index¶

Return the index of this time program.

Returns:	The index of this time program.
Return type:	`int`

name¶

Return the name of this time program.

Returns:	The name of this time program.
Return type:	`int`

number_of_days¶

Return the number of days of this time program.

Returns:	The number of days of this time program.
Return type:	`int`

number_of_states¶

Return the number of states of this time program.

Returns:	The number of states of this time program.
Return type:	`int`

set_entry(day: int, num: int, entry: htheatpump.httimeprog.TimeProgEntry) → None[source]¶

Set the properties of a given time program entry of the heat pump.

Parameters:	day (int) – The day of the time program entry. num (int) – The number of the time program entry. entry (TimeProgEntry) – The time program entry itself.
Raises:	ValueError – Will be raised if any property of the given entry is out of the specification of this time program.

step_size¶

Return the step-size (in minutes) of the start- and end-times of this time program entries.

Returns:	The step-size (in minutes) of the start- and end-times of this time program entries.
Return type:	`int`

htheatpump.htparams¶

Definition of the Heliotherm heat pump parameters together with their

data point type (“MP”, “SP”),
data point number,
access rights,
data type,
minimal value and
maximal value.

class htheatpump.htparams.HtDataTypes[source]¶

Supported data types of the Heliotherm heat pump:

BOOL The value of the parameter is given as boolean (e.g. on/off, yes/no, enabled/disabled).
INT The value of the parameter is given as integer.
FLOAT The value of the parameter is given as floating point number.

class htheatpump.htparams.HtParam(dp_type: str, dp_number: int, acl: str, data_type: htheatpump.htparams.HtDataTypes, min_val: Union[bool, int, float, None] = None, max_val: Union[bool, int, float, None] = None)[source]¶

Representation of a specific heat pump parameter.

Parameters:

dp_type (str) – The data point type ("MP", "SP").
dp_number (int) – The data point number.
acl (str) – The access rights ('r' = read, 'w' = write).
data_type (HtDataTypes) – The data type, see HtDataTypes.
min_val (bool, int, float or None) – The minimal value (default None, which means “doesn’t matter”).
max_val (bool, int, float or None) – The maximal value (default None, which means “doesn’t matter”).

Raises:

TypeError – Will be raised if the passed minimal or maximal value has an invalid type.

check_value_type(arg: Union[bool, int, float, htheatpump.htparams.HtDataTypes]) → None[source]¶

Check the type of the passed value against the given parameter data type.

This method can be called as a static method, e.g.:

s = HtParam.check_value_type(123, HtDataTypes.FLOAT)

or as a member method of HtParam, e.g.:

param = HtParams["Temp. Aussen"]
s = param.check_value_type(3.2)

If the method is called as a member method of HtParam, the data type of the passed value don’t have to be specified. It will be automatically determined from the HtParam instance.

Raises:	TypeError – Will be raised if the passed value has an invalid type.

cmd() → str[source]¶

Return the command string, based on the data point type and number of the parameter.

Returns:	The command string.
Return type:	`str`

from_str(arg: Union[str, htheatpump.htparams.HtDataTypes], strict: bool = True) → Union[bool, int, float][source]¶

Convert the passed value (in form of a string) to the expected data type.

This method can be called as a static method, e.g.:

val = HtParam.from_str("123", HtDataTypes.INT)

or as a member method of HtParam, e.g.:

param = HtParams["Temp. Aussen"]
val = param.from_str(s, strict=False)

If the method is called as a member method of HtParam, the expected data type don’t have to be specified. It will be automatically determined from the HtParam instance.

Parameters:	strict – Determines whether the conversion to `float` should be strict (if `False` also integers are accepted, e.g. `'328'`).
Returns:	The passed value which data type matches the expected one.
Return type:	`bool`, `int` or `float`
Raises:	TypeError – Will be raised if the passed value has an invalid type. ValueError – Will be raised if the passed value could not be converted to the expected data type.

in_limits(val: Union[bool, int, float, None]) → bool[source]¶

Determine whether the passed value is in between the parameter limits or not.

Parameters:	val (bool, int or float) – The value to check against the parameter limits.
Returns:	`True` if the passed value is in between the limits, `False` otherwise.
Return type:	`bool`
Raises:	TypeError – Will be raised if the passed value has an invalid type.

set_limits(min_val: Union[bool, int, float, None] = None, max_val: Union[bool, int, float, None] = None) → bool[source]¶

Set the limits of the parameter and return whether the passed limit values differed from the old one.

Parameters:	min_val (bool, int, float or None) – The minimal value (default `None`, which means “doesn’t matter”). max_val (bool, int, float or None) – The maximal value (default `None`, which means “doesn’t matter”).
Returns:	`True` if the passed min- and/or max-value differed from the old one, `False` otherwise.
Return type:	`bool`
Raises:	TypeError – Will be raised if the passed minimal or maximal value has an invalid type.

to_str(arg: Union[bool, int, float, htheatpump.htparams.HtDataTypes]) → str[source]¶

Convert the passed value to a string.

This method can be called as a static method, e.g.:

s = HtParam.to_str(123, HtDataTypes.FLOAT)

or as a member method of HtParam, e.g.:

param = HtParams["Temp. Aussen"]
s = param.to_str(3.2)

If the method is called as a member method of HtParam, the data type of the passed value don’t have to be specified. It will be automatically determined from the HtParam instance.

Returns:	The string representation of the passed value.
Return type:	`str`

class htheatpump.htparams.HtParams[source]¶

Dictionary of the supported Heliotherm heat pump parameters. [*]

Note

The supported parameters and their definitions are loaded from the CSV file htparams.csv in this package, but the user can create his own user specific CSV file under ~/.htheatpump/htparams.csv.

[*]	Most of the supported heat pump parameters were found by “sniffing” the serial communication of the Heliotherm home control Windows application (http://homecontrol.heliotherm.com) during a refresh! ;-)

htheatpump.protocol¶

Protocol constants and functions for the Heliotherm heat pump communication.

htheatpump.protocol.add_checksum(s: bytes) → bytes[source]¶

Add a checksum at the end of the provided bytes array.

Parameters:	s (bytes) – The provided byte array.
Returns:	Byte array with the added checksum.
Return type:	`bytes`
Raises:	ValueError – Will be raised for an invalid byte array with length less than 1 byte.

htheatpump.protocol.calc_checksum(s: bytes) → int[source]¶

Function that calculates the checksum of a provided bytes array.

Parameters:	s (bytes) – Byte array from which the checksum should be computed.
Returns:	The computed checksum as `int`.
Return type:	`int`

htheatpump.protocol.create_request(cmd: str) → bytes[source]¶

Create a specified request command for the heat pump.

Parameters:	cmd (str) – The command string.
Returns:	The request string for the specified command as byte array.
Return type:	`bytes`
Raises:	ValueError – Will be raised for an invalid byte array with length greater than 253 byte.

htheatpump.protocol.verify_checksum(s: bytes) → bool[source]¶

Verify if the provided bytes array is terminated with a valid checksum.

Parameters:	s (bytes) – The byte array including the checksum.
Returns:	`True` if valid, `False` otherwise.
Return type:	`bool`
Raises:	ValueError – Will be raised for an invalid byte array with length less than 2 bytes.

htheatpump.utils¶

Some useful helper classes and methods.

class htheatpump.utils.Singleton[source]¶

Singleton base class.

Example:

>>> class MySingleton(Singleton):
...     def __init__(self, v):
...         self._val = v
...     def __str__(self):
...         return str(self._val)

>>> s1 = MySingleton(1)
>>> print(str(s1))
1
>>> s2 = MySingleton(2)
>>> print(str(s2))
2
>>> print(str(s1))
2