github.com/berezhinskiy/ecoflow_exporter @v2.1.0
Chat with this repoWhat it actually does AI analysis from the code graph — generated when you open this
README
⚡ EcoFlow to Prometheus exporter
About
An implementation of a Prometheus exporter for EcoFlow products. To receive information from the device, exporter works the same way as the official mobile application by subscribing to EcoFlow MQTT Broker mqtt.ecoflow.com
Unlike REST API exporters, it is not required to request for APP_KEY and SECRET_KEY since MQTT credentials can be extracted from api.ecoflow.com. Another benefit of such implementation is that it provides much more device information:
The project provides:
- Python program that accepts a number of arguments to collect information about a device and exports the collected metrics to a prometheus endpoint
- Dashboard for Grafana
- Docker image for your convenience
- Quick Start guide for your pleasure
The exporter collects all possible metrics names and their values sent by the device to MQTT EcoFlow Broker. In case of any new objects in the queue, new metrics will be generated automatically based on the JSON object key/value. For example, payload:
{
"bms_bmsStatus.minCellTemp": 25,
"bms_bmsStatus.maxCellTemp": 27,
"bms_emsStatus.f32LcdShowSoc": 56.5,
"inv.acInVol": 242182,
"inv.invOutVol": 244582
}
will generate the following metrics:
ecoflow_bms_bms_status_min_cell_temp{device="XXXXXXXXXXXXXXXX"} 25.0
ecoflow_bms_bms_status_max_cell_temp{device="XXXXXXXXXXXXXXXX"} 27.0
ecoflow_bms_ems_status_f32_lcd_show_soc{device="XXXXXXXXXXXXXXXX"} 56.5
ecoflow_inv_ac_in_vol{device="XXXXXXXXXXXXXXXX"} 242182.0
ecoflow_inv_inv_out_vol{device="XXXXXXXXXXXXXXXX"} 244582.0
All metrics are prefixed with ecoflow and reports label device for multiple device support
Disclaimers
⚠️ This project is in no way connected to EcoFlow company, and is entirely developed as a fun project with no guarantees of anything.
⚠️ Unexpectedly, some values are always zero (like ecoflow_bms_ems_status_fan_level and ecoflow_inv_fan_state). It is not a bug in the exporter. No need to create an issue. The exporter just converts the MQTT payload to Prometheus format. It implements small hacks like here, but in general, values is provided by the device as it is. To dive into received payloads, enable DEBUG logging.
⚠️ This has only been tested with the following EcoFlow products:
- RIVER Max
- RIVER 2
- RIVER 2 Max
- DELTA Max
- DELTA 2
- DELTA 2 Max
- DELTA Pro
Please, create an issue to let me know if exporter works well (or not) with your model.
Usage
- Connect the device to WiFi and register an EcoFlow account using the official mobile application
- Get your unit's serial number
- Exporter is parameterized via environment variables:
Required:
DEVICE_SN - the device serial number
ECOFLOW_USERNAME - EcoFlow account username
ECOFLOW_PASSWORD - EcoFlow account password
Optional:
DEVICE_NAME - If given, this name will be exported as device label instead of the device serial number
ECOFLOW_API_HOST - (default: api.ecoflow.com).
EXPORTER_PORT - (default: 9090)
LOG_LEVEL - (default: INFO) Possible values: DEBUG, INFO, WARNING, ERROR
- Example of running docker image:
docker run -e DEVICE_SN=<your device SN> -e ECOFLOW_USERNAME=<your username> -e ECOFLOW_PASSWORD=<your password> -it -p 9090:9090 --network=host ghcr.io/berezhinskiy/ecoflow_exporter
will run the image with the exporter on *:9090
Quick Start
Don't know anything about Prometheus? Wanna a quick start? Lazy person? This guide is for you.
Metrics
Prepared by exporter itself:
ecoflow_onlineecoflow_mqtt_messages_receive_totalecoflow_mqtt_messages_receive_created
Actual list of payload metrics:
ecoflow_bms_bms_status_ampecoflow_bms_bms_status_bms_faultecoflow_bms_bms_status_bq_sys_stat_regecoflow_bms_bms_status_cell_idecoflow_bms_bms_status_cyclesecoflow_bms_bms_status_design_capecoflow_bms_bms_status_err_codeecoflow_bms_bms_status_f32_show_socecoflow_bms_bms_status_full_capecoflow_bms_bms_status_input_wattsecoflow_bms_bms_status_max_cell_tempecoflow_bms_bms_status_max_cell_volecoflow_bms_bms_status_max_mos_tempecoflow_bms_bms_status_min_cell_tempecoflow_bms_bms_status_min_cell_volecoflow_bms_bms_status_min_mos_tempecoflow_bms_bms_status_numecoflow_bms_bms_status_open_bms_idxecoflow_bms_bms_status_output_wattsecoflow_bms_bms_status_remain_capecoflow_bms_bms_status_remain_timeecoflow_bms_bms_status_socecoflow_bms_bms_status_sohecoflow_bms_bms_status_sys_verecoflow_bms_bms_status_tag_chg_ampecoflow_bms_bms_status_tempecoflow_bms_bms_status_typeecoflow_bms_bms_status_volecoflow_bms_ems_status_bms_modelecoflow_bms_ems_status_bms_war_stateecoflow_bms_ems_status_chg_ampecoflow_bms_ems_status_chg_cmdecoflow_bms_ems_status_chg_remain_timeecoflow_bms_ems_status_chg_stateecoflow_bms_ems_status_chg_volecoflow_bms_ems_status_dsg_cmdecoflow_bms_ems_status_dsg_remain_timeecoflow_bms_ems_status_ems_is_normal_flagecoflow_bms_ems_status_f32_lcd_show_socecoflow_bms_ems_status_fan_levelecoflow_bms_ems_status_lcd_show_socecoflow_bms_ems_status_max_avail_numecoflow_bms_ems_status_max_charge_socecoflow_bms_ems_status_max_close_oil_ebecoflow_bms_ems_status_min_dsg_socecoflow_bms_ems_status_min_open_oil_ebecoflow_bms_ems_status_open_bms_idxecoflow_bms_ems_status_open_ups_flagecoflow_bms_ems_status_para_vol_maxecoflow_bms_ems_status_para_vol_minecoflow_inv_ac_dip_switchecoflow_inv_ac_in_ampecoflow_inv_ac_in_freqecoflow_inv_ac_in_volecoflow_inv_cfg_ac_enabledecoflow_inv_cfg_ac_out_freqecoflow_inv_cfg_ac_out_volecoflow_inv_cfg_ac_work_modeecoflow_inv_cfg_ac_xboostecoflow_inv_charger_typeecoflow_inv_chg_pause_flagecoflow_inv_dc_in_ampecoflow_inv_dc_in_tempecoflow_inv_dc_in_volecoflow_inv_discharge_typeecoflow_inv_err_codeecoflow_inv_fan_stateecoflow_inv_fast_chg_wattsecoflow_inv_input_wattsecoflow_inv_inv_out_ampecoflow_inv_inv_out_freqecoflow_inv_inv_out_volecoflow_inv_inv_typeecoflow_inv_out_tempecoflow_inv_output_wattsecoflow_inv_slow_chg_wattsecoflow_inv_standby_minsecoflow_inv_sys_verecoflow_mppt_ac_standby_minsecoflow_mppt_beep_stateecoflow_mppt_car_out_ampecoflow_mppt_car_out_volecoflow_mppt_car_out_wattsecoflow_mppt_car_standby_minecoflow_mppt_car_stateecoflow_mppt_car_tempecoflow_mppt_cfg_ac_enabledecoflow_mppt_cfg_ac_out_freqecoflow_mppt_cfg_ac_out_volecoflow_mppt_cfg_ac_xboostecoflow_mppt_cfg_chg_typeecoflow_mppt_cfg_chg_wattsecoflow_mppt_chg_pause_flagecoflow_mppt_chg_stateecoflow_mppt_chg_typeecoflow_mppt_dc24v_stateecoflow_mppt_dc24v_tempecoflow_mppt_dc_chg_currentecoflow_mppt_dcdc12v_ampecoflow_mppt_dcdc12v_volecoflow_mppt_dcdc12v_wattsecoflow_mppt_discharge_typeecoflow_mppt_fault_codeecoflow_mppt_in_ampecoflow_mppt_in_volecoflow_mppt_in_wattsecoflow_mppt_mppt_tempecoflow_mppt_out_ampecoflow_mppt_out_volecoflow_mppt_out_wattsecoflow_mppt_pow_standby_minecoflow_mppt_scr_standby_minecoflow_mppt_sw_verecoflow_mppt_x60_chg_typeecoflow_pd_ac_auto_on_cfgecoflow_pd_ac_enabledecoflow_pd_beep_modeecoflow_pd_bright_levelecoflow_pd_car_stateecoflow_pd_car_tempecoflow_pd_car_used_timeecoflow_pd_car_wattsecoflow_pd_charger_typeecoflow_pd_chg_dsg_stateecoflow_pd_chg_power_a_cecoflow_pd_chg_power_d_cecoflow_pd_chg_sun_powerecoflow_pd_dc_in_used_timeecoflow_pd_dc_out_stateecoflow_pd_dsg_power_a_cecoflow_pd_dsg_power_d_cecoflow_pd_err_codeecoflow_pd_ext3p8_portecoflow_pd_ext4p8_portecoflow_pd_ext_rj45_portecoflow_pd_in_wattsecoflow_pd_input_wattsecoflow_pd_inv_used_timeecoflow_pd_lcd_off_sececoflow_pd_modelecoflow_pd_mppt_used_timeecoflow_pd_out_wattsecoflow_pd_output_wattsecoflow_pd_pv_chg_prio_setecoflow_pd_qc_usb1_wattsecoflow_pd_qc_usb2_wattsecoflow_pd_remain_timeecoflow_pd_socecoflow_pd_standby_minecoflow_pd_sys_verecoflow_pd_typec1_tempecoflow_pd_typec1_wattsecoflow_pd_typec2_tempecoflow_pd_typec2_wattsecoflow_pd_typec_used_timeecoflow_pd_usb1_wattsecoflow_pd_usb2_wattsecoflow_pd_usb_used_timeecoflow_pd_usbqc_used_timeecoflow_pd_watts_in_sumecoflow_pd_watts_out_sumecoflow_pd_wifi_auto_rcvyecoflow_pd_wifi_rssiecoflow_pd_wifi_verecoflow_pd_wire_watts
Core symbols most depended-on inside this repo
Shape
Languages
Modules by API surface
For agents
$ claude mcp add ecoflow_exporter \
-- python -m otcore.mcp_server <graph>