Intégration externe - Zendure

Développement
1

:battery: Zendure (intégration externe) — présentation + récap jusqu’à la v1.3.0

Bonjour à tous :waving_hand:

Je me rends compte que je n’ai jamais ouvert de sujet dédié à l’intégration externe Zendure, alors qu’elle existe depuis cet été (première version le 19 juillet 2026). Je rattrape mon retard : voici une présentation complète et le récap des versions jusqu’à la v1.3.0, qui vient de sortir. Ce sujet servira ensuite pour annoncer les nouveautés et recueillir vos retours.

:puzzle_piece: C’est quoi ?

Une intégration externe Gladys pour les batteries solaires Zendure SolarFlow / Hyper. Elle tourne dans son propre conteneur, s’installe depuis le catalogue d’intégrations (rayon Énergie) et remonte la télémétrie de vos batteries dans Gladys, depuis le cloud Zendure et, si vous le souhaitez, directement depuis le MQTT local de chaque appareil.

:sparkles: Ce qui est pris en charge

  • Modèles : SolarFlow 800, 800 Pro, 1600 AC+, 2400 AC+, 2400 AC, 2400 Pro, et Hyper 2000 (expérimental).
  • 5 mesures par batterie (lecture seule), rangées dans les catégories énergie de Gladys depuis la v1.3.0 :
    • Niveau de batterie, puissance de charge et puissance de décharge → Batterie de stockage ;
    • puissance vers la maison → Capteur de sortie maison ;
    • puissance d’entrée solaire → Capteur de production d’énergie.
  • MQTT local (optionnel) : valeurs rafraîchies toutes les 1 à 3 s au lieu d’environ 30 s par le cloud, et la télémétrie continue pendant une panne du cloud Zendure ou d’internet.
  • Repli cloud automatique, appareil par appareil : si une batterie devient muette en local, l’intégration bascule seule sur le cloud, puis revient au local dès que les messages reprennent.
  • Badges de transport sur chaque appareil : Local, Cloud, Cloud + point orange (dégradé : l’appareil devrait être en local mais tourne sur le repli cloud, la raison s’affiche au survol) et Injoignable.
  • Statut de connexion sur l’écran de configuration (clé manquante, cloud injoignable ou clé invalide).
  • Publication des valeurs cadencée sous la limite de requêtes du cœur Gladys, qui ralentit d’elle-même si le cœur sature, pour tenir avec une grosse flotte (je tourne avec une quinzaine de SolarFlow).

:rocket: Installation

  1. Dans l’application mobile Zendure, section développeur / intégration Home Assistant : générez (ou copiez) votre clé d’autorisation (la « clé HA »).
  2. Dans Gladys : Intégrations → cherchez Zendure → Installer.
  3. Onglet Configuration : collez la clé, ajustez l’intervalle de rafraîchissement si besoin (30 s par défaut), activez éventuellement le MQTT local (zenSDK), puis Enregistrer la configuration.
  4. Créez vos batteries depuis l’onglet Découverte.

Le pas-à-pas complet est dans la documentation de l’intégration (lien « Documentation » sur l’écran de configuration).

:scroll: Le récap des versions

  • v1.0.1 (19 juillet) : première version : découverte des SolarFlow 800 Pro via le cloud Zendure, télémétrie en lecture seule, interrogation périodique et temps réel MQTT.
  • v1.1.0 (21 juillet) : MQTT local avec repli cloud par appareil et retour automatique au local, badges de transport, statut de connexion, et 6 modèles SolarFlow / Hyper supplémentaires.
  • v1.2.0 (24 juillet) :
    • badge dégradé (point orange) quand une batterie tourne sur le repli cloud ;
    • documentation FR/EN et section « Pour commencer » sur l’écran de configuration ;
    • cadence de publication adaptative sous la limite du cœur ;
    • fiabilisation : les échos de nos propres requêtes MQTT ne faussent plus la télémétrie, intervalle vide ou invalide → 30 s, délai de 15 s sur le cloud, plus de valeurs en cache republiées pendant une coupure.
  • v1.3.0 (16 octobre) :
    • les mesures passent dans les catégories énergie de Gladys (Batterie de stockage, Capteur de sortie maison, Capteur de production d’énergie) : votre batterie domestique ne compte plus dans les alertes « batterie faible » de Gladys ;
    • les puissances du pack s’appellent maintenant Puissance de charge et Puissance de décharge : les anciens noms (« Battery input/output power ») se lisaient à l’envers par rapport à ce qu’ils mesurent ;
    • classement dans la catégorie Énergie du catalogue ;
    • toute l’intégration en français, anglais, allemand et espagnol (configuration, messages, documentation) ;
    • mise à niveau technique (SDK 0.15, outillage de release, notes de version sur GitHub).

:warning: Prérequis

  • Gladys ≥ 4.86.0 pour la v1.3.0.
  • Un compte Zendure avec vos batteries déjà en ligne dans l’application.
  • Pour le MQTT local : l’activer dans l’application Zendure (mode développeur).

:counterclockwise_arrows_button: Vous aviez déjà vos batteries avant la v1.3.0 ?

Après la mise à jour (bouton Mettre à jour de l’onglet Supervision), vos batteries gardent leurs anciennes catégories tant que vous n’appliquez pas la nouvelle définition : dans l’onglet Découverte, cliquez sur Mettre à jour sur chaque batterie (marquée Déjà ajouté). Les fonctionnalités sont mises à jour sur place : l’historique, les scènes et les tableaux de bord sont conservés.

:light_bulb: Bon à savoir

  • Un seul consommateur cloud par compte Zendure : si Home Assistant ou une seconde instance Gladys utilise la connexion cloud du même compte, les deux se la disputent et la télémétrie devient intermittente. Pour un second consommateur, passez par le MQTT local, qui n’a pas cette limite. L’intégration le signale une fois dans ses journaux quand elle détecte cette situation.
  • Une batterie en « Cloud (dégradé) » alors que le MQTT local est activé : son firmware a pu arrêter de publier en local sans prévenir. Dans l’application Zendure, désactivez puis réactivez le contrôle MQTT de cette batterie, et elle repart en moins d’une minute.
  • Intégration bloquée en « dégradé » dès l’installation, avec des timeouts WebSocket dans les journaux : vérifiez que le pare-feu de la machine laisse passer le port utilisé par les intégrations externes pour joindre Gladys (voir ce sujet).

:motorway: La suite

  • Le pilotage des batteries (consignes de charge/décharge, limites de sortie) : c’est la prochaine grosse étape.
  • Des mesures supplémentaires (index de charge/décharge, énergie restante, sortie secours) une fois leurs noms confirmés sur de vraies remontées.

:test_tube: Retours bienvenus

Merci d’avance pour vos retours :folded_hands:

2

:new_button: Mise à jour : v1.3.1 → v1.5.0

Grosse journée sur l’intégration Zendure ! Voici ce qui est arrivé depuis la v1.3.0 :

v1.3.1 — sécurité

  • Mise à jour de la bibliothèque MQTT (6 failles corrigées, dont 4 pouvaient faire planter l’intégration). La reconnexion après un refus du broker (session reprise par un autre client du compte, broker qui redémarre) est conservée.

v1.4.0 — noms des fonctionnalités

  • Nouvelle option Noms des fonctionnalités (français, anglais, allemand, espagnol) : les batteries que vous créez ensuite ont leurs fonctionnalités dans votre langue. Une batterie déjà créée garde ses noms.
  • Un modèle Zendure non reconnu apparaît dans l’onglet Journaux avec son nom exact (Unsupported Zendure model skipped: productModel "..."). Copiez-le dans une issue et je l’ajoute.

v1.5.0 — énergie, pilotage et widgets (:warning: Gladys ≥ 5.1.0)

:high_voltage: Énergie

  • 4 nouveaux compteurs en kWh : énergie chargée, déchargée, solaire et envoyée vers la maison. Zendure ne remonte que des puissances, donc l’intégration les cumule elle-même. Les compteurs survivent aux redémarrages, et un silence de plus de 5 minutes n’est pas compté.
  • L’énergie solaire alimente directement les graphiques de production de Gladys.
  • Énergie restante en kWh : le niveau de charge multiplié par la capacité des packs déclarés (AB1000, AB2000, AB3000, packs intégrés).

