Aller au contenu principal

Intégration domotique EcoFlow, gratuite et open source

Intégration EcoFlow pour Gladys Assistant

Surveillez et contrôlez vos stations EcoFlow River 2 via l'API officielle ou une connexion simple.

Voir sur GitHubToutes les intégrations

Surveillez et contrôlez votre EcoFlow River 2 (et plus largement la gamme River 2 : River 2 Max, River 2 Pro) directement dans Gladys, via le cloud EcoFlow — le même que celui utilisé par l'application EcoFlow elle-même.

Important : les appareils EcoFlow n'ont aucun mode de contrôle local/LAN. Même un appareil qui ne quitte jamais votre réseau WiFi est piloté via le cloud EcoFlow, aussi bien par l'application officielle que par cette intégration — confirmé par la position officielle d'EcoFlow (le contrôle local sans internet n'est actuellement pas pris en charge pour cette gamme de produits ; la seule exception dans tout le catalogue EcoFlow est l'EZ1, un minuteur d'arrosage sans rapport). Votre appareil a besoin d'un accès internet sur votre réseau pour que cette intégration fonctionne.

Nécessite Gladys Assistant 5.1 ou plus récent (widget de tableau de bord et cartes de scène).

Deux façons de se connecter​

  • Méthode 1 — Open Platform officielle (recommandée) : un compte développeur gratuit et une paire Access Key/Secret Key. Documentée, et tous les appareils du compte sont découverts automatiquement. Le seul inconvénient est l'approbation EcoFlow, qui peut prendre environ une semaine.
  • Méthode 2 — Connexion simple (non officielle, optionnelle) : le même email et mot de passe que pour vous connecter à l'application EcoFlow — aucun compte développeur, aucune attente. Cela utilise les points d'accès internes de l'application EcoFlow plutôt que l'API documentée : cela peut donc changer ou casser sans préavis, et il n'y a pas de découverte automatique des appareils : vous saisissez vous-même le numéro de série de chaque appareil.

Les deux peuvent être configurées en même temps — un appareil est cherché via la méthode dont le numéro de série est renseigné (champ de la méthode 2), ou via le compte de la méthode 1 sinon.

Ce que vous obtenez​

Un appareil Gladys est créé par appareil EcoFlow, quelle que soit la méthode qui l'a trouvé. Chaque appareil expose :

  • Niveau de batterie (%)
  • Puissance de charge AC (W) — puissance entrante par l'entrée secteur
  • Puissance de sortie totale (W) — puissance sortante sur toutes les sorties combinées
  • Puissance de sortie AC (W)
  • Puissance d'entrée solaire (W) — depuis un panneau solaire connecté, le cas échéant
  • Autonomie restante (minutes) — lorsque la station fonctionne sur batterie
  • En charge (oui/non) — déduit du bilan de puissance (entrées supérieures aux sorties, batterie non pleine)
  • Sortie AC (marche/arrêt)
  • X-Boost (marche/arrêt) — permet à la sortie AC d'alimenter des appareils plus gourmands, au prix d'une onde sinusoïdale moins propre
  • Sortie DC (allume-cigare) (marche/arrêt)
  • Réserve de secours (marche/arrêt)

Un interrupteur actionné dans Gladys affiche immédiatement sa nouvelle position, puis la station est relue quelques secondes plus tard pour confirmer.

Mise à jour depuis la 0.2.x : les deux nouveaux capteurs (autonomie, en charge) font apparaître un bouton Mettre à jour sur votre appareil dans l'onglet Découverte — cliquez dessus pour les ajouter. Les fonctionnalités existantes et leur historique sont conservés.

Widget de tableau de bord​

Ajoutez le widget Station EcoFlow à un tableau de bord (sélecteur de widgets → section EcoFlow) et choisissez une station dans ses réglages. Il affiche :

  • ce que fait la station : « Sur batterie · 3 h 10 restantes », « En charge · 300 W entrants », « Hors ligne — ne répond pas »… ;
  • des tuiles en direct : jauge de batterie, entrée secteur, entrée solaire, sortie totale ;
  • les réglages qui ne sont pas des interrupteurs : sorties AC/DC, X-Boost, réserve de secours et son niveau, limites de charge et de décharge, méthode de connexion ;
  • des boutons pour activer/couper les sorties AC et DC — ou un bouton Réessayer tant que la station ne répond pas.

Scènes​

