Skip to content

Home

Jump to bottom
Rabit edited this page Nov 11, 2025 · 17 revisions

Welcome to the ha-ef-ble wiki!

This page is made to help you to connect your HA to EcoFlow BLE device and do whatever you want.

Recognized devices:

  • Smart Home Panel 2 (EF-HD3####, FW Version: 4.0.0.122, WiFi Version: 2.0.1.20)
  • Delta Pro Ultra (EF-YJ####, FW Version: 5.0.0.25, WiFi Version: 2.0.2.4)
  • River 3 (Plus, UPS) (EF-R3####, FW Version: 1.0.0.0)
  • Delta 3 (Plus, 1500) (EF-D3####, FW Version: 6.49.76.57)
  • Delta Pro 3 (EF-DP3####)

NOTICE: this integration utilizes Bluetooth LE of the EF device, which is supporting just one connection at a time - so if you want to manage the device through BLE from your phone, you will need to disable this device in HA for that and later re-enable it to continue to collect data. It's an internal EF device limitation, so not much to do here...

WARNING: Support & Warranty

Sorry, limited support and no warranty - you on your own and I take no responsibility for any of your actions. We all grown-ups here and know that we deal with quite dangerous voltages and storage devices that could injure or cause death. So make sure you know what you doing for each and every step - otherwise you can't use the provided information in this repository or integration.

In case you see some issues with your device after using this integration - ecoflow support could be unable to help you. Author of the integration is not connected to EcoFlow anyhow and they can't support anything you will find here.

Configuration

Install the integration as custom_component and it will automatically find the supported devices. If it did not find anything - you can try to add device manually, just go to HA integrations, click "Add Integration" button and select "EcoFlow BLE (Unofficial)". It will show you menu where you can select the device and provide/find your EcoFlow UserID there.

The helper allows you to quickly find your user ID by requesting your login/password - they are not stored in the configuration and used once just to send a request to ecoflow API to receive back your ID. In case it doesn't work or you don't trust the implementation - you can always find it by hand:

Two ways to find your UserID - it's sent to device when you bind it to your EcoFlow account and becomes integral part of the authentication mechanism, but usually user don't see it. It's only visible through:

  • By log in to ecoflow site: go to https://us.ecoflow.com/ , open dev console of your browser (press F12) and switch to "Network" tab. Then login and find POST to https://api-a.ecoflow.com/auth/login. The response contains json, which have data.user.userId field string. api_get_userId
  • If you have root on your device with ef app and have a courage to figure it out no matter what, you can get the info from efmmkv encrypted db of the ecoflow android application. Please follow the https://github.com/rabits/ha-ef-ble/issues/86 description (thanks to @kotori2).

After configuration device will be added and you can use it.

Additional help

Besides general Issues you can use this Home Assistant community thread to ask for questions or if you want to find some useful workaround.

FAQ

I frequently see that device is disconnected or log shows alot of exceptions about CRC/padding

  • This is a well-known issue with instability of the BLE protocol - unfortunately I found not much ways to make it more stable, but to put the BLE adapter as close as possible to the device. If you see those errors - make sure nothing significant is crossing the line of sight from adapter to the target device. If you feel like debugging, you can check those suggestions: https://community.home-assistant.io/t/ecoflow-ble-unofficial/774794/58

  • Also that could be an unstable drivers for your BLE adapter or improper config of BLEProxy: unfortunately linux kernel sometimes breaks the Bluetooth stack (it's very complicated), so one solution I found is to use ESPHome BLE Proxy (here you can find config I used). It's very important to make sure scan_parameters will not interrupt the connectivity, in my case removing of those interval and window keys (marked minus and red in the diff) helped:

    ...
 esp32_ble_tracker:
   scan_parameters:
-    interval: 1100ms
-    window: 1100ms
     active: true
...

    That's my whole config right here in case someone just want to start from scratch (it uses 1 esp32 devboard per connection, because previously I had issues with disconnecting of my secondary SHP2 - now with separated devboards it works stable):

    esphome:
  name: bluetooth-proxy-01
  friendly_name: Bluetooth Proxy 01

esp32:
  board: esp32dev
  framework:
    type: esp-idf

# Enable logging
logger:

# Enable Home Assistant API
api:
  encryption:
    key: "<KEY_BASE64>"

ota:
  - platform: esphome
    password: "<PASSWORD_OTA>"

wifi:
  domain: .local
  ssid: !secret wifi_ssid
  password: !secret wifi_password

  # Enable fallback hotspot (captive portal) in case wifi connection fails
  ap:
    ssid: "Bluetooth-Proxy-01"
    password: "<PASSWORD_AP>"

esp32_ble_tracker:
  scan_parameters:
    active: true

bluetooth_proxy:
  active: true
  connection_slots: 1 # 1 connection per proxy - it's much more stable this way. Concurrent connections has tendency to fail.

  • Another thing could haunt you - is the limited amount of slots on BLEProxy. So please make sure you have not too much devices, otherwise they will fight for the slots and we don't need any hussle in our automation.

My device is not supported, could you add it to the integration?

I would gladly accept the change (PR) with the implementation - the framework in ef-ble allows to relatively easy add a new device if it's based on BLEv2 EcoFlow protocol. But I would not be able to create this logic for you, because:

  1. I have no such device, means I can't properly test it and getting back and forth with the users trying to figure out what's going wrong is a huge pain. So nope, no way I will spend my time on it.
  2. I can make sure the integration works with my devices, because I have them. So long-term support is possible just if you using the device through the integration. Devices getting new firmware, HA updates frequently, so I have enough to think about already.
  3. I'm lazy ass and would prefer someone else who needs the result to do the job. That how it goes.

But since EcoFlow is creating good hardware - I think we're in luck to have alot of people around, so please create a ticket and it will wait for the developer with the device to add it's support.

Clone this wiki locally