The problem

EcoFlow offers no local API. We solved that.

The official Developer Portal provides HTTP polling at ~30-second intervals. Too coarse for meaningful automations or real-time energy monitoring. Modbus access is not available for these devices.

EcoFlow Energy works around this with dual connection modes. Standard Mode uses the official IoT API with HTTP polling and real-time MQTT push. Enhanced Mode uses a community-driven WSS bridge for ~2-3 second Protobuf-encoded updates, with no Developer API keys required. All connections work independently of the EcoFlow portal. The integration does not compete with your mobile app for a session slot.

If the connection drops, a 4-tier reconnect strategy kicks in automatically. In Enhanced Mode, entities degrade gracefully through defined stages while retaining last-known-good values. Data collection resumes without manual intervention. Set it up once.

Features

Everything your energy dashboard needs.

Auto-discovery, dual connection modes, and sensors that map directly to the HA Energy Dashboard. No YAML required.

Real-time Streaming

Delta and Stream devices get real-time MQTT push in Standard Mode out of the box. Enhanced Mode adds ~3-second WSS streaming for PowerOcean. Both modes are configurable per device.

Energy Dashboard Ready

All energy sensors use total_increasing state class. Solar, grid, battery, and home consumption map directly into the HA Energy Dashboard.

Auto-discovery

Enter your EcoFlow API credentials once. All devices bound to your account are discovered automatically, and multiple devices are managed within a single integration instance.

Bidirectional Control

Toggle outputs, set charge limits, and configure SoC thresholds. Switches, selects, and number entities across seven of eleven device families.

Never Offline

4-tier MQTT reconnect strategy with graduated availability degradation. If the real-time stream drops, entities retain last-known-good values while the connection recovers through defined stages.

Built-in Diagnostics

Download HA diagnostics with full device state. Credentials are automatically redacted. Debug with confidence.

Supported Devices

Eleven device families. One integration.

Home batteries, plug-in and whole-home batteries, portable power stations, an air conditioner, a wallbox, a plug, a meter, a microinverter, and a solar tracker. 704 entities total. Multi-device configurations supported natively.

PowerOcean

Home Battery System

235 sensors: 115 core + 120 per-pack for up to 5 battery packs
13 binary sensors, 1 select for work mode
10 number controls: backup reserve, solar surplus threshold, charge power for 8 scheduled tasks
8 switches: enable or disable each scheduled charge task
Scheduled charge tasks from the EcoFlow app, readable and switchable from HA
3-phase grid, MPPT per-string, battery cell detail
PowerPulse wallbox readings in Enhanced Mode
Covers PowerOcean Plus, the single-phase 5kW hybrid, and the 3-phase variant
Standard + Enhanced Mode (~3s)

Stream Series

Plug-in / Balcony Battery

55 sensors, 2 binary sensors for per-outlet state
4 number controls: backup reserve, plus charge limit, discharge limit, and LED brightness on AC Pro
2 switches: AC outlets on Stream AC Pro
Per-string solar telemetry across up to 4 strings
Signed AC grid connection power, matches the EcoFlow app
Stream Ultra, AC Pro, Max, AC, Ultra X, and Stream Micro, detected automatically

Stream AC 5000

Whole-home AC-coupled Battery

56 sensors, 2 binary sensors
7 number controls: scheduled charge and discharge power, charge and discharge limits, backup reserve, max grid-tied output, max grid input
1 select: work mode
2 switches: backup reserve, backup socket
5 PV readings: total and strings 1 to 4
Per-unit battery power when up to three units share one account

Delta 2 Max

Portable Power Station

94 sensors, 4 binary sensors
7 switches: AC, DC, 12V, beeper, X-Boost, AC auto restart, backup reserve
8 number controls: charge speed, SoC limits, standby, screen, 12V timeout, backup level
Expansion battery pack support (up to 2)
Standard + Enhanced Mode (~2s)

Delta 3 Series

Portable Power Station

47 sensors, 1 binary sensor, covering AC, solar, 12V, USB and Anderson ports
10 switches: both AC outputs, 12V, X-Boost, beeper, bypass lock, backup reserve, port priority on the Delta 3 Max Plus
7 number controls: charge limit, discharge limit, AC charge power, port priority cutoff levels
5 selects: screen timeout and idle shutdown for the unit, both AC outlets and the 12V group
4 Energy Dashboard sensors, integrated from live power telemetry
Entity IDs identical in both modes, so history survives a mode switch
Covers Delta 3, Delta 3 Max, and Delta 3 Max Plus

