Intégration domotique APsystems EZ1 & ECU, gratuite et open source

Connecteur non officiel : micro-onduleurs APsystems EZ1 et passerelles ECU, production solaire.

• Publiée par LM1LC3N7
• Appareils
• Version 0.1.3
• Nécessite Gladys >=5.1.0
• ★ 0

Voir sur GitHubToutes les intégrations

Connecteur non officiel, sans lien avec APsystems. Il lit vos micro-onduleurs APsystems EZ1 (solaire de balcon : EZ1-M, et les autres modèles EZ1 qui offrent l'API locale) sur votre réseau local, via l'API locale que l'onduleur ouvre lui-même, ainsi que les micro-onduleurs derrière une passerelle ECU (ECU-B, ECU-R, ECU-C : DS3, DS3-L, QS1, YC600, YC1000, QT2…) via le port local 8899 de l'ECU (voir Passerelles ECU) : ni cloud ni compte, rien ne sort de chez vous. APsystems est une marque d'Altenergy Power System Inc.

Ce que vous obtenez

Surface	Contenu
Un appareil par onduleur	puissance produite (W, totale et par panneau), énergie du jour (kWh), énergie totale (kWh, un index de production pour le suivi énergétique de Gladys, avec sa production par tranche de 30 minutes), limite de puissance (W, réglable), marche/arrêt, joignable, alarmes
Déclencheurs de scène	production solaire démarrée (le matin), production solaire arrêtée (le soir), alarme d'onduleur solaire (hors réseau, défaut de sortie, court-circuit DC sur un panneau)
Actions de scène	régler la limite de puissance solaire d'un onduleur, lire la production solaire (puissance, énergie du jour et totale, d'un onduleur ou de tous)
Widget	Production solaire : puissance actuelle, énergie du jour et totale, par panneau, la limite et l'état d'un onduleur, ou le total de tous
Un appareil par ECU	puissance produite (W), énergie du jour (kWh), énergie totale (kWh, index de production), onduleurs en ligne, joignable ; lecture seule
Un appareil par micro-onduleur derrière un ECU	en ligne, puissance produite (W, totale et par panneau), tension AC (V, par phase sur un modèle triphasé), fréquence du réseau (Hz), température (°C) ; lecture seule

Installation

1. Activez l'API locale de chaque onduleur, une fois : dans l'application AP EasyPower, connectez-vous à l'onduleur (Bluetooth, « Connexion directe »), ouvrez Réglages → Mode local, activez-le et choisissez Continu. L'application affiche l'adresse IP de l'onduleur.
2. Dans votre box, donnez à chaque onduleur une adresse fixe (réservation DHCP) : l'intégration retrouve les onduleurs par leur adresse.
3. Dans Gladys, saisissez les adresses dans Adresses des onduleurs, séparées par des virgules : 192.168.1.50, 192.168.1.51. Le port est 8050 ; ajoutez :port seulement si le vôtre est différent.
4. Enregistrez, puis cliquez sur Tester les onduleurs : chaque adresse répond avec son modèle, son numéro de série, son firmware et sa puissance actuelle. Faites-le de jour : un EZ1 dort la nuit.
5. Ouvrez Découverte et ajoutez les onduleurs. Placez le widget Production solaire sur un tableau de bord : choisissez un onduleur, ou laissez vide pour le total de tous.

