Skip to main content

EcoFlow integration for Gladys Assistant

EcoFlow integration for Gladys Assistant

Monitor and control EcoFlow River 2 power stations via the official API or a simple login.

View on GitHubAll external integrations

Monitor and control your EcoFlow River 2 (and the wider River 2 family: River 2 Max, River 2 Pro) directly in Gladys, through EcoFlow's cloud — the same one the EcoFlow app itself uses.

Important: EcoFlow devices have no LAN-only control path. Even a device that only ever sits on your own WiFi is controlled through EcoFlow's cloud, both by the official app and by this integration — confirmed against EcoFlow's own support stance (local control without internet is not currently supported for this product line; the one exception in EcoFlow's whole catalog is the unrelated EZ1 sprinkler-timer-sized unit). Your device does need internet access on your network for this integration to work.

Two ways to connect​

  • Method 1 — Official Open Platform (recommended): a free developer account and an Access Key/Secret Key pair. Documented, and every device on the account is discovered automatically. The only downside is EcoFlow's own approval, which can take about a week.
  • Method 2 — Simple login (unofficial, optional): the same email and password you use to sign in to the EcoFlow app — no developer account, no waiting. This uses EcoFlow's internal app endpoints rather than the documented API, so it can change or break without notice, and there is no device auto-discovery: you type in each device's serial number by hand.

Both can be configured at once — a device is looked up through whichever method its serial number is entered under (Method 2's field), or through Method 1's account otherwise.

What you get​

One Gladys device is created per EcoFlow device, however it was found. Every device exposes:

  • Battery level (%)
  • AC charging power (W) — power coming in through the AC input
  • Total output power (W) — power leaving the unit across every output combined
  • AC output power (W)
  • Solar input power (W) — from a connected solar panel, if any
  • AC output (on/off)
  • X-Boost (on/off) — lets the AC output power higher-draw appliances at the cost of a less clean sine wave
  • DC (car) output (on/off)
  • Backup reserve (on/off)

Configuration​

Method 1 (recommended):

  1. Create a free developer account and an Access Key/Secret Key pair at the EcoFlow Open Platform (Europe) or developer.ecoflow.com (global) — approval can take about a week.
  2. Open the Configuration tab of the integration and enter your Access Key and Secret Key, and pick the matching region.
  3. Save: every device on your EcoFlow account appears in the Discovery tab.

Method 2 (simple, unofficial):

  1. Open the Configuration tab and enter your EcoFlow account email and password (the same ones the app uses).
  2. Enter each device's serial number (comma-separated if more than one) — find it in the EcoFlow app under Settings > Device Info, or printed on the unit itself.
  3. Save: the device(s) appear in the Discovery tab.

Actions​

  • Test connection — re-polls a specific device right now and reports its battery level and AC output power, or the exact API error if it fails.

Possible follow-ups​

Deliberately out of scope for now, listed here rather than silently left out:

  • Real-time MQTT push instead of polling, for Method 1 — the private method (Method 2) already talks MQTT, but Method 1's real-time push topic has a message shape that needs confirming against a real account before it can replace the current poll loop.
  • Numeric charge/discharge-limit and backup-reserve-level settings (the percentages the EcoFlow app lets you set) — Gladys' battery-storage device-feature category has no "target level" type distinct from the battery-level sensor itself, so this needs either a Gladys core addition or a deliberate (and clearly documented) reuse of an existing type.

Tested and confirmed​

Honest status, so it's clear what "it works" actually rests on — no EcoFlow account (developer or app) and no physical River 2 unit were available while writing this integration.

  • The REST API (device list, quota snapshot, set command) and its HMAC-SHA256 request signing (Method 1) are hand-written and cross-confirmed against two independent, live-used implementations read directly: the Home Assistant community integration tolwi/hassio-ecoflow-cloud's own api/public_api.py, and rustyy/ecoflow-api's SignatureBuilder/RestClient source — not executed as a dependency (see the README), but read to confirm the algorithm and endpoints.
  • The simple login + MQTT path (Method 2) is likewise cross-confirmed against tolwi/hassio-ecoflow-cloud's api/private_api.py and devices/__init__.py (the latestQuotas request/reply and the {moduleType, operateType, params} command shape are IDENTICAL to Method 1's — only the transport envelope differs).
  • The River 2 family's quota field names (pd.soc, inv.outputWatts, mppt.inWatts...) and set-command shapes (acOutCfg, mpptCar, upsConfig, dsgCfg, watthConfig) are validated at runtime against @ecoflow-api/schemas' own zod schemas — real, current schemas published by that project, not a hand-copied snapshot.
  • A real bug was found and worked around: the published @ecoflow-api/[email protected] package crashes on import for every consumer (a broken internal path that can never resolve). This integration does not depend on it — the REST/signing layer is hand-written instead, confirmed to load and run correctly by this repository's own test suite.
  • What is not independently confirmed: an actual login against a real EcoFlow account (either method), the exact out_voltage/out_freq values a real River 2 reports for mppt.cfgAcOutVol/mppt.cfgAcOutFreq (used to fill in the AC output command alongside whichever field you actually toggle), and the device's real reported serial number prefix (a placeholder was used in tests). Run this integration with LOG_LEVEL=debug against your own River 2 and open an issue if something behaves unexpectedly.

Troubleshooting​

Check the integration logs from the Gladys UI (or docker logs on the host) with LOG_LEVEL=debug for the full detail of every request made to EcoFlow, through either method.

Configuration settings​

These are the settings EcoFlow asks for in its configuration screen in Gladys.

SettingTypeRequiredDescription
Method 1: Official EcoFlow Open Platform (recommended)sectionNoEcoFlow devices have no local/LAN control path — even a device that only ever sits on your own WiFi is controlled through EcoFlow's cloud, both by the official app and by this integration (confirmed against EcoFlow's own support stance; the only exception in EcoFlow's whole catalog is the unrelated EZ1 sprinkler-timer-sized unit). Create a free developer account, then an Access Key/Secret Key pair, at the EcoFlow Open Platform below — approval can take about a week. Every device on the account is discovered automatically after saving; there is nothing else to enter. Prefer this method: it is documented and auto-discovers your devices. See Method 2 below for a simpler-to-start, unofficial alternative if you would rather not wait for approval.
Access KeysecretNo
Secret KeysecretNo
API regionselectNoThe region your EcoFlow developer account/Access Key was created in.
Method 2: Simple login (unofficial, optional)sectionNoNo developer account, no approval wait — just the same email and password you use to sign in to the EcoFlow app. Read before using: this uses EcoFlow's internal app endpoints, not the documented Open Platform API — it can change or break without notice, and there is no device auto-discovery with this method, so you must type in each device's serial number yourself (Settings > Device Info in the EcoFlow app, or printed on the unit). Both methods can be used at once; a serial number listed below is always handled through this method even if the same device also appears on an official account configured above.
EcoFlow account emailsecretNoThe email address you use to sign in to the EcoFlow app.
EcoFlow account passwordsecretNoStored encrypted by Gladys and never leaves your instance except to talk to EcoFlow.
Device serial number(s)stringNoComma-separated if you have more than one, e.g. "R331ZEB4HFJC1234,R331ZEB4HFJC5678". Required for this method — there is no auto-discovery.
Refresh interval (s)numberNoHow often each device's telemetry (battery level, power in/out) is re-polled, through whichever method it uses.

How to install EcoFlow in Gladys​

  1. In Gladys, open Integrations: EcoFlow appears in the catalog, next to the native integrations, with a community badge.
  2. Click Install. Gladys pulls the Docker image (ghcr.io/lm1lc3n7/gladys-ecoflow:0.2.2), starts it in a sandbox isolated from the core, and generates the integration's interface (devices, discovery and configuration).
  3. Open the Configuration screen of the integration, fill in the settings, and save.
  4. You can also install it directly from its repository URL: https://github.com/LM1LC3N7/gladys-ecoflow.

EcoFlow requires Gladys >=4.86.1. The catalog inside Gladys refreshes every hour, so a new version becomes available at most one hour after its release.

Not running Gladys yet? It is free and open source: follow the installation guide to get started.

About external integrations​

EcoFlow is an external integration: a community integration packaged as a Docker container and published on GitHub, that Gladys installs in one click and runs in a sandbox isolated from its core. It is published and maintained by LM1LC3N7, not by the Gladys core team.

Subscribe to the Gladys Assistant newsletter

A few emails per month about new releases and project news. Sent by Pierre-Gilles Leymarie, founder of the project. Unsubscribe anytime 🙂
Last updated on