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

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

@@ -34,22 +34,88 @@ 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[];
+/**
+ * Product-code prefix of the gen-4 Solarbank (the `ats_ax170` family, e.g. `AE103` Solarbank 4 E5000
+ * Pro) whose ff09 tag layout {@link SOLIX_SOLARBANK_FIELD_NAMES} + the SOC/temperature extraction
+ * describe. Like the meter table this is family-specific — the SAME tag carries a different quantity on
+ * the meter (`0xac` is line voltage there, battery power here), so the Solarbank names are applied ONLY
+ * to a frame from this family. A product-code prefix used to pick a decode table, not a model import.
+ * `AE10` covers the AE10x gen-4 Solarbanks and does NOT match the meter (`AE1X0`, whose 4th char is `X`).
+ */
+export declare const SOLIX_SOLARBANK_PRODUCT_PREFIX = "AE10";
+/**
+ * Confirmed ff09 tag → field bindings for the gen-4 Solarbank (`ats_ax170`), correlated live against the
+ * app UI. Power values in watts; signed fields note their sign convention:
+ * - `0xac` battery power, SIGNED (+ charging / − discharging) — the measured net pack power.
+ * - `0xbc` charge power (0 unless charging); `0xad` discharge power (0 unless discharging).
+ * - `0xae` AC plug power, SIGNED (+ feeding the home / − drawing in to charge).
+ * - `0xaf` socket power — the unit's own on-board AC outlet (an appliance plugged into the Solarbank).
+ * - `0xc4` grid input power; `0xc5` home load power.
+ * SOC and temperature are NOT float channels — see {@link solixReadings}, which reads SOC from tag `0xa3`
+ * (a uint8) and temperature from the `0xa4` BMS status blob. The 4 PV-string channels (`0xc6`–`0xc9`),
+ * the AC currents (`0xb2`/`0xb3`) and export energy (`0xb4`) are not yet confirmed, so they stay raw
+ * `channel_<hex>` until a capture pins them.
+ */
+export declare const SOLIX_SOLARBANK_FIELD_NAMES: Readonly<Record<number, string>>;
+/**
+ * Confirmed `state_info` tag → field bindings for the gen-4 Solarbank. `state_info` is a SEPARATE push
+ * topic from `param_info` and, though it shares the ff09 framing, its tags carry SETTINGS/targets, NOT
+ * live measurements — so the SAME tag byte means something different here than in
+ * {@link SOLIX_SOLARBANK_FIELD_NAMES} (e.g. `0xab` is live PV power in param_info, the mode's AC-socket
+ * export limit here). Mapped by live observation against the app's SOC-setting screen; everything else
+ * stays raw `state_<hex>` until confirmed the same way.
+ */
+export declare const SOLIX_STATE_FIELD_NAMES: Readonly<Record<number, string>>;
+/**
+ * Decode a `state_info` ff09 frame to named + raw settings values. Skips the header tags (`< 0xa5`:
+ * request marker, serial, timestamps). Each settings tag is emitted under `state_<hex>` (a plain number
+ * so it's watchable in a consumer while more tags get mapped) AND, when confirmed, under its name from
+ * {@link SOLIX_STATE_FIELD_NAMES}. Value is read type-aware: `0x05` float32, `0x02` u16, `0x01` u8, and
+ * `0x03` the whole-number settings byte (`payload[1]`).
+ *
+ * The header cutoff is `0xa5` here, deliberately one lower than {@link solixReadings}' `0xa6` for
+ * `param_info`: the two frames are different layouts under the same ff09 framing — `state_info` carries
+ * a settings value at `0xa5` (SOC), where `param_info` has a header tag. The cutoffs are not meant to
+ * match; the spec pins `0xa5`'s treatment in each so they can't silently drift together.
+ */
+export declare function solixStateReadings(frame: SolixParamFrame): Record<string, number>;
 /** Interpret one TLV value as a telemetry channel (leading type byte + payload). */
 export declare function readSolixChannel(value: Buffer | undefined): SolixChannel | undefined;
 /**
@@ -65,9 +131,13 @@ 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 AND `productCode` is from a known family — pass the
+ * telemetry topic's product code so a device outside the meter/Solarbank families keeps raw
+ * `channel_<hex>` rather than borrowing another family'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.
+ * Meter family: {@link SOLIX_METER_PRODUCT_PREFIXES}; Solarbank: {@link SOLIX_SOLARBANK_PRODUCT_PREFIX}.
  */
