Ecoflow API client via REST API or MQTT

This is an Ecoflow API client that allows you to get parameters from your Ecoflow devices either from Ecoflow Rest API (requires developer's access token and secret token) or from MQTT (requires user's email and password, the same as in Ecoflow mobile app).

The client implemented via Ecoflow Rest API has much more functionality:

You can get a specific parameter from your Ecoflow device
You can get all current parameters from your Ecoflow device
You can change parameters for your Ecoflow device
You can list all linked Ecoflow Devices

The MQTT version on the other hand allows to subscribe for the device's parameters changes.

Important notice is that MQTT version requires only user's email/password, but using the client implemented via Ecoflow Rest API requires Access Token and Secret Token which you'll need to receive from Ecoflow (there is an instruction below).

The library was tested on Ecoflow Delta 2 and Ecoflow River 2.

Installation

To get the library just use go get command: go get github.com/tess1o/go-ecoflow

Supported devices

Here is the list of devices for which the complete api (get and set device parameters) using Ecoflow REST API is implemented:

Power Stations (regular ecoflow power stations, like Delta 2, River 2, etc)
Power Stations (PRO versions)
Smart Plug
PowerStream Micro Inverter
Smart Home Panel
Wave Air Conditioner
Glacier

Features via Ecoflow Rest API

This is the list of features implemented using Ecoflow Rest API:

Get list of all linked devices
Get specified parameters from a device
Get all parameters from a device
Change device's settings

Basically that's all documented features the Ecoflow REST API provides

Features via MQTT

Currently only getting device's parameters via MQTT is implemented. Please note you have to know device's serial number in order to use MQTT api.

Documentation

Link to official documentation: https://developer-eu.ecoflow.com/us/document/introduction

How to get Access Token and Secret Token

This is required if you would like to use REST API. For MQTT only user's email address and password is required.
You can skip this section if you want to use MQTT.

Go to https://developer-eu.ecoflow.com/
Click on "Become a Developer"
Login with your Ecoflow username and Password
Wait until the access is approved by Ecoflow
Receive email with subject "Approval notice from EcoFlow Developer Platform". May take some time
Go to https://developer-eu.ecoflow.com/us/security and create new AccessKey and SecretKey

Usage example - MQTT

package main

import (
	"context"
	"encoding/json"
	"fmt"
	mqtt "github.com/eclipse/paho.mqtt.golang"
	"github.com/tess1o/go-ecoflow"
	"log"
	"time"
)

func main() {
	var deviceSn = "Ecoflow device serial number "

	mqttClientConfig := ecoflow.MqttClientConfiguration{
		Email:            "ecoflow_email_address",
		Password:         "ecoflow_password",
		OnConnect:        connectHandler,     //can be nil
		OnConnectionLost: connectLostHandler, // can be nil
		OnReconnect:      nil,                //can be nil
	}

	//an error can be returned if wrong login/password is provided, ecoflow api is not available, network issue, etc
	client, err := ecoflow.NewMqttClient(context.Background(), mqttClientConfig)
	if err != nil {
		log.Fatalf("Unable to create mqtt client: %+v\n", err)
	}

	//connect to MQTT broker and subscribe to the device's topic where its parameters are published
	// It's not described in documentation, 
	// however looks like it sends to the topic only parameters that are changed, not all list of current values

	err = client.Connect()
	if err != nil {
		log.Fatalf("Unable to connect to the broker: %+v\n", err)
	}
	
	err = client.SubscribeForParameters(deviceSn, messagePubHandler)
	if err != nil {
		log.Fatalf("Unable to subscribe: %+v\n", err)
	}
	// keep receiving parameters for 1 hour
	time.Sleep(1 * time.Hour)
}

// handle payload - device's parameters
var messagePubHandler mqtt.MessageHandler = func(client mqtt.Client, msg mqtt.Message) {
	var params ecoflow.MqttDeviceParams
	err := json.Unmarshal(msg.Payload(), &params)
	if err != nil {
		fmt.Printf("Unable to parse message %s from topic %s due to error: %+v\n", msg.Payload(), msg.Topic(), err)
	} else {
		fmt.Printf("Received message: %+v from topic: %s\n", params, msg.Topic())
	}
}

