Skip to main content

EcoFlow smart home integration, free and open source

EcoFlow integration for Gladys Assistant

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

View on GitHubAll 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.

Requires Gladys Assistant 5.1 or later (dashboard widget and scene cards).

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
  • Discharge remaining time (minutes) — while running on battery
  • Charging (yes/no) — derived from the power balance (inputs above outputs, battery not full)
  • 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)

A switch you flip in Gladys shows its new position at once, then the unit is re-read a few seconds later to confirm it.

Updating from 0.2.x: the two new sensors (remaining time, charging) make Gladys show an Update button on your device in the Discovery tab — click it to add them. Existing features and their history are kept.

Dashboard widget​

Add the EcoFlow power station widget to a dashboard (widget picker → EcoFlow section) and pick a station in its settings. It shows:

  • what the station is doing: "On battery · 3 h 10 left", "Charging · 300 W in", "Offline — not answering"…;
  • live tiles: battery gauge, AC input, solar input, total output;
  • the settings that are not switches: AC/DC outputs, X-Boost, backup reserve and its level, charge and discharge limits, connection method;
  • buttons to turn the AC and DC outputs on/off — or a Retry button while the station does not answer.

Scenes​

Triggers (scene editor → "When…"), each with an optional station filter (empty = any station) and the variables battery level and total output power:

TriggerWhen it fires
Wall power lostthe AC input goes dead — e.g. a power cut on a unit used as a UPS
Wall power restoredthe AC input comes back
Station stopped answeringoffline in the EcoFlow cloud, or 3 failed refreshes in a row
Station answering againback from the state above
Charge limit reachedthe battery reaches its charge limit (100 % by default)
Battery lowthe battery falls to 50, 30, 20, 10 or 5 % — pick the level in the Level reached filter (empty = any); extra variables level reached and remaining time

Each fires once per change, never at every refresh. "Battery low" fires again only after the battery climbed 5 points back above that level. For any other threshold ("battery below 25 %", "remaining time below 30 min"), use Gladys' standard trigger: A device state changes → the station's Battery level (or Discharge remaining time) feature → < and your value, with the option to trigger only when the threshold is crossed.

Actions (scene editor → "Then…"):

ActionFields
Set the charge limitstation, max charge level (50–100 %)
Set the discharge limitstation, min discharge level (0–30 %)
Set the backup reservestation, enabled, level (5–100 %, empty keeps the current one)
Set AC chargingstation, AC charging power (100–1200 W), pause AC charging
Read the station nowstation — outputs battery level, remaining time, input power, output power, charging for the next steps

Example: "every weekday at 22:00 (off-peak), set AC charging to 600 W, not paused; at 06:00, pause it", or "when wall power is lost, send me a message with the battery level".

Connection status​

  • The Configuration tab reports each method separately, after actually trying it — e.g. "Official API: 2 devices · Simple login failed: incorrect password". A serial number that does not look like one is pointed out too.
  • Each device card shows a cloud badge, with an orange dot when the last refresh failed, and unreachable when EcoFlow reports the unit offline or after 3 failed refreshes in a row.

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.
  • Diagnostics — lists every telemetry key the device reports (serial number, Wi-Fi and network values redacted); the full list is written to the integration logs. Paste it into an issue when a value looks wrong, or to help support another model.

Possible follow-ups​

  • Real-time MQTT push instead of polling, for Method 1 — the message shape of the Open Platform push topic needs confirming against a real account before it can complement the poll loop.
  • Other EcoFlow models (Delta, River 3…) — per-model feature tables, fed by Diagnostics reports.
  • Energy categories — Gladys 4.86 files a plug-in battery's AC input under the "grid" category; moving the existing AC charging power feature there would change how Gladys counts energy, so it is left as is for now.

Tested and confirmed​

Honest status, so it's clear what "it works" actually rests on:

  • Method 2 (simple login) was tested by the maintainer on a real River 2 Pro. No real-account test of Method 1 is recorded here yet.
  • 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.
  • 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.
  • Every command shape (acOutCfg, mpptCar, upsConfig, dsgCfg, watthConfig, acChgCfg) is validated at runtime against @ecoflow-api/schemas' own zod schemas.
  • Safety: a command that must echo other current settings (AC output and X-Boost travel with the output voltage/frequency, the backup reserve with its level) re-reads the unit first, and is not sent if the unit has not reported those values — never a made-up default.
  • Not confirmed on a real unit yet: the scene actions (charge/discharge limits, backup reserve, AC charging), the wall-power detection from inv.acInVol (when absent, the AC input power is used, confirmed on two refreshes in a row), and the remaining-time field. Run Diagnostics 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.3.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 >=5.1.0. 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