Déclencheurs (éditeur de scènes → « Quand… »), chacun avec un filtre de station optionnel (vide = n'importe quelle station) et les variables niveau de batterie et puissance de sortie totale :

DéclencheurQuand il se déclenche
Coupure de l'entrée secteurl'entrée AC n'est plus alimentée — par exemple une coupure de courant sur une station utilisée comme onduleur
Retour de l'entrée secteurl'entrée AC est de nouveau alimentée
La station ne répond plushors ligne dans le cloud EcoFlow, ou 3 rafraîchissements en échec d'affilée
La station répond à nouveausortie de l'état précédent
Limite de charge atteintela batterie atteint sa limite de charge (100 % par défaut)
Batterie faiblela batterie descend à 50, 30, 20, 10 ou 5 % — choisissez le niveau dans le filtre Niveau atteint (vide = n'importe lequel) ; variables en plus niveau atteint et autonomie restante

Chacun se déclenche une seule fois par changement, jamais à chaque rafraîchissement. « Batterie faible » ne se redéclenche qu'une fois la batterie remontée de 5 points au-dessus du niveau. Pour tout autre seuil (« batterie sous 25 % », « autonomie sous 30 min »), utilisez le déclencheur standard de Gladys : Changement d'état d'un appareil → la fonctionnalité Niveau de batterie (ou Autonomie restante) de la station → < et votre valeur, avec l'option pour ne déclencher qu'au franchissement du seuil.

Actions (éditeur de scènes → « Alors… ») :

ActionChamps
Régler la limite de chargestation, niveau de charge max (50–100 %)
Régler la limite de déchargestation, niveau de décharge min (0–30 %)
Régler la réserve de secoursstation, activée, niveau (5–100 %, vide conserve l'actuel)
Régler la charge secteurstation, puissance de charge secteur (100–1200 W), mise en pause
Relever la station maintenantstation — renvoie niveau de batterie, autonomie, puissance d'entrée, puissance de sortie, en charge pour les étapes suivantes

Exemple : « en semaine à 22 h (heures creuses), régler la charge secteur à 600 W sans pause ; à 6 h, la mettre en pause », ou « en cas de coupure de l'entrée secteur, m'envoyer un message avec le niveau de batterie ».

État de la connexion​

  • L'onglet Configuration indique le résultat de chaque méthode séparément, après l'avoir réellement essayée — par exemple « API officielle : 2 appareils · Échec de la connexion simple : incorrect password ». Un numéro de série qui n'en a pas l'air est également signalé.
  • Chaque carte d'appareil affiche un badge cloud, avec un point orange quand le dernier rafraîchissement a échoué, et injoignable quand EcoFlow signale l'appareil hors ligne ou après 3 rafraîchissements en échec d'affilée.

Configuration​

Méthode 1 (recommandée) :

  1. Créez un compte développeur gratuit et une paire Access Key/Secret Key sur EcoFlow Open Platform (Europe) ou developer.ecoflow.com (international) — l'approbation peut prendre environ une semaine.
  2. Ouvrez l'onglet Configuration de l'intégration et entrez votre Access Key et votre Secret Key, puis choisissez la région correspondante.
  3. Enregistrez : tous les appareils de votre compte EcoFlow apparaissent dans l'onglet Découverte.

Méthode 2 (simple, non officielle) :

  1. Ouvrez l'onglet Configuration et entrez l'email et le mot de passe de votre compte EcoFlow (les mêmes que pour l'application).
  2. Entrez le numéro de série de chaque appareil (séparés par des virgules si plusieurs) — trouvable dans l'app EcoFlow sous Paramètres > Infos appareil, ou imprimé sur l'appareil.
  3. Enregistrez : le ou les appareils apparaissent dans l'onglet Découverte.

Actions​

  • Tester la connexion — rafraîchit immédiatement un appareil donné et rapporte son niveau de batterie et sa puissance de sortie AC, ou l'erreur API exacte en cas d'échec.
  • Diagnostic — liste toutes les clés de télémétrie remontées par l'appareil (numéro de série, Wi-Fi et valeurs réseau masqués) ; la liste complète est écrite dans les logs de l'intégration. Collez-la dans un ticket quand une valeur semble fausse, ou pour aider à prendre en charge un autre modèle.

Suites possibles​

  • Push MQTT en temps réel à la place du sondage périodique, pour la méthode 1 — la forme des messages du sujet de push de l'Open Platform reste à confirmer sur un compte réel avant de pouvoir compléter la boucle de sondage.
  • Autres modèles EcoFlow (Delta, River 3…) — des tables de fonctionnalités par modèle, alimentées par les rapports de Diagnostic.
  • Catégories énergie — Gladys 4.86 range l'entrée AC d'une batterie branchée sur le réseau dans la catégorie « réseau » ; y déplacer la fonctionnalité existante Puissance de charge AC changerait la façon dont Gladys compte l'énergie, elle est donc laissée telle quelle pour l'instant.

Testé et confirmé​

État honnête, pour que ce que « ça fonctionne » recouvre réellement soit clair :

  • La méthode 2 (connexion simple) a été testée par le mainteneur sur un vrai River 2 Pro. Aucun essai de la méthode 1 sur un vrai compte développeur n'est encore consigné ici.
  • L'API REST (liste des appareils, instantané de quota, envoi de commande) et sa signature de requête HMAC-SHA256 (méthode 1) sont écrites à la main et recoupées avec deux implémentations indépendantes et réellement utilisées, lues directement : le code api/public_api.py de l'intégration communautaire Home Assistant tolwi/hassio-ecoflow-cloud, et le code source SignatureBuilder/RestClient de rustyy/ecoflow-api.
  • Le chemin connexion simple + MQTT (méthode 2) est de même recoupé avec api/private_api.py et devices/__init__.py de tolwi/hassio-ecoflow-cloud.
  • Chaque forme de commande (acOutCfg, mpptCar, upsConfig, dsgCfg, watthConfig, acChgCfg) est validée à l'exécution par les schémas zod de @ecoflow-api/schemas.
  • Sécurité : une commande qui doit reprendre d'autres réglages actuels (la sortie AC et le X-Boost voyagent avec la tension/fréquence de sortie, la réserve de secours avec son niveau) relit d'abord la station, et n'est pas envoyée si la station n'a pas remonté ces valeurs — jamais de valeur par défaut inventée.
  • Pas encore confirmé sur un vrai appareil : les actions de scène (limites de charge/décharge, réserve, charge secteur), la détection de l'entrée secteur via inv.acInVol (en son absence, la puissance d'entrée AC est utilisée, confirmée sur deux rafraîchissements d'affilée), et le champ d'autonomie restante. Lancez le Diagnostic et ouvrez un ticket si quelque chose se comporte de façon inattendue.

Dépannage​

Consultez les logs de l'intégration depuis l'interface Gladys (ou docker logs sur l'hôte) avec LOG_LEVEL=debug pour le détail complet de chaque requête envoyée à EcoFlow, quelle que soit la méthode.

Paramètres de configuration​

Voici les paramètres demandés par EcoFlow dans son écran de configuration dans Gladys.

ParamètreTypeObligatoireDescription
Méthode 1 : EcoFlow Open Platform officielle (recommandée)sectionNonLes appareils EcoFlow n'ont aucun mode de contrôle local/LAN — même un appareil qui ne quitte jamais votre réseau WiFi est piloté via le cloud EcoFlow, aussi bien par l'application officielle que par cette intégration (confirmé par la position officielle d'EcoFlow ; la seule exception dans tout le catalogue EcoFlow est l'EZ1, un minuteur d'arrosage sans rapport). Créez un compte développeur gratuit, puis une paire Access Key/Secret Key, sur l'EcoFlow Open Platform ci-dessous — l'approbation peut prendre environ une semaine. Tous les appareils du compte sont découverts automatiquement après l'enregistrement — rien d'autre à saisir. Privilégiez cette méthode : elle est documentée et découvre vos appareils automatiquement. Voir la méthode 2 ci-dessous pour une alternative non officielle, plus rapide à démarrer, si vous préférez ne pas attendre l'approbation.
Access KeysecretNon
Secret KeysecretNon
Région de l'APIselectNonLa région dans laquelle votre compte développeur/Access Key EcoFlow a été créé.
Méthode 2 : connexion simple (non officielle, optionnelle)sectionNonAucun compte développeur, aucune attente d'approbation — juste le même email et mot de passe que pour vous connecter à l'application EcoFlow. À lire avant utilisation : ceci utilise les points d'accès internes de l'application EcoFlow, pas l'API Open Platform documentée — cela peut changer ou casser sans préavis, et il n'y a pas de découverte automatique des appareils avec cette méthode : vous devez saisir vous-même le numéro de série de chaque appareil (Paramètres > Infos appareil dans l'app EcoFlow, ou imprimé sur l'appareil). Les deux méthodes peuvent être utilisées ensemble ; un numéro de série listé ci-dessous est toujours géré par cette méthode, même si le même appareil apparaît aussi sur un compte officiel configuré plus haut.
Email du compte EcoFlowsecretNonL'adresse email utilisée pour vous connecter à l'application EcoFlow.
Mot de passe du compte EcoFlowsecretNonStocké chiffré par Gladys, il ne quitte jamais votre instance sauf pour parler à EcoFlow.
Numéro(s) de série des appareilsstringNonSéparés par des virgules si vous en avez plusieurs, ex. « R331ZEB4HFJC1234,R331ZEB4HFJC5678 ». Requis pour cette méthode — il n'y a pas de découverte automatique.
Intervalle de rafraîchissement (s)numberNonFréquence de rafraîchissement des données de chaque appareil (niveau de batterie, puissance entrante/sortante), via la méthode utilisée pour cet appareil.

Comment installer EcoFlow dans Gladys​

  1. Dans Gladys, ouvrez Intégrations : EcoFlow 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-ecoflow:0.3.2), 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-ecoflow.

EcoFlow 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​

EcoFlow 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.

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 🙂
Dernière mise à jour le