Smart Plug

Smart Energy Plug

11 sensors, 1 binary sensor
1 switch: relay on/off
2 number entities: LED brightness, max power limit
Real-time power, current, voltage, frequency
Standard + Enhanced Mode (~3s)

WAVE 3

Portable Air Conditioner

18 sensors, 5 binary sensors, 1 climate entity
4 switches: power, buzzer, automatic drainage, pet care
5 number controls: target temperature, fan speed, target humidity, screen brightness, pet care warning temperature
5 selects: operating mode, submode, display temperature, mood light, screen timeout
Thermostat card: cool, heat, fan, dry, and a two-temperature band in constant temperature mode
Lifetime energy counter integrated from 2-second input power, Energy Dashboard ready
Enhanced Mode only, the Developer API refuses the unit

PowerPulse 2

EV Wallbox

17 sensors, 1 binary sensor
Charging power, voltage and current per phase, phase mode, maximum and session current
Session start, duration, energy and lifetime energy counter
Cable lock state as binary sensor
Works on an account without a PowerOcean
Read-only in this release, Enhanced Mode only

Read-only devices

Sensors, no controls

PowerStream: Microinverter, 25 sensors. Both PV strings, inverter output, grid balance, attached battery. Standard Mode.
Smart Meter: EF-EM-P3-120, 18 sensors, 3 binary sensors. Grid power, per-phase power, voltage and current, six energy counters. Enhanced Mode.
Solar Tracker: 6 sensors. Tilt, target and optimal angle, light level, mode, battery. Enhanced Mode.

Real-world Automations

You monitored. Now you control.

Three automations running in production. Each uses entity data from this integration, standard Home Assistant triggers, and zero custom code.

Solar Cascade Charging: three device types, one integration, zero grid export.

01

Solar Cascade Charging

PowerOcean hits 98% SoC. Smart Plug turns on. Delta 2 Max charges from solar surplus instead of exporting to the grid. Plug turns off when Delta reaches 99% or PowerOcean drops below 50%.

Three device types coordinated through one integration. No solar energy wasted on feed-in.

trigger: sensor.powerocean_battery_soc ≥ 98
action: switch.plug → on
condition: sensor.delta_2_max_soc < 99

02

Delta 2 Max as Office UPS

Delta 2 Max powers office equipment via AC output. When SoC drops below 20%, a push notification fires. Solar surplus charges it back to 80% via max_charge_soc.

AC output off at 23:00, on at 07:00. Standby timeout configured through the number entity. Set it, forget it.

monitor: sensor.delta_2_max_soc < 20 → notify
schedule: switch.ac_output off 23:00, on 07:00
charge: number.max_charge_soc = 80

03

Solar Surplus Awareness

PowerOcean grid export exceeds 1000W for 5 minutes. Push notification with current export value. Shift the dishwasher, laundry, or EV charger into the solar window.

Not automation for its own sake. Actionable awareness that turns monitoring into lower grid bills.

trigger: sensor.grid_export_power_w > 1000 for 5min
action: notify.mobile_app
data: "Solar surplus: {{ export_power }}W"

Field Setup

The pillar sees a limit. The caravan sees a battery.

A campsite pillar is fused anywhere from 2 to 16 amps, and a caravan running an air conditioner alongside a kettle can ask for more than that on one circuit. Three control layers sit between the two on my caravan, acting in order, so the pillar sees a steady draw instead of a spike.

Shore power control chain: the plug enforces the limit, the battery buffers the load, the fridge keeps running.

01

The Shelly as a remote-reset cut-off

Current and power limits follow the hookup size in use. A charge power setpoint is a target for the battery, not a ceiling on the wire. At a 500 W setpoint with the air conditioner running, the grid pull measured 1415 W.

The plug is set to trip before the pillar's breaker sees that number. The Delta is already in bypass mode, so fridge and lights keep running from the battery while the switch resets from Home Assistant instead of a walk to the reception.

limit: current + power, whichever trips first

02

Charge power regulation

Every two minutes the regulation subtracts the caravan's own load and a reserve from the budget, then writes what is left to the Delta's charge power.

It reads a ten-minute rolling average rather than the instant number, so an air conditioner compressor cycling on and off looks like one steady draw. None of it has any effect unless the Delta's own Charge Speed switch sits on ADJUST.