Chaque onduleur est lu toutes les 30 secondes (option Intervalle de rafraîchissement, 10 s minimum : l'EZ1 répond lentement) ; ses alarmes et sa marche/arrêt toutes les 5 minutes, ses informations et sa limite de puissance toutes les heures.

La nuit

Un EZ1 est alimenté par ses panneaux : sans soleil il s'éteint, Wi-Fi compris. C'est normal et pas une erreur : après trois lectures sans réponse, l'onduleur est affiché en veille (nuit), sa puissance passe à 0 W, ses compteurs d'énergie gardent leur valeur, et il n'est plus essayé que toutes les 5 minutes jusqu'à son réveil. Le statut de connexion reste vert.

Le statut ne passe au rouge que si un onduleur disparaît en pleine production (au moins 50 W à sa dernière réponse), ou reste muet une journée entière : vérifiez alors son Wi-Fi, son adresse, et que le mode local est toujours activé.

L'énergie du jour est le compteur de l'onduleur depuis son réveil ce matin ; elle garde la valeur du soir pendant la nuit et repart au lever du soleil. Un redémarrage de l'onduleur dans la journée (un nuage très sombre) est additionné, pas perdu.

Suivi de l'énergie

La fonctionnalité énergie totale est un index de production : Gladys le transforme en production par tranche de 30 minutes (la fonctionnalité « Lifetime energy (30-minute production) », que Gladys remplit elle-même) pour ses écrans d'énergie. Gladys compte chaque hausse d'un index en entier : l'intégration le protège donc (EZ1 comme ECU) :

• un 0 (ou une valeur manquante) n'est jamais publié ;
• une hausse est publiée quand les onduleurs ont pu la produire : au plus 1,5 fois la puissance maximale d'un EZ1 (2 kW par onduleur derrière un ECU) depuis la dernière valeur publiée, sur deux intervalles au moins, plus une petite marge ;
• une baisse, ou un saut plus grand, est retenu : jamais accepté par simple répétition ni avec le temps. Le statut de connexion (qui reste vert) et le bouton Tester les onduleurs l'affichent, avec les deux valeurs. S'il est réel (compteur remis à zéro, onduleur remplacé), cliquez sur Accepter l'énergie totale (il accepte toutes les valeurs retenues à la fois) : la lecture suivante proche de la valeur affichée (plus ce que les onduleurs ont pu produire depuis) est prise ; toute autre lecture est de nouveau retenue. Un saut accepté est compté une fois comme production ; une baisse ne compte rien. L'acceptation n'est pas gardée après un redémarrage de l'intégration : recliquez après un redémarrage. Une valeur revenue à la normale (c'était un raté) lève la retenue d'elle-même ;
• la dernière valeur publiée et ce qui est retenu sont gardés dans /data/state.json : un redémarrage ne change rien.

Limite de puissance et marche/arrêt

• Limite de puissance : plafonne la production, dans les bornes que l'onduleur annonce (30 à 800 W sur un EZ1-M). L'intégration ne l'écrit jamais d'elle-même, et ne réécrit pas une valeur que l'onduleur a déjà. APsystems ne dit pas si l'onduleur la garde en mémoire : une scène qui la change toutes les quelques secondes n'est pas une bonne idée, une fois toutes les quelques minutes suffit largement.
• Marche/arrêt : arrête ou relance la production ; l'API locale continue de répondre onduleur arrêté. Certains firmwares (ceux qui finissent par _b, pour les systèmes avec batterie) n'ont pas de marche/arrêt : la fonctionnalité n'est alors pas proposée.

Passerelles ECU (ECU-B, ECU-R, ECU-C)

Jamais testé avec un vrai ECU. Cette partie a été écrite d'après l'intégration Home Assistant de HAEdwin (APsystems ECU Reader 2.15.0) et sa source de ksheumaker, toutes deux sous Apache-2.0 (voir THIRD_PARTY_NOTICES.md), sans ECU sous la main. Si vous en avez un, vos retours sur le forum sont les bienvenus.

Les micro-onduleurs comme les DS3, DS3-L, QS1, YC600 ou YC1000 parlent à une passerelle ECU en Zigbee ; l'ECU envoie ses données au cloud EMA et répond sur votre réseau local, sur le port TCP 8899. L'intégration l'interroge là : rien ne passe par EMA.

1. Mettez l'ECU sur votre réseau local, avec l'accès local. L'ECU-B et l'ECU-R de la série 2160 se raccordent en Wi-Fi uniquement ; l'ECU-R « Pro » (série 2162, son identifiant commence par 2162) et l'ECU-C se raccordent en Wi-Fi ou en Ethernet (câble). En Wi-Fi : installez EMA Manager, maintenez le bouton de l'ECU jusqu'à ce que son propre Wi-Fi démarre, rejoignez ce Wi-Fi (mot de passe par défaut 88888888), lancez EMA Manager et choisissez la connexion Locale, puis reliez l'ECU au Wi-Fi de la maison (le même réseau que Gladys). Le port 8899 répond alors sur votre réseau.
2. Dans votre box, donnez à l'ECU une adresse fixe (réservation DHCP).
3. Dans Gladys, saisissez-la dans Adresses des passerelles ECU (192.168.1.60 ; port 8899, ajoutez :port seulement si le vôtre est différent). Plusieurs ECU : séparez-les par des virgules.
4. Enregistrez, cliquez sur Tester les onduleurs, puis ouvrez Découverte : un appareil pour l'ECU et un par micro-onduleur qu'il connaît (leur identifiant est celui de l'onduleur lui-même : ils restent les mêmes si l'ECU est remplacé).

Le rythme. Un ECU est connu pour se bloquer si on l'interroge trop souvent. Il est lu à chaque intervalle de lecture des ECU (300 s par défaut, et jamais moins : le rythme que recommande l'intégration Home Assistant), une seule connexion à la fois pour tous vos ECU, avec une pause de 5 secondes entre deux requêtes ; une lecture compte deux requêtes (l'ECU, puis ses onduleurs). Après un échec, l'essai suivant attend 5 minutes, puis 10, puis 20, jusqu'à 30 minutes : jamais avant l'intervalle, même quand le lien avec Gladys se coupe et revient ou que l'intégration redémarre (le rythme est gardé dans /data/state.json). Le bouton de test n'interroge jamais un ECU avant sa prochaine lecture prévue : il décrit la dernière. Après trois lectures ratées de suite, le statut passe au rouge : un ECU bloqué repart en général après l'avoir débranché une minute.

La nuit. L'ECU est alimenté par le secteur et continue de répondre ; ses micro-onduleurs passent hors ligne avec le soleil. C'est l'état en veille (nuit), jamais une erreur : la puissance de l'ECU passe à 0 W, chaque micro-onduleur est hors ligne à 0 W, le reste garde sa dernière valeur. Un micro-onduleur que l'ECU ne liste plus, ou dont il n'a rien dit depuis deux intervalles, est lui aussi hors ligne à 0 W.

Les valeurs sont celles de l'ECU : sa puissance actuelle, son énergie du jour, son énergie totale, le nombre d'onduleurs en ligne ; par micro-onduleur, ce que l'ECU donne (en ligne, la puissance de chaque panneau, la tension AC, la fréquence du réseau, la température quand il est en ligne). Un onduleur d'un type que la référence ne connaît pas n'a que en ligne, et les onduleurs listés après lui ne sont pas lus (deviner inventerait des onduleurs). L'énergie totale de l'ECU est l'index de production du suivi énergétique de Gladys, protégé comme décrit dans Suivi de l'énergie (certains firmwares d'ECU répondent 0 de temps en temps ; 80 onduleurs sont supposés quand l'ECU ne dit pas combien il en a). Les micro-onduleurs n'ont pas de compteur d'énergie : l'ECU compte l'énergie, une seule fois. Des micro-onduleurs créés sans leur ECU sont comptés à part entière dans le widget et l'action « lire la production solaire ».

Lecture seule. Pas de marche/arrêt ni de limite de puissance via l'ECU dans cette version ; l'action « régler la limite de puissance solaire » ne concerne que les EZ1. Les déclencheurs « production solaire démarrée/arrêtée » se déclenchent aussi pour un ECU (sa puissance totale), et le widget comme l'action « lire la production solaire » le comptent.

Scènes

• Production solaire démarrée : un onduleur a produit 10 W ou plus pendant une minute. Variables : la puissance et l'énergie du jour jusque-là.
• Production solaire arrêtée : sous 5 W pendant 15 minutes, ou en veille. Variable : {{triggerEvent.data.energy_today}}, l'énergie du jour (le bon moment pour un message « production du jour »).
• Alarme d'onduleur solaire : une alarme s'est levée : hors réseau (vérifiez le raccordement AC), défaut de sortie (le raccordement AC aussi), court-circuit DC (vérifiez le connecteur du panneau de cette entrée, {{triggerEvent.data.input}}). La première lecture après le démarrage ou après la nuit ne déclenche rien : l'onduleur vérifie le réseau chaque matin.

Dans chaque déclencheur, choisissez un onduleur ou laissez vide pour n'importe lequel. Les variables contiennent toujours le nom de l'onduleur, {{triggerEvent.data.name}}, et son numéro de série, {{triggerEvent.data.serial}}.

• L'action régler la limite de puissance solaire prend un onduleur et une valeur en W, et donne limit, la limite appliquée.
• L'action lire la production solaire prend un onduleur, ou aucun pour tous, et donne power (W), energy_today et energy_total (kWh), producing, sleeping et inverters (le nombre d'onduleurs comptés), pour un message ou une condition. Elle utilise les dernières lectures ; seul un onduleur pas encore lu depuis le démarrage est lu d'abord.

Les actions suivantes de la scène trouvent ces sorties dans leur liste de variables (écrites {{<étape>.<action>.<clé>}}, par exemple {{0.0.power}} quand l'action de lecture est la première de la scène).

Dépannage

• Pas de réponse de jour : vérifiez l'adresse (une adresse fixe), que le mode local est activé et réglé sur « Continu », et que Gladys peut joindre le réseau de l'onduleur (l'intégration tourne dans un conteneur sur l'hôte Gladys).
• « …does not answer: it sleeps without sun » sur une commande : l'onduleur dort ; réessayez quand il produit.
• Pas de marche/arrêt : le firmware n'en a pas (voir plus haut).
• L'énergie totale ne bouge plus : une baisse ou un saut est retenu (le statut le dit, avec les deux valeurs) : cliquez sur Accepter l'énergie totale s'il est réel.
• L'ECU ne répond pas : vérifiez son adresse, qu'il est sur votre réseau (nc -v <adresse de l'ECU> 8899 depuis un ordinateur, puis tapez APS1100160001END : il répond une ligne qui commence par APS11), et débranchez-le une minute s'il est bloqué.
• Logs : le niveau de log de l'intégration se règle avec la variable LOG_LEVEL.

Confidentialité

Tout reste sur votre réseau local : l'intégration ne parle qu'aux adresses que vous avez saisies, en HTTP sur le port 8050 (EZ1) et en TCP sur le port 8899 (ECU).

Paramètres de configuration

Voici les paramètres demandés par APsystems EZ1 & ECU dans son écran de configuration dans Gladys.

Paramètre	Type	Obligatoire	Description
Vos micro-onduleurs APsystems dans Gladys	section	Non	Connecteur non officiel, sans lien avec APsystems. Il lit vos micro-onduleurs EZ1 (solaire de balcon) sur votre réseau local, via l'API locale que chaque onduleur ouvre une fois le « Mode local » activé dans l'application AP EasyPower (choisissez « Continu ») : ni cloud ni compte. Un appareil par onduleur : puissance produite (totale et par panneau), énergie du jour, énergie totale pour le suivi énergétique de Gladys, limite de puissance, marche/arrêt et alarmes. Déclencheurs de scène (production, alarme), actions de scène (limite, lecture), un widget. La nuit, un EZ1 dort (pas de Wi-Fi) : c'est normal. Les micro-onduleurs derrière une passerelle ECU (ECU-B, ECU-R, ECU-C : DS3, QS1, YC600, YC1000…) sont lus par le port local 8899 de l'ECU, en lecture seule : un appareil par ECU (puissance, énergie du jour, énergie totale, onduleurs en ligne) et un par micro-onduleur (en ligne, puissance par panneau, tension, fréquence, température). Jamais testé avec un vrai ECU.
Adresses des onduleurs	string	Non	L'adresse IP de chaque EZ1, séparées par des virgules (port 8050 par défaut, ajoutez :port sinon). Donnez à chaque onduleur une adresse fixe dans votre box (réservation DHCP). Ouvrez ensuite Découverte.
Intervalle de rafraîchissement (s)	number	Non	Fréquence de lecture de la production. L'EZ1 répond lentement : 30 s est un bon rythme, 10 s le minimum. La nuit, un onduleur en veille n'est essayé que toutes les 5 minutes.
Adresses des passerelles ECU	string	Non	Pour des micro-onduleurs derrière une passerelle APsystems ECU (ECU-B, ECU-R, ECU-C) : l'adresse IP de chaque ECU, séparées par des virgules (port 8899 par défaut). Donnez-lui une adresse fixe dans votre box. Laissez vide si vous n'avez que des EZ1.
Intervalle de lecture des ECU (s)	number	Non	Fréquence de lecture de chaque ECU. Un ECU se bloque si on l'interroge trop souvent : 300 s (5 minutes) est le minimum, le rythme recommandé par l'intégration Home Assistant. Après un échec, l'essai suivant attend plus longtemps.

Comment installer APsystems EZ1 & ECU dans Gladys

1. Dans Gladys, ouvrez Intégrations : APsystems EZ1 & ECU apparaît dans le catalogue, aux côtés des intégrations natives, avec un badge communautaire.
2. Cliquez sur Installer. Gladys télécharge l'image Docker (ghcr.io/lm1lc3n7/gladys-apsystems:0.1.3), 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).
3. Ouvrez l'écran Configuration de l'intégration, remplissez les paramètres, puis enregistrez.
4. Vous pouvez aussi l'installer directement depuis l'URL de son dépôt : https://github.com/LM1LC3N7/gladys-apsystems.

APsystems EZ1 & ECU 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

APsystems EZ1 & ECU 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

Inscrivez-vous à la newsletter Gladys Assistant

Quelques emails par mois sur les nouveautés et l'actualité du projet. Envoyés par Pierre-Gilles Leymarie, le fondateur du projet. Désinscription possible à tout moment 🙂