search

berezhinskiy / ecoflow_exporter

Prometheus exporter for EcoFlow portable power stations
GNU General Public License v3.0
184 stars 27 forks source link

readme

⚡ EcoFlow to Prometheus exporter

GitHub Build Status GitHub branch checks state GitHub release (latest SemVer)

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:

Dashboard

The project provides:

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:

Please, create an issue to let me know if exporter works well (or not) with your model.

Usage

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

EXPORTER_PORT - (default: 9090)

LOG_LEVEL - (default: INFO) Possible values: DEBUG, INFO, WARNING, ERROR

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:

Actual list of payload metrics: