EcoFlow (IoT Open API)

The EcoFlow driver connects a GEM controller to EcoFlow portable power stations and inverters (Delta, River, PowerStream, smart plugs) through the EcoFlow IoT Open Platform. It reads battery, input, and output telemetry per station and exposes a control passthrough for model-specific commands.

Each EcoFlow account (identified by an access/secret key pair) is one GEM device; each station serial number bound to that account becomes a GEM zone. The device is a power controller — it holds the account credentials and does the polling, and the individual stations hang off it as zones.

Cloud API

This is a cloud integration — GEM talks to api-e.ecoflow.com, not the station directly. There is no local LAN protocol in the Open Platform. Requests are signed with HMAC-SHA256; there is no OAuth redirect.

Prerequisites

• An EcoFlow account with at least one station added in the EcoFlow mobile app.
• A developer access key and secret key from the EcoFlow developer portal (Developer Center → create an application). API access must be approved for the account before the keys will authenticate.

Developer access

The access/secret key pair is issued by the EcoFlow developer portal, not the normal app login. If the portal has not approved API access for your account, signed requests return a sign/authorization error.

Setup steps

1. Create the key pair. In the EcoFlow developer portal, create an application and copy its access key and secret key.
2. Have a Power subsystem ready. If the site has no power/energy subsystem yet, create one first in Subsystems. The station zones live here alongside any other energy devices.
3. Create the GEM device. In Devices, add a device with driver ecoflow. GEM auto-fills the Device Type to Controller — leave it. Set the Subsystem field to your Power subsystem; that is the subsystem the station zones will belong to. Then set:
   • access_key — the developer access key
   • secret_key — the developer secret key (stored encrypted)
   • api_base — leave at https://api-e.ecoflow.com unless EcoFlow assigned your account a different regional host
4. Enumerate stations. Run get_devices (see Running commands below) to list the serial numbers bound to the account and confirm they are online.
5. Create one zone per station. In Zones, add a zone for each station. Under Device Assignment, pick the EcoFlow device in the Device field — the editor then pre-selects your Power subsystem and shows the SN example as the Address hint. Set Address to that station's serial number (SN). GEM does not create these zones automatically — you add one per station you want to monitor.

Attribute reference

Device attributes

Attribute	Required	Description
access_key	yes	EcoFlow developer access key (public identifier).
secret_key	yes	EcoFlow developer secret key. Used as the HMAC-SHA256 signing secret; stored encrypted.
api_base	no	Regional API host. Default https://api-e.ecoflow.com.
status_interval	no	Telemetry poll interval, in milliseconds. Default 60000; accepts 15000–600000. Keep it at 60 s or higher — the Open API is rate limited.

Zone address format

zone.address is the EcoFlow station serial number (SN), e.g. R331ZEB4ZEAL0001, exactly as returned by get_devices. The zone's Address field in the editor shows this hint as you type.

Commands

Every command below is driver-managed and available from the Commands editor, macros, triggers, and the Script Console. Most take address — the station SN.

Command	Arguments	Notes
get_devices	—	List the station serial numbers bound to the account, with each station's name and online/offline state.
get_status	address	Read all quota telemetry for one station SN (the full model-specific key map).
get_quota	address, quotas	Read specific quota keys. quotas is an array (or comma list) of dotted key names.
set_quota	address, params, module_type, operate_type, cmd_code	Control passthrough — see Controlling a station below.

Running commands

The Script Console is the quickest place to run them by hand. For example, to enumerate the account and then read one station:

command({device: <id>, action: "get_devices"})
command({device: <id>, action: "get_status", args: {address: "R331ZEB4ZEAL0001"}})

get_devices is the quickest first check after saving the device — a populated list confirms the keys authenticate and the account has stations bound.

Zone attributes (written by the driver)

On each poll the driver writes these attributes to every zone, when the station exposes the underlying metric. They appear automatically — you do not pre-create them — and can be shown on widgets/dashboards or used in triggers and macros.

Attribute	Type	Meaning
battery_level	integer	State of charge, 0–100 (%).
output_watts	float	Total output power (W).
input_watts	float	Total input power (W).
remaining_time	integer	Minutes remaining — charge or discharge, as the model reports it.
state	string	on when output_watts > 0, else off.

quota/all returns a flat map of model-specific dotted keys. The driver extracts the metrics above by matching well-known key fragments — battery from *.soc or showSoc, output from wattsOutSum or *outputWatts, input from wattsInSum or *inputWatts, and remaining from remainTime. A model that names a field differently simply will not surface that metric until it is mapped.

Controlling a station — set_quota

Control payloads differ by product line (Delta, River, PowerStream, and smart plugs each use their own params, and some require a moduleType / operateType or cmdCode envelope). Rather than guess a schema per model, set_quota is a faithful passthrough:

• params — the model-specific control object copied from the EcoFlow Open API documentation for your station. May be entered as a JSON object.
• module_type / operate_type / cmd_code — optional envelope fields some models require.

The driver wraps these as {sn, params, moduleType?, operateType?, cmdCode?}, signs the request, and PUTs it to /iot-open/sign/device/quota. Consult the EcoFlow Open API reference for the exact params your model expects (for example, AC output enable/disable, charge-speed limits, or PowerStream power setpoints).

Telemetry (get_devices, get_status, polling) works for every model with no extra configuration; only set_quota needs a model-specific body.

Known limitations

• Control is model-specific. There is no universal on/off verb — send the documented params via set_quota for your station.
• Cloud-only and rate limited. Keep status_interval at 60 s or higher and poll a reasonable number of stations; the Open API throttles aggressive clients. The driver polls stations sequentially with a short gap between each.
• Metric coverage varies by model. Only the well-known telemetry keys are extracted automatically.

Troubleshooting

Symptom	Check
401 / sign verification failed	Confirm access_key and secret_key are the developer-portal key pair (not the app login) and that API access is approved for the account.
get_devices returns an empty list	The station must be bound to the same EcoFlow account the key pair belongs to. Add it in the EcoFlow app, then retry.
Telemetry attributes never populate	Confirm the zone's Device is the EcoFlow device and its Address is the exact SN. Then run get_status and inspect the raw keys — the model may not use the well-known suffixes.
Requests intermittently fail	You are likely being rate limited. Raise status_interval and reduce how many stations one device polls.

Related documentation

• Devices — adding and configuring the EcoFlow device
• Subsystems — placing the station zones under a Power subsystem
• Zones — creating one zone per station and setting its SN address
• Commands — the full driver-managed command list
• Script Console — running get_devices / get_status and other commands by hand