EpluControl (your heatpump)

Control Heatpump via pythonscript (re)using capabilities of the Eplucon website

Introduction

I am a big fan of using Home Assistant and was quite disappointed about the possibilities to integrate the Ecoforest Heatpump which I own. It is the provider to blame, not Home Assistant. Of course you could say you should have done your due dilligence before buying it. And I did during the procurement when i asked about the possiblities, it was told that you could control temperature with for example Google. In the end yes there was a possiblity to integrate the seperate room controllers, but sadly not the main controller "Th-Touch" which is actually controlling the heatpump.

Background

First I started with scraping the eplucon website - using the nice multiscrape integration - to read information and present it in Home Assistant. This enabled that I could ask Google about the current temperature and if the heating was on. For each item I found the html representation on the website and defined a sensor scraping it. Luckily they made an API available which provides the actual information of the heatpump in a more structured way. It was a big improvement and more stable as I experienced in the beginning issues when they overhauled the website and then I could startover again finding out the html representation of the values to read. However there was and is still no possbility to control for example the indoor temperature or the mode of the heatpump using the API. I asked for it but without any usable reaction.

The App and the website as offered by the provider can be used to control and that is it. So not fully integrated within my home automation and always in the need to use another app as well without opportunity to do some automations. It should be possible!!!

I looked around and identified two possible solutions (1) adding an additional card in the pump yourself to read and control it locally using modbus etc. or (2) scrape it from the site. For now I did not want to open the heatpump and add an additional card to prevent any guarantee issues. I just wanted to stay away from any possible discussion about it in case of a mallfunction.

Sadly the th-touch controller connected to the heatpump does not provide capabilities to connect locally from Home Assistant. Even not for reading while itself is sending all data from the heatpump to the service provider. I sniffed the network for traffic and thought about some interception but without any luck. So in the end I choose to experiment with discovering which requests are being sent from the website to read and update data of the heatpump. I was in the believe that it should be possible to replay this with some creativity and tools which are currently available. I accept for now that it is not local and having a dependency with the cloud. When the service provider is maintaining the heatpump I will aks if he can add the additional card.

The current solution I have is assuming that you have (1) an account on the eplucon website and you're able to control your heatpump from there and (2) you are already able to read data and have sensors within Home Assistant. You need at least to have the indoor temperature and the configured indoor temperature available for the thermostat in Home Assistant. You can use the Ecoforest integration from Koen Hendriks (https://github.com/koenhendriks/ha-eplucon) or use your own implementation of invoking the API as provided by Eplucon (https://portaal.eplucon.nl/docs/api). You can use the multiscrape or rest integration to invoke the API. I am still using my own invocation of the API as the Ecoforest integration was not available at that time and it has currently a sync issue. Also I wanted to be able to pause the integration as the API has a service window which then provides 0 as values for a minute or 15 which makes the diagrams unreadable.

So I am now able to read the data in a nice structured way. The next idea, make an native integration for it, however Koen Hendriks already started this (https://github.com/koenhendriks/ha-eplucon) so no need to work on that.

Controlling the heatpump

However I still wanted to be able to control the temperature from my Home Assistant.

Why? Just because it can and should be possible without the use of multiple apps/websites and do repetitive things manually. Also I experienced that the heatpump finished heating my house in the morning just before waking up. When woke up the floor was already cooling down. I just wanted to the delay the moment that starts heating during the night and then still runs when waking up. Just because it is possible and the floor is then still nice comfortly warmer. I also use it for other things like lowering the room temperature when in holiday mode. It turns down production of domestic water and starts again just before returning from holiday.

Using the developer tools from the browesr, I discovered what is sent/received when using the website to control the heatpump. I created a Python script to reproduce the same steps to control the heatpump. By having it in a script it is possible to use within automations in Home Assistant. It is the first attempt and there is still plenty room for improvement and to get it more robust, however for me currently it does the job for now. Lets hope that they do not change the implementation to frequently. As mentiones before I experienced some changes in the past 18 months when they overhauled the website twice.

Altough the script is written in Python is is pending on the Pyscript Python scripting integration (https://github.com/custom-components/pyscript) to be installed in Home Assistant. In that way you could use the script as an action within an automation and do not have to start bash session. Also it enables some opportunities to write to the log of Home Assisant and provide responses to the automations in Home Assistant. So the script does not run in a bash session on its own.

What can be controlled currently

"indoor_temperature", the indoor temperature to achieve when cooling or heating
"heating_active", enable or disable heating
"stop_heating_above", stop heating when outside temperature above
"heating_curve_correction", adjustment of the heat curve (quicker or slower heating)
"warm_water_active", enable or disable production of warm water
"boiler_temperature", the max temperature of domestic water in the boiler
"boiler_temperature_delta", the delta which determines when the production of domestic water starts again
"heatpump_mode", in which mode the heatpump is like cooling or heating
"heatpump_operation", in which operation mode the heatpump is like off,
"cooling_active": enable or disable cooling
"stop_passive_cooling_below": stop passive cooling when outside temperature below

Get it running

Install Pyscript See https://github.com/custom-components/pyscript. After installation it should be available as an integration.

Place the script in the pyscript folder You can use SSH, Samba integration or just create the file via Studio Code server integration and copy/paste the code into that file.

Go to Developer Tools in Home Assistant

If all went OK the script is available as an Action within Home Assisstant and can be used accordingly in automations etc.

When selecting the action in the Developer Tools it shows which parameters are expected. Sadly I could not find a easy way to add username, password and index as a secret from YAML. So for now they are expected as parameters. Of course you can add them as default in the python script. Or define helpers in Home Assistant and use them in your automations.

To be able to run the script and control your heatpump you need to use the same account which you use to login on the eplucon site and also know the module_index which repesennts the heatpump.

Determine the module_index of the heatpump The quickest way is to open the Developer Tools (F12 in Edge) and have a look which requests are sent from the website when the Warmtepomp is selected

Open the Developer Tools using F12 and click on the OpenDev button to continue. Select the Network Tab which will show the requests sent from this page to the webserver.

Make sure that the networkconsole is opened and active (a red circle in the toplef should be shown) in the Developer Tools to see which requests are sent.

Just wait for a couple of seconds and some rows will appear in the list. The string after the = is the value to use as module_index

Now you can go to he developer tools using all the information to actually change a setting of the heatpump Fill in the loginname, password, and module_index. And lets use the command "indoor_temperature" to change the temperature to the selected value. Press the perfom Action, when all is OK the button wil flash green and in the Response is stated that everything went OK.

After a short while you should see the temperature also updated in the Eplucon Website or the App to the selected

EpluControl

Install / Use

README