ecoflow2mqtt 0.2.0 → 0.3.0

package/README.md

@@ -83,20 +83,49 @@ sees a new client on every start.
 
 - The **EcoFlow app account** the inverter is bound to (a shared device does not work — bind it to
   this account in the app).
-- The **serial number**, as shown in the app or on the device.
+- The **serial number**, as shown in the app or on the device — or let `--discover` find it, below.
 - The **region** the account was created in (`--region`, default `eu`). Accounts are region bound;
   a wrong region answers "account doesn't exist or incorrect password", which is also what an
   EcoFlow outage answers, so the adapter keeps retrying instead of giving up.
 
 No developer account, no API keys: the adapter logs in the way the app does.
 
+### Finding the serial number
+
+```
+ecoflow2mqtt --email you@example.com --password 'your-app-password' --discover
+```
+
+prints every device the account owns, with its serial, name and whether EcoFlow currently
+considers it online:
+
+```
+BK01Z…  Balcony  (cloud)
+```
+
+`--discover-json` gives the same as JSON. `--sn auto` takes the serial when the account owns
+exactly one device and refuses when it owns several, so nothing is guessed:
+
+```
+sudo ecoflow2mqtt --install -n balcony --email … --password … --sn auto
+```
+
+resolves it **once** and writes it into the instance's env file, rather than making every service
+start depend on EcoFlow's API being reachable.
+
+Note this is not a network scan, and there is nothing on your LAN to scan for: the inverter only
+ever talks to EcoFlow (see [How it works](#how-it-works-and-what-that-means-for-you)). `--discover`
+is a login, so unlike other adapters in the fleet it needs `--email` and `--password` — the two
+options it cannot do without. An `online: false` device is still listed: EcoFlow's flag lags by up
+to ~15 minutes, and an inverter that is dark at night is still the one you want to configure.
+
 ## Options
 
 | Option              | Default            | Meaning                                                         |
 | ------------------- | ------------------ | --------------------------------------------------------------- |
 | `--email`           | required           | EcoFlow app account                                             |
 | `--password`        | required           | its password                                                    |
-| `--sn`              | required           | serial number of the inverter                                   |
+| `--sn`              | required           | serial number of the inverter, or `auto` (see `--discover`)     |
 | `--region`          | `eu`               | `eu`, `us`, `global`, `americas`, `cn`                          |
 | `--api-host`        | from region        | override the API host                                           |
 | `--mqtt-host`       | from login         | override the EcoFlow broker (it occasionally names a wrong one) |

package/config.js

@@ -11,6 +11,7 @@
 import {parseConfig} from 'mqtt-interfaces-core';
 import pkg from './package.json' with {type: 'json'};
 import {REGIONS} from './lib/app/login.js';
+import {DISCOVERY_SHAPE} from './lib/discovery.js';
 import {defaultStateDir} from './lib/clientid.js';
 
 export const OPTIONS = {
@@ -28,9 +29,11 @@ export const OPTIONS = {
     },
     sn: {
         type: 'string',
-        describe: 'serial number of the inverter (as shown in the app)',
+        describe: 'serial number of the inverter (as shown in the app), or "auto" (see --discover)',
         demandOption: true,
         secret: true,
+        // the option --discover fills; one inverter per instance, so it stays a single value
+        discover: true,
     },
     region: {
         type: 'string',
@@ -100,9 +103,11 @@ export function parse(overrides = {}) {
         pkg,
         defaults: {name: 'ecoflow'},
         options: OPTIONS,
+        discovery: DISCOVERY_SHAPE,
         check,
         examples: [
             ['$0 --email me@example.com --password secret --sn BK01Z... -u mqtt://broker', 'run in the foreground'],
+            ['$0 --email me@example.com --password secret --discover', 'list the account’s devices and exit'],
             ['sudo $0 --install -n balcony', 'install as service ecoflow2mqtt@balcony'],
         ],
         // the core's own epilog (environment variables) plus what is specific to this adapter

package/index.js

@@ -8,7 +8,7 @@
  * (ROADMAP.md §1); there are no settable items yet.
  */
 
-import {createAdapter} from 'mqtt-interfaces-core';
+import {createAdapter, createLogger, runDiscovery, autoAddress} from 'mqtt-interfaces-core';
 import config, {stateDirOf} from './config.js';
 import pkg from './package.json' with {type: 'json'};
 import {handle as handleInstall} from './lib/install.js';
@@ -19,6 +19,30 @@ import {createCapture} from './lib/capture.js';
 import {discoveryModel} from './lib/hadiscovery.js';
 import {maskSn, modelOf} from './lib/mask.js';
 import {apiHostOf} from './lib/app/login.js';
+import {discoveryHint} from './lib/discovery.js';
+
+/*
+ * Finding the inverter (core B-2): there is nothing on the LAN to scan — the device only ever
+ * talks to EcoFlow's broker — so --discover logs into the account and lists what it owns, and
+ * `--sn auto` takes the serial when the account owns exactly one. Before handleInstall() so
+ * `--install --sn auto` persists the serial instead of resolving it on every service start,
+ * which would make each start depend on EcoFlow's api being up. The adapter does not exist yet,
+ * so discovery gets its own logger.
+ */
+if (config.discover || config.sn === 'auto') {
+    const discoveryLog = createLogger({envPrefix: config.$envPrefix || 'ECOFLOW2MQTT', level: config.verbosity});
+    const hint = discoveryHint(config);
+    if (config.discover) {
+        await runDiscovery({hint, config, log: discoveryLog}); // prints and exits
+    }
+    try {
+        config.sn = await autoAddress(hint, {config, log: discoveryLog});
+    } catch (err) {
+        // none, or several inverters on the account: bridging the wrong one is worse than stopping
+        discoveryLog.error('--sn auto:', err.message);
+        process.exit(1);
+    }
+}
 
 handleInstall(config); // --install / --uninstall never reach the rest
 

package/lib/app/login.js

@@ -139,6 +139,44 @@ export async function certification({host, token, userId, fetchImpl = globalThis
     };
 }
 
+/**
+ * GET /iot-service/user/device — the devices bound to the account, for `--discover` / `--sn auto`.
+ *
+ * Verified on the real account (ROADMAP §6.1): `data.bound` is an **object keyed by SN**, not an
+ * array, each value `{deviceName, model, productType, online, productSkuId, createTime}`.
+ * RESEARCH §4.1 records the shape as a list instead, so both are accepted — the endpoint is
+ * unofficial and has changed before, and the cost of tolerating the other shape is four lines.
+ *
+ * `model` is a number (1 on the STREAM Micro), not a model name, and nothing here knows what it
+ * enumerates; it is passed through as EcoFlow sends it. The readable model comes from the serial
+ * prefix instead (`modelOf()` in lib/mask.js). `productType` 55 is the STREAM Micro.
+ *
+ * `online` lags by up to ~15 minutes on EcoFlow's side, so it is reported and never used to drop
+ * a device: an inverter that is dark at night is still the one to configure.
+ *
+ * @returns {Promise<Array<{sn: string, name?: string, model?: string, productType?: number, online: boolean}>>}
+ */
+export async function deviceList({host, token, userId, fetchImpl = globalThis.fetch}) {
+    const data = await getJson({
+        url: `https://${host}/iot-service/user/device?userId=${encodeURIComponent(userId)}`,
+        headers: {authorization: `Bearer ${token}`},
+        fetchImpl,
+    });
+    const bound = data?.bound ?? data;
+    const entries = Array.isArray(bound)
+        ? bound.map((entry) => [entry?.sn ?? entry?.deviceSn, entry])
+        : Object.entries(bound && typeof bound === 'object' ? bound : {});
+    return entries
+        .filter(([sn]) => typeof sn === 'string' && sn)
+        .map(([sn, entry = {}]) => ({
+            sn,
+            name: entry.deviceName || undefined,
+            model: entry.model || undefined,
+            productType: entry.productType,
+            online: entry.online === 1 || entry.online === true,
+        }));
+}
+
 /**
  * Login + certification in one step.
  *

package/lib/discovery.js

@@ -0,0 +1,72 @@
+/**
+ * Finding the inverter (core B-2) — by asking EcoFlow, because there is nothing to scan.
+ *
+ * A STREAM Micro never speaks to anything on the LAN: it opens an outbound TLS connection to
+ * EcoFlow's broker and talks only to that (R §4.2). No SSDP, no mDNS, no open port, no MAC of its
+ * own on the wire once it is behind the router — every network method the core offers would find
+ * exactly nothing. What the user has to configure is the serial number printed in the app, so
+ * "discovery" here means listing the devices the account owns, which is the core's `cloud` hint.
+ *
+ * That inverts the usual rule about mandatory options: `--discover` normally drops them, but this
+ * scan *is* an account login, so `needs` keeps `--email` and `--password` demanded. `--sn` is the
+ * one it fills and stays exempt.
+ *
+ * The SN is printed in full by `--discover` on purpose. E-2 masks it in logs, `<name>/info` and
+ * captures because those get shared; this output exists so the user can copy it into a config.
+ */
+
+import {apiHostOf, login, deviceList} from './app/login.js';
+import {modelOf} from './mask.js';
+
+/**
+ * Log in and list what the account owns, in the shape the core's `cloud` hint expects: `id` is
+ * the identity of a candidate, the rest are fields `describe()` prints.
+ *
+ * Errors are not caught. The core lets a cloud failure propagate precisely so that a wrong
+ * password says so, instead of being reported as an empty network the way a silent ssdp search
+ * would be.
+ *
+ * @param {{email: string, password: string, region?: string, apiHost?: string}} config
+ * @returns {Promise<Array<{id: string, name?: string, model?: string, online: boolean}>>}
+ */
+export async function listAccountDevices(config, {fetchImpl = globalThis.fetch} = {}) {
+    const host = apiHostOf(config);
+    const {token, userId} = await login({
+        host,
+        email: config.email,
+        password: config.password,
+        fetchImpl,
+    });
+    const devices = await deviceList({host, token, userId, fetchImpl});
+    return devices.map(({sn, name, productType, online}) => ({
+        id: sn,
+        ...(name && {name}),
+        // not EcoFlow's `model`, which is a bare number we cannot interpret — the serial prefix
+        // is what actually names the hardware (`BK01…` → STREAM Microinverter)
+        ...(modelOf(sn) && {model: modelOf(sn)}),
+        ...(productType !== undefined && {productType}),
+        online,
+    }));
+}
+
+/** Options the scan itself consumes, so `--discover` keeps demanding them. */
+export const NEEDS = ['email', 'password'];
+
+/**
+ * What `config.js` hands `parseConfig()`: the *kind* of discovery and what it needs, with no
+ * callable — the credentials it would run on are the very thing being parsed. That is enough for
+ * `--config-schema` (`x-discover: "cloud"`, which is what she reads) and for the `--discover*`
+ * options; the core skips a cloud spec without a `list` rather than calling it.
+ */
+export const DISCOVERY_SHAPE = {cloud: true, needs: NEEDS};
+
+/**
+ * The hint that actually scans, built in `index.js` once the config exists. Unlike the network
+ * adapters' hints this one closes over the config: the credentials are what the scan runs on.
+ */
+export function discoveryHint(config, deps = {}) {
+    return {
+        cloud: {list: () => listAccountDevices(config, deps)},
+        needs: NEEDS,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ecoflow2mqtt",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Interface between EcoFlow STREAM / PowerStream micro-inverters and MQTT",
   "type": "module",
   "main": "index.js",
@@ -59,7 +59,7 @@
   },
   "dependencies": {
     "mqtt": "^5.10.0",
-    "mqtt-interfaces-core": "^0.8.0",
+    "mqtt-interfaces-core": "^0.11.3",
     "protobufjs": "^7.4.0"
   },
   "devDependencies": {