ha-ecoflow-local

A Home Assistant custom integration for EcoFlow power stations using local TCP communication only — no cloud account, no internet required.

This is a modernized fork of vwt12eh8/hassio-ecoflow updated to work with Home Assistant 2024.x and later (tested on 2026.3.1).

---

Supported Devices

Device	Product ID
RIVER	5
RIVER Max	5 (model 2)
RIVER 600 Pro	7
RIVER Pro	12
RIVER Plus	18
RIVER Max Plus	18 (model 2)
RIVER Mini	17
DELTA Max	13
DELTA Pro	14
DELTA Mini	15
Smart Generator	20

---

Requirements

• Home Assistant 2024.1 or later
• EcoFlow device connected to your local Wi-Fi network
• Device must have TCP port 8055 accessible on your LAN

Verify local connectivity

Before installing, confirm your device is reachable locally:

nc -zv <device-ip> 8055

You should see: Connection to <device-ip> port 8055 [tcp] succeeded!

---

Installation

Via HACS (recommended)

1. Open HACS in Home Assistant
2. Go to Integrations → three-dot menu → Custom repositories
3. Add this repository URL with category Integration
4. Search for "EcoFlow" and install
5. Restart Home Assistant

Manual

1. Copy the custom_components/ecoflow folder into your HA config directory:

   /config/custom_components/ecoflow/
   

2. Restart Home Assistant

---

Configuration

1. Go to Settings → Devices & Services → Add Integration
2. Search for EcoFlow
3. Enter your device's local IP address
4. The integration will auto-detect the device model and serial number

Tip: Assign a static/reserved IP to your EcoFlow device in your router to prevent the IP from changing.

---

Entities

Sensors

Entity	Description
Battery	State of charge (%)
Total input	Combined input power (W)
Total output	Combined output power (W)
AC input voltage	Volts
AC input current	Amps
AC input frequency	Hz
AC output voltage	Volts
AC output current	Amps
AC output frequency	Hz
DC input voltage	Volts
DC input current	Amps
MPPT input energy	Wh (lifetime)
Total input energy	Wh (lifetime)
Total output energy	Wh (lifetime)
Battery temperature	°C
Battery voltage	V
Battery cycles	Count
Remain time	Estimated time to full/empty
Fan	Fan speed state

Switches

Entity	Description
AC output	Enable/disable AC outlets
DC output	Enable/disable DC/car output
Beep	Enable/disable button sounds
X-Boost	Enable/disable X-Boost (DELTA only)

Numbers (configurable)

Entity	Description
Charge level	Max battery charge %
Discharge level	Min battery discharge % (DELTA)
AC charge speed	Max AC input watts
Car input	DC input current (amps)
Screen brightness	LCD brightness %
Smart generator auto on	Battery % to start generator
Smart generator auto off	Battery % to stop generator

Selects (configurable)

Entity	Description
AC timeout	Auto-off timer for AC output
AC frequency	50Hz / 60Hz
Screen timeout	LCD auto-off timer
DC mode	Auto / Solar / Car input type
Unit timeout	Device standby timer

---

Energy Dashboard

To use your EcoFlow with the Home Assistant Energy Dashboard:

• MPPT input energy → Solar Panels → Solar production energy
• Total input energy → Home Battery Storage → Energy going in to the battery
• Total output energy → Home Battery Storage → Energy coming out of the battery

---

About the Remain Entity

The Remain entity (estimated time to full/empty) is disabled by default because it changes frequently and generates a large number of database writes. If you enable it, consider excluding it from the recorder:

recorder:
  exclude:
    entities:
      - sensor.your_ecoflow_remain

---

Protocol

The integration communicates with EcoFlow devices over a binary TCP protocol on port 8055:

• Packet framing: magic bytes 0xAA 0x02 + little-endian length
• Header integrity: CRC8
• Payload integrity: CRC16
• Some packets use XOR deobfuscation
• Communication is bidirectional (push from device + commands to device)
• iot_class: local_push — no polling, real-time updates

---

Changes from Upstream

The following breaking changes from the original repo were fixed for modern Home Assistant compatibility:

Issue	Fix
async_setup_platforms removed	replaced with async_forward_entry_setups
DhcpServiceInfo import moved	now imported from homeassistant.helpers.service_info.dhcp
ELECTRIC_CURRENT_AMPERE removed	UnitOfElectricCurrent.AMPERE
ELECTRIC_POTENTIAL_VOLT removed	UnitOfElectricPotential.VOLT
ENERGY_WATT_HOUR removed	UnitOfEnergy.WATT_HOUR
FREQUENCY_HERTZ removed	UnitOfFrequency.HERTZ
POWER_WATT removed	UnitOfPower.WATT
TEMP_CELSIUS removed	UnitOfTemperature.CELSIUS

---

Credits

Original integration by vwt12eh8.

---

License

See LICENSE.