Intégration domotique Helios easyControls, gratuite et open source
Ventilation Helios KWL EC (easyControls), Modbus TCP local : air, filtres ; commandes en option.
Publiée par LM1LC3N7
- Appareils
- Version 0.1.1
- Nécessite Gladys >=5.1.0
- ★ 0
Affiche une ventilation double flux Helios KWL EC à carte easyControls dans
Gladys, par son interface Modbus TCP sur votre réseau local (sans cloud).
Non officiel : sans lien avec Helios. Jamais testé avec un vrai appareil :
merci de signaler ce que montre votre centrale (voir « To check » dans
TODO.md).
Prérequis
- Une centrale Helios KWL EC à carte easyControls (l’interface web de la centrale), logiciel 2.01 ou plus récent (exigé par Helios pour le Modbus TCP). Les centrales easyControls 3.0, en Modbus RTU seulement, ne sont pas prises en charge.
- La centrale sur votre réseau local, avec une adresse IP fixe (réglée dans votre routeur). Le Modbus TCP utilise le port 502 et l’identifiant d’unité 180, fixés par Helios.
- Le Modbus TCP n’a pas de mot de passe : tout appareil de votre réseau peut lire et commander la centrale. Gardez-la sur un réseau de confiance.
Installation
- Installez l’intégration depuis le store de Gladys.
- Dans sa configuration, saisissez l’adresse IP de la centrale et enregistrez.
- Ouvrez l’onglet Découverte et ajoutez la centrale.
Ce que Gladys affiche
- Températures de l’air extérieur, soufflé, rejeté et extrait (°C).
- Mode de fonctionnement (automatique, manuel) et niveau de ventilation (1 à 4 ; le niveau 0, ventilateurs arrêtés, n’apparaît que dans le statut), niveau de ventilation (%), vitesses des ventilateurs de soufflage et d’extraction (tr/min).
- Mode fête et mode veille (actif ou non, minutes restantes).
- Changement des filtres à faire, jours restants avant ce changement.
- Défaut (tout bit d’erreur de la centrale) et avertissement ; le code d’erreur est dans le statut.
- Les capteurs externes d’humidité (KWL-FTF) et de CO2 (KWL-CO2) branchés sur la centrale : chacun apparaît dès que la centrale renvoie une valeur pour lui (vérifié à la première lecture, puis toutes les heures), et il reste ensuite.
Une valeur renvoyée vide, en « - » (pas de capteur), hors de sa plage ou
mal formée est inconnue : elle n’est pas publiée, et jamais comme 0. Une
valeur de CO2 sous 250 ppm est prise pour une erreur du capteur. Le nom du
modèle ne garde que les lettres, les chiffres, les espaces et . _ / ( ) + -.
Lectures
La centrale est lue à chaque intervalle de rafraîchissement (60 s par
défaut, de 30 s à 1 h), par une seule connexion Modbus TCP, une requête à
la fois (chaque variable demande deux requêtes : sa sélection, puis sa
lecture). Les lectures ne viennent jamais avant l’intervalle depuis la
précédente, y compris après le bouton « Tester la connexion », un scan de
la Découverte, une reconnexion à Gladys ou un redémarrage de l’intégration
(l’heure de la dernière lecture est gardée dans /data). Lectures plus
tôt : une nouvelle adresse enregistrée, les lectures d’une commande (avant
et après son écriture), un arrêt du mode fête et ses renvois (la relecture
du mode fête), et les lectures de suivi 5 s et 20 s après une commande.
L’adresse MAC de la centrale est lue en premier. La première lue est gardée pour cette adresse ; si une autre répond ensuite, ses valeurs ne sont pas affichées, les commandes sont refusées et le statut le dit. « Tester la connexion » accepte alors l’adresse MAC affichée (carte remplacée).
Un autre client Modbus (Home Assistant, un script) qui lit la centrale au même moment peut changer la variable sélectionnée entre nos deux requêtes : la réponse nomme alors une autre variable et cette valeur reste inconnue pour cette lecture.
Commandes
Désactivées par défaut. Avec « Autoriser les commandes » :
- Mode de fonctionnement (automatique, manuel).
- Niveau de ventilation 1 à 4, en mode manuel seulement (en mode automatique, la centrale règle elle-même le niveau : passez d’abord en manuel). Le niveau 0 (ventilateurs arrêtés) n’est jamais proposé.
- Démarrer le mode fête (avec la durée et le niveau réglés sur la centrale).
Chaque commande relit la centrale juste avant (adresse MAC, veille, niveau
de ventilation, mode de fonctionnement ou mode fête) et est refusée si l’un
d’eux ne peut pas être relu, si une autre adresse MAC répond, en mode veille
ou ventilateurs arrêtés (niveau 0 : la commande pourrait les relancer), ou si
/data est illisible. Un démarrage du mode fête après un arrêt est aussi
refusé si /data ne peut pas être écrit (la garde d’arrêt doit d’abord y
être levée). La commande est écrite dans les 3,5 s qui suivent le clic, puis
relue : succès seulement si la valeur relue est celle demandée. Sinon la
réponse est « envoyée, sans confirmation » (une vérification suit 5 s et
20 s plus tard), « refusée par la centrale » (exception Modbus 1 à 3), ou
« non envoyée ».
Arrêter le mode fête
« Arrêter le mode fête » ne dépend jamais de l’option « Autoriser les
commandes », d’une autre commande, du contrôle d’identité, d’une lecture en
échec ni de la lecture de la configuration : avant celle-ci, ou tant qu’elle n’a
pas d’adresse valide, il part vers la dernière adresse valide gardée dans
/data. Il prend la connexion à toute lecture
ou commande, et une commande pas encore écrite est alors refusée. La
connexion est retentée toutes les 250 ms pendant 3,5 s après l’appui.
Il peut échouer dans ces cas, et la réponse dit lequel :
- pas d’adresse : aucune valide dans la configuration et aucune gardée
dans
/data(« non envoyée ») ; - la centrale reste injoignable pendant 3,5 s (« non envoyée ») ;
- l’écriture est partie mais la centrale n’a pas répondu, a répondu autre chose, ou le mode fête est relu actif, ou ne peut pas être relu (« envoyée, sans confirmation ») ;
- la centrale a refusé l’écriture par une exception Modbus 1 à 3 (« refusée par la centrale ») ;
- une autre adresse valide est enregistrée pendant l’arrêt, ou l’intégration s’arrête.
Après un appui, une garde d’arrêt est gardée dans /data. Tant que l’arrêt
n’est pas vu appliqué, une lecture qui montre le mode fête actif renvoie
l’arrêt, et un arrêt non confirmé est renvoyé au démarrage de
l’intégration, avant la lecture de la configuration : trois renvois au plus
par appui, ceux du démarrage compris. Si un
démarrage du mode fête depuis Gladys a été écrit sans confirmation avant
l’arrêt, le mode fête relu actif dans les 2 minutes qui suivent l’arrêt est
aussi pris pour ce démarrage arrivé en retard, et l’arrêt est renvoyé (même
limite). La garde n’est pas levée par le temps : seulement par un démarrage
du mode fête depuis Gladys (option activée), par le mode fête relu actif à
deux lectures de suite après que l’arrêt a été vu appliqué (démarré sur la
centrale ou par une autre application), ou par une autre adresse valide
enregistrée (une adresse vide ou invalide la conserve).
Statut
L’écran de configuration affiche l’état de la centrale (niveau, mode, mode fête, code de défaut, filtres), la cause d’un échec et le délai avant la prochaine lecture. Si Gladys ne peut pas donner la configuration à l’intégration, le statut le dit et la configuration est redemandée après 5 s, 15 s, 30 s, puis toutes les minutes. Une configuration lue depuis Gladys pendant que vous en enregistrez une autre est écartée : la dernière enregistrée gagne.
Données
/data/helios-state.json contient l’heure de la dernière lecture, l’adresse
et l’adresse MAC de la centrale, les capteurs externes vus et la garde
d’arrêt du mode fête. Rien n’est envoyé ailleurs qu’à la centrale.
Paramètres de configuration
Voici les paramètres demandés par Helios easyControls dans son écran de configuration dans Gladys.
| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
| Votre centrale Helios | section | Non | Affiche votre ventilation double flux Helios KWL EC à carte easyControls (logiciel 2.01 ou plus récent) dans Gladys par son interface Modbus TCP (port 502) sur votre réseau local, sans cloud : quatre températures d’air, mode de fonctionnement, niveau et vitesses de ventilation, modes fête et veille, changement des filtres, défauts, et capteurs externes d’humidité et de CO2. Saisissez l’adresse IP de la centrale, enregistrez, puis ajoutez-la depuis l’onglet Découverte. Le mode de fonctionnement, le niveau de ventilation et le démarrage du mode fête ne se changent depuis Gladys que si vous autorisez les commandes ci-dessous ; l’arrêt du mode fête ne dépend jamais de cette option (voir le guide pour les cas où il peut échouer). Gladys n’écrit jamais le niveau 0 (ventilateurs arrêtés) ni le mode veille. Le Modbus TCP n’a pas de mot de passe : gardez la centrale sur un réseau de confiance. Jamais testé avec un vrai appareil. Sans lien avec Helios. |
| Adresse IP de la centrale | string | Oui | Une adresse IPv4 ou un nom d’hôte (port 502 sauf si vous en ajoutez un, par exemple 192.168.1.90:502). |
| Autoriser les commandes | boolean | Non | Désactivé par défaut. Activé : Gladys peut changer le mode de fonctionnement (automatique, manuel), le niveau de ventilation (1 à 4, en mode manuel) et démarrer le mode fête ; tous sont refusés en mode veille ou ventilateurs arrêtés (niveau 0). Désactivé : ces commandes sont refusées. L’arrêt du mode fête ne dépend jamais de cette option. |
| Intervalle de rafraîchissement (s) | number | Non | Fréquence de lecture de la centrale, en secondes. |
| Langue des noms des fonctionnalités | select | Non | Sert aux noms de l’appareil et des fonctionnalités ajoutés désormais, au statut et aux erreurs des commandes. |
Comment installer Helios easyControls dans Gladys
- Dans Gladys, ouvrez Intégrations : Helios easyControls apparaît dans le catalogue, aux côtés des intégrations natives, avec un badge communautaire.
- Cliquez sur Installer. Gladys télécharge l'image Docker (
ghcr.io/lm1lc3n7/gladys-helios:0.1.1), la démarre dans un bac à sable isolé du cœur, et génère l'interface de l'intégration (appareils, découverte et configuration). - Ouvrez l'écran Configuration de l'intégration, remplissez les paramètres, puis enregistrez.
- Vous pouvez aussi l'installer directement depuis l'URL de son dépôt : https://github.com/LM1LC3N7/gladys-helios.
Helios easyControls nécessite Gladys >=5.1.0. Le catalogue dans Gladys se rafraîchit toutes les heures : une nouvelle version est donc disponible au plus tard une heure après sa sortie.
Vous n'utilisez pas encore Gladys ? C'est gratuit et open source : suivez le guide d'installation pour démarrer.
À propos des intégrations externes
Helios easyControls est une intégration externe : une intégration communautaire empaquetée dans un conteneur Docker et publiée sur GitHub, que Gladys installe en un clic et exécute dans un bac à sable isolé de son cœur. Elle est publiée et maintenue par LM1LC3N7, et non par l'équipe cœur de Gladys.
- Parcourir toutes les intégrations, natives et communautaires
- Créer et publier votre propre intégration externe
- Code source sur GitHub — source de cette documentation