writes: number.ac_charge_power, every 2 min

03

SoC staged load shedding

Below 30 percent Home Assistant sheds the second AC outlet and sends a notification. Below 20 percent the Delta marks that same outlet non-essential and sheds it on its own, no network required.

Below 10 percent the discharge limit takes over on the device itself. The fridge, the cooler, and the air conditioner on the first outlet are never shed by the automation, only flagged.

stages: 30% software, 20% device, 10% discharge limit

This is the same integration behind the automations above, on my own caravan, against a harder constraint: a fuse that trips once and stays tripped until someone finds the reset. The full package, the YAML, and the two approaches that did not work are in the repository.

Caravan guide on GitHub

Connection Modes

Standard or Enhanced. Your call.

Standard Mode uses the official EcoFlow IoT API with HTTP polling and MQTT push. Enhanced Mode uses a community-driven WSS bridge for ~2-3s real-time updates across all devices, with graduated availability degradation instead of HTTP fallback.

Aspect	Standard	Enhanced
API	Official IoT Developer API	Community-driven WSS bridge
Update rate	~30s HTTP polling + real-time MQTT push	~2s Delta, ~3s PowerOcean/Smart Plug
Credentials	Access Key + Secret Key	Email + Password only
Stability	Stable (official API)	May break with EcoFlow updates
Applies to	PowerOcean, Stream, Stream AC 5000, Delta, Smart Plug	All of them, and required for PowerOcean Plus and the single-phase variants
Best for	Users preferring official API stability	Users needing ~2-3s real-time updates

How it compares

Built for depth, not just compatibility.

Side-by-side with alternative EcoFlow integrations for Home Assistant.

Feature	EcoFlow Energy	Alternatives
Data source	MQTT push for all devices (Enhanced), graduated availability with last-known-good data	HTTP polling (10–30s) or basic TCP MQTT
Cloud dependency	No portal login required	Required, or HTTP-only fallback
Connection resilience	4-tier reconnect, graduated availability degradation	Simple reconnect, no fallback
Control	Switches, charge speed, SoC limits, thermostat card, optimistic lock	Switches and sliders, depending on project
Entity depth	267 (PowerOcean), 113 (Delta 2 Max), 70 (Delta 3), 68 (Stream AC 5000), 63 (Stream), 38 (WAVE 3), 25 (PowerStream), 21 (Smart Meter), 18 (PowerPulse 2), 15 (Smart Plug), 6 (Solar Tracker)	Varies widely by project and device
Mobile tolerance	Offline = expected state	Offline = error condition

These differences compound. An integration that handles one device cleanly is useful. One that handles device families, connection failures, and a van-mounted battery going offline for three days takes deliberate architecture.

Installation

Three steps. Done.

Install via HACS, add your EcoFlow credentials, and your devices appear automatically.

Install

Open HACS in Home Assistant. Search for EcoFlow Energy, download, and restart.

Configure

Add the integration in Settings. Enter your Access Key and Secret Key from the EcoFlow Developer Portal.

Monitor

Devices are auto-discovered. Entities appear in your dashboards, Energy Dashboard sensors are ready to map.

Under the Hood

Proven tools.

A focused stack for reliability. Reverse-engineered protocols, typed Python, and a test suite that covers every parser.

Python Runtime

Home Assistant Platform

MQTT / WSS Transport

Protobuf Protocol

HMAC-SHA256 Auth

HACS Distribution

Claude Code Dev Tool

Process

One architect. One agent team.

EcoFlow Energy was built by one person with a clear division of responsibility: architectural decisions, domain knowledge, and protocol understanding stay with the human. Test generation, code review, schema analysis, and scaffolding are delegated to a coordinated set of AI agents.

This is not a solo project that used AI as a productivity tool. It is a different development model. One architect setting direction, agents executing with precision. The 2942-test suite covering every parser edge case was not written by hand. It was specified, reviewed, and shipped through that workflow.

The result is public and auditable. If you want to see what this model produces in practice, start with the repository.

Support

Open source thrives on community.

Back this project

EcoFlow Energy exists because the existing options were shallow. The reverse engineering, the Protobuf parsers, the reconnect logic, the multi-device architecture. None of that was required to ship something functional. It was required to ship something reliable.

This is how I approach every technical problem. The code is public. Draw your own conclusions.

Buy me a coffee

Every watt, every device. Native in Home Assistant.