{"id":14985283,"url":"https://github.com/shedc/python-masterthermconnect","last_synced_at":"2025-10-13T12:36:18.769Z","repository":{"id":63628566,"uuid":"343856432","full_name":"sHedC/python-masterthermconnect","owner":"sHedC","description":"MasterTherm HeatPump API","archived":false,"fork":false,"pushed_at":"2025-04-09T07:28:48.000Z","size":389,"stargazers_count":3,"open_issues_count":1,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-08-27T07:41:32.361Z","etag":null,"topics":["heat-pumps","home-assistant","mastertherm"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sHedC.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-03-02T17:26:59.000Z","updated_at":"2024-12-11T10:21:01.000Z","dependencies_parsed_at":"2022-11-22T18:31:40.551Z","dependency_job_id":"b09f84da-e813-48fe-998d-81ef419b181e","html_url":"https://github.com/sHedC/python-masterthermconnect","commit_stats":{"total_commits":254,"total_committers":3,"mean_commits":84.66666666666667,"dds":"0.019685039370078705","last_synced_commit":"7e8025293e09a66b5febd944f836cf9d6411329a"},"previous_names":[],"tags_count":71,"template":false,"template_full_name":null,"purl":"pkg:github/sHedC/python-masterthermconnect","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sHedC%2Fpython-masterthermconnect","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sHedC%2Fpython-masterthermconnect/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sHedC%2Fpython-masterthermconnect/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sHedC%2Fpython-masterthermconnect/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sHedC","download_url":"https://codeload.github.com/sHedC/python-masterthermconnect/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sHedC%2Fpython-masterthermconnect/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279015056,"owners_count":26085643,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-13T02:00:06.723Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["heat-pumps","home-assistant","mastertherm"],"created_at":"2024-09-24T14:10:39.049Z","updated_at":"2025-10-13T12:36:18.755Z","avatar_url":"https://github.com/sHedC.png","language":"Python","funding_links":["https://www.buymeacoffee.com/sHedC"],"categories":[],"sub_categories":[],"readme":"# Mastertherm Connect Module\n[![License][license-shield]](LICENSE)\n[![GitHub Activity][commits-shield]][commits]\n[![BuyMeCoffee][buymecoffeebadge]][buymecoffee]\n\nMain -\n[![workflow-main][workflow-main-shield]][workflow-main-link]\n[![codecov][codecov-shield]][codecov-link]\n[![issues][issues-shield]][issues-link]\n\nLatest -\n[![GitHub Release][latest-release-shield]][releases]\n[![workflow-latest][workflow-latest-shield]][workflow-latest-link]\n\nStable -\n[![GitHub Release][stable-release-shield]][releases]\n[![workflow-stable][workflow-stable-shield]][workflow-stable-link]\n\n## About\nThis module provides the connection and conversion for the two Mastertherm Heat Pump APIs. It is being developed as a best effort to support an integration plugin for Home Assistant.\n\nThere are two entry points for the Mastertherm Heat Pumps:\n- mastertherm.vip-it.cz - This is the server for pre 2022 heat pumps\n- mastertherm.online - This is the server for 2022 onward\n\nNOTES:\n- materhterm.online is sensitive to too many requests so take care when using the command line or using this libary. The Application and Web App does a refresh on one module/ unit every 30 seconds.\n- if multiple requests are sent at the same time (i.e. from home assistant/ the app and web) some will be refused by the servers, its temporary.  The updates have been built to report but ignore these.\n\n\n## Installation\nReleases are done using PyPi, the release is here: \u003ca href=\"https://pypi.org/project/masterthermconnect\" target=\"_blank\"\u003emasterthermconnect\u003c/a\u003e\n- Latest Release Version: python -m pip install masterthermconnect\n- Specific Version or Pre-Release e.g.: python -m pip install masterthermconnect==1.1.0rc9\n\n### Command Line\nThis is used as a libary but it can also be run directly for debug purposes and must be used with extreme caution, especially when using the set commands.\n\n\u003e :warning: **Use SET with REG directly with extreme caution**: There is no protection on the masterhterm API Web for updating registry settings you must not and updating these can break your system, this applies to using the mastertherm set \u0026 reg command you have to actively confirm each set command when using this feature.\n\n\u003e :warning: **Do Not Run This Too Frequently**: The new API may lock you're IP out for an unknown period of time.  The app and web app refresh every 30 seconds. I don't know how many times in succession would lock you out, probably frequent calls over a period of time such as an hour.\n\n```\nusage: masterthermconnect [-h] [--version] [-d] [-v] {get,set} ...\n\nPython Mastertherm Connect API Module, used for debug purposes, allows you to get and set registers and other information for testing, use with\ncaution!!!\n\noptions:\n  -h, --help        show this help message and exit\n  --version         display the Mastertherm Connect API version\n  -d, --debug       display Debug Logging\n  -v, --verbose     display Verbose/ Info logging\n\ncommands:\n  Valid commands to access the API, use -h to get more help after the command for specific help.\n\n  {get,set}         Retrieve and Send data to or from the API.\n    get             Read data from the API and Display it\n    set             Set data to the API and check the Result\n\nDO NOT RUN THIS TOO FREQENTLY, IT IS POSSIBLE TO GET YOUR IP BLOCKED, I think new new API is sensitive to logging in too frequently.\n```\n\nGet\n```\nusage: masterthermconnect get [-h] [--user USER] [--password PASSWORD] [--api-ver {v1,v2}] [--hide-sensitive] [--pretty] {devices,data,reg} ...\n\noptions:\n  -h, --help           show this help message and exit\n  --user USER          login user for Mastertherm\n  --password PASSWORD  login password for Mastertherm\n  --api-ver {v1,v2}    API Version to use: Default: v1 (pre 2022), v2 (post 2022)\n  --hide-sensitive     Hide the actual sensitive information, used when creating debug information for sharing.\n  --pretty             Prettify the Output in JSON Format.\n\nget commands:\n  {devices,data,reg}\n    devices            All Devices List associated with the account.\n    data               Normalized data for a speicif device, e.g. data 1234 1\n    reg                Registers for a specific device, e.g. get reg 1234 1 A_101,A102 or reg 1234 1 all\n```\n\nSet\n```\nusage: masterthermconnect set [-h] [--user USER] [--password PASSWORD] [--api-ver {v1,v2}] {reg} ...\n\noptions:\n  -h, --help           show this help message and exit\n  --user USER          login user for Mastertherm\n  --password PASSWORD  login password for Mastertherm\n  --api-ver {v1,v2}    API Version to use: Default: v1 (pre 2022), v2 (post 2022)\n\nset commands:\n  {reg}\n    reg                Registers for a specific device, e.g. reg 1234 1 D_3 0\n```\n\nIf you can login using mastertherm.online then use the api version v2, for mastertherm.vip-it.cz use v1 or do not provide. If you use special characters or spaces in user name or password use double quotes \"user name\" to quote the parameter.\n\n### API Version\nFor examples on how to use the API please see `__main__.py` file as an exmaple, it is quite simple to use and retrieve information and is documented inline:\n\n\u003e :warning: **Do NOT use the MasterthermAPI Directly**: There is no control on updating registries using the API and updating the wrong one can break your system.  The MasterthermController has controls to only allow certain updates that are avialable on the Web UI and Thermostats.\n\nTo import the required modules:\n```\nfrom masterthermconnect import (\n    MasterthermController,\n    MasterthermAuthenticationError,\n    MasterthermConnectionError,\n    MasterthermResponseFormatError,\n    MasterthermTokenInvalid,\n    MasterthermUnsupportedRole,\n    MasterthermUnsupportedVersion,\n)\n```\n\nTo setup a connection create a new aiohttp ClientSession and pass the login details:\n```\n    async def connect(\n        username: str, password: str, api_version: str, refresh: bool\n    ) -\u003e MasterthermController:\n        \"\"\"Setup and Connect to the Mastertherm Server.\"\"\"\n        # Login to the Server.\n        session = ClientSession()\n        controller = MasterthermController(\n            username, password, session, api_version=api_version\n        )\n\n        try:\n            await controller.connect()\n            if refresh:\n                await controller.refresh()\n\n            return controller\n        except MasterthermAutenticationError as mte:\n            print(\"Authentication Failed \" + mte.message)\n        except MaseterthermConnectionError as mte:\n            print(\"Connection Failed \" + mte.message)\n        finally:\n            await session.close()\n\n        return None\n```\n\nDevice Information and Data can be retrieved from the controller for example. Data is available in a dictionary format described below:\n```\n     devices = controller.get_devices()\n     device_data = controller.get_device_data(module_id, unit_id)\n```\n\n## Heat Pump Details\nWrites are avaialble in limited capacity based on the UI and Thermostat controls. Some controls have a min/ max value that is configured in the heatpump, whilst we don't have any restrictions built in masterthermconnect the min and max values are available:\n- Domestic Hot Water has a min and max temperature exposed\n- Heating/ Cooling Curves - have a min/ max in the main heating/ cooling curve\n\n This is being developed to support the Home Assistant integration.\n\nEverything is based on observations from the Web and Android Applications, the current testing has been done on some basic setup we have not tested options with Solar and Pool but have tried to add sensors based on the apps.\n1. One Main circuit with heating and cooling and domestic hot water with attached room thermostats\n2. Main Circuit for heating and two optional circuits for Barn and House Domestic Hot Water, no room thermostats\n\n#### Mapping Setup\nPretty much every piece of information and settings are stored as registry keys such as D_110 and I_120, there are hundreds. There is a mapping to the structure used in this module in the const.py.\n\nThe data is stored under the controller as an array of module and unit's making a device.\n\n```\n{\n    \"module_id_unit_id\": {\n        \"last_data_update\": \u003cdatetime\u003e control data update frequency\n        \"last_info_update\": \u003cdatetime\u003e control info update frequently\n        \"last_update_time\": \"1192282722\" used for data updates in the API\n        \"info\":             normallised information for the device\n        \"data\":             normallised data for the devive\n        \"api_info\":         All Info retrieved from the API\n        \"api_update_data\":  All Updated Data since last update\n        \"api_full_data\":    Full Data including last updated\n    },\n    ...\n}\n```\n\nThe information is stored as key value pairs as below:\n\n```\n{\n    \"name\": \"givenname\",\n    \"surname\": \"surname\",\n    \"country\": \"localization\",\n    \"language\": \"lang\",\n    \"hp_type\": \"type\",\n    \"controller\": \"regulation\",\n    \"exp\": \"exp\",\n    \"output\": \"output\",\n    \"reservation\": \"reservation\",\n    \"place\": \"city\",\n    \"latitude\": \"password9\",\n    \"longitude\": \"password10\",\n    \"notes\": \"notes\",\n    \"pada\": \"pada\",\n    \"padb\": \"padb\",\n    \"padc\": \"padc\",\n    \"padd\": \"padd\",\n    \"pade\": \"pade\",\n    \"padf\": \"padf\",\n    \"padz\": \"padz\",\n}\n```\n\nThe data is normallies based on the following key value pairs and sub dictionary setup below is the format but exact mappings can be found in the const.py file.\n\nWhere possble the normalized data is filtered out based on whether a feature is enabled or not, for example HC0-HC6, Pool and Solar are avaialble only if the circuits are enabled and available.\n```\n{\n    \"hp_power_state\": [\"bool\", \"D_3\"],\n    \"hp_function\": [\"int\", \"I_51\"],  # 0: heating, #1: cooling, #2: auto (Write)\n    \"season\": {\n        \"mode\": [\n            Special(str, Special.FORMULA),\n            [\n                \"('' if {0} else 'auto-') + ('winter' if {1} else 'summer')\",\n                [[bool, \"I_50\"], [bool, \"D_24\"]],\n            ],\n        ],\n        \"manual_set\": [bool, \"I_50\"],\n        \"winter\": [bool, \"D_24\"],\n        \"winter_temp\": [float, \"A_82\"],\n        \"summer_temp\": [float, \"A_83\"],\n    },\n    \"operating_mode\": [\"fixed\", \"heating\"],  # heating, cooling, pool, dhw, dpc\n    \"cooling_mode\": [\"bool\", \"D_4\"],\n    \"control_curve_heating\": {\n        \"setpoint_a_outside\": [\"float\", \"A_122\"],\n    },\n    \"control_curve_cooling\": {\n        \"setpoint_a_outside\": [\"float\", \"A_362\"],\n    },\n    \"domestic_hot_water\": {\n        \"heating\": [\"bool\", \"D_66\"],\n        \"enabled\": [\"bool\", \"D_275\"],\n    },\n    \"compressor_running\": [\"bool\", \"D_5\"],\n    \"compressor2_running\": [\"bool\", \"D_32\"],\n    \"runtime_info\": {\n        \"compressor_run_time\": [\"int\", \"I_11\"],\n        \"compressor_start_counter\": [\"int\", \"I_12\"],\n    },\n    \"error_info\": {\n        \"some_error\": [\"bool\", \"D_20\"],\n        \"three_errors\": [\"bool\", \"D_21\"],\n    },\n    \"heating_circuits\": {}, # Heating and Cooling Circuits\n}\n```\n\nThe Heating/ Cooling Ciruits are optionally installed, HC0 refers to the main heat pump, HC1 to 6 are optional heating and cooling cirguits and additionally there is Pool and Solar as optional components.\n\nIn addition each Heating/ Cooling Circuit can have a room thermostat installed or not.  Where possible the sections that are not enabled are removed. Within each of the hc0 to hc6 a room thermostat can be installed if so then the pad sub key is enabled, if not then the int sub key is enabled.\n\nNote Ambient Requested Temperature and Ambient Current Temperatures remain at the hcX level in line with the UI, they should show the correct temperature based on whether a thermostat is installed or not.\n\nAdditionally hc0 the control curves are the same as the main cuves so not shown in this section.\n\n```\n{\n    \"hc0\": {\n        \"enabled\": boolean Disabled if any of HC1 to HC6 are installed.\n        \"name\": [\"string\", []],  # hc0 does not have a name, default is Home\n        \"ambient_temp\": [\"float\", \"A_211\"],\n        \"pad\": {\n            \"enabled\": [\"not bool\", \"D_242\"],  # Seems to be enabled if this is false.\n            \"current_humidity\": [\"float\", \"I_185\"],\n        },\n    },\n    \"hc1\": {\n        \"enabled\": [\"fixed\", False],\n        \"name\": [\n            \"string\",\n            [\"I_211\", \"I_212\", \"I_213\", \"I_214\", \"I_215\", \"I_216\"],\n        ],\n        \"on\": [\"bool\", \"D_212\"],\n        \"int\": {\n            \"enabled\": [\"not bool\", \"D_245\"],\n        },\n        \"ambient_requested\": [\"if\", \"D_245\", \"float\", \"A_219\", \"A_215\"],\n        \"ambient_temp\": [\"float\", \"A_216\"],\n        \"pad\": {\n            \"enabled\": [\"bool\", \"D_245\"],\n            \"state\": [\"int\", \"I_15\"],  # 0 - Permanently Off, 1 - Scheduled Off, 2 - On\n            \"current_humidity\": [\"float\", \"I_219\"],\n        },\n        \"control_curve_heating\": {\n            \"setpoint_a_outside\": [\"float\", \"A_101\"],\n        },\n        \"control_curve_cooling\": {\n            \"setpoint_a_outside\": [\"float\", \"A_314\"],\n        },\n    },\n    .\n    .\n    .\n    \"solar\": {\n        \"enabled\": [\"bool\", \"D_433\"],\n        \"name\": [\"fixed\", \"Solar\"],\n    },\n    \"pool\": {\n        \"enabled\": [\"bool\", \"D_348\"],\n        \"name\": [\"fixed\", \"Pool\"],\n    },\n}\n```\n\n***\n[commits-shield]: https://img.shields.io/github/commit-activity/y/sHedC/python-masterthermconnect?style=for-the-badge\n[commits]: https://github.com/shedc/python-masterthermconnect/commits/main\n[license-shield]: https://img.shields.io/github/license/shedc/python-masterthermconnect?style=for-the-badge\n[maintenance-shield]: https://img.shields.io/badge/maintainer-Richard%20Holmes%20%40shedc-blue.svg?style=for-the-badge\n\n[buymecoffee]: https://www.buymeacoffee.com/sHedC\n[buymecoffeebadge]: https://img.shields.io/badge/buy%20me%20a%20coffee-donate-yellow.svg?style=for-the-badge\n\n[codecov-shield]: https://codecov.io/gh/sHedC/python-masterthermconnect/branch/main/graph/badge.svg?token=747WODRAGO\n[codecov-link]: https://codecov.io/gh/sHedC/python-masterthermconnect\n\n[issues-shield]: https://img.shields.io/github/issues/shedc/python-masterthermconnect?style=flat\n[issues-link]: https://github.com/sHedC/python-masterthermconnect/issues\n\n[releases]: https://github.com/shedc/python-masterthermconnect/releases\n[stable-release-shield]: https://img.shields.io/github/v/release/shedc/python-masterthermconnect?style=flat\n[latest-release-shield]: https://img.shields.io/github/v/release/shedc/python-masterthermconnect?include_prereleases\u0026style=flat\n\n[workflow-main-shield]: https://github.com/sHedC/python-masterthermconnect/actions/workflows/push-main.yml/badge.svg\n[workflow-main-link]: https://github.com/sHedC/python-masterthermconnect/actions/workflows/push-main.yml\n[workflow-stable-shield]: https://github.com/sHedC/python-masterthermconnect/actions/workflows/push-release.yml/badge.svg\n[workflow-stable-link]: https://github.com/sHedC/python-masterthermconnect/actions/workflows/push-release.yml\n[workflow-latest-shield]: https://github.com/sHedC/python-masterthermconnect/actions/workflows/push-prerelease.yml/badge.svg\n[workflow-latest-link]: https://github.com/sHedC/python-masterthermconnect/actions/workflows/push-prerelease.yml\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshedc%2Fpython-masterthermconnect","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshedc%2Fpython-masterthermconnect","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshedc%2Fpython-masterthermconnect/lists"}