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 ¶
New validates cfg and returns a ready Client. It performs no I/O; the connection is made in Run.
func (*Client) Run ¶
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 ¶
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.)
Source Files
¶
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. |