powerocean

package module
v0.0.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 9, 2026 License: MIT Imports: 20 Imported by: 0

README

ecoflow-powerocean-plus-client

Unofficial Go client for the EcoFlow Power Ocean Plus home battery (product type 87, serial prefix R37).

It connects to the EcoFlow cloud MQTT API and live-streams energy telemetry: battery SOC and power, PV (per-string MPPT + PV inverter), house load, and grid power — the same values as the official app's dashboard, at the same cadence. Primary use is as a third-party library; a console client is included.

Not affiliated with, endorsed by, or supported by EcoFlow. Use at your own risk.

Install

go get github.com/mpollmeier/ecoflow-powerocean-plus-client

Library usage

The package name is powerocean. Create a client with powerocean.New, then run it with a context — Run blocks and delivers a Report to your callback until the context is cancelled:

package main

import (
	"context"
	"fmt"
	"os/signal"
	"syscall"

	powerocean "github.com/mpollmeier/ecoflow-powerocean-plus-client"
)

func main() {
	client, err := powerocean.New(powerocean.Config{
		Email:    "you@example.com",
		Password: "your password", // sent as base64(UTF-8), like the official app
		DeviceSN: "R37…",          // device serial
		// StreamSwitch: true,    // opens the telemetry stream — see the note below; default off
		OnReport: func(r powerocean.Report) { fmt.Print(r) },
	})
	if err != nil {
		panic(err)
	}

	ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT)
	defer stop()
	if err := client.Run(ctx); err != nil {
		panic(err)
	}
}

Report carries battery SOC (system + per-pack), battery/solar/load/grid watts, and a Derived flag (see wire-format notes below). The zero config is strictly read-only; StreamSwitch: true opts into the stream keepalive write (what that write does).

Setting the backup reserve

The backup reserve (the discharge floor the German app labels "Backup-Reserve") is a one-shot write, not part of the streaming loop:

client, err := powerocean.New(powerocean.Config{
	Email:    "you@example.com",
	Password: "your password",
	DeviceSN: "R37…",
	OnReport: func(r powerocean.Report) { fmt.Print(r) },
})
if err != nil {
	panic(err)
}

ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT)
defer stop()

// Set the backup reserve to 30 % and wait for the device's acknowledgement.
if err := client.SetBackupReserve(ctx, 30); err != nil {
	panic(err)
}

SetBackupReserve authenticates, connects, publishes one SYS_BAT_CHG_DSG_SET (cmd 112, field sys_bat_dsg_down_limie), waits briefly for the acknowledgement, and disconnects. The value is also surfaced read-only during streaming: Report.BackupReserve, Report.ChargeLimit and Report.BackupRatio (see what that write does).

Console client

export ECOFLOW_EMAIL='you@example.com'
export ECOFLOW_PASSWORD='your password'
export ECOFLOW_DEVICE_SN='R37…'           # device serial

go run ./cmd/ecoflow-powerocean-plus-client

To set the backup reserve (the discharge floor the German app labels "Backup-Reserve") and exit, pass the value as a flag:

go run ./cmd/ecoflow-powerocean-plus-client --set-backup-reserve=30

Example output (updated every few seconds while the stream switch is on):

[22:54:13] PowerOcean Plus telemetry
  Battery SOC    : 73%  (packs 76% / 74%)
  Battery        : -521 W (discharging)
  Solar (MPPT)   : 0 W
  Solar (PV1-3)  : 0 / 0 / 0 W
  Solar (PV inv) : 0 W
  Load           : 519 W
  Grid           : -2 W (exporting)

Sign conventions: battery > 0 = charging, < 0 = discharging; grid > 0 = importing, < 0 = exporting. System SOC is capacity-weighted from the individual battery packs; a () suffix shows each pack.

