{
    "info": {
        "author": "B\u00e1lint Aradi",
        "author_email": "baradi09@gmail.com",
        "bugtrack_url": null,
        "classifiers": [
            "Development Status :: 4 - Beta",
            "License :: OSI Approved :: BSD License",
            "Programming Language :: Python :: 3",
            "Topic :: Home Automation"
        ],
        "description": "********\nEazyCtrl\n********\n\nPython module and command line tool to monitor and control the air exchangers of\nHelios (KWL EasyControls) via their Modbus/TCP interface. It allows for an easy\ncommand line handling of the devices and for a smooth integration of those into\nsmart home systems (e.g. Home Assistant).\n\n**Important note**: The module and the command line tool were created based on\nthe publicly accessible documentation for the EasyControls Modbus/TCP interface\nand for the Modbus/TCP protocol. They were only tested with a Helios KWL EC 300\nW air exchanger. **Use them on your own risk**.\n\nThe tools are distributed under the terms of the *2-clause BSD License*.\n\n\nInstalling\n==========\n\nEazyCtrl should work with any recent Python 3 interpreters. (It has been tested\nwith Python 3.6).\n\nUse Pythons command line installer ``pip`` to install it::\n\n  pip install eazyctrl\n\nThis installs both, the single file command line tool ``eazyctrl`` and the\nsingle file Python module ``eazyctrl.py``. Latter you can import if you want to\naccess the functionality from within your Python scripts.\n\n\nUsing as command line tool\n==========================\n\nAll functionality can be accessed through the command line script\n``eazyctrl``. In order to get information about the possible command line\noptions, issue ::\n\n  eazyctrl -h\n\nIf you want help about a given subcommand, add the subcommand name before the\n``-h`` option, e.g. ::\n\n  eazyctrl set -h\n\nwill list the available options for the ``set`` subcommand.\n\n\nObtaining the feature list\n--------------------------\n\nIn order to list the features which you can access through ``eazyctrl``, use the\n``list`` subcommand::\n\n  eazyctrl list\n\nThis would return a table containing the feature names, their access flag\n(read-only or read-write) and the corresponding variable, e.g.::\n\n  Feature name                   Access Variable\n  ----------------------------------------------\n  fan_stage                      rw     v00102  \n  temp_outside_air               r      v00104  \n  temp_supply_air                r      v00105  \n  temp_outgoing_air              r      v00106  \n  temp_extract_air               r      v00107\n\n\nNote, that not all variables have been mapped to features yet. Those, not in the\ntable can be queried and set by the low-level variable access methods (see\nbelow). But whenever a named feature is available for a given variable, it is\nrecommended to use the more convenient and more robust access via the feature.\n\n\nGetting the value of a feature\n------------------------------\n\nUse the ``get`` subcommand to query the value of a given feature.\n\nFor example, to query the temperature of the outside air, issue::\n\n  eazyctrl get helios-kwl.fritz.box temp_outside_air\n\nThe first argument is the host name of the remote device (or its IP-address),\nfollowed by the feature name. The result is printed on the console, like::\n\n  23.3\n\n\nSetting the value of a feature\n------------------------------\n\nUse the ``set`` subcommand to set the value of a given feature.\n\nFor example, in order to set the fan stage to level 2, issue::\n\n  eazyctrl set helios-kwl.fritz.box fan_stage 2\n\nIf the script returns without error message, the communication with the device\nwas successful.\n\n\nGetting the value of a variable\n-------------------------------\n\nThe command line tool allows to query a variable directly by using its name.\nThis direct variable accesss should only be used, if the given variable has not\nbeen mapped to a feature yet.\n\nAdditionally to the name of the variable, you also have to provide the maximal\nlength of the expected answer (which can be looked up in the EasyControls\nmanual).\n\nFor example, to query the fan stage by reading the variable ``v00102``, issue ::\n\n  eazyctrl getvar helios-kwl.fritz.box v00102 1\n\n\nSetting the value of a variable\n-------------------------------\n\nThe command line tool allows to set a variable directly by using its name.  This\ndirect variable accesss should only be used, if the given variable has not been\nmapped to a feature yet.\n\nNote, that the value you provide for the variable must be exactly in the right\nformat since it is passed unaltered to the remote device. Consult the\nEasyControls manual about the expected format for each variable.\n\nFor example, to set the fan stage directly via the ``v00102`` variable, issue ::\n\n  eazyctrl setvar helios-kwl.fritz.box v00102 1\n\n\nUsing as a Python module\n========================\n\nThe functionality of EazyCtrl can be accessed using the ``eazyctrl`` Python\nmodule. The module can be imported in the usual way ::\n\n  import eazyctrl\n\nThe high level class `EazyController` provides an access similar to the command\nline tool.\n\n\nObtaining the feature list\n--------------------------\n\nThe static method ``get_feature_list()`` returns the available\nfeatures. It returns a list of tuples, each one containing the name of the\nfeature and a dictionary with various parameters of that feature.\n\nFor example the snippet ::\n\n  host = 'helios-kwl.fritz.box'   # replace with the IP-address of your device\n  ftrlist = eazyctrl.EazyController.get_feature_list()\n  print(ftrlist)\n\nresults in ::\n\n  [('fan_stage', {'rw': True, 'varname': 'v00102'}),\n   ('temp_outside_air', {'rw': False, 'varname': 'v00104'}),\n   ('temp_supply_air', {'rw': False, 'varname': 'v00105'}),\n   ('temp_outgoing_air', {'rw': False, 'varname': 'v00106'}),\n   ('temp_extract_air', {'rw': False, 'varname': 'v00107'})]\n\n\nGetting the value of a feature\n------------------------------\n\nThe method ``get_feature()`` returns the value of a given feature. The value is\nconverted to an appropriate Python type (e.g. integer, float, etc.).\n\nThe following example queries the value of the outside air temperature sensor ::\n\n  host = 'helios-kwl.fritz.box'   # replace with the IP-address of your device\n  ctrl = eazyctrl.EazyController(host)\n  temp_out = ctrl.get_feature('temp_outside_air')\n  print(temp_out, type(temp_out))\n\nThis results in ::\n\n  24.4 <class 'float'>\n\n\nSetting the value of a feature\n------------------------------\n\nYou can use the ``set_feature()`` method to set a value for a given feature. You\nshould provide the value as a Python type (e.g. integer, float, etc.) and it\nwill be automatically converted to the right text representation before being\npassed to the device.\n\nFor example, you can set the fan stage to level 3 by the following snippet::\n\n  host = 'helios-kwl.fritz.box'   # replace with the IP-address of your device\n  ctrl = eazyctrl.EazyController(host)\n\n  # Setting the fan stage\n  success = ctrl.set_feature('fan_stage', 3)\n  print(success)\n\n  # Querying the fan stage to check, whether it has the desired value now\n  fan_stage = ctrl.get_feature('fan_stage')\n  print(fan_stage)\n\nThe ``set_feature()`` method returns ``True`` or ``False`` indicating whether\nthe communication with the device was successful or not. So, for the snippet\nabove, you should get the output ::\n\n  True\n  3\n\nand of course, the fan should have been switched to stage 3.\n\n\nGetting the value of a variable\n-------------------------------\n\nSimilar to the command line tool, the `EazyController` object allows direct\nvariable access as well. This low-level function returns the response of the\nserver unaltered as a string, unless you specify a conversion function. Beyond\nthe variable name, you also have to pass the length of the expected answer (to\nbe found in the EasyConfigs manual).\n\nLet's query the outside air temperature via the v00104 variable and convert it\nto a float value ::\n\n  host = 'helios-kwl.fritz.box'   # replace with the IP-address of your device\n  ctrl = eazyctrl.EazyController(host)\n  temp_out = ctrl.get_variable('v00104', 7, conversion=float)\n\n\nSetting the value of a variable\n-------------------------------\n\nVia the ``set_variable()`` method you can set the value of a given variable.\n\nThe example below, sets the fan stage using the variable ``v00102``. It also\ndemonstrates, that you can use a formatting string instead of a conversion\nfunction for the ``conversion`` argument::\n\n  host = 'helios-kwl.fritz.box'   # replace with the IP-address of your device\n  ctrl = eazyctrl.EazyController(host)\n\n  # Setting the variable\n  ctrl.set_variable('v00102', 3, conversion=\"{:d}\")\n\n  # Check, whether the variable contains the right value\n  fan_stage = ctrl.get_variable('v00102', 1, conversion=int)\n\n  print(\"Expected: {:d}, obtained {:d}\".format(3, fan_stage))\n\nIf everything went well, you should obtain ::\n\n  Expected: 3, obtained 3\n\n\n\nNotes on concurrent access conflicts\n====================================\n\nDue to its design, the EasyControls protocol can not deal well with concurrent\naccesses of multiple clients. Especially, reading out a variable/feature is very\nerror-prone as it needs two communications. The first communication tells the\nserver, which variable should be queried, while the corresponding variable value\nis returned during the second communication. If between the first and second\ncommunication a second client starts a query for a different variable, the first\nclient may get back the value for the wrong variable (namely the one the second\nclient asked for).\n\nWhen EazyCtrl detects, that the wrong variable was returned, it will repeat the\ngiven query again after a short random time delay (maximally 3 times). While\nthis strategy should be enough to resolve concurrent access conflicts in typical\nuse cases, it may fail if too many clients / threads are accessing the device at\nthe same time.\n\nTherefore, always try to make sure, that only a single client is accessing the\ndevice at a time.",
        "description_content_type": "text/x-rst",
        "docs_url": null,
        "download_url": "",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "https://github.com/baradi09/eazyctrl",
        "keywords": "easycontrols kwl air-exchanger",
        "license": "BSD",
        "maintainer": "",
        "maintainer_email": "",
        "name": "eazyctrl",
        "package_url": "https://pypi.org/project/eazyctrl/",
        "platform": "",
        "project_url": "https://pypi.org/project/eazyctrl/",
        "project_urls": {
            "Homepage": "https://github.com/baradi09/eazyctrl"
        },
        "release_url": "https://pypi.org/project/eazyctrl/0.2/",
        "requires_dist": null,
        "requires_python": "",
        "summary": "Monitoring and controlling Easy Controls KWL (air exchanger)devices via Modbus/TCP.",
        "version": "0.2"
    },
    "last_serial": 5631159,
    "releases": {
        "0.2": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "0c61c628647c2303ccee75b9a060c8b2",
                    "sha256": "2eb3b46f9d135478456095e9ad5c9d1c6880fca7bacda6f9311439e1d9ccfc52"
                },
                "downloads": -1,
                "filename": "eazyctrl-0.2.tar.gz",
                "has_sig": false,
                "md5_digest": "0c61c628647c2303ccee75b9a060c8b2",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 12084,
                "upload_time": "2019-08-04T17:44:55",
                "url": "https://files.pythonhosted.org/packages/38/7b/0709d894af318992518809b34166b39f52b0784fac37ae2d1c309c2dc903/eazyctrl-0.2.tar.gz"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "0c61c628647c2303ccee75b9a060c8b2",
                "sha256": "2eb3b46f9d135478456095e9ad5c9d1c6880fca7bacda6f9311439e1d9ccfc52"
            },
            "downloads": -1,
            "filename": "eazyctrl-0.2.tar.gz",
            "has_sig": false,
            "md5_digest": "0c61c628647c2303ccee75b9a060c8b2",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 12084,
            "upload_time": "2019-08-04T17:44:55",
            "url": "https://files.pythonhosted.org/packages/38/7b/0709d894af318992518809b34166b39f52b0784fac37ae2d1c309c2dc903/eazyctrl-0.2.tar.gz"
        }
    ]
}