Intégration EcoFlow pour Gladys Assistant

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

• Publiée par LM1LC3N7
• Appareils
• Version 0.2.2
• Nécessite Gladys >=4.86.1
• ★ 0

Voir sur GitHubToutes les intégrations externes

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.

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
• 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)

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.

Suites possibles

Volontairement hors du périmètre actuel, listées ici plutôt que simplement omises :

• Push MQTT en temps réel à la place du sondage périodique, pour la méthode 1 — la méthode privée (méthode 2) parle déjà MQTT, mais le sujet de push temps réel de la méthode 1 a une forme de message qui reste à confirmer sur un compte réel avant de pouvoir remplacer la boucle de sondage actuelle.
• Réglages numériques de limite de charge/décharge et de niveau de réserve de secours (les pourcentages que l'application EcoFlow permet de régler) — la catégorie de fonctionnalité battery-storage de Gladys n'a pas de type « niveau cible » distinct du capteur de niveau de batterie lui-même : cela nécessite soit un ajout au cœur de Gladys, soit une réutilisation délibérée (et clairement documentée) d'un type existant.

Testé et confirmé

État honnête, pour que ce que « ça fonctionne » recouvre réellement soit clair — aucun compte EcoFlow (développeur ou app) ni appareil River 2 physique n'étaient disponibles lors de l'écriture de cette intégration.

• 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 — non exécutées comme dépendance (voir le README), mais lues pour confirmer l'algorithme et les points d'accès.
• 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 (la requête/réponse latestQuotas et la forme de commande {moduleType, operateType, params} sont IDENTIQUES à la méthode 1 — seule l'enveloppe de transport diffère).
• Les noms des champs de quota de la gamme River 2 (pd.soc, inv.outputWatts, mppt.inWatts...) et la forme des commandes (acOutCfg, mpptCar, upsConfig, dsgCfg, watthConfig) sont validés au moment de l'exécution par les schémas zod réels de @ecoflow-api/schemas — des schémas réels et à jour publiés par ce projet, pas une copie figée.
• Un bug réel a été trouvé et contourné : le paquet publié @ecoflow-api/[email protected] plante à l'import pour tout consommateur (un chemin interne cassé qui ne peut jamais se résoudre). Cette intégration n'en dépend pas — la couche REST/signature est écrite à la main, et confirmée fonctionnelle par la suite de tests de ce dépôt.
• Ce qui n'est pas confirmé indépendamment : une vraie connexion à un compte EcoFlow réel (les deux méthodes), les valeurs exactes de out_voltage/out_freq qu'un vrai River 2 rapporte pour mppt.cfgAcOutVol/mppt.cfgAcOutFreq (utilisées pour compléter la commande de sortie AC en plus du champ que vous modifiez réellement), et le préfixe réel du numéro de série rapporté par l'appareil (un espace réservé a été utilisé dans les tests). Faites tourner cette intégration avec LOG_LEVEL=debug sur votre propre River 2 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ètre	Type	Obligatoire	Description
Méthode 1 : EcoFlow Open Platform officielle (recommandée)	section	Non	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 ; 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 Key	secret	Non
Secret Key	secret	Non
Région de l'API	select	Non	La région dans laquelle votre compte développeur/Access Key EcoFlow a été créé.
Méthode 2 : connexion simple (non officielle, optionnelle)	section	Non	Aucun 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 EcoFlow	secret	Non	L'adresse email utilisée pour vous connecter à l'application EcoFlow.
Mot de passe du compte EcoFlow	secret	Non	Stocké chiffré par Gladys, il ne quitte jamais votre instance sauf pour parler à EcoFlow.
Numéro(s) de série des appareils	string	Non	Sé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)	number	Non	Fré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.2.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 >=4.86.1. 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.

• Parcourir toutes les intégrations externes
• Découvrir les intégrations natives intégrées à Gladys
• 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 🙂