:control_knobs: Pilotage depuis les scènes (catégorie Intégrations)

  • Régler la limite de sortie, Régler la limite de charge (charge AC depuis le réseau), Régler le mode AC (charge / décharge), Régler les niveaux de charge (cible 70-100 %, plancher 0-50 %).
  • Des garde-fous protègent la batterie :
    • les limites sont plafonnées à la puissance nominale du modèle ;
    • les limites de puissance sont envoyées en « mode intelligent », gardées en mémoire et non écrites dans la flash ;
    • un même réglage ne change pas plus d’une fois toutes les 3 s (puissance) ou 30 s (mode, niveaux) ;
    • une valeur déjà appliquée n’est pas renvoyée.
  • Nouveau déclencheur Joignabilité d’une batterie : une batterie ne remonte plus rien, ou remonte à nouveau (mode MQTT local).

:bar_chart: Deux widgets de tableau de bord

  • Batterie Zendure : niveau et puissances en direct, source (local / cloud / repli / injoignable), énergie stockée, limites, mode et niveaux de charge actuels. Deux boutons ouvrent un formulaire pré-rempli pour les modifier.
  • Groupe de batteries : plusieurs batteries cumulées sous un nom de votre choix. Elles affichent le niveau moyen (pondéré par la capacité), les puissances totales, l’énergie stockée et une ligne par batterie. En triphasé, posez un groupe par phase (« Phase L1 », « L2 », « L3 ») et un dernier sans sélection pour tout le site.

:counterclockwise_arrows_button: Pour en profiter

  1. Supervision → Mettre à jour.
  2. Onglet Découverte : cliquez sur Mettre à jour sur chaque batterie (marquée « Déjà ajouté ») pour ajouter les fonctionnalités d’énergie. L’historique, les scènes et les tableaux de bord sont conservés.
  3. Ajoutez les widgets depuis l’édition du tableau de bord.

:motorway: La suite

Gladys n’a pas encore de type « consigne » pour une batterie, d’où le pilotage par scènes et widgets pour l’instant. Une PR cœur est en cours pour l’ajouter : limites de puissance de charge et de décharge, niveau de charge cible, réserve de décharge et mode (feat(battery-storage): add power limit, state-of-charge limit and mode commands by Terdious · Pull Request #3210 · GladysAssistant/Gladys · GitHub). Une fois intégrée, ces réglages seront directement modifiables depuis la carte de chaque batterie.

:test_tube: Retours bienvenus

  • Le pilotage sur vos modèles : limites, mode AC, niveaux de charge. En particulier l’échelle du SOC selon les firmwares : remontez-moi tout comportement bizarre.
  • Les compteurs d’énergie : sont-ils cohérents avec l’application Zendure sur une journée ?
  • Les widgets de groupe pour ceux qui ont plusieurs batteries.

Changelog complet : gladys-zendure/CHANGELOG.md at master · Terdious/gladys-zendure · GitHub

3

Petit point sur la suite annoncée : tout est prêt côté core, SDK et intégration, il ne reste que les merges. @pierre-gilles, quand tu auras un moment pour les relire :smiley:

La PR a pas mal évolué avec les relectures. Elle ajoute maintenant des consignes standard pour les batteries de stockage, valables pour toutes les marques (batteries plug-in, onduleurs hybrides…) :

  • limites de puissance de charge et de décharge ;
  • limite de charge depuis le réseau : elle borne la charge AC sans brider le solaire ;
  • niveau de charge cible et réserve de décharge ;
  • mode : auto, charge, décharge, veille, heures creuses, secours.

Plus une nouvelle catégorie « Sortie maison » avec sa limite de puissance de sortie : la puissance maximale que l’appareil envoie dans la maison, solaire et batterie confondus. C’est le réglage qu’on touche le plus sur une SolarFlow, et il sert aussi aux micro-onduleurs (Hoymiles, APsystems, Enphase…). Les mesures restent dans « Capteur de sortie maison », comme la consigne d’un thermostat est séparée de la mesure de température.

Côté intégration, la branche est prête et testée : limite de sortie, limite de charge AC, niveaux de charge et mode AC (charge / décharge) deviennent réglables directement depuis la carte de chaque batterie. Ils passent par les mêmes garde-fous que les scènes : plafond à la puissance du modèle, mode intelligent, cadence limitée, valeur déjà appliquée non renvoyée. La carte affiche ensuite la valeur réellement appliquée par la batterie. Elle restera en attente tant que Gladys ne connaît pas ces nouveaux types. Je la validerai sur mes propres batteries avant la release.

Merci d’avance ! Dès que ces PR sont publiées, je fais la mise à jour côté intégration.