@mega-yfue/eufy-sdk 0.2.0-beta.16 → 0.2.0-beta.17

package/dist/model/capabilities/solix.d.ts

@@ -14,26 +14,27 @@ import type { Surface } from "./members.js";
 /** Every capability a Solix device may carry. Solix's OWN union (not eufy's `Capability`). */
 export type SolixCapability = "identity" | "firmware" | "connectivity" | "energyMeter" | "battery" | "solarInput" | "acOutput" | "evCharger" | "charger" | "cooler";
 /**
- * The `energyMeter` surface, declared once. Only the ONE confirmed tag→name binding is a member:
- * `meterVoltageL1` (ff09 tag `0xAC`), confirmed against a live single-phase frame. The evidence gate
- * (`bindMembers`) installs its getter only once a frame carrying tag `0xAC` has landed and answers
- * `undefined` before.
+ * The `energyMeter` surface — the electrical readings the vendor app names, as typed members. Each is
+ * read-only and evidence-gated: `bindMembers` installs a getter only once a frame that REPORTS that tag
+ * has landed, and answers `undefined` (not a fabricated `0`) before any has. The gate is "reported", not
+ * "non-zero": a single-phase / single-CT meter still reports its L2/L3 slots as `0.0`, so those members
+ * install and read `0` rather than staying absent — a caller sees `0` for an idle phase, not `undefined`.
  *
- * The meter reports many more quantities (per-line power/current/voltage, totals, import/export energy),
- * but their tag→name bindings are a structural inference not yet pinned to a known-load capture. Rather
- * than assert a name that could mislabel a live float, those stay reachable raw as `channel_<hex>` from
- * the device's telemetry (a static members table cannot enumerate dynamic hex tags); each is promoted to
- * a member here, one line, as a capture confirms its binding.
+ * Provenance splits by what the evidence actually pins. The app's field VOCABULARY (these twelve names)
+ * is authoritative. For the tag→field binding, a live single-phase frame confirmed the L1 and total
+ * magnitudes (a nominal mains voltage, an equal line/total power pair, the line current), so those four
+ * positions are `verified`. The L2/L3 tags are never non-zero on a single-CT install and the app itself
+ * receives the meter as named JSON — there is no tag→phase decoder in the app binary — so their phase
+ * assignment is inferred from the block ordering and is marked `guessed`, not `apk`. The energy counters (`meterImportEnergy`/`meterExportEnergy`) are named
+ * on the wire but are NOT members here: their tag→name is confirmed, but their unit SCALE is not (a live
+ * reading is consistent with either Wh or kWh), so they stay raw named values via
+ * {@link SOLIX_METER_FIELD_NAMES} until a capture pins the scale, rather than ship a member with a guessed unit.
  *
  * @internal — the declaration `SolixEnergyMeterReads` derives from; exported (like the eufy `*_MEMBERS`
  * tables) so it is a known symbol, but excluded from the rendered API reference.
  */
 export declare const SOLIX_ENERGY_METER_MEMBERS: {
-    /**
-     * Line-1 voltage (V), ff09 tag `0xAC` — the ONE confirmed meter binding, matched against a live
-     * single-phase frame (a nominal mains voltage). Read-only; the evidence gate installs its getter only
-     * once a frame carrying `0xAC` has landed, so it is absent (not a fabricated `0`) until then.
-     */
+    /** Line-1 voltage (V), ff09 tag `0xAC` — confirmed live (a nominal mains voltage). */
     readonly meterVoltageL1: {
         readonly param: 172;
         readonly type: "number";
@@ -42,6 +43,87 @@ export declare const SOLIX_ENERGY_METER_MEMBERS: {
         readonly provenance: "verified";
         readonly description: "Meter line-1 voltage (V) — ff09 tag 0xAC, confirmed against a live single-phase frame.";
     };
+    /** Line-2 voltage (V), ff09 tag `0xAD` — the app's field; reads 0 until a multi-phase frame carries it. */
+    readonly meterVoltageL2: {
+        readonly param: 173;
+        readonly type: "number";
+        readonly kind: "scalar";
+        readonly unit: "V";
+        readonly provenance: "guessed";
+        readonly description: "Meter line-2 voltage (V) — ff09 tag 0xAD; phase assignment inferred from block ordering (never observed non-zero), 0 on a single-phase install.";
+    };
+    /** Line-3 voltage (V), ff09 tag `0xAE` — the app's field; reads 0 until a multi-phase frame carries it. */
+    readonly meterVoltageL3: {
+        readonly param: 174;
+        readonly type: "number";
+        readonly kind: "scalar";
+        readonly unit: "V";
+        readonly provenance: "guessed";
+        readonly description: "Meter line-3 voltage (V) — ff09 tag 0xAE; phase assignment inferred from block ordering (never observed non-zero), 0 on a single-phase install.";
+    };
+    /** Line-1 current (A), ff09 tag `0xAF` — confirmed live (the line's CT current). */
+    readonly meterCurrentL1: {
+        readonly param: 175;
+        readonly type: "number";
+        readonly kind: "scalar";
+        readonly unit: "A";
+        readonly provenance: "verified";
+        readonly description: "Meter line-1 current (A) — ff09 tag 0xAF, confirmed against a live single-phase frame.";
+    };
+    /** Line-2 current (A), ff09 tag `0xB0` — the app's field; reads 0 until a multi-phase frame carries it. */
+    readonly meterCurrentL2: {
+        readonly param: 176;
+        readonly type: "number";
+        readonly kind: "scalar";
+        readonly unit: "A";
+        readonly provenance: "guessed";
+        readonly description: "Meter line-2 current (A) — ff09 tag 0xB0; phase assignment inferred from block ordering (never observed non-zero), 0 on a single-phase install.";
+    };
+    /** Line-3 current (A), ff09 tag `0xB1` — the app's field; reads 0 until a multi-phase frame carries it. */
+    readonly meterCurrentL3: {
+        readonly param: 177;
+        readonly type: "number";
+        readonly kind: "scalar";
+        readonly unit: "A";
+        readonly provenance: "guessed";
+        readonly description: "Meter line-3 current (A) — ff09 tag 0xB1; phase assignment inferred from block ordering (never observed non-zero), 0 on a single-phase install.";
+    };
+    /** Line-1 active power (W), ff09 tag `0xA8` — confirmed live; negative on export. */
+    readonly meterPowerL1: {
+        readonly param: 168;
+        readonly type: "number";
+        readonly kind: "scalar";
+        readonly unit: "W";
+        readonly provenance: "verified";
+        readonly description: "Meter line-1 active power (W) — ff09 tag 0xA8, confirmed live; negative on export.";
+    };
+    /** Line-2 active power (W), ff09 tag `0xA9` — the app's field; reads 0 until a multi-phase frame carries it. */
+    readonly meterPowerL2: {
+        readonly param: 169;
+        readonly type: "number";
+        readonly kind: "scalar";
+        readonly unit: "W";
+        readonly provenance: "guessed";
+        readonly description: "Meter line-2 active power (W) — ff09 tag 0xA9; phase assignment inferred from block ordering (never observed non-zero), 0 on a single-phase install.";
+    };
+    /** Line-3 active power (W), ff09 tag `0xAA` — the app's field; reads 0 until a multi-phase frame carries it. */
+    readonly meterPowerL3: {
+        readonly param: 170;
+        readonly type: "number";
+        readonly kind: "scalar";
+        readonly unit: "W";
+        readonly provenance: "guessed";
+        readonly description: "Meter line-3 active power (W) — ff09 tag 0xAA; phase assignment inferred from block ordering (never observed non-zero), 0 on a single-phase install.";
+    };
+    /** Aggregate active power (W), ff09 tag `0xAB` — confirmed live; equals line-1 on a single phase. */
+    readonly meterPowerTotal: {
+        readonly param: 171;
+        readonly type: "number";
+        readonly kind: "scalar";
+        readonly unit: "W";
+        readonly provenance: "verified";
+        readonly description: "Meter total active power (W) — ff09 tag 0xAB, confirmed live; equals L1 on one phase.";
+    };
 };
 /** Bound `energyMeter` reads (the members-derived half of `dev.energyMeter()`). Read-only. */
 export type SolixEnergyMeterReads = Surface<typeof SOLIX_ENERGY_METER_MEMBERS>;
@@ -52,7 +134,12 @@ export type SolixEnergyMeterReads = Surface<typeof SOLIX_ENERGY_METER_MEMBERS>;
  * Unlisted categories contribute nothing here.
  */
 export declare const CATEGORY_CAPABILITIES: Readonly<Record<string, readonly SolixCapability[]>>;
-/** Product-code prefixes known to be grid/energy meters (detects `energyMeter` regardless of category). */
+/**
+ * Product-code prefixes known to be grid/energy meters (detects `energyMeter` regardless of category).
+ * Keep in lockstep with `SOLIX_METER_PRODUCT_PREFIXES` in `transport/mqtt/solix-mqtt.ts` (the same meter
+ * prefixes, transport-side, that gate the tag→name table): a prefix added here but not there grants
+ * `energyMeter` to a device whose frames the decoder then refuses to name. Add a meter prefix to both.
+ */
 export declare const SOLIX_METER_MODELS: readonly string[];
 /**
  * Product-code prefixes for the grid-tie Solarbank / home-battery family (detects `battery` +

package/dist/transport/mqtt/solix-mqtt.d.ts

@@ -34,22 +34,43 @@ export interface SolixParamFrame {
 }
 /**
  * Telemetry field tags for the Smart Meter (AE1X0) that we emit under a stable NAME, keyed by ff09 tag
- * byte. Only tags whose tag→name binding is CONFIRMED against a live frame live here:
+ * byte. These twelve are the meter fields the vendor app itself names, and their tag→name bindings are
+ * confirmed:
  *
- * - `0xac` = `meterVoltageL1` — confirmed against live single-phase data (a nominal mains voltage).
+ * - The app's field vocabulary is exactly these twelve — voltage, current and power per line
+ *   (L1/L2/L3), a power total, and cumulative import/export energy — with no current total, no
+ *   frequency and no power-factor field.
+ * - A live single-phase frame confirms the tag→field magnitudes: `0xac` a nominal mains voltage,
+ *   `0xa8` == `0xab` an equal power pair (line power equals total on one phase, one of them going
+ *   negative on export), `0xaf` the line current, `0xb3` a slowly-cumulative import counter; the L2/L3
+ *   slots read 0 on a single-CT install.
  *
- * Every other measurement tag still surfaces as `channel_<hex tag>` (see {@link solixReadings}), so
- * nothing on the wire is lost — a caller reads unconfirmed tags there. The names are deliberately NOT
- * asserted for the rest: the app exposes the field *list*, but the tag→name *binding* below is a
- * structural inference until a known-load capture pins it, and a mislabelled live float is worse than an
- * honest `channel_<tag>`. The recovered candidates, to re-add one line each (moving the tag from this
- * comment to the map above) as a known-load capture confirms each binding:
+ * The frame carries sixteen float slots (`0xa8`..`0xb7`). The four that name no field — `0xb2`, `0xb5`,
+ * `0xb6`, `0xb7` — stay raw `channel_<hex tag>` (see {@link solixReadings}). `0xb2` in particular is NOT
+ * a current total: under a 1.371 A line current it reads 0.009, three orders of magnitude off. Both
+ * `0xb2` and `0xb7` read zero at idle and non-zero under load, so they carry *something* load-related;
+ * what, is not established.
  *
- *   0xa8 meterPowerL1   0xa9 meterPowerL2   0xaa meterPowerL3   0xab meterPowerTotal
- *   0xad meterVoltageL2 0xae meterVoltageL3 0xaf meterCurrentL1 0xb0 meterCurrentL2
- *   0xb1 meterCurrentL3 0xb2 meterCurrentTotal 0xb3 meterImportEnergy 0xb4 meterExportEnergy
+ * This table is **meter-family-specific**: the same tag carries a different quantity on another Solix
+ * device (a Solarbank's `0xac` reads a power value, not a voltage), so {@link solixReadings} applies
+ * these names ONLY to a frame from the meter family — see {@link SOLIX_METER_PRODUCT_PREFIXES}. Every
+ * measurement tag still surfaces as `channel_<hex tag>` regardless of device, so nothing on the wire is
+ * lost; the model layer names non-meter tags per capability.
  */
 export declare const SOLIX_METER_FIELD_NAMES: Readonly<Record<number, string>>;
+/**
+ * Product-code prefixes of the Smart Meter family that {@link SOLIX_METER_FIELD_NAMES} decodes. The table
+ * is meter-specific, so {@link solixReadings} applies its named fields ONLY to a frame whose product code
+ * starts with one of these; a Solarbank (`AE103`) reporting the same `0xac` tag would otherwise be
+ * mislabelled `meterVoltageL1` with a nonsensical (negative-power) value. These are product-code prefixes
+ * used to select a decode table — not a model import — so the `transport ⊥ model` rule is untouched.
+ *
+ * Keep this in lockstep with `SOLIX_METER_MODELS` in `model/capabilities/solix.ts` (the same meter
+ * prefixes, model-side): a prefix added there but not here grants `energyMeter` to a device whose frames
+ * this decoder then refuses to name, and no guard can catch the split (the model layer can't import
+ * transport). Add a meter prefix to both.
+ */
+export declare const SOLIX_METER_PRODUCT_PREFIXES: readonly string[];
 /** Interpret one TLV value as a telemetry channel (leading type byte + payload). */
 export declare function readSolixChannel(value: Buffer | undefined): SolixChannel | undefined;
 /**
@@ -65,9 +86,12 @@ export declare function decodeSolixParamFrame(buf: Buffer): SolixParamFrame | nu
  * carry the field count, the serial and the status, not measurements. A measurement channel is one whose
  * leading type byte is `0x05` (float32 LE over a 4-byte payload); any other type is a non-measurement
  * param and contributes nothing. Each measurement is emitted under `channel_<hex tag>`, and additionally
- * under its name when the tag has a confirmed one in {@link SOLIX_METER_FIELD_NAMES}.
+ * under its name when the tag has a confirmed one in {@link SOLIX_METER_FIELD_NAMES} AND `productCode` is
+ * from the meter family (see {@link SOLIX_METER_PRODUCT_PREFIXES}) — so a non-meter device's tags stay
+ * raw `channel_<hex>` rather than borrowing the meter's tag→name table. `productCode` is required (it
+ * comes straight from the telemetry topic); pass `""` for a frame of unknown origin and no names apply.
  */
-export declare function solixReadings(frame: SolixParamFrame): Record<string, number>;
+export declare function solixReadings(frame: SolixParamFrame, productCode: string): Record<string, number>;
 /** A live telemetry sample emitted by {@link SolixMqtt} as a `reading` event. */
 export interface SolixReading {
     deviceSn: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mega-yfue/eufy-sdk",
-  "version": "0.2.0-beta.16",
+  "version": "0.2.0-beta.17",
   "description": "One typed TypeScript client for the Anker eufy v6 cloud — capability-driven devices, realtime events over P2P/MQTT/push, and live media",
   "license": "Apache-2.0",
   "author": "mega-yfue",