Skip to main content

Waterkotte smart home integration, free and open source

Waterkotte integration for Gladys Assistant

Waterkotte EcoTouch heat pumps on the local network: temperatures, state, optional commands.

View on GitHubAll integrations

Shows a Waterkotte heat pump in Gladys through the local web interface of its controller (EcoTouch, or the older EasyCon), without any cloud. Unofficial: not affiliated with Waterkotte. Never tested with a real heat pump: it was written from the open source Home Assistant integration ha-waterkotte and tested against a simulated controller. Please report what you see on yours.

What you get​

One device, "Waterkotte heat pump", with what its controller gives:

  • temperatures: outside, flow, return and return target, heating demand, source inlet and outlet, buffer tank, room (when a sensor is connected), hot water and hot water demand;
  • compressor running, heating hot water, alarm;
  • electric power (kW), heat output (kW), COP;
  • Heating and Hot water: Off, Auto or Manual;
  • Hot water setpoint (°C).

The values are read every 60 seconds (30 to 600, in the configuration).

Setting up​

  1. Find the IP address of the heat pump (its web page) and give it a fixed address in your router.
  2. In Gladys, open the integration's configuration: enter the address, choose the controller (EcoTouch when the web page asks for a password, even when it shows "EasyCon"; EasyCon for the older controllers without a login page), the user name (waterkotte unless your installer changed it) and the password of the web page. Save.
  3. Add the heat pump from the Discovery tab.

The password is kept by Gladys in its database, never shown again, sent only to the heat pump. The web page is plain HTTP: keep the heat pump on a trusted network.

Sessions​

The controller accepts few sessions at once (two according to ha-waterkotte; its web page open in a browser uses one) and closes an idle one after about 5 minutes: after a restart of Gladys, the previous session may stay taken that long. Gladys keeps a single session open, ends it when it stops or when the configuration changes (saved several times in a row: applied one after the other, the last one saved wins), and logs in again at most once per read or per command, never in a loop. When the controller answers "too many users", Gladys pauses for 1 minute, then 2, 4... up to 6 hours, and says so in the configuration screen. When it refuses the user name or the password, Gladys stops trying: correct them and save, or click Test the connection (one try per click).

Commands​

Off (heating or hot water) is a stop: it does not depend on the "Allow the commands" option, a pause or a read in progress. It is written, then read back:

  • read back Off: done;
  • otherwise Gladys answers "not sent", "sent, without confirmation" or "not applied yet", keeps the stop (also across a restart) and writes it with the next reads: written again 3 times at most, and dropped 15 minutes after the click whatever the reads. Once written, it is not written again over a value someone else set after the click (on the controller, its web page); an older command of Gladys does not count. A stop not written yet is tried again 10 seconds later, then every minute; during a pause too, until its 15 minutes (one login a minute at most). Such a stop can thus leave up to 15 minutes after the click, once, over a setting made on the controller in between.

Off is refused, nothing sent, in these cases only:

  • the controller is EasyCon (read only in this integration);
  • the address or the password is missing: the stop is kept and written as soon as the configuration is complete (15 minutes at most);
  • the heat pump refused the credentials before: the stop is kept and written once they are corrected (15 minutes at most);
  • nothing could be written within 3 seconds (no answer, network down, a login refused "too many users"): the stop is kept and written by the next reads.

Auto, Manual and the hot water setpoint are refused unless you turn on Allow the commands (off by default). Then:

  • the hot water setpoint takes whole degrees from 28 °C to the ceiling of the configuration, 65 °C by default, 40 to 65 °C (never more than 65 °C, whatever is typed): scalding risk;
  • each command reads the value and the serial number of the heat pump just before writing, and succeeds only when a read back shows the value asked;
  • a command refused or cancelled says "nothing sent"; one sent without an answer says "sent, without confirmation" and the value is read again 5 and 20 seconds later;
  • a command clicked before an Off of the same value (or a hot water setpoint clicked before a hot water Off) never leaves after it.

The integration has no switch: a "turn everything off" of a voice assistant or a scene never reaches the heat pump.

Limits​

  • One heat pump per integration. Its serial number is checked at every read and before every command: when another heat pump answers at the address, nothing is published and the commands other than Off are refused.
  • The controller answers one request at a time: when it is slow (more than about half a second per request), a scene changing several values at once may see the last ones refused "did not answer in time, nothing sent".
  • EasyCon: read only, and its tags are those of EcoTouch (unchecked).
  • The tag list comes from ha-waterkotte; Waterkotte publishes none.

Credits​

Built on the work of Matthias Marquardt and the contributors of ha-waterkotte (MIT).

Configuration settings​

These are the settings Waterkotte asks for in its configuration screen in Gladys.

SettingTypeRequiredDescription
Your heat pumpsectionNoShows your Waterkotte heat pump (EcoTouch controller, or the older EasyCon) in Gladys through its local web interface, without any cloud: temperatures, compressor, hot water, alarm, and optionally the operation of heating and hot water and the hot water setpoint. Enter the IP address of the heat pump (give it a fixed address in your router) and the password of its web page, save, then add it from the Discovery tab. The controller accepts few sessions at once: Gladys keeps one open. The web page is plain HTTP: keep the heat pump on a trusted network. Never tested with a real heat pump. Not affiliated with Waterkotte.
IP address of the heat pumpstringYesThe address of its web page: an IPv4 address or a host name (port 80 unless you add one, for example 192.168.1.50:8080).
ControllerselectNoEcoTouch when the web page asks for a password (even when it shows "EasyCon"); EasyCon for the older controllers without a login page (read only here).
User namestringNoThe user of the web page: waterkotte unless your installer changed it.
PasswordsecretNoThe password of the web page of the heat pump. Kept by Gladys in its database, never shown again, sent only to the heat pump.
Allow the commandsbooleanNoOff by default. On: Gladys may set heating and hot water to Auto or Manual and change the hot water setpoint, up to the ceiling below. Off: those are refused. Turning heating or hot water Off does not depend on this option.
Hot water ceiling (°C)numberNoScalding risk: Gladys never sets the hot water above this temperature. 65 °C by default, from 40 to 65 °C (never more than 65 °C, whatever is typed).
Refresh interval (s)numberNoHow often the heat pump is read, in seconds.
Language of the feature namesselectNoUsed for the names of the device and features added from now on, for the options and for the command errors.

How to install Waterkotte in Gladys​

  1. In Gladys, open Integrations: Waterkotte appears in the catalog, next to the native integrations, with a community badge.
  2. Click Install. Gladys pulls the Docker image (ghcr.io/lm1lc3n7/gladys-waterkotte:0.1.2), starts it in a sandbox isolated from the core, and generates the integration's interface (devices, discovery and configuration).
  3. Open the Configuration screen of the integration, fill in the settings, and save.
  4. You can also install it directly from its repository URL: https://github.com/LM1LC3N7/gladys-waterkotte.

Waterkotte requires Gladys >=5.1.0. The catalog inside Gladys refreshes every hour, so a new version becomes available at most one hour after its release.

Not running Gladys yet? It is free and open source: follow the installation guide to get started.

About external integrations​

Waterkotte is an external integration: a community integration packaged as a Docker container and published on GitHub, that Gladys installs in one click and runs in a sandbox isolated from its core. It is published and maintained by LM1LC3N7, not by the Gladys core team.

Subscribe to the Gladys Assistant newsletter

A few emails per month about new releases and project news. Sent by Pierre-Gilles Leymarie, founder of the project. Unsubscribe anytime 🙂
Last updated on