EcoFlow River 3 Plus — HA Integration¶
Overview¶
EcoFlow RIVER 3 Plus (R631ZE1AWH5K0073) integrated into Home Assistant via hassio-ecoflow-cloud custom component.
Uses private_api mode (EcoFlow app credentials) — not REST Developer API (River 3 Plus blocked with code 1006).
Integration Details¶
| Item | Value |
|---|---|
| Integration | ecoflow_cloud (hassio-ecoflow-cloud) |
| Version | latest from main branch |
| Device | RIVER 3 Plus |
| Serial | R631ZE1AWH5K0073 |
| API Mode | private_api (EcoFlow app login) |
| MQTT | EcoFlow cloud MQTT broker (auto-fetched credentials) |
| Entities | 46 total (36 sensors, 6 switches, 4 numbers, 5 selects, 1 button) |
| Update rate | 5 seconds |
| HA config path | /mnt/user/appdata/homeassistant/config/custom_components/ecoflow_cloud/ |
Authentication¶
Private API mode — uses EcoFlow app account (not Developer API keys):
| Item | Value |
|---|---|
minhlucnd@gmail.com |
|
| API Host | api.ecoflow.com |
| Auth flow | Email/password → EcoFlow cloud token → MQTT credentials auto-fetched |
Note: Developer API keys (d0XnC9rhSikH6i7lE5XgHrYb4FJBvKXD) exist but River 3 Plus returns code 1006 (device not allowed) on REST API.
MQTT Architecture¶
River 3 Plus (device)
↓ Wi-Fi
EcoFlow Cloud Server
↓ MQTT (auto credentials)
hassio-ecoflow-cloud (HA integration)
↓
Home Assistant entities
- MQTT broker: EcoFlow cloud (NOT local broker)
- Credentials: fetched from
/api/certification/listendpoint - Client ID:
ANDROID_{uuid}_{user_id} - Keepalive: 15s
- Auto-reconnect on disconnect
Key Entities¶
Sensors (monitoring)¶
| Entity ID | Description | Example Value |
|---|---|---|
sensor.river_3_plus_status |
Device online/offline | online |
sensor.river_3_plus_main_battery_level |
Battery % | 85 |
sensor.river_3_plus_total_in_power |
Total input (W) | 232 |
sensor.river_3_plus_total_out_power |
Total output (W) | 232 |
sensor.river_3_plus_ac_in_power |
AC input (W) | 232.24 |
sensor.river_3_plus_ac_out_power |
AC output (W) | 232 |
sensor.river_3_plus_solar_in_power |
Solar input (W) | 0 |
sensor.river_3_plus_battery_temperature |
Battery temp (°C) | 32 |
sensor.river_3_plus_state_of_health |
Battery health % | 100 |
sensor.river_3_plus_cycles |
Charge cycle count | 0 |
sensor.river_3_plus_charge_remaining_time |
Time to full (min) | 0 |
sensor.river_3_plus_ac_output_energy |
Cumulative AC out (Wh) | 31843 |
Switches (control)¶
| Entity ID | Description |
|---|---|
switch.river_3_plus_ac_enabled |
AC output on/off |
switch.river_3_plus_dc_12v_enabled |
DC 12V output on/off |
switch.river_3_plus_x_boost_enabled |
X-Boost on/off |
switch.river_3_plus_beeper |
Beeper on/off |
switch.river_3_plus_ac_always_on |
AC always on mode |
switch.river_3_plus_backup_reserve_enabled |
Backup reserve mode |
Numbers (sliders)¶
| Entity ID | Description | Range |
|---|---|---|
number.river_3_plus_ac_charging_power |
AC charge speed (W) | 100-600 |
number.river_3_plus_max_charge_level |
Max charge % | 50-100 |
number.river_3_plus_min_discharge_level |
Min discharge % | 0-30 |
number.river_3_plus_backup_reserve_level |
Backup reserve % | 5-100 |
CLI Commands (via HA skill)¶
# Check status
ha.py entity sensor.river_3_plus_status
# Monitor battery
ha.py entity sensor.river_3_plus_main_battery_level
# Search all ecoflow entities
ha.py search river
# Toggle AC output
ha.py toggle switch.river_3_plus_ac_enabled
# Set charging power
ha.py call number.set_value --data '{"entity_id": "number.river_3_plus_ac_charging_power", "value": 300}'
# Send notification about battery
ha.py notify "River 3 Plus battery at {{ states('sensor.river_3_plus_main_battery_level') }}%" --title "EcoFlow Alert"
Installation Path¶
Custom component installed at /mnt/user/appdata/homeassistant/config/custom_components/ecoflow_cloud/ — persisted on unraid appdata, survives container restart/redeploy.
Source: https://github.com/tolwi/hassio-ecoflow-cloud
Troubleshooting¶
| Issue | Fix |
|---|---|
code 1006 on REST API |
Normal — River 3 Plus not supported by Developer REST API. Use private_api mode instead |
| Device offline | Check Wi-Fi on device, use button.river_3_plus_reconnect |
| MQTT disconnected | Integration auto-reconnects. Check internet connectivity |
| Credentials rejected | Verify email/password matches EcoFlow app login. EU users may need api-e.ecoflow.com |
Energy Tracking & Cost Analysis¶
EcoFlow powers NAS + Router on unraid. Energy tracked via HA Energy Dashboard + utility_meter, stored in PostgreSQL.
Energy Sensors (reliability)¶
| Sensor | Unit | Reliable? | Notes |
|---|---|---|---|
sensor.river_3_plus_total_in_energy |
kWh | ✅ Yes | All input (AC + solar). Use for Energy Dashboard grid source |
sensor.river_3_plus_total_out_energy |
kWh | ✅ Yes | All output. Use for battery discharge |
sensor.river_3_plus_ac_output_energy |
Wh | ✅ Yes | Cumulative AC output only |
sensor.river_3_plus_ac_input_energy |
Wh | ❌ No | Resets to unknown periodically → HA statistics sum = 0. Do NOT use for Energy Dashboard |
sensor.river_3_plus_solar_in_energy |
Wh | — | unknown until solar panel connected |
HA Energy Dashboard¶
Config at /mnt/user/appdata/homeassistant/config/.storage/energy:
- Grid source:
sensor.river_3_plus_total_in_energy@ 2,536 VND/kWh (fixed) - Battery: IN =
total_in_energy, OUT =total_out_energy - "Home" label: Hardcoded by HA, cannot rename to "NAS (Router)"
- No per-device tracking: EcoFlow doesn't report per-plug energy. Need smart plugs for NAS vs Router breakdown
PostgreSQL Recorder¶
| Item | Value |
|---|---|
| Container | pigsty-postgres (port 5439) |
| DB | homeassistant |
| User | homeassistant / ha_recorder_2026 |
| Retention | 36,500 days |
| Tables | 13 (states, events, statistics, etc.) |
| Data rate | ~165K rows/day, ~65 MB/day, ~24 GB/year |
utility_meter¶
Configured in configuration.yaml — tracks daily/monthly/yearly kWh:
energy_ecoflow_ac_in_daily/monthly/yearly(grid tariff)ecoflow_ac_out_daily/monthly/yearlyecoflow_solar_daily/monthly
Power Outage Detection¶
No dedicated outage sensor. Detect via:
- battery_charging_state = discharging (best indicator)
- ac_in_power = 0W
- Requires router on UPS for MQTT to keep reporting during outage
Gotchas¶
- NOT in git repo — custom component installed directly on unraid appdata (not via docker-compose)
- EcoFlow app credentials required — if password changed in app, must reconfigure integration
- Cloud-dependent — needs internet for MQTT connection to EcoFlow servers
- No local control — all commands go through EcoFlow cloud, not direct device communication
- Integration was
ecoflow_api(TarasKhust) first, replaced withecoflow_cloud(tolwi) because River 3 Plus blocked on REST API ac_input_energysensor unreliable — usetotal_in_energyinstead for energy tracking- Energy Dashboard "Home" label — hardcoded, cannot rename
- New recorder needs ~1 hour — hourly
statisticstable must populate before Energy Dashboard shows data