Skip to main content

Easy-to-use Python communication module for Heliotherm heat pumps

Project description


PyPI version Python versions License Build status Documentation status Updates

Easy-to-use Python communication module for Heliotherm and Brötje BSW NEO heat pumps.


This library provides a pure Python interface to access Heliotherm and Brötje BSW NEO heat pumps over a serial connection. It’s compatible with Python version 3.7 and 3.8.


  • read the manufacturer’s serial number of the heat pump
  • read the software version of the heat pump
  • read and write the current date and time of the heat pump
  • read the fault list of the heat pump
  • query whether the heat pump is malfunctioning
  • query for several parameters of the heat pump
  • change parameter values of the heat pump
  • fast query of MP data points / parameters (“Web-Online”)
  • read and write the time programs of the heat pump

Tested with [*]

  • Heliotherm HP08S10W-WEB, SW 3.0.20

  • Heliotherm HP10S12W-WEB, SW 3.0.8

  • Heliotherm HP08E-K-BC, SW 3.0.7B

  • Heliotherm HP05S07W-WEB, SW 3.0.17 and SW 3.0.37

  • Heliotherm HP12L-M-BC, SW 3.0.21

  • Heliotherm HP07S08W-WEB, SW 3.0.37

  • Heliotherm HP-30-L-M-WEB, SW 3.0.21

  • Brötje BSW NEO 8 SW 3.0.38


    thanks to Kilian, Hans, Alois, Simon, Felix (FelixPetriconi) and Matthias for contribution


You can install or upgrade htheatpump with:

$ pip install htheatpump --upgrade

Or you can install from source with:

$ git clone
$ cd htheatpump
$ python install

Getting started

To use htheatpump in a project take a look on the following example. After establishing a connection with the Heliotherm heat pump one can interact with it by different functions like reading or writing parameters.

from htheatpump import HtHeatpump

hp = HtHeatpump("/dev/ttyUSB0", baudrate=9600)
    # query for the outdoor temperature
    temp = hp.get_param("Temp. Aussen")
    # ...
    hp.logout()  # try to logout for an ordinary cancellation (if possible)
from htheatpump import AioHtHeatpump

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

A full list of supported functions can be found in the htheatpump documentation at

There are also some sample scripts that are part of the htheatpump package and can be run immediately after installation, e.g.:

$ htquery --device /dev/ttyUSB1 "Temp. Aussen" "Stoerung"
HTHEATPUMP: load parameter definitions from: /home/pi/prog/htheatpump/htheatpump/htparams.csv
Stoerung    : False
Temp. Aussen: 5.0


This library uses the logging module. To set up logging to standard output, put

import logging

at the beginning of your script.



Please note that any incorrect or careless usage of this module as well as errors in the implementation can damage your heat pump!

Therefore, the author does not provide any guarantee or warranty concerning to correctness, functionality or performance and does not accept any liability for damage caused by this module, examples or mentioned information.

Thus, use it on your own risk!


Contributions are always welcome. Please review the contribution guidelines to get started. You can also help by reporting bugs.

Wanna support me?

Buy Me A Coffee



Distributed under the terms of the GNU General Public License v3.


1.3.1 (2021-01-20)

  • replaced Travis CI by GitHub Actions
  • added async version of console scripts
  • updated copyright statements
  • some minor cleanup and improvements

1.3.0 (2020-12-28)

  • added new class AioHtHeatpump for asynchronous communication (async/await) with the heat pump
  • Python code reformatting using Black and isort
  • moved protocol related constants and functions to
  • dropped support for Python 3.5 and 3.6

1.2.4 (2020-04-20)

  • added support for Python 3.8
  • some minor cleanup and improvements
  • changed log statements to the form with the preferred and well-known %s (and %d, %f, etc.) string formatting indicators (due to performance reasons)
  • added additional heat pump parameter (data points) Hauptschalter in htparams.csv

1.2.3 (2020-03-31)

  • changed behaviour of HtHeatpump.reconnect(), which will now also establish a connection if still not connected
  • added sample scripts (e.g. htcomplparams, htquery, etc.) to be part of the htheatpump package
  • clean-up of and

1.2.2 (2020-03-29)

  • added sample file htparams-xxxxxx-3_0_20-273.csv with a complete list of all heat pump parameters from a Heliotherm heat pump with SW 3.0.20
  • added new sample script to create a complete list of all heat pump parameters
  • added some more heat pump parameters (data points) in htparams.csv
  • Python code reformatting using Black
  • changed package requirements structure; some changes in, setup.cfg, tox.ini, etc.

1.2.1 (2020-02-07)

  • updated copyright statements
  • added factory function from_json to classes TimeProgPeriod, TimeProgEntry and TimeProgram
  • fixed issue with fault lists with larger number of entries (in HtHeatpump.get_fault_list()); thanks to Alois for reporting
  • added new function HtParam.check_value_type to verify the correct type of a passed value; the type of a passed value to HtHeatpump.set_param() will now be verified
  • fixed issue with passing a larger number of indices to HtHeatpump.fast_query()

1.2.0 (2019-06-10)

  • added support for Python’s “with” statement for the HtHeatpump class
  • added some more unit-tests (especially for the time program functions)
  • extended the sample scripts to query for time programs of the heat pump
  • added new sample samples/ to read the time programs of the heat pump
  • added new functions to write/change time program entries of the heat pump (see HtHeatpump.set_time_prog...)
  • added new functions to read the time program of the heat pump (see HtHeatpump.get_time_prog...)
  • added type annotations and hints for static type checking (using mypy)
  • splitted up property HtHeatpump.verify_param to HtHeatpump.verify_param_action and HtHeatpump.verify_param_error
  • renamed exception ParamVerificationException to VerificationException
  • added support for Python 3.7
  • dropped support for Python 3.4
  • added some more heat pump parameters (data points) in htparams.csv

1.1.0 (2019-02-23)

  • added some more heat pump parameters (data points) in htparams.csv
  • extended sample script by the possibility to write a JSON/CSV file
  • added new sample scripts and
  • fixed some formatting (flake8) errors
  • some improvement for the reconnect in the login() method of class HtHeatpump
  • changed return type of HtHeatpump.get_fault_list() from dict to list
  • added support for Python 3.6
  • added support for a user specific parameter definition file under ~/.htheatpump/htparams.csv
  • extended sample to store also the limits (MIN and MAX) of each data point
  • added method to verify the parameter definitions in htparams.csv during a HtHeatpump.get_param(), HtHeatpump.set_param() or HtHeatpump.query(); this is just for safety to be sure that the parameter definitions in HtParams are correct (deactivated by default, but can be activated by setting the property HtHeatpump.verify_param to True)
  • added new method HtHeatpump.fast_query() to retrieve “MP” data point values in a faster way (“Web-Online”)
  • extended the HtHeatpump.login() method to perform an update of the parameter limits if desired

1.0.0 (2018-01-12)

  • First release on PyPI.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for htheatpump, version 1.3.1
Filename, size File type Python version Upload date Hashes
Filename, size htheatpump-1.3.1.tar.gz (94.9 kB) File type Source Python version None Upload date Hashes View
Filename, size htheatpump-1.3.1-py3-none-any.whl (113.3 kB) File type Wheel Python version py3 Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page