Integración domótica Helios easyControls, gratuita y de código abierto
Helios KWL EC ventilation (easyControls), local Modbus TCP: air, fans, filter; optional commands.
Publicado por LM1LC3N7
- Dispositivos
- Versión 0.1.1
- Requiere Gladys >=5.1.0
- ★ 0
La documentación de esta integración la escribe su autor y, por ahora, solo está disponible en inglés.
Shows a Helios KWL EC heat recovery ventilation unit with the easyControls
board in Gladys, through its Modbus TCP interface on your local network
(no cloud). Unofficial: not affiliated with Helios. Never tested with a real
device: please report what your unit shows (see "To check" in TODO.md).
Requirements
- A Helios KWL EC unit with the easyControls board (the web interface of the unit), software 2.01 or later (Helios requires it for Modbus TCP). Units with easyControls 3.0, which speak Modbus RTU only, are not supported.
- The unit on your local network, with a fixed IP address (set it in your router). Modbus TCP uses port 502 and unit id 180, fixed by Helios.
- Modbus TCP has no password: anyone on your network can read and command the unit. Keep it on a trusted network.
Setup
- Install the integration from the Gladys store.
- In its configuration, enter the IP address of the unit and save.
- Open the Discovery tab and add the unit.
What Gladys shows
- Outdoor, supply, exhaust and extract air temperatures (°C).
- Operating mode (automatic, manual) and fan stage (1 to 4; stage 0, fans stopped, is shown in the status only), fan level (%), supply and extract fan speeds (rpm).
- Party mode and standby mode (active or not, minutes left).
- Filter change due, days left before the filter change.
- Fault (any error bit of the unit) and warning; the error code is in the status.
- The external humidity (KWL-FTF) and CO2 (KWL-CO2) sensors connected to the unit: each one appears once the unit returns a value for it (checked at the first read, then every hour), and is kept afterwards.
A value the unit returns empty, as "-" (no sensor), out of its range or
malformed is unknown: it is never published, never as 0. A CO2 value below
250 ppm is taken for a sensor error. The model name keeps letters, digits,
spaces and . _ / ( ) + - only.
Reads
The unit is read every refresh interval (60 s by default, 30 s to 1 h),
over one Modbus TCP connection, one request at a time (each variable is two
requests: its selection, then its read). Reads never come sooner than the
interval after the previous one, including after the "Test the connection"
button, a Discovery scan, a reconnection to Gladys or a restart of the
integration (the time of the last read is kept in /data). Reads that come
sooner: a new address saved, the reads of a command (before and after its
write), a party stop and its resends (the read back of the party mode), and
the follow-up reads 5 s and 20 s after a command.
The MAC address of the unit is read first. The first one read is kept for this address; if another one answers later, its values are not shown, the commands are refused, and the status says so. "Test the connection" then accepts the MAC address shown (for a replaced board).
Another Modbus client (Home Assistant, a script) reading the unit at the same time may change the variable selected between our two requests: the answer then names another variable and that value stays unknown for this read.
Commands
Off by default. With "Allow the commands" on:
- Operating mode (automatic, manual).
- Fan stage 1 to 4, only in manual mode (in automatic mode the unit sets the stage itself: switch to manual first). Stage 0 (fans stopped) is never offered.
- Start the party mode (with the duration and stage set on the unit).
Each command reads the unit just before (MAC address, standby, fan stage,
operating mode or party mode) and is refused when one of them cannot be
read, when another MAC address answers, in standby mode or with the fans
stopped (stage 0: the command could start them), or when /data cannot be
read. A party mode start after a party stop is also refused when /data
cannot be written (the stop guard must be lifted there first). It is written within 3.5 s of the click, then read back: success only
when the value read back is the one asked. Otherwise the answer is "sent,
without confirmation" (a check follows 5 s and 20 s later), "refused by the
unit" (Modbus exception 1 to 3), or "not sent".
Stopping the party mode
"Stop the party mode" never depends on the "Allow the commands" option, on
another command, on the identity check, on a failed read or on the
configuration being read: before the configuration is read, or while it
holds no valid address, it goes to the last valid address kept in /data. It takes the connection from any read or
command, and a command not written yet is then refused. The connection is
tried again every 250 ms for 3.5 s after the press.
It can fail in these cases, and the answer says which:
- no address: no valid one in the configuration and none kept in
/data("not sent"); - the unit cannot be reached for 3.5 s ("not sent");
- the write left but the unit did not answer, answered something else, or the party mode is still read on, or cannot be read back ("sent, without confirmation");
- the unit refused the write with a Modbus exception 1 to 3 ("refused by the unit");
- another valid address is saved while it runs, or the integration stops.
After a press, a stop guard is kept in /data. While the stop is not seen
applied, a read showing the party mode on sends the stop again, and a stop
not confirmed is sent again when the integration starts, before the
configuration is read: three resends at most per press, those at start
included. If a party mode start
from Gladys was written and not confirmed before the stop, the party mode
read on in the 2 minutes after the stop is also taken for that start
landing late, and the stop is sent again (same limit). The guard is not
lifted by the time: only by a party mode start from Gladys (option on), by
the party mode read on two reads in a row after the stop was seen applied
(started on the unit or by another app), or by another valid address saved
(an empty or invalid address keeps it).
Status
The configuration screen shows the state of the unit (stage, mode, party mode, fault code, filter), the reason of a failure and the time to the next read. If Gladys cannot give the configuration to the integration, the status says so and the configuration is asked again after 5 s, 15 s, 30 s, then every minute. A configuration read from Gladys while you save another one is dropped: the one saved last wins.
Privacy
/data/helios-state.json holds the time of the last read, the address and
MAC address of the unit, the external sensors seen and the party stop
guard. Nothing is sent anywhere but to the unit.
Parámetros de configuración
Estos son los parámetros que Helios easyControls te pide en su pantalla de configuración en Gladys.
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| Your Helios unit | section | No | Shows your Helios KWL EC heat recovery ventilation with the easyControls board (software 2.01 or later) in Gladys through its Modbus TCP interface (port 502) on your local network, without any cloud: outdoor, supply, exhaust and extract temperatures, operating mode, fan stage and speeds, party and standby modes, filter change, faults, and the external humidity and CO2 sensors. Enter the IP address of the unit (give it a fixed address in your router), save, then add it from the Discovery tab. The operating mode, the fan stage and the party mode start can be changed from Gladys only if you allow the commands below; stopping the party mode never depends on that option (see the guide for the cases where it can fail). Gladys never writes fan stage 0 (fans off) nor the standby mode. Modbus TCP has no password: keep the unit on a trusted network. Never tested with a real device. Not affiliated with Helios. |
| IP address of the unit | string | Sí | An IPv4 address or a host name (port 502 unless you add one, for example 192.168.1.90:502). |
| Allow the commands | boolean | No | Off by default. On: Gladys may change the operating mode (automatic, manual), the fan stage (1 to 4, in manual mode) and start the party mode; all are refused in standby mode or with the fans stopped (stage 0). Off: these commands are refused. Stopping the party mode never depends on this option. |
| Refresh interval (s) | number | No | How often the unit is read, in seconds. |
| Language of the feature names | select | No | Used for the names of the device and features added from now on, the status and the command errors. |
Cómo instalar Helios easyControls en Gladys
- En Gladys, abre Integraciones: Helios easyControls aparece en el catálogo junto a las integraciones nativas, con una insignia de comunidad.
- Haz clic en Instalar. Gladys descarga la imagen Docker (
ghcr.io/lm1lc3n7/gladys-helios:0.1.1), la ejecuta en un entorno aislado del núcleo y genera la interfaz de la integración (dispositivos, descubrimiento y configuración). - Abre la pantalla de Configuración de la integración, rellena los parámetros y guarda.
- También puedes instalarla directamente desde la URL de su repositorio: https://github.com/LM1LC3N7/gladys-helios.
Helios easyControls requiere Gladys >=5.1.0. El catálogo de Gladys se actualiza cada hora, así que una nueva versión está disponible como máximo una hora después de publicarse.
¿Todavía no usas Gladys? Es gratuito y de código abierto: sigue la guía de instalación para empezar.
Sobre las integraciones externas
Helios easyControls es una integración externa: una integración comunitaria empaquetada como contenedor Docker y publicada en GitHub. Gladys la instala con un clic y la ejecuta en un entorno aislado del núcleo. La publica y mantiene LM1LC3N7, no el equipo principal de Gladys.
- Explorar todas las integraciones, nativas y de la comunidad
- Crear y publicar tu propia integración externa
- Código fuente en GitHub — fuente de esta documentación