ecoflow2mqtt 0.0.1 → 0.2.0

package/lib/items.js

@@ -0,0 +1,211 @@
+/**
+ * The item table and the small amount of state behind it.
+ *
+ * One row per published item (ROADMAP.md E-7: a new reading is a row, not code). `field` is the
+ * protobuf field of `DisplayPropertyUpload`, `precision` the decimals the device's float32 values
+ * are worth, `measurement` whether the value is a reading (Home Assistant `state_class`) rather
+ * than a setting, `category` marks the ones Home Assistant should file under diagnostics.
+ *
+ * `pv_watts` is the only computed item: the STREAM Microinverter firmware never sends
+ * `pow_get_pv_sum`, so the adapter adds the inputs up (E-4).
+ */
+
+const SOLAR = 'mdi:solar-power-variant';
+
+/** `grid_connection_sta` (R §4.5). */
+export const GRID_STATUS = {
+    0: 'invalid',
+    1: 'grid_in',
+    2: 'offline',
+    3: 'feed_grid',
+};
+
+export const ITEMS = [
+    {item: 'pv1_watts', field: 'powGetPv', label: 'PV 1', unit: 'W', deviceClass: 'power', icon: SOLAR},
+    {item: 'pv2_watts', field: 'powGetPv2', label: 'PV 2', unit: 'W', deviceClass: 'power', icon: SOLAR},
+    {
+        item: 'pv_watts',
+        field: 'powGetPvSum',
+        label: 'PV total',
+        unit: 'W',
+        deviceClass: 'power',
+        icon: SOLAR,
+        computed: true,
+    },
+    {
+        item: 'grid_watts',
+        field: 'gridConnectionPower',
+        label: 'Grid',
+        unit: 'W',
+        deviceClass: 'power',
+        icon: 'mdi:transmission-tower',
+    },
+    {
+        item: 'grid_status',
+        field: 'gridConnectionSta',
+        label: 'Grid status',
+        map: GRID_STATUS,
+        icon: 'mdi:transmission-tower-export',
+    },
+    {
+        item: 'pv1_volts',
+        field: 'plugInInfoPvVol',
+        label: 'PV 1 voltage',
+        unit: 'V',
+        deviceClass: 'voltage',
+        precision: 2,
+        category: 'diagnostic',
+    },
+    {
+        item: 'pv1_amps',
+        field: 'plugInInfoPvAmp',
+        label: 'PV 1 current',
+        unit: 'A',
+        deviceClass: 'current',
+        precision: 2,
+        category: 'diagnostic',
+    },
+    {
+        item: 'pv2_volts',
+        field: 'plugInInfoPv2Vol',
+        label: 'PV 2 voltage',
+        unit: 'V',
+        deviceClass: 'voltage',
+        precision: 2,
+        category: 'diagnostic',
+    },
+    {
+        item: 'pv2_amps',
+        field: 'plugInInfoPv2Amp',
+        label: 'PV 2 current',
+        unit: 'A',
+        deviceClass: 'current',
+        precision: 2,
+        category: 'diagnostic',
+    },
+    {
+        item: 'grid_volts',
+        field: 'gridConnectionVol',
+        label: 'Grid voltage',
+        unit: 'V',
+        deviceClass: 'voltage',
+        precision: 1,
+        category: 'diagnostic',
+    },
+    {
+        item: 'grid_amps',
+        field: 'gridConnectionAmp',
+        label: 'Grid current',
+        unit: 'A',
+        deviceClass: 'current',
+        precision: 2,
+        category: 'diagnostic',
+    },
+    {
+        item: 'grid_hz',
+        field: 'gridConnectionFreq',
+        label: 'Grid frequency',
+        unit: 'Hz',
+        deviceClass: 'frequency',
+        precision: 2,
+        category: 'diagnostic',
+    },
+    {
+        item: 'feed_limit_watts',
+        field: 'feedGridModePowLimit',
+        label: 'Feed-in limit',
+        unit: 'W',
+        deviceClass: 'power',
+        precision: 0,
+        measurement: false,
+        category: 'diagnostic',
+        icon: 'mdi:speedometer-slow',
+    },
+    {
+        item: 'feed_limit_max_watts',
+        field: 'feedGridModePowMax',
+        label: 'Feed-in limit maximum',
+        unit: 'W',
+        deviceClass: 'power',
+        precision: 0,
+        measurement: false,
+        category: 'diagnostic',
+        icon: 'mdi:speedometer',
+    },
+    {
+        item: 'wifi_rssi',
+        field: 'moduleWifiRssi',
+        label: 'Wi-Fi signal',
+        unit: 'dBm',
+        deviceClass: 'signal_strength',
+        precision: 0,
+        category: 'diagnostic',
+        icon: 'mdi:wifi',
+    },
+];
+
+/** Round to the decimals a row is worth — the device sends float32, the rest is float64 noise. */
+export function round(value, precision = 1) {
+    const factor = 10 ** precision;
+    return Math.round(value * factor) / factor;
+}
+
+/**
+ * Turns decoded `DisplayPropertyUpload` payloads into items to publish.
+ *
+ * Frames are incremental: one carries only what changed, so only the items present in it come
+ * back. `pv_watts` follows whenever an input was in the frame and both inputs are known — or
+ * directly, should a future firmware ever send `pow_get_pv_sum`.
+ *
+ * @returns {{update: (data: object) => Array<{item: string, value: number|string}>,
+ *   get: (item: string) => number|string|undefined, known: () => object}}
+ */
+export function createItems() {
+    const state = new Map();
+
+    function valueOf(row, raw) {
+        if (row.map) {
+            return row.map[raw] ?? `unknown_${raw}`;
+        }
+        return round(raw, row.precision ?? 1);
+    }
+
+    /** The PV total for this frame, or undefined when there is nothing new to say. */
+    function totalFor(data, published) {
+        if (Object.hasOwn(data, 'powGetPvSum')) {
+            return round(data.powGetPvSum);
+        }
+        const inputChanged = published.some(({item}) => item === 'pv1_watts' || item === 'pv2_watts');
+        if (inputChanged && state.has('pv1_watts') && state.has('pv2_watts')) {
+            return round(state.get('pv1_watts') + state.get('pv2_watts'));
+        }
+        return undefined;
+    }
+
+    function update(data = {}) {
+        const out = [];
+
+        // ITEMS order is publish order, and the computed total sits right behind its inputs
+        for (const row of ITEMS) {
+            const value = row.computed ? totalFor(data, out) : undefined;
+            if (row.computed) {
+                if (value === undefined) {
+                    continue;
+                }
+            } else if (!Object.hasOwn(data, row.field)) {
+                continue;
+            }
+            const published = row.computed ? value : valueOf(row, data[row.field]);
+            state.set(row.item, published);
+            out.push({item: row.item, value: published});
+        }
+
+        return out;
+    }
+
+    return {
+        update,
+        get: (item) => state.get(item),
+        known: () => Object.fromEntries(state),
+    };
+}

package/lib/mask.js

@@ -0,0 +1,40 @@
+/**
+ * Serial numbers identify a device and the account it is bound to, so they are masked everywhere
+ * they could be read by someone else — logs at info level, `<name>/info`, issue reports
+ * (ROADMAP.md E-2). The full SN appears at debug level only, and in captures it is replaced
+ * altogether (lib/capture.js).
+ */
+
+/** Prefix (device family + region) and the last two characters: `BK01Z…9K`. */
+export function maskSn(sn) {
+    if (typeof sn !== 'string' || sn.length <= 8) {
+        return sn ? '…' : '';
+    }
+    return `${sn.slice(0, 5)}…${sn.slice(-2)}`;
+}
+
+/**
+ * The placeholder captures use: the family prefix, then X for every remaining character, so the
+ * string keeps its length and frames stay byte-compatible (`BK01ZXXXXXXXXXXX`).
+ */
+export function placeholderSn(sn) {
+    if (typeof sn !== 'string' || sn.length <= 5) {
+        return 'X'.repeat(typeof sn === 'string' ? sn.length : 0);
+    }
+    return sn.slice(0, 5) + 'X'.repeat(sn.length - 5);
+}
+
+/** Model name from the SN prefix (R §1); undefined for an unknown prefix. */
+export function modelOf(sn) {
+    if (typeof sn !== 'string') {
+        return undefined;
+    }
+    const prefix = sn.slice(0, 4).toUpperCase();
+    if (prefix === 'BK01' || prefix === 'BK02' || prefix === 'N011') {
+        return 'STREAM Microinverter';
+    }
+    if (prefix === 'HW51') {
+        return 'PowerStream';
+    }
+    return undefined;
+}

