ecoflow2mqtt 0.0.1 → 0.2.0

package/lib/app/mqtt.js

@@ -0,0 +1,267 @@
+/**
+ * Step 3-6 of the app path (ROADMAP.md §2): the client on EcoFlow's own MQTT broker.
+ *
+ * It authenticates, connects with the client id the broker expects (`ANDROID_<UUID>_<userId>`,
+ * the UUID persisted so reconnects do not pile up sessions — E-6), subscribes to the device's
+ * property topic and emits decoded frames. A protobuf get every `--poll` seconds pulls a full
+ * frame; it is a refresh, not a keep-alive (E-9).
+ *
+ * An unreachable cloud is normal operation for a daemon: everything retries with backoff, and
+ * credentials are never discarded because of an error (R §4.1).
+ */
+
+import {EventEmitter} from 'node:events';
+import mqtt from 'mqtt';
+import {decodeFrames} from '../proto/decode.js';
+import {encodeGet, encodeEnergyStreamSwitch} from '../proto/encode.js';
+import {authenticate as defaultAuthenticate} from './login.js';
+import {maskSn} from '../mask.js';
+
+const MIN_BACKOFF = 10_000;
+const MAX_BACKOFF = 300_000;
+/** connack return codes that mean "these credentials are not (or no longer) valid" */
+const AUTH_ERRORS = new Set([4, 5]);
+
+export class EcoflowClient extends EventEmitter {
+    /**
+     * @param {object} options
+     * @param {object} options.config parsed config (email, password, sn, region, poll, ...)
+     * @param {object} options.log core logger
+     * @param {string} options.uuid stable UUID for the client id (lib/clientid.js)
+     * @param {Function} [options.authenticate] injected for tests
+     * @param {Function} [options.connect] injected for tests (mqtt.connect)
+     */
+    constructor({config, log, uuid, authenticate = defaultAuthenticate, connect = mqtt.connect}) {
+        super();
+        this.config = config;
+        this.log = log;
+        this.uuid = uuid;
+        this.authenticate = authenticate;
+        this.connectImpl = connect;
+
+        this.client = null;
+        this.userId = null;
+        this.broker = null;
+        this.stopped = false;
+        this.backoff = MIN_BACKOFF;
+        this.timers = [];
+        this.retryTimer = null;
+        this.lastAuthError = null;
+    }
+
+    get connected() {
+        return Boolean(this.client?.connected);
+    }
+
+    /** Topics of this instance's device; the SN is masked in everything we log. */
+    topics() {
+        const {sn} = this.config;
+        return {
+            property: `/app/device/property/${sn}`,
+            get: `/app/${this.userId}/${sn}/thing/property/get`,
+            getReply: `/app/${this.userId}/${sn}/thing/property/get_reply`,
+            set: `/app/${this.userId}/${sn}/thing/property/set`,
+            setReply: `/app/${this.userId}/${sn}/thing/property/set_reply`,
+        };
+    }
+
+    start() {
+        this.stopped = false;
+        return this.#run();
+    }
+
+    async stop() {
+        this.stopped = true;
+        this.#clearTimers();
+        clearTimeout(this.retryTimer);
+        const {client} = this;
+        this.client = null;
+        if (client) {
+            await new Promise((resolve) => client.end(false, {}, resolve));
+        }
+    }
+
+    /** Authenticate, then connect. Any failure schedules a retry — the daemon never gives up. */
+    async #run() {
+        if (this.stopped) {
+            return;
+        }
+        try {
+            const {userId, broker, apiHost} = await this.authenticate(this.config);
+            this.userId = userId;
+            this.broker = broker;
+            this.lastAuthError = null;
+            this.log.info(`ecoflow api ${apiHost}: logged in, broker ${broker.host}:${broker.port}`);
+            this.#connect();
+        } catch (error) {
+            this.#authFailed(error);
+        }
+    }
+
+    /**
+     * Log an authentication failure once at error level, repeats at debug — a wrong password and
+     * an EcoFlow outage are indistinguishable here (R §4.1), so this never stops the adapter.
+     */
+    #authFailed(error) {
+        const message = `ecoflow login failed: ${error.message} (${error.code ?? 'no code'})`;
+        if (this.lastAuthError === message) {
+            this.log.debug(message);
+        } else {
+            this.log.error(`${message} — check --email / --password / --region, or the cloud is down`);
+            this.lastAuthError = message;
+        }
+        this.#retry();
+    }
+
+    #retry() {
+        if (this.stopped) {
+            return;
+        }
+        const delay = this.backoff;
+        this.backoff = Math.min(this.backoff * 2, MAX_BACKOFF);
+        this.log.debug(`ecoflow: retrying in ${Math.round(delay / 1000)} s`);
+        clearTimeout(this.retryTimer);
+        this.retryTimer = setTimeout(() => this.#run(), delay);
+        this.retryTimer.unref?.();
+    }
+
+    #connect() {
+        const {broker, config} = this;
+        const url = `${broker.protocol}://${broker.host}:${broker.port}`;
+        const clientId = `ANDROID_${this.uuid}_${this.userId}`;
+        this.log.debug(`ecoflow > connecting to ${url} as ${clientId}`);
+
+        const client = this.connectImpl(url, {
+            clientId,
+            username: broker.username,
+            password: broker.password,
+            protocolVersion: 4,
+            clean: true,
+            keepalive: 30,
+            reconnectPeriod: MIN_BACKOFF,
+            connectTimeout: 30_000,
+        });
+        this.client = client;
+
+        client.on('connect', () => {
+            this.backoff = MIN_BACKOFF;
+            this.log.info(`ecoflow broker ${broker.host} connected, device ${maskSn(config.sn)}`);
+            this.#subscribe();
+            this.#startTimers();
+            this.emit('connect');
+        });
+
+        client.on('message', (topic, payload) => this.#onMessage(topic, payload));
+
+        client.on('error', (error) => {
+            const code = error?.code;
+            this.log.warn(`ecoflow broker error: ${error.message}`);
+            if (AUTH_ERRORS.has(code)) {
+                // credentials rejected: certification again, then keep trying
+                this.log.warn('ecoflow broker rejected the credentials, re-authenticating');
+                this.#restart();
+            }
+        });
+
+        client.on('close', () => {
+            this.#clearTimers();
+            this.log.debug('ecoflow broker connection closed');
+            this.emit('close');
+        });
+
+        client.on('reconnect', () => this.log.debug('ecoflow broker reconnecting'));
+    }
+
+    /** Tear the client down and start over at step 1 (login), after a backoff. */
+    #restart() {
+        const {client} = this;
+        this.client = null;
+        this.#clearTimers();
+        client?.end(true);
+        this.#retry();
+    }
+
+    #subscribe() {
+        const topics = this.topics();
+        for (const topic of [topics.property, topics.getReply]) {
+            this.client.subscribe(topic, {qos: 1}, (error) => {
+                if (error) {
+                    this.log.warn(`ecoflow subscribe ${this.#safe(topic)} failed: ${error.message}`);
+                } else {
+                    this.log.debug(`ecoflow < subscribed ${this.#safe(topic)}`);
+                }
+            });
+        }
+    }
+
+    #startTimers() {
+        this.#clearTimers();
+        const {poll, streamInterval} = this.config;
+        if (poll > 0) {
+            this.requestFullFrame();
+            this.timers.push(setInterval(() => this.requestFullFrame(), poll * 1000));
+        }
+        if (streamInterval > 0) {
+            this.activateStream();
+            this.timers.push(setInterval(() => this.activateStream(), streamInterval * 1000));
+        }
+        for (const timer of this.timers) {
+            timer.unref?.();
+        }
+    }
+
+    #clearTimers() {
+        for (const timer of this.timers) {
+            clearInterval(timer);
+        }
+        this.timers = [];
+    }
+
+    /** Ask for a full DisplayPropertyUpload (arrives on the get_reply topic). */
+    requestFullFrame() {
+        if (!this.connected) {
+            return;
+        }
+        const topic = this.topics().get;
+        this.log.debug(`ecoflow > get ${this.#safe(topic)}`);
+        this.client.publish(topic, encodeGet(), {qos: 1}, (error) => {
+            if (error) {
+                this.log.warn(`ecoflow get failed: ${error.message}`);
+            }
+        });
+    }
+
+    /** EnergyStreamSwitch — only when `--stream-interval` is set (E-9). */
+    activateStream() {
+        if (!this.connected) {
+            return;
+        }
+        const topic = this.topics().set;
+        this.log.debug(`ecoflow > EnergyStreamSwitch ${this.#safe(topic)}`);
+        this.client.publish(topic, encodeEnergyStreamSwitch({sn: this.config.sn}), {qos: 1}, (error) => {
+            if (error) {
+                this.log.warn(`ecoflow EnergyStreamSwitch failed: ${error.message}`);
+            }
+        });
+    }
+
+    #onMessage(topic, payload) {
+        this.emit('raw', topic, payload);
+        let frames;
+        try {
+            frames = decodeFrames(payload);
+        } catch (error) {
+            this.log.debug(`ecoflow < ${this.#safe(topic)}: not a protobuf frame (${error.message}), ignored`);
+            return;
+        }
+        const mine = frames.filter((frame) => !frame.deviceSn || frame.deviceSn === this.config.sn);
+        if (mine.length > 0) {
+            this.emit('frames', mine, topic);
+        }
+    }
+
+    /** A topic with the serial masked — safe for info/warn level. */
+    #safe(topic) {
+        return this.config.sn ? topic.replaceAll(this.config.sn, maskSn(this.config.sn)) : topic;
+    }
+}

package/lib/capture.js

@@ -0,0 +1,85 @@
+/**
+ * `--capture <dir>`: append every frame the cloud sends as one base64 line, so new fields and new
+ * firmware can be turned into test fixtures without a device.
+ *
+ * Everything that identifies the device or the account is removed **here**, not later by hand
+ * (ROADMAP.md E-2): the header fields `device_sn` / `module_sn` are replaced before re-encoding,
+ * and the serial number and the account's user id are replaced in the topic and in any remaining
+ * literal occurrence in the payload. A capture file is therefore safe to attach to an issue.
+ *
+ * Line format (test/fixtures/README.md): `<epoch ms> <topic> <base64 HeaderMessage>`.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import {HeaderMessage} from './proto/decode.js';
+import {placeholderSn} from './mask.js';
+
+/**
+ * @param {{dir: string, sn: string, userId?: string|(() => string), log: object,
+ *   now?: () => number}} options `userId` may be a getter: it is only known after login.
+ * @returns {{write: (topic: string, payload: Buffer) => void, close: () => Promise<void>, file: string}}
+ */
+export function createCapture({dir, sn, userId, log, now = () => Date.now()}) {
+    const placeholder = placeholderSn(sn);
+    const stamp = new Date(now()).toISOString().slice(0, 19).replaceAll(':', '-');
+    const file = path.join(dir, `frames-${stamp}.b64`);
+
+    fs.mkdirSync(dir, {recursive: true});
+    const stream = fs.createWriteStream(file, {flags: 'a'});
+    log.info(`capturing frames to ${file} (serial replaced by ${placeholder})`);
+
+    /** Same-length replacement for the SN, so buffers stay valid wherever it is embedded; the
+     * account id only ever appears in topics, where length does not matter. */
+    function scrubText(text) {
+        let out = String(text);
+        if (sn) {
+            out = out.replaceAll(sn, placeholder);
+        }
+        const id = typeof userId === 'function' ? userId() : userId;
+        if (id) {
+            out = out.replaceAll(String(id), 'USERID');
+        }
+        return out;
+    }
+
+    function scrubPayload(payload) {
+        try {
+            const message = HeaderMessage.decode(payload);
+            let touched = false;
+            for (const header of message.header ?? []) {
+                if (header.deviceSn) {
+                    header.deviceSn = placeholder;
+                    touched = true;
+                }
+                if (header.moduleSn) {
+                    header.moduleSn = placeholder;
+                    touched = true;
+                }
+            }
+            if (touched) {
+                return Buffer.from(HeaderMessage.encode(message).finish());
+            }
+        } catch {
+            // not a HeaderMessage (a JSON ping, a truncated frame): fall through to the text pass
+        }
+        const text = payload.toString('binary');
+        const scrubbed = scrubText(text);
+        return scrubbed === text ? payload : Buffer.from(scrubbed, 'binary');
+    }
+
+    return {
+        file,
+        write(topic, payload) {
+            try {
+                stream.write(`${now()} ${scrubText(topic)} ${scrubPayload(payload).toString('base64')}\n`);
+            } catch (error) {
+                log.warn(`capture write failed: ${error.message}`);
+            }
+        },
+        /** Resolves once everything written is on disk (shutdown waits for it). */
+        close() {
+            return new Promise((resolve) => stream.end(resolve));
+        },
+    };
+}

package/lib/clientid.js

@@ -0,0 +1,60 @@
+/**
+ * The UUID inside the MQTT client id `ANDROID_<UUID>_<userId>`.
+ *
+ * EcoFlow's broker filters on that shape (R §4.2) and keeps a session per client id, so the UUID
+ * is generated once and then reused for the life of the instance (ROADMAP.md E-6). It lives in
+ * the state directory (`$STATE_DIRECTORY` under systemd, `~/.ecoflow2mqtt` otherwise) — it is
+ * state, not configuration, and the service user must be able to write it.
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+/** Where the client id of an instance is kept when `--state-dir` is not given. */
+export function defaultStateDir() {
+    return process.env.STATE_DIRECTORY || path.join(os.homedir(), '.ecoflow2mqtt');
+}
+
+export function clientIdFile({stateDir, name}) {
+    return path.join(stateDir || defaultStateDir(), `${name}.client-id`);
+}
+
+/** EcoFlow's client ids use the hex uppercase form without dashes. */
+export function newUuid() {
+    return crypto.randomUUID().replaceAll('-', '').toUpperCase();
+}
+
+/**
+ * Read the instance's UUID, creating (and persisting) one on first start. A state directory that
+ * cannot be written is a warning, not a failure: the adapter then runs with a fresh UUID per
+ * start, which works but leaves stale sessions behind.
+ *
+ * @returns {string}
+ */
+export function loadClientUuid({stateDir, name, log = {debug() {}, warn() {}}}) {
+    const file = clientIdFile({stateDir, name});
+    try {
+        const stored = fs.readFileSync(file, 'utf8').trim();
+        if (/^[0-9A-F]{32}$/.test(stored)) {
+            log.debug(`client id uuid read from ${file}`);
+            return stored;
+        }
+        log.warn(`ignoring malformed client id in ${file}`);
+    } catch (error) {
+        if (error.code !== 'ENOENT') {
+            log.warn(`cannot read ${file}: ${error.message}`);
+        }
+    }
+
+    const uuid = newUuid();
+    try {
+        fs.mkdirSync(path.dirname(file), {recursive: true, mode: 0o750});
+        fs.writeFileSync(file, `${uuid}\n`, {mode: 0o640});
+        log.debug(`client id uuid created in ${file}`);
+    } catch (error) {
+        log.warn(`cannot persist the client id in ${file}: ${error.message} — using a temporary one`);
+    }
+    return uuid;
+}

package/lib/hadiscovery.js

@@ -0,0 +1,71 @@
+/**
+ * Home Assistant MQTT discovery (device-based, HA >= 2024.4) — the device block for the core's
+ * `discovery()` hook. Pure: config in, {device, components} out.
+ *
+ * Every row of the item table becomes a sensor: readings carry `state_class: measurement` so HA
+ * keeps statistics for them, settings (the feed-in limits) and the grid status do not. Volts,
+ * amps, hertz, the limits and the Wi-Fi signal are marked as diagnostics so the device page keeps
+ * the four power values in front.
+ *
+ * An energy (kWh) sensor for the energy dashboard would need the device's energy counters, which
+ * this firmware does not send (ROADMAP.md OQ-E3); a Riemann sum helper on `pv_watts` is the way
+ * to get one today.
+ */
+
+import {entity, discoveryId} from 'mqtt-interfaces-core';
+import {ITEMS, GRID_STATUS} from './items.js';
+import {modelOf} from './mask.js';
+
+export const ADAPTER = 'ecoflow2mqtt';
+
+/** The HA attributes a row implies: unit, device class, state class, enum options. */
+export function extraFor(row) {
+    const extra = {};
+    if (row.unit) {
+        extra.unit_of_meas = row.unit;
+    }
+    if (row.deviceClass) {
+        extra.dev_cla = row.deviceClass;
+    }
+    if (row.map) {
+        // an enum sensor: HA validates the state against the option list
+        extra.dev_cla = 'enum';
+        extra.options = Object.values(row.map);
+    } else if (row.measurement !== false) {
+        extra.stat_cla = 'measurement';
+        extra.sug_dsp_prc = row.precision ?? 1;
+    }
+    return extra;
+}
+
+/**
+ * @param {{name: string, sn?: string, jsonPayloads?: boolean}} options
+ * @returns {{id: string, device: object, components: object}}
+ */
+export function discoveryModel({name, sn, jsonPayloads = true}) {
+    const id = discoveryId(ADAPTER, name);
+    const model = modelOf(sn);
+    const components = {};
+
+    for (const row of ITEMS) {
+        components[row.item] = entity({
+            id,
+            name,
+            item: row.item,
+            platform: 'sensor',
+            label: row.label,
+            icon: row.icon, // no fallback: without one HA picks the icon of the device class
+            category: row.category,
+            jsonPayloads,
+            extra: extraFor(row),
+        });
+    }
+
+    return {
+        id,
+        device: {mf: 'EcoFlow', ...(model && {mdl: model})},
+        components,
+    };
+}
+
+export {GRID_STATUS};

package/lib/install.js

@@ -0,0 +1,21 @@
+/**
+ * --install / --uninstall: systemd template service ecoflow2mqtt@<name>, one instance per
+ * inverter (mqtt-interfaces-core installer): /etc/ecoflow2mqtt/<name>.env (mode 600 — it holds
+ * the account credentials and the serial), /var/lib/ecoflow2mqtt/<name>/ for the persisted mqtt
+ * client id, system user ecoflow2mqtt, optional shared /etc/mqtt-interfaces/broker.env.
+ */
+
+import {createInstaller} from 'mqtt-interfaces-core';
+
+export const SERVICE = 'ecoflow2mqtt';
+export const ENV_PREFIX = 'ECOFLOW2MQTT';
+
+const installer = createInstaller({
+    service: SERVICE,
+    envPrefix: ENV_PREFIX,
+    description: `${SERVICE} %i - EcoFlow micro-inverter to MQTT bridge`,
+    documentation: 'https://github.com/hobbyquaker/ecoflow2mqtt',
+});
+
+export const {unitFile, envFile, installService, uninstallService, handle, CONF_DIR, STATE_DIR} = installer;
+export {envVarName, instanceName} from 'mqtt-interfaces-core';