htheatpump 1.1.0

HtHeatpump
==========


.. image:: https://img.shields.io/pypi/v/htheatpump.svg
:target: https://pypi.python.org/pypi/htheatpump

.. image:: https://img.shields.io/travis/dstrigl/htheatpump.svg
:target: https://travis-ci.org/dstrigl/htheatpump

.. image:: https://readthedocs.org/projects/htheatpump/badge/?version=latest
:target: https://htheatpump.readthedocs.io/en/latest/?badge=latest
:alt: Documentation Status

.. image:: https://pyup.io/repos/github/dstrigl/htheatpump/shield.svg
:target: https://pyup.io/repos/github/dstrigl/htheatpump/
:alt: Updates


Easy-to-use Python communication module for `Heliotherm <http://www.heliotherm.com/>`_ heat pumps.


* GitHub repo: https://github.com/dstrigl/htheatpump
* Documentation: https://htheatpump.readthedocs.io
* Free software: `GNU General Public License v3 <https://www.gnu.org/licenses/gpl-3.0.en.html>`_


Introduction
------------

This library provides a pure Python interface to access `Heliotherm <http://www.heliotherm.com/>`_ heat pumps
over a serial connection. It's compatible with Python version 3.4, 3.5 and 3.6.

Features
~~~~~~~~

* 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")


Todo
~~~~

* check access right for writing parameters of the heat pump
* read and write the time programs of the heat pump
* add some (more) examples
* add some (more) unit tests
* cleanup/extend documentation


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
* Heliotherm HP12L-M-BC, SW 3.0.21

.. [*] thanks to Kilian, Hans, Alois and Simon for contribution


Installing
----------

You can install or upgrade :mod:`htheatpump` with:

.. code-block:: console

$ pip install htheatpump --upgrade

Or you can install from source with:

.. code-block:: console

$ git clone https://github.com/dstrigl/htheatpump.git
$ cd htheatpump
$ python setup.py install


Getting started
---------------

To use :mod:`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.

.. code:: python

from htheatpump.htheatpump import HtHeatpump

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()

A full list of supported functions can be found in the :mod:`htheatpump` documentation at
`readthedocs.io <https://htheatpump.readthedocs.io/en/latest/?badge=latest>`_.


Logging
~~~~~~~

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

.. code:: python

import logging
logging.basicConfig(level=logging.DEBUG)

at the beginning of your script.


Disclaimer
----------

.. warning::

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!**


Contributing
------------

Contributions are always welcome. Please review the
`contribution guidelines <https://github.com/dstrigl/htheatpump/blob/master/CONTRIBUTING.rst>`_
to get started.
You can also help by `reporting bugs <https://github.com/dstrigl/htheatpump/issues/new>`_.


Credits
-------

This package was created with Cookiecutter_ and the `audreyr/cookiecutter-pypackage`_ project template.

.. _Cookiecutter: https://github.com/audreyr/cookiecutter
.. _`audreyr/cookiecutter-pypackage`: https://github.com/audreyr/cookiecutter-pypackage


History
=======

1.1.0 (2019-02-23)
------------------

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

1.0.0 (2018-01-12)
------------------

* First release on PyPI.