Open Source · HACS · v1.0

EcoFlow Energy
for Home Assistant.

Native integration for EcoFlow devices. Real-time energy monitoring with 50+ sensors, full Energy Dashboard support, and bidirectional device control.

View on GitHub Install via HACS
50+ Sensors per device
~3s PowerOcean Enhanced
332 Unit tests
The problem

EcoFlow offers no local API. We solved that.

EcoFlow does not offer a local API. The official Developer Portal provides HTTP polling at ~30-second intervals — too coarse for meaningful automations or real-time energy monitoring. Requests to enable Modbus access have been declined.

EcoFlow Energy works around this by maintaining a persistent MQTT connection with Protobuf-encoded payloads. This delivers ~3-second updates in Enhanced Mode, independent of whether you are logged into the EcoFlow app. 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. 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

Standard Mode uses the official IoT API, polling every ~30 seconds. Enhanced Mode adds real-time WSS MQTT push with ~3-second updates 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 AC/DC output, set charge speed limits, and configure SoC thresholds. Switches and number entities for Delta devices.

Never Offline

4-tier MQTT reconnect strategy with automatic HTTP fallback. If the real-time stream drops, polling takes over seamlessly.

Built-in Diagnostics

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

Supported Devices

Three device families. One integration.

PowerOcean home batteries, Delta portable power stations, and Smart Plugs. Multi-device configurations supported natively.

PowerOcean

Home Battery System

  • 57 sensors including 6 Energy Dashboard sensors
  • 3-phase grid monitoring per phase
  • MPPT per-string solar tracking
  • Battery cell temps, voltages, SoH, cycles
  • Standard + Enhanced Mode (~3s real-time)

Delta 2 Max

Portable Power Station

  • 58 sensors, 5 binary sensors
  • 3 switches: AC, DC, 12V output control
  • 4 number controls: charge speed, SoC limits
  • Battery SoC/SoH, temperatures, voltages
  • Standard Mode (HTTP polling ~30s)

Smart Plug

Smart Energy Plug

  • 9 sensors: power, current, voltage, frequency
  • 1 switch: relay on/off for automations
  • Temperature monitoring
  • Ideal for charging automation triggers
  • Standard Mode (HTTP polling ~30s)
Connection Modes

Standard or Enhanced. Your call.

Standard Mode uses the official EcoFlow IoT API. Enhanced Mode adds real-time WSS streaming with automatic fallback to HTTP when the stream is stale.

Aspect Standard Enhanced
API Official IoT Developer API Unofficial WSS MQTT push
Update rate ~30 seconds ~3 seconds
Credentials Access Key + Secret Key + EcoFlow email & password
Stability Stable (official API) May change with EcoFlow updates
Best for Most users Power users needing real-time data
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
Support

Open source thrives on community.

Back this project

EcoFlow Energy is free and open source. If it saves you time or solves a problem, consider supporting continued development.

Buy me a coffee