Stable -
Latest -
If you feel like donating, my wife is rasing money for and the Salvation Army here:
This adds an integration to homeassistant (HACS) to connect to Mastertherm Heat Pumps. There are two entry points for the Mastertherm Heat Pumps:
- mastertherm.vip-it.cz - This is the server for pre 2022 heat pumps
- mastertherm.online - This is the server for 2022 onward
NOTES:
- materhterm.online is sensitive to too many requests, for this reason by default it defaults to updates every 2 minutes, the App updates every 30 seconds. To help the Info updates every 30 min, data can be set in the options down to 30 seconds.
- 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.
The preferred and easiest way to install this is from the Home Assistant Community Store (HACS). Follow the link in the badge above for details on HACS.
At this time its not automatically part of HACS, so after installing HACS, visit the HACS Integrations pane and add https://github.com/sHedC/homeassistant-mastertherm.git as an Integration by following these instructions. You'll then be able to install it through the Integrations pane.
Once installed go to the Home Assistant UI, go to "Configuration" -> "Integrations" click "+" and search for "Mastertherm"
- Select the correct mastertherm login version, if not sure try online directly to see which server you use.
- Once connected you can change the refresh time in the options
Mastertherm only allows a single install, mutliple accounts are not currently supported. Additionally if you have an installation with more than 2 units/ devices keep the refresh rate as at least 2 min or even increase it, the app/ web only connects to a single device/ unit at a time and refreshes every 30 seconds but this integration retrieves all device and unit combinations.
Local connection is not possible at this time, it seems the heat pumps connect to the servers using SSH.
To install manually, if you really want to:
- Using the tool of choice open the directory (folder) for your HA configuration (where you find
configuration.yaml). - If you do not have a
custom_componentsdirectory (folder) there, you need to create it. - In the
custom_componentsdirectory (folder) create a new folder calledmastertherm. - Download all the files from the
custom_components/mastertherm/directory (folder) in this repository. - Place the files you downloaded in the new directory (folder) you created.
- Add the masterthermconnect module: pip install -I masterthermconnect==1.2.0
- Restart Home Assistant
- In the HA UI go to "Configuration" -> "Integrations" click "+" and search for "Mastertherm"
Current version is read only, updates do not work but that will come.
The sensors are 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.
- One Main circuit with heating and cooling and domestic hot water with attached room thermostats
- Main Circuit for heating and two optional circuits for Barn and House Domestic Hot Water, no room thermostats
These are the main entities for the heat pump, currently we understand the following.
| Entity | Type | Description |
|---|---|---|
| hp_power_state | Switch | Turn on and off the Heat Pump |
| hp_function | Select | The function is heating/ cooling or auto |
| season | Sensor | Shows the Season, Winter or Summer or Auto Winter and Auto Summer |
| operating_mode | Sensor | The current Operating Mode which shows 5 states: heating/ cooling/ pool/ hot water and defrost protection |
| cooling_mode | Binary Sensor | Whether the pump is in cooling mode or not (if not its heating) |
| compressor_running | Binary Sensor | Main compressor running |
| compressor2_running | Binary Sensor | Compressor 2 if installed |
| circulation_pump_running | Binary Sensor | Circulating water to where it is being requested, this is always true if any circuit is requesting heating or cooling |
| fan_running | Binary Sensor | Internal Fan is running |
| defrost_mode | Binary Sensor | If the heat pump is in defrost mode |
| aux_heater_1 | Binary Sensor | If installed indicates if the auxillary heater is on |
| aux_heater_2 | Binary Sensor | If installed indicates if the second auxillary heater is on |
| outside_temp | Sensor | The outside temperature |
| requested_temp | Sensor | This is the temperature that the heat pump is requesting, it is calcuated by an unknown algorithm and can go higher than expected. An example here is when heating is initially requested it goes higher than needed then reduces as room temperature is reached. |
| dewp_control | Binary Sensor | If Dew Point Control is active |
| hdo_on | Binary Sensor | Something to do with High Tarrif Rates, do not know about this indicator |
| Entity | Type | Description |
|---|---|---|
| heating | Binary Sensor | Whether hot water is requested, also activates if HC1 to 6 is for hot water |
| enabled | Binary Sensor | Not sure on mine always shows disabled. |
| current_temp | Sensor | The current temperature of the hot water, should be taken from the sensor in the water tank |
| required_temp | Sensor | The temperature that was set as required for your hot water. |
| Entity | Type | Description |
|---|---|---|
| compressor_run_time | Sensor | Number of hours the compressor has run for |
| compressor_start_counter | Sensor | Probably the number of times the compressor has started |
| pump_runtime | Sensor | The number of hours the circulation pump has run |
| aux1_runtime | Sensor | The house the auxillary heaters have run |
| aux2_runtime | Sensor | The house the auxillary heaters have run |
The switches here define if Winter/ Summer or Auto
| Entity | Type | Description |
|---|---|---|
| hp_season | Switch | If set on then winter, if set off then summer |
| hp_seasonset | Switch | If set on then Seasion is auto set. |
Work in Progress, error information just decoded from he web application.
| Entity | Type | Description |
|---|
The main circuit is HC0, this is linked to the main pump but some details in this circuit are hidden if any of HC1 to HC6 optional circuits are installed.
HC1 to HC6 are used to provide things like heating/ cooling to different room zones or multiple water tanks for hot water.
HC0 to HC6 usually have room thermostat's installed, if used for heating/ cooling, in this case there is a pad sub-section that contains ambient temperatures and humidity. If not installed then there is an int (internal) sub-section that has the ambient temperatures.
| Entity | Type | Description |
|---|---|---|
| name | sensor | The name of the circuit, hc0 is usually Home |
| on | Swtich | If the circuit is turns on or not |
| cooling | Binary Sensor | Circuit is in cooling mode |
| circulation_valve | Binary Sensor | If this circuit is requesting then this is open, this also triggers the main circulation pump |
| water_requested | Sensor | The requested water temperature based on heating and cooling curves |
| water_temp | Sensor | The actual water temperature for the circuit |
| auto | Sensor | No idea, it can be set on the thermostats but not sure what it does. |
| ambient_temp | Sensor | Ambient temperature, either from the room if the pad is installed or internal |
| ambient_requested | Sensor | requested temperature, either from the room if the pad is installed or internal |
| pad.current_humidity | Sensor | Room Humidity, if the thermostat is installed |
Some entities have been added based on debugging and best guess.
If you want to contribute to this please read the Contribution guidelines
Also to determine mappings use the mastertherm connect module directly from the command line where you can get a list of current registers for your heatpump.