Environment variables
Variable Meaning
ECOFLOW_EMAIL, ECOFLOW_PASSWORD, ECOFLOW_DEVICE_SN required credentials and target device
--set-backup-reserve=<0-100> one-shot write: set the battery's backup reserve and exit, instead of streaming (library equivalent: SetBackupReserve)
ECOFLOW_STREAM=0 disable the stream-switch write (strictly read-only, slower cadence; library equivalent: leave Config.StreamSwitch false)
ECOFLOW_DEBUG=1 raw payload hex dumps and request sniff logs

Protocol summary

Details and provenance: docs/protocol.md (wire schema and transport findings) and docs/auth.md (login → MQTT credentials). Schemas live in proto/, Go bindings in pb/.

Connection flow
  1. Login — POST https://api.ecoflow.com/auth/login (email + base64 of the UTF-8 password) → bearer token + user ID.
  2. MQTT credentials — GET /iot-auth/app/certification?userId=… → broker host/port and MQTT username/password (despite the name, no TLS client certificates are involved).
  3. Connect — TLS MQTT (mqtts://broker:8883) with those credentials, client ID ANDROID_<uuid>_<userId>.
  4. Subscribe to the device's topics, all under the user's account:
    • /app/device/property/{sn} — device → us telemetry pushes
    • /app/{userId}/{sn}/thing/property/get_reply — replies to get requests
    • (the get/set and biz/data/request request topics are also subscribed, but only to log echoes in debug mode)
Messages we send (all on the two thing/property topics)
What Topic When Effect
Fetch-all Send_Header_Msg{src:32, dest:32, from:"Android"} (a get, no cmd) …/thing/property/get once at connect / reconnect device replies on get_reply with its cached snapshot (seed data)
Stream switch ENERGY_STREAM_SWITCH=1 (cmd 97 set, pdata=0801) …/thing/property/set every 10 s keepalive (see warning below) device accelerates EnergyStreamReport pushes from ~30-60 s to a few seconds
Backup reserve SYS_BAT_CHG_DSG_SET (cmd 112 set, sys_bat_dsg_down_limie=%) …/thing/property/set only with --set-backup-reserve (or SetBackupReserve) changes the battery's backup-reserve level (a real battery-setting write)

That is the complete outbound surface — nothing else is ever published.

Messages we receive
Message cmd Cadence Content
EnergyStreamReport 96/33 few seconds with stream switch, ~30-60 s without load, grid, MPPT/PV, battery W, SOC
HeartbeatReport 96/1 ~60 s live powers, grid meter (per phase), per-string PV
BpHeartbeatReport 96/7 ~40-60 s bursts per-pack SOC, power, capacity, serial
EnergyStreamDetail 96/34 ~10 min timestamped history samples of the same telemetry
Wire format

Everything rides MQTT as Common.Send_Header_Msg protobuf — a list of Header{pdata, src, dest, cmd_func, cmd_id, enc_type, seq, …}, where pdata is the command-specific protobuf (enc_type=1 payloads are XOR-obfuscated with (byte)seq and decoded transparently). Dispatch is by cmd_func/cmd_id (EMS = 96). Note that EnergyStreamReports arriving in get_reply are the device's cached snapshot — the client ignores those and uses the live push sources above; system SOC is capacity-weighted from the individual packs, and load is derived as solar + grid − battery.

Development

go test ./...        # includes byte-level tests against captured wire frames
go vet ./...

Regenerate Go bindings after editing protos:

protoc -I . --go_out=. --go_opt=module=github.com/mpollmeier/ecoflow-powerocean-plus-client \
  --go_opt=Mproto/Common.proto=github.com/mpollmeier/ecoflow-powerocean-plus-client/pb \
  --go_opt=Mproto/jt_s1_cmd.proto=github.com/mpollmeier/ecoflow-powerocean-plus-client/pb \
  --go_opt=Mproto/jt_s1_sys.proto=github.com/mpollmeier/ecoflow-powerocean-plus-client/pb \
  proto/Common.proto proto/jt_s1_cmd.proto proto/jt_s1_sys.proto

Note: the client's write commands

The client is read-only by default. It can perform exactly two writes, both strictly opt-in:

  1. Stream switch (Config.StreamSwitch: true, the console client's default): it publishes ENERGY_STREAM_SWITCH = 1 (a set command) every 10 seconds. This is the same command the official app sends whenever its dashboard is open: it opens the telemetry reporting stream, which makes the device push EnergyStreamReport every few seconds instead of its default ~30–60 s cadence. It does not touch any power-flow, charge, or inverter setting — only how often the device reports.

  2. Backup reserve (SetBackupReserve, console flag --set-backup-reserve=<0-100>): publishes one SYS_BAT_CHG_DSG_SET (cmd 112) with sys_bat_dsg_down_limie set (the device's discharge floor, labelled "Backup-Reserve" in the German app), then exits. This is the same command the app's battery settings send and it does change a battery setting. It is never sent unless you explicitly invoke it.

  • Leave StreamSwitch false (the library default) and never call SetBackupReserve for a strictly read-only client: it then only subscribes and sends a single read-only "fetch all" get at connect time (plus one per reconnect), and telemetry arrives at the device's slower natural cadence. Console equivalent: ECOFLOW_STREAM=0.
  • No other write commands are ever sent (no charge-limit changes, no work-mode changes, no reset — nothing else).

This project was created by independent reverse engineering of the official Android app for interoperability purposes, which is a widely recognised legitimate practice (e.g. EU Software Directive Art. 6; US case law on reverse engineering for interoperability). No copyrighted material from the app is included in this repository — no app code, no decompiled sources, no APK contents. Everything here is independently written. Protocol field names and wire schemas are functional interface specifications.

Be aware that the app's terms of service likely prohibit reverse engineering; using this software may be against those terms. That is your decision to make.

License

MIT

Documentation

Overview

Package powerocean is a client for the EcoFlow Power Ocean (Plus) home battery, speaking the EcoFlow cloud MQTT protocol. It streams live energy telemetry — battery state of charge and power, per-string PV, house load, and grid power — at the same cadence as the official app.

It was created by independent reverse engineering of the official Android app for interoperability purposes. No copyrighted material from the app is included. Be aware that the app's terms of service likely prohibit reverse engineering; using this software may be against those terms.

The zero-config stance is read-only: with Config.StreamSwitch unset the client only subscribes and sends one read-only fetch at connect, and telemetry arrives at the device's natural push cadence (~30-60 s). Setting StreamSwitch enables the write that opens the telemetry reporting stream (ENERGY_STREAM_SWITCH keepalive, cmd 97 = 1); SetBackupReserve is the other, one-shot write that changes a battery setting (cmd 112). Both are opt-in.

Basic use:

client, err := powerocean.New(powerocean.Config{
	Email:    "...",
	Password: "...",
	DeviceSN: "R37…",
	OnReport: func(r powerocean.Report) { fmt.Println(r) },
})
if err != nil {
	return err
}
return client.Run(ctx) // blocks until ctx is cancelled

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client is a live telemetry connection to one device. Create with New, run with Run.

func New

func New(cfg Config) (*Client, error)

New validates cfg and returns a ready Client. It performs no I/O; the connection is made in Run.

func (*Client) Run

func (c *Client) Run(ctx context.Context) error

Run connects and delivers telemetry reports through Config.OnReport until ctx is cancelled, then disconnects cleanly and returns nil.

Outbound traffic is limited to: one fetch-all *get* per (re)connect that seeds state from the device's cache, and — only if Config.StreamSwitch is set — the energy-stream switch keepalive.

func (*Client) SetBackupReserve

func (c *Client) SetBackupReserve(ctx context.Context, percent uint32) error

SetBackupReserve sets the battery's backup reserve — the minimum state of charge the battery discharges to in normal operation (kept for backup power) — to percent (0–100). In the German app this setting is labelled "Backup-Reserve".

It authenticates, connects, and publishes one SYS_BAT_CHG_DSG_SET command (cmd 112, field sys_bat_dsg_down_limie) on .../thing/property/set, the same command the online app's battery settings send. It waits briefly for the device's acknowledgement and disconnects. This is a real write: it changes a battery setting, so it is only ever sent when the caller explicitly invokes this method (the console client does so via --set-backup-reserve).

type Config

type Config struct {
	// Email, Password and DeviceSN are required. The password is sent to the
	// EcoFlow API as base64 of its UTF-8 bytes, exactly like the official app.
	Email    string
	Password string
	DeviceSN string

	// StreamSwitch enables the energy-stream keepalive write: the
	// ENERGY_STREAM_SWITCH (cmd 97 = 1, re-sent every 10 s), the same command
	// the official app sends while its dashboard is open. It opens the
	// telemetry *reporting stream* — the device pushes EnergyStreamReport
	// every few seconds instead of every ~30-60 s. It does NOT touch any
	// power-flow, charge, or inverter setting. (The other write is
	// SetBackupReserve.)
	//
	// Leave false for a strictly read-only client (slower cadence).
	StreamSwitch bool

	// OnReport is called with each coalesced telemetry update (reports within
	// a short window are merged into one). Required.
	OnReport func(Report)

	// Logger receives diagnostics. Defaults to slog.Default().
	Logger *slog.Logger

	// DebugLog additionally logs raw MQTT payload hex dumps. Verbose.
	DebugLog bool
}

Config configures a Client.

type Pack

type Pack struct {
	SN      string
	SOC     uint32  // displayed state of charge, %
	RealSOC float32 // coulomb-counted SOC, %
	PowerW  float32 // + charging, - discharging
	FullCap uint32  // full capacity (device units)
}

Pack is one battery pack's latest live snapshot.

type Report

type Report struct {
	Time time.Time

	BatterySOC uint32 // system SOC, capacity-weighted across packs
	HasSOC     bool   // false while no pack has reported yet
	Packs      []Pack // per-pack detail, sorted by SN

	BatteryW     float32
	SolarMPPT    float32 // total solar (MPPT + PV inverter)
	SolarPV1     float32
	SolarPV2     float32
	SolarPV3     float32
	SolarPVInv   float32
	SolarOtherPV float32
	LoadW        float32
	GridW        float32

	// Battery setters, reported by the device in EmsChangeReport (cmd 8).
	// HasLimits is true once these have been received and reflect the current
	// device settings.
	//
	//	BackupReserve = sys_bat_dsg_down_limit — the discharge floor, labelled
	//	                "Backup-Reserve" in the German app.
	//	ChargeLimit   = sys_bat_chg_up_limit — "Ladegrenze".
	//	BackupRatio   = sys_bat_backup_ratio — a separate (AI-mode) ratio.
	BackupReserve uint32
	ChargeLimit   uint32
	BackupRatio   uint32
	HasLimits     bool

	// Derived is true when the report was assembled from live heartbeats and
	// pack updates rather than a full system sample pushed by the device.
	// Derived reports compute LoadW from the power balance
	// load = solar + grid - battery.
	Derived bool
}

Report is one telemetry snapshot of the whole system.

Sign conventions (verified against live power balance on the JtS1Sys driver): GridW is positive when importing, negative when exporting; BatteryW is positive when charging, negative when discharging. (The other EcoFlow driver's JSON protocol uses the opposite battery sign.)

func (Report) String

func (r Report) String() string

String renders the report like the app dashboard: battery, solar, load, grid.

Directories

Path Synopsis
cmd
ecoflow-powerocean-plus-client command
Command ecoflow-powerocean-plus-client streams live energy telemetry from an EcoFlow Power Ocean Plus battery to the console, or — with --set-backup-reserve=<0-100> — writes the battery's backup-reserve level once and exits.
Command ecoflow-powerocean-plus-client streams live energy telemetry from an EcoFlow Power Ocean Plus battery to the console, or — with --set-backup-reserve=<0-100> — writes the battery's backup-reserve level once and exits.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL