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, **kwargs)[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 (optional).
  • bytesize (int) – The bytesize of the serial messages (optional).
  • parity (str) – Which kind of parity to use (optional).
  • stopbits (float) – The number of stop bits to use (optional).
  • xonxoff (bool) – Software flow control enabled (optional).
  • rtscts (bool) – Hardware flow control (RTS/CTS) enabled (optional).
  • dsrdtr (bool) – Hardware flow control (DSR/DTR) enabled (optional).
  • verify_param_action (set) – Parameter verification actions (optional).
  • verify_param_error (bool) – Interpretation of parameter verification failure as error enabled (optional).

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()
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 2.
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.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.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
class htheatpump.utils.Timer[source]

Context manager for execution time measurement.

Example:

>>> with Timer() as timer:
...     s = "-".join(str(n) for n in range(1000))
...
>>> exec_time = timer.elapsed
elapsed

Return the elapsed time (in seconds).

Returns:The elapsed time in seconds.
Return type:float