Real-time Streaming
Delta 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.
Open Source · HACS · v1.10.0
Every watt, every device.
Native in Home Assistant.
333 entities across three device families. Real-time MQTT streaming, native Energy Dashboard integration, and bidirectional control for every supported device.
333
Entities total
~2-3s
Enhanced Mode
766
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 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 across all three device families, 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.
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 and number entities across all three device types.
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
Three device families. One integration.
PowerOcean home batteries, Delta portable power stations, and Smart Plugs. 333 entities total. Multi-device configurations supported natively.
PowerOcean
Home Battery System
- 203 sensors: 83 core + 120 per-pack for up to 5 BP5000 battery packs
- 1 number entity: Min Discharge SoC (Enhanced Mode)
- 6 Energy Dashboard sensors
- 3-phase grid, MPPT per-string, battery cell detail
- Standard + Enhanced Mode (~3s)
Delta 2 Max
Portable Power Station
- 95 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)
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)
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
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
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"
action: notify.mobile_app
data: "Solar surplus: {{ export_power }}W"
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 | All devices (PowerOcean, Delta, Smart Plug) | All devices (PowerOcean, Delta, Smart Plug) |
| 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, optimistic lock | Read-only |
| Sensor depth | 114 (Delta), 204 (PowerOcean), 15 (Smart Plug) | 10–20 typical |
| 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. That 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 766-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, the repository is the most direct answer.
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