//executes when we're successfully connected to the mqtt broker
var connectHandler mqtt.OnConnectHandler = func(client mqtt.Client) {
	optionsReader := client.OptionsReader()
	fmt.Printf("Connected to the broker: %s\n", optionsReader.Servers()[0].String())
}

// executes when the mqtt connection is lost
var connectLostHandler mqtt.ConnectionLostHandler = func(client mqtt.Client, err error) {
	fmt.Printf("Connect lost: %v", err)
}

Usage example - REST API

This is an example how to use this library via Ecoflow Rest API. It requires Access Token and Secret Token which you can receive from Ecoflow.

package main

import (
	"context"
	"github.com/tess1o/go-ecoflow"
	"log/slog"
	"os"
)

func main() {
	slog.SetLogLoggerLevel(slog.LevelDebug)
	accessKey := os.Getenv("ACCESS_KEY")
	secretKey := os.Getenv("SECRET_KEY")

	if accessKey == "" || secretKey == "" {
		slog.Error("AccessKey and SecretKey are mandatory")
		return
	}

	//create new client.
	client := ecoflow.NewEcoflowClient(accessKey, secretKey)

	// creating new client with options. Current supports two options:
	// 1. custom ecoflow base url (can be used with proxies, or if they change the url)
	// 2. custom http client

	// client = ecoflow.NewEcoflowClient(accessKey, secretKey,
	//	ecoflow.WithBaseUrl("https://ecoflow-api.example.com"),
	//	ecoflow.WithHttpClient(customHttpClient()),
	//)

	//get all linked ecoflow devices. Returns SN and online status
	client.GetDeviceList(context.Background())
	// get param1 and param2 for device 
	client.GetDeviceParameters(context.Background(), "DEVICE_SERIAL_NUMBER", []string{"param1", "param2"})
	// get all parameters for device
	client.GetDeviceAllParameters(context.Background(), "DEVICE_SERIAL_NUMBER")

	ctx := context.Background()

	// get set / get functions for power stations. PRO version is not currently implemented
	ps := client.GetPowerStation("DEVICE_SERIAL_NUMBER")

	//set functions, see details in documentation to each function. There are much more functions for each type of device
	ps.SetDcSwitch(ctx, ecoflow.SettingEnabled)
	ps.SetMaxChargeSoC(ctx, 99)
	ps.SetMinDischargeSoC(ctx, 1)
	ps.SetStandByTime(ctx, 60)
	ps.SetCarStandByTime(ctx, 60)
	ps.SetPrioritizePolarCharging(ctx, ecoflow.SettingEnabled)

	//get parameters functions
	ps.GetAllParameters(ctx)
	ps.GetParameter(ctx, []string{"mppt.acStandbyMins", "mppt.dcChgCurrent"})
}

Rest API detailed description

Here you can find details how to use the library via Ecoflow REST API and the list of all functions supported for all devices.

Client

ecoflow.Client must be created using the accessToken and secretToken. It provides function to get all linked devices and generic functions to get all parameters for any Ecoflow device or set parameters for any Device. It can be useful if a new devices is introduced and not supported by this library or new APIs are introduced and not implemented by the library. Usually you don't need to use client.GetDeviceAllParameters or client.SetParameters, it's implemented in each device type.
Additionally ecoflow.Client provides functions to get API for each type of Ecoflow device (see examples below)

//get client by providing access key and secret key
client := ecoflow.NewEcoflowClient(accessKey, secretKey)

// creating new client with options. Current supports two options:
// 1. custom ecoflow base url (can be used with proxies, or if they change the url)
// 2. custom http client

// client = ecoflow.NewEcoflowClient(accessKey, secretKey,
//	ecoflow.WithBaseUrl("https://ecoflow-api.example.com"),
//	ecoflow.WithHttpClient(customHttpClient()),
//)

//get all linked ecoflow devices. Returns SN and online status
client.GetDeviceList(context.Background())
// get param1 and param2 for device 
client.GetDeviceParameters(context.Background(), "DEVICE_SERIAL_NUMBER", []string{"param1", "param2"})
// get all parameters for device
client.GetDeviceAllParameters(context.Background(), "DEVICE_SERIAL_NUMBER")

// set parameters, where params is the map[string]interface{}.
client.SetParameters(context.Background(), params)