package/lib/proto/bk_series.proto

@@ -0,0 +1,50 @@
+// EcoFlow STREAM family (BK series: STREAM Microinverter BK01/BK02/N011, STREAM AC/Ultra/Pro).
+//
+// Field numbers reverse-engineered by the community; this file follows
+// tolwi/hassio-ecoflow-cloud (Apache License 2.0) `ef_bk_series.proto` and
+// rabits/ha-ef-ble (Apache License 2.0) `bk_series.proto`. Only the subset ecoflow2mqtt decodes
+// today is declared — an unknown field is skipped by protobuf, so adding a row later is enough.
+//
+// All values are floats in their natural unit (W, V, A, Hz) — no scaling. Every field is
+// `optional`: DisplayPropertyUpload is incremental (only changed fields, every ~2 s), the full
+// frame (~31 fields) arrives every ~120 s and as the reply to a property get.
+//
+// Observed on a STREAM Microinverter (product_id 17409) on 2026-08-28: pow_get_pv (361) and
+// pow_get_pv2 (70) are sent, pow_get_pv_sum (517) is never sent — the adapter computes the total
+// (ROADMAP.md E-4). A full frame carries 31 fields; the ones still unnamed are logged at debug
+// (133 = 200, 135, 371 = 31..32, 617, 618 = 1, 638, 729-734 with 731 = 10001, and a few empty
+// byte fields). 371 and 730 look like temperatures in °C but nothing confirms that yet, so they
+// stay out of the item table rather than being guessed at (ROADMAP.md OQ-E7).
+
+syntax = "proto3";
+
+message DisplayPropertyUpload {
+    optional float pow_get_pv2 = 70; // PV input 2 power, W
+    optional float plug_in_info_pv2_amp = 71; // PV input 2 current, A
+    optional float pow_get_pv = 361; // PV input 1 power, W
+    optional float plug_in_info_pv_vol = 380; // PV input 1 voltage, V
+    optional float plug_in_info_pv_amp = 381; // PV input 1 current, A
+    optional float plug_in_info_pv2_vol = 442; // PV input 2 voltage, V
+    optional float pow_get_pv_sum = 517; // total PV power, W (not sent by the firmware seen so far)
+    optional uint32 feed_grid_mode_pow_limit = 521; // feed-in limit, W
+    optional float module_wifi_rssi = 602; // wifi signal, dBm
+    optional float grid_connection_vol = 613; // grid voltage, V
+    optional float grid_connection_amp = 614; // grid current, A
+    optional float grid_connection_freq = 615; // grid frequency, Hz
+    optional float grid_connection_power = 616; // power fed into the grid, W
+    optional uint32 grid_connection_sta = 619; // 0 invalid, 1 grid in, 2 offline, 3 feed grid
+    optional uint32 feed_grid_mode_pow_max = 727; // highest feed-in limit the device accepts, W
+}
+
+// cmd_func 254 / cmd_id 22: the upload periods the device runs with (ms). No temperatures, so it
+// contributes no items — it is decoded to make the cadence visible at debug level.
+message RuntimePropertyUpload {
+    optional uint32 display_property_full_upload_period = 293; // 120000 ms observed
+    optional uint32 display_property_incremental_upload_period = 294; // 2000 ms observed
+    // 295 (300000) and 296 (60000) are the same pair for the runtime properties [unverified]
+}
+
+// app -> device "activate stream": cmd_func 96, cmd_id 97. Off by default (ROADMAP.md E-9).
+message EnergyStreamSwitch {
+    optional int32 sw = 1;
+}

package/lib/proto/decode.js

@@ -0,0 +1,121 @@
+/**
+ * Protobuf layer: MQTT payload -> frames.
+ *
+ * A payload is a `HeaderMessage` with one or more `Header`s; each header carries a `pdata` blob
+ * that belongs to the message identified by `(cmd_func, cmd_id)`. STREAM devices obfuscate pdata
+ * by XORing every byte with `seq & 0xFF` (`enc_type == 1`, device -> app direction, `src != 32`).
+ *
+ * The `.proto` files are vendored text and parsed at runtime (ROADMAP.md E-7): a new firmware
+ * field is a line in `bk_series.proto`, not a code change. Unknown `(cmd_func, cmd_id)` pairs are
+ * returned as frames without `data` so the caller can log them once and carry on.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import protobuf from 'protobufjs';
+
+const dir = path.dirname(fileURLToPath(import.meta.url));
+
+const root = new protobuf.Root();
+for (const file of ['header.proto', 'bk_series.proto']) {
+    protobuf.parse(fs.readFileSync(path.join(dir, file), 'utf8'), root);
+}
+
+export const HeaderMessage = root.lookupType('HeaderMessage');
+export const DisplayPropertyUpload = root.lookupType('DisplayPropertyUpload');
+export const RuntimePropertyUpload = root.lookupType('RuntimePropertyUpload');
+export const EnergyStreamSwitch = root.lookupType('EnergyStreamSwitch');
+
+/** `${cmd_func}/${cmd_id}` -> message. Everything else is returned undecoded. */
+export const MESSAGES = {
+    '254/21': {name: 'DisplayPropertyUpload', type: DisplayPropertyUpload, items: true},
+    '254/22': {name: 'RuntimePropertyUpload', type: RuntimePropertyUpload},
+};
+
+/** Names of the frames we know of but do not decode — for readable debug logs (R §4.5). */
+export const FRAME_NAMES = {
+    '254/17': 'ConfigWrite',
+    '254/18': 'ConfigWriteAck',
+    '254/19': 'ConfigRead',
+    '254/20': 'ConfigReadAck',
+    '254/21': 'DisplayPropertyUpload',
+    '254/22': 'RuntimePropertyUpload',
+    '254/32': 'BatchEnergyTotalReport',
+    '32/2': 'CMSHeartBeatReport',
+    '32/50': 'BMSHeartBeatReport',
+    '96/97': 'EnergyStreamSwitch',
+};
+
+/**
+ * Undo the XOR obfuscation. STREAM devices XOR every pdata byte with the low byte of `seq`;
+ * frames the app sends (`src == 32`) and replies with `enc_type == 0` are plain.
+ *
+ * @param {Buffer|Uint8Array} pdata
+ * @param {{encType?: number, src?: number, seq?: number}} header
+ * @returns {Buffer} a new buffer, never the input
+ */
+export function deobfuscate(pdata, {encType = 0, src = 0, seq = 0} = {}) {
+    const buffer = Buffer.from(pdata ?? []);
+    if (encType !== 1 || src === 32) {
+        return buffer;
+    }
+    const key = seq & 0xff;
+    for (const [index, byte] of buffer.entries()) {
+        buffer[index] = byte ^ key;
+    }
+    return buffer;
+}
+
+/**
+ * Decode one MQTT payload.
+ *
+ * Throws only when the outer envelope is not a `HeaderMessage` (a JSON ping, a truncated frame) —
+ * a payload whose inner pdata is garbled yields a frame with `error` set, so one bad message
+ * cannot take the stream down.
+ *
+ * @param {Buffer} payload
+ * @returns {Array<{cmdFunc: number, cmdId: number, key: string, name: string, seq: number,
+ *   src: number, dest: number, encType: number, productId: number, version: number,
+ *   deviceSn: string, moduleSn: string, code: string, pdata: Buffer, data: object|null,
+ *   items: boolean, error: string|null}>}
+ */
+export function decodeFrames(payload) {
+    const message = HeaderMessage.decode(payload);
+    return (message.header ?? []).map((header) => {
+        const cmdFunc = header.cmdFunc ?? 0;
+        const cmdId = header.cmdId ?? 0;
+        const key = `${cmdFunc}/${cmdId}`;
+        const pdata = deobfuscate(header.pdata, header);
+        const frame = {
+            cmdFunc,
+            cmdId,
+            key,
+            name: FRAME_NAMES[key] ?? `unknown ${key}`,
+            seq: header.seq ?? 0,
+            src: header.src ?? 0,
+            dest: header.dest ?? 0,
+            encType: header.encType ?? 0,
+            productId: header.productId ?? 0,
+            version: header.version ?? 0,
+            deviceSn: header.deviceSn ?? '',
+            moduleSn: header.moduleSn ?? '',
+            code: header.code ?? '',
+            pdata,
+            data: null,
+            items: false,
+            error: null,
+        };
+        const known = MESSAGES[key];
+        if (!known || pdata.length === 0) {
+            return frame;
+        }
+        try {
+            frame.data = known.type.toObject(known.type.decode(pdata));
+            frame.items = Boolean(known.items);
+        } catch (error) {
+            frame.error = error.message;
+        }
+        return frame;
+    });
+}

package/lib/proto/encode.js

@@ -0,0 +1,57 @@
+/**
+ * The two frames ecoflow2mqtt sends. Both are what the EcoFlow app sends, replayed byte for byte
+ * (R §4.4, §4.5) — 0.1.0 has no `set` items, so nothing here changes the device's configuration.
+ */
+
+import {HeaderMessage, EnergyStreamSwitch} from './decode.js';
+
+/** protobuf seq is a uint32; the app uses a millisecond timestamp. */
+function nextSeq(now = Date.now()) {
+    return now % 0xffffffff;
+}
+
+/**
+ * "Give me everything": an empty header `src 32 -> dest 32`. The device answers with a full
+ * DisplayPropertyUpload on `.../thing/property/get_reply`. Not a keep-alive (ROADMAP.md E-9), a
+ * full-frame refresh.
+ *
+ * @returns {Buffer}
+ */
+export function encodeGet({seq = nextSeq()} = {}) {
+    return Buffer.from(HeaderMessage.encode({header: [{src: 32, dest: 32, seq, from: 'ios'}]}).finish());
+}
+
+/**
+ * `EnergyStreamSwitch {1: 1}` (cmd_func 96 / cmd_id 97) — the app's "activate stream" frame for
+ * the STREAM family. Off by default (`--stream-interval 0`); kept for the case that the cloud
+ * starts throttling a passive subscriber (OQ-E1).
+ *
+ * @param {{sn: string, seq?: number}} options
+ * @returns {Buffer}
+ */
+export function encodeEnergyStreamSwitch({sn, seq = nextSeq()}) {
+    const pdata = EnergyStreamSwitch.encode({sw: 1}).finish();
+    return Buffer.from(
+        HeaderMessage.encode({
+            header: [
+                {
+                    pdata,
+                    src: 32,
+                    dest: 53,
+                    dSrc: 1,
+                    dDest: 1,
+                    checkType: 3,
+                    cmdFunc: 96,
+                    cmdId: 97,
+                    dataLen: pdata.length,
+                    needAck: 1,
+                    seq,
+                    version: 19,
+                    payloadVer: 1,
+                    from: 'ios',
+                    deviceSn: sn,
+                },
+            ],
+        }).finish(),
+    );
+}

package/lib/proto/header.proto

@@ -0,0 +1,43 @@
+// EcoFlow protobuf envelope, used by every protobuf device (PowerStream, Smart Plug, STREAM
+// family). One MQTT message may stack several Header entries.
+//
+// Field numbers reverse-engineered by the community; this file follows
+// tolwi/hassio-ecoflow-cloud (Apache License 2.0)
+// custom_components/ecoflow_cloud/devices/internal/proto/*.proto
+// and rabits/ha-ef-ble (Apache License 2.0) eflib/pb/*.proto.
+//
+// pdata is the payload of the (cmd_func, cmd_id) message; when enc_type == 1 and src != 32 every
+// byte is XORed with (seq & 0xFF) — see lib/proto/decode.js.
+
+syntax = "proto3";
+
+message Header {
+    bytes pdata = 1;
+    int32 src = 2;
+    int32 dest = 3;
+    int32 d_src = 4;
+    int32 d_dest = 5;
+    int32 enc_type = 6;
+    int32 check_type = 7;
+    int32 cmd_func = 8;
+    int32 cmd_id = 9;
+    int32 data_len = 10;
+    int32 need_ack = 11;
+    int32 is_ack = 12;
+    uint32 seq = 14;
+    int32 product_id = 15;
+    int32 version = 16;
+    int32 payload_ver = 17;
+    int32 time_snap = 18;
+    int32 is_rw_cmd = 19;
+    int32 is_queue = 20;
+    int32 ack_type = 21;
+    string code = 22;
+    string from = 23;
+    string module_sn = 24;
+    string device_sn = 25;
+}
+
+message HeaderMessage {
+    repeated Header header = 1;
+}

package/package.json

@@ -1,20 +1,28 @@
 {
   "name": "ecoflow2mqtt",
-  "version": "0.0.1",
-  "description": "Interface between EcoFlow PowerStream / STREAM micro-inverters and MQTT, with Home Assistant discovery (placeholder release, work in progress)",
+  "version": "0.2.0",
+  "description": "Interface between EcoFlow STREAM / PowerStream micro-inverters and MQTT",
   "type": "module",
   "main": "index.js",
+  "preferGlobal": true,
   "bin": {
     "ecoflow2mqtt": "index.js"
   },
   "files": [
-    "index.js"
+    "index.js",
+    "config.js",
+    "lib/"
   ],
   "engines": {
     "node": "^20.19 || ^22.12 || >=24"
   },
   "scripts": {
-    "start": "node index.js"
+    "start": "node index.js",
+    "lint": "eslint . && prettier --check .",
+    "format": "prettier --write . && eslint --fix .",
+    "test": "node --test",
+    "test:watch": "node --test --watch",
+    "deploy": "bash deploy.sh"
   },
   "repository": {
     "type": "git",
@@ -24,6 +32,7 @@
     "mqtt",
     "smarthome",
     "mqtt-smarthome",
+    "mqtt-interfaces",
     "home-automation",
     "home-assistant",
     "ecoflow",
@@ -38,5 +47,26 @@
   "bugs": {
     "url": "https://github.com/hobbyquaker/ecoflow2mqtt/issues"
   },
-  "homepage": "https://github.com/hobbyquaker/ecoflow2mqtt"
+  "homepage": "https://github.com/hobbyquaker/ecoflow2mqtt",
+  "mqttInterfaces": {
+    "spec": "2.0",
+    "envPrefix": "ECOFLOW2MQTT",
+    "needs": [
+      "network",
+      "cloud"
+    ],
+    "serviceExtra": []
+  },
+  "dependencies": {
+    "mqtt": "^5.10.0",
+    "mqtt-interfaces-core": "^0.8.0",
+    "protobufjs": "^7.4.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.0.0",
+    "eslint": "^9.0.0",
+    "eslint-config-prettier": "^10.0.0",
+    "globals": "^16.0.0",
+    "prettier": "^3.0.0"
+  }
 }