Metadata-Version: 2.1
Name: htheatpump
Version: 1.3.0
Summary: Easy-to-use Python communication module for Heliotherm heat pumps
Home-page: https://github.com/dstrigl/htheatpump
Author: Daniel Strigl
License: GNU General Public License v3
Keywords: python python3 heatpump serial protocol Heliotherm
Platform: Linux
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Manufacturing
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Natural Language :: English
Classifier: Operating System :: POSIX
Classifier: Operating System :: POSIX :: Linux
Classifier: Topic :: Communications
Classifier: Topic :: Home Automation
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Hardware :: Hardware Drivers
Classifier: Topic :: Terminals :: Serial
Description-Content-Type: text/x-rst
Requires-Dist: pyserial (==3.5)
Requires-Dist: aioserial (==1.3.0)
Provides-Extra: dev
Requires-Dist: mypy (==0.790) ; extra == 'dev'
Requires-Dist: coverage (==5.3.1) ; extra == 'dev'
Requires-Dist: pytest (==6.2.1) ; extra == 'dev'
Requires-Dist: pytest-asyncio (==0.14.0) ; extra == 'dev'
Requires-Dist: pytest-mypy (==0.8.0) ; extra == 'dev'
Requires-Dist: pytest-cov (==2.10.1) ; extra == 'dev'
Requires-Dist: pytest-sugar (==0.9.4) ; extra == 'dev'
Requires-Dist: flake8 (==3.8.4) ; extra == 'dev'
Requires-Dist: tox (==3.20.1) ; extra == 'dev'
Provides-Extra: doc
Requires-Dist: Sphinx (==3.4.1) ; extra == 'doc'
Requires-Dist: sphinx-rtd-theme (==0.5.0) ; extra == 'doc'
Provides-Extra: test
Requires-Dist: mypy (==0.790) ; extra == 'test'
Requires-Dist: coverage (==5.3.1) ; extra == 'test'
Requires-Dist: pytest (==6.2.1) ; extra == 'test'
Requires-Dist: pytest-asyncio (==0.14.0) ; extra == 'test'
Requires-Dist: pytest-mypy (==0.8.0) ; extra == 'test'
Requires-Dist: pytest-cov (==2.10.1) ; extra == 'test'
Requires-Dist: pytest-sugar (==0.9.4) ; extra == 'test'

HtHeatpump
==========

.. image:: https://img.shields.io/pypi/v/htheatpump.svg
  :target: https://pypi.org/project/htheatpump
  :alt: PyPI version

.. image:: https://img.shields.io/pypi/pyversions/htheatpump.svg
  :target: https://pypi.org/project/htheatpump
  :alt: Python versions

.. image:: https://img.shields.io/pypi/l/htheatpump.svg
  :target: https://pypi.org/project/htheatpump
  :alt: License

.. image:: https://img.shields.io/travis/dstrigl/htheatpump/master?logo=travis
  :target: https://travis-ci.org/dstrigl/htheatpump
  :alt: Build status

.. 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/>`_ and
`Brötje BSW NEO <https://www.broetje.de/>`_ 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/>`_ and
`Brötje BSW NEO <https://www.broetje.de/>`_ heat pumps
over a serial connection. It's compatible with Python version 3.7 and 3.8.


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")
* 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
* Brötje BSW NEO 8 SW 3.0.38

  .. [*] thanks to Kilian, Hans, Alois, Simon and Felix (`FelixPetriconi <https://github.com/FelixPetriconi>`_) for contribution


Installation
------------

You can install or upgrade ``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 ``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 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()

.. code:: python

    from htheatpump import AioHtHeatpump

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

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

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

.. code-block:: shell

    $ 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


Logging
~~~~~~~

This library uses the ``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>`_.


Wanna support me?
-----------------

.. image:: https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png
   :target: https://www.buymeacoffee.com/N362PLZ
   :alt: Buy Me A Coffee


Credits
-------

* Created with Cookiecutter_ and the `audreyr/cookiecutter-pypackage`_ project template.
* Project dependencies scanned by `PyUp.io`_.

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


License
-------

Distributed under the terms of the `GNU General Public License v3 <https://www.gnu.org/licenses/gpl-3.0.en.html>`_.


History
=======

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 ``protocol.py``
* 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 ``setup.py`` and ``MANIFEST.in``

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 ``htcomplparams.py`` 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.py``, ``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 ``hthttp.py`` to query for time programs of the heat pump
* added new sample ``samples/httimeprog.py`` 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 ``htfaultlist.py`` by the possibility to write a JSON/CSV file
* added new sample scripts ``hthttp.py`` and ``htfastquery.py``
* 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 ``htbackup.py`` 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.


