Local Modbus TCP integration for the EcoFlow PowerOcean Plus home battery system.
⚠️ This integration communicates directly with your device over your local network via Modbus TCP. No cloud connection required.
- Local polling – no EcoFlow cloud account needed
- Configurable poll interval (2–30 seconds, default 5 s)
- Real-time power flow: house consumption, grid import/export, solar generation, battery
- Full battery monitoring: SOC, voltage, current, power, temperature, remaining energy
- Per-string PV power, current and voltage (1–3 strings)
- Per-phase AC measurements: voltage, current, frequency
- Energy counters: daily and lifetime for grid, solar, battery charge/discharge, house consumption
- Reconfigurable after setup via Settings → Configure (no re-install needed)
- Debug logging toggle directly in the HA UI
- German and English translations
| Device | Status |
|---|---|
| EcoFlow PowerOcean Plus | ✅ Confirmed |
| EcoFlow PowerOcean | ✅ Confirmed |
| EcoFlow PowerOcean Connect | ❓ Untested – feedback welcome |
The ModBus must be enabled by your EcoFlow Partner / Installer, it is disabled by default!
- Open HACS in Home Assistant
- Go to Integrations → ⋮ → Custom repositories
- Add
https://github.com/MaxGrmm/EF-PowerOcean-TcpModbusas category Integration - Click Install
- Restart Home Assistant
- Download the latest release
- Copy the
custom_components/ef_powerocean_tcpmodbusfolder to your HAconfig/custom_components/directory - Restart Home Assistant
- Go to Settings → Devices & Services → Add Integration
- Search for EF-PowerOcean-TcpModbus
- Fill in the setup form:
| Field | Default | Description |
|---|---|---|
| IP Address | – | Local IP of your PowerOcean Plus |
| Port | 502 | Modbus TCP port |
| Inverter model | PowerOcean Three Phase | |
| Number of Batteries | 0 | Number of installed battery modules |
| Maximum solar power | 12kW | Installed solar power |
| Maximum grid power | 15kW | Expected maximum grid power to detect unauthorized values |
| Calculation of solar power | false | In some inverters, the modbus register delivers 0W of solar power. This switch allows the solar power to be calculated from the individual powers of the string. |
| Poll Interval (seconds) | 5 | How often values are fetched |
To change settings after setup: Settings → Devices & Services → EF-PowerOcean-TcpModbus → Configure
Install the development dependencies and enable the formatting hooks:
python -m pip install -r requirements-development.txt
pre-commit installRun all linting and formatting checks manually with:
pre-commit run --all-filesCI also runs these checks. Formatting fixes are committed automatically to branches in this repository.
| Sensor | Unit | Description |
|---|---|---|
| House Power | W | Current house consumption |
| Grid Power | W | Grid exchange (negative = export) |
| Solar Power | W | Total PV generation (sum of active strings) |
| Battery Power | W | Battery charge/discharge power |
| Sensor | Unit | Description |
|---|---|---|
| Battery SOC | % | State of charge |
| Battery 1 SOC | % | State of charge |
| Battery 2 SOC | % | State of charge |
| Battery 3 SOC | % | State of charge |
| Battery Remaining Energy | kWh | Calculated from SOC × configured capacity |
| Battery Voltage | V | DC bus voltage |
| Battery Current | A | Positive = charging, negative = discharging |
| Battery Temperature | °C | Battery temperature |
| Battery Nominal Capacity | kWh | User-configured capacity |
| Maximum Battery Charge Power | W | Configured max charging in the EcoFlow app |
| Sensor | Unit | Description |
|---|---|---|
| PV String 1/2/3 Power | W | Per-string power (current × own string voltage) |
| PV String 1/2/3 Current | A | MPPT string current |
| PV String 1/2/3 Voltage | V | Per-string DC voltage |
| Sensor | Unit | Description |
|---|---|---|
| Grid Voltage L1/L2/L3 | V | Per-phase voltage |
| Grid Current L1/L2/L3 | A | Per-phase current |
| Grid Frequency | Hz | Grid frequency |
| Inverter Temperature | °C | Inverter temperature |
| Sensor | Unit | Description |
|---|---|---|
| Inverter Nominal Power Limit | W | Maximum inverter output |
| Inverter Rated Power Limit | W | Maximum inverter rated power |
| Inverter Current Max Power | W | Current active power limit |
| Max Battery Discharge Power | W | Calculated: 3300 W × number of modules |
| Max Charge Power | W | Calculated: 2500 W × number of modules |
| Min SOC Limit | % | Configured minimum state of charge |
| Sensor | Unit | Description |
|---|---|---|
| House Consumption Today | kWh | Calculated from energy balance |
| Solar Yield Today | kWh | Total solar energy generated today |
| Grid Import Today | kWh | Energy imported from grid today |
| Grid Export Today | kWh | Energy exported to grid today |
| Battery Charged Today | kWh | Energy charged today |
| Battery Discharged Today | kWh | Energy discharged today |
| Sensor | Unit | Description |
|---|---|---|
| House Consumption Total | kWh | Calculated from energy balance |
| Solar Yield Total | kWh | Lifetime solar generation |
| Grid Import Total | kWh | Lifetime grid import |
| Grid Export Total | kWh | Lifetime grid export |
| Battery Charged Total | kWh | Lifetime energy charged |
| Battery Discharged Total | kWh | Lifetime energy discharged |
| Battery Net Energy | kWh | Charged minus discharged |
To enable debug logging without editing configuration.yaml:
- Settings → Devices & Services → EF-PowerOcean-TcpModbus → Enable debug logging
- Protocol: Modbus TCP (port 502)
- Register type: Holding Registers (Function Code 3)
- Float encoding: 32-bit IEEE 754, little-endian word order (word-swapped)
- Read strategy: Block reads (5 requests per poll cycle)
- Tested firmware: 3.0.15.10
- Tested pymodbus version: 3.6.9, 3.11.x and 3.13.x
Full register map: EcoFlow_PowerOcean_Modbus.md
Pull requests are welcome! Especially:
- Testing on other EcoFlow devices (PowerOcean DC, Connect)
- Identifying further Modbus registers
- Home Assistant Energy Dashboard configuration examples
Please open an issue before submitting large changes.
Special thanks to Kater Carlo for his significant contributions to register mapping, sensor definitions and testing – this release would not have happened without him. 🐱
This integration was developed through community reverse engineering. EcoFlow does not officially support or document this Modbus interface. Use at your own risk. Not affiliated with EcoFlow Technology Co., Ltd.
MIT License – free to use, modify and distribute with attribution.