-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;
@@ -152,9 +222,14 @@ export declare class SolixMqtt extends EventEmitter {
      * Connect, subscribe to the device's telemetry (+ command-reply) topics, ARM realtime reporting, and
      * start the re-arm/heartbeat timer so telemetry keeps flowing without the app. Idempotent per device.
      *
-     * Subscribes ONLY to what the device sends — `param_info` plus the device and account command-reply
-     * channels — never the `…/req` channels, which are the app→device request side this arms on, and would
-     * echo its own publishes back.
+     * Subscribes to `param_info` (+ the device/account command-reply channels) AND the device's `…/req`
+     * channel. `…/req` is the app→device request side — the broker copies the APP's own publishes there to
+     * any co-subscriber, so watching it lets us read a control the app changed that the telemetry does NOT
+     * reflect: the Solarbank's ambient light and display timeout ride an `…/req` cmd-17 (`0x68`) command
+     * (tags `a4`/`a5`), and the `param_info` `ba` bit only tracks OUR `set_device_attrs` write, never the
+     * app's separate command path. `onMessage` filters these — our own arming/echoes carry no
+     * `a4`/`a5` — and turns an app command into a `reading` with the app-set state. A `…/req` grant denial
+     * is non-fatal (only `param_info` is required); we just won't see app-side changes.
      *
      * Throws when `param_info` was not granted. A scope-denied filter comes back as SUBACK_FAILURE rather
      * than an error (see `SecureMqtt.subscribe`), so an unusable subscription otherwise looks like
@@ -165,6 +240,14 @@ export declare class SolixMqtt extends EventEmitter {
     watch(device: SolixMqttDevice): Promise<void>;
     /** Tear down the connection and stop the re-arm timer. */
     close(): Promise<void>;
+    /**
+     * Set a Solarbank's display screen-off timeout — publishes the captured cmd-17 command (ff09 msgtype
+     * `0x68`, tag `a5 = [01, index]`) on the device's `…/req` channel via the same envelope the arming
+     * poll uses (`sign_code:1`, no per-message signature — which the device accepts for cmd 17). `index`
+     * is the 1-based dropdown position (10s=1, 20s=2, 30s=3, 1m=4, 5m=5, 30m=6); "Never" is a separate
+     * command not handled here. Fire-and-forget: the device does not ack on a subscribed channel.
+     */
+    setDisplayTimeout(device: SolixMqttDevice, index: number): Promise<void>;
     /**
      * Re-arm every watched device and send the site heartbeat. The device only pushes `param_info` while
      * a client keeps requesting it — this replays the app's `requestDeviceInfo` (cmd 17) + `power_site`
@@ -192,8 +275,25 @@ export declare class SolixMqtt extends EventEmitter {
      * Decode one inbound MQTT message envelope and emit a `reading` if it carries an ff09 param frame. The
      * product code and the fallback serial come from the topic (`dt/{app}/{pn}/{sn}/param_info`); the frame's
      * own `a2` field wins for the serial when it carries one.
+     *
+     * Serial resolution matters because NOT every frame carries it: the device-info frame (which alone
+     * carries SOC/temperature via tags a3/a4) has a 1-byte `a2` (a status, not a serial) and can arrive on
+     * a topic whose serial segment isn't the device serial either — leaving a `deviceSn` that matches no
+     * watched device, so a consumer keying on it would drop the reading (and its temperature). So when the
+     * resolved serial isn't a watched device, fall back to the single watched device of this product code.
      */
     private onMessage;
+    /**
+     * Turn an app→device cmd-17 (`0x68`) command seen on the `…/req` channel into a `reading` carrying the
+     * app-set control state, so a change made in the app reflects back. The Solarbank's ambient light and
+     * display timeout are set this way (byte-identical to what {@link setDisplayTimeout} publishes), and the
+     * broker copies the app's publish to us as a co-subscriber. Only `0x68` frames carrying `a4`/`a5` are
+     * emitted, so the arming polls (`0x40`/`0x57`) and our own echoes contribute nothing:
+     * - `a4 = [01, s]` → ambient light, INVERTED (`s` 0 = on) → `ambientLightOn` 1/0. The `ba` telemetry
+     *   bit only tracks our `set_device_attrs` write, so this is the ONLY read-back of an app light toggle.
+     * - `a5 = [01, i]` → display timeout, `i` = 1-based dropdown index → `displayTimeoutIndex`.
+     */
+    private handleCommand;
 }
 /**
  * Pull the ff09 binary frame out of a received message. Solix telemetry arrives as a `{head, payload}`
@@ -211,4 +311,11 @@ export declare function extractFf09Payload(raw: unknown): Buffer | null;
  * `fe` carries a fresh unix-timestamp nonce; the trailing byte is XOR of every preceding byte (the same
  * checksum the meter's telemetry frames use — verified to reproduce the captured frames exactly).
  */
+/**
+ * Build the display screen-off-timeout command frame (ff09 msgtype `0x68`, tag `a5 = [01, index]`),
+ * captured live from the app on `cmd/anker_power/<pc>/<sn>/req` (cmd 17). `index` is the 1-based
+ * position in the app dropdown `[10s,20s,30s,1m,5m,30m]` — live-confirmed 10s=1, 30s=3, 1m=4. "Never"
+ * is a separate command (not this one). Byte-identical to the captured frames modulo the index byte.
+ */
+export declare function buildDisplayTimeoutFrame(index: number): Buffer;
 export declare function buildFf09Request(variant: "info" | "realtime", atUnixSec?: number): Buffer;

package/dist/transport/mqtt/topics.d.ts

@@ -80,14 +80,24 @@ export interface ParsedTopic {
 export declare function parseSecureTopic(topic: string): ParsedTopic | undefined;
 /** The per-device Solix topics for `{appName, productCode, deviceSn}`. */
 export interface SolixDeviceTopics {
-    /** Telemetry the device pushes (SUBSCRIBE) — ff09 `param_info` frames. */
+    /** Telemetry the device pushes (SUBSCRIBE) — ff09 `param_info` frames (live measurements). */
     paramInfo: string;
+    /**
+     * Settings/state the device pushes (SUBSCRIBE) — ff09 `state_info` frames. Same ff09 framing as
+     * `param_info` but the TAGS carry SETTINGS/targets (mode export limit, SOC limits, max_load, toggles),
+     * NOT live measurements — so it needs its own tag→name table, not the param_info one.
+     */
+    stateInfo: string;
     /** This device's command replies (SUBSCRIBE). */
     cmdRes: string;
-    /** The device's requestDeviceInfo channel (PUBLISH only — the app arms reporting here). */
+    /**
+     * The device's requestDeviceInfo channel (cmd 17). PUBLISH to arm reporting; also SUBSCRIBE — the
+     * broker copies the APP's publishes here to any co-subscriber, which is the only way to observe a
+     * control the app changed that `param_info` does not reflect (ambient light, display timeout).
+     */
     req: string;
 }
-/** Build the per-device Solix topics. `param_info` is the telemetry we decode; `req` is publish-only. */
+/** Build the per-device Solix topics. `param_info` is the telemetry we decode; `req` is arm + read-back. */
 export declare function solixDeviceTopics(appName: string, productCode: string, deviceSn: string): SolixDeviceTopics;
 /** The per-account Solix topics keyed by `user_id`. */
 export interface SolixUserTopics {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mega-yfue/eufy-sdk",
-  "version": "0.2.0-beta.16",
+  "version": "0.2.0-beta.18",
   "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",