@enyo-energy/sunspec-sdk 0.0.75 → 0.0.76

package/dist/cjs/sunspec-devices.cjs

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SunspecMeter = exports.SunspecBattery = exports.SunspecInverter = exports.BaseSunspecDevice = void 0;
 exports.detectFeaturesFromRegisters = detectFeaturesFromRegisters;
+exports.selectLiveBatteryPowerW = selectLiveBatteryPowerW;
 exports.filterFeaturesByCalibrationResult = filterFeaturesByCalibrationResult;
 const sunspec_interfaces_js_1 = require("./sunspec-interfaces.cjs");
 const node_crypto_1 = require("node:crypto");
@@ -852,6 +853,35 @@ function detectFeaturesFromRegisters(batteryData) {
  *   the full detected set to preserve the old all-or-nothing semantics on
  *   upgrade.
  */
+/**
+ * Pick the live battery power, in preference order:
+ *
+ *   1. Model 160 (MPPT) `StCha 3` / `StDisCha 4` — direct DC-link reading,
+ *      passed in as the already-summed `mpptBatteryPowerW`.
+ *   2. Model 802 `w` (offset 47) — surfaced as `chargePower` / `dischargePower`
+ *      by the Model 802 path of `SunspecModbusClient.readBatteryData`.
+ *   3. `undefined` — no reliable live source on this device.
+ *
+ * The Model 124 path of `readBatteryData` no longer manufactures
+ * `chargePower` / `dischargePower` from `inWRte × wChaMax` (a commanded rate
+ * cap, not a live measurement). So whenever this function sees
+ * `chargePower` / `dischargePower` defined, they came from Model 802.
+ *
+ * Exported as a free function so the preference logic can be unit-tested
+ * without the full `SunspecBattery` scaffold.
+ */
+function selectLiveBatteryPowerW(mpptBatteryPowerW, batteryData) {
+    if (mpptBatteryPowerW !== undefined) {
+        return mpptBatteryPowerW;
+    }
+    if (!batteryData) {
+        return undefined;
+    }
+    if (batteryData.chargePower === undefined && batteryData.dischargePower === undefined) {
+        return undefined;
+    }
+    return (batteryData.chargePower ?? 0) - (batteryData.dischargePower ?? 0);
+}
 function filterFeaturesByCalibrationResult(detected, result, controllable) {
     if (!result || result.state !== 'calibrated') {
         return detected.filter(f => !controllable.includes(f));
@@ -1115,17 +1145,8 @@ class SunspecBattery extends BaseSunspecDevice {
                 return messages;
             }
             if (batteryData) {
-                const advancedBatteryModel = this.sunspecClient.findModel(this.unitId, 801);
-                const batteryBaseModel = this.sunspecClient.findModel(this.unitId, sunspec_interfaces_js_1.SunspecModelId.BatteryBase);
-                // Determine battery power: prefer model 802 w field, then MPPT extraction, then undefined
-                let batteryPowerW;
-                if (batteryBaseModel && (batteryData.chargePower !== undefined || batteryData.dischargePower !== undefined)) {
-                    // Model 802 provides power directly: positive = charge, negative = discharge
-                    batteryPowerW = (batteryData.chargePower || 0) - (batteryData.dischargePower || 0);
-                }
-                else if (!advancedBatteryModel) {
-                    batteryPowerW = mpptBatteryPowerW;
-                }
+                // See `selectLiveBatteryPowerW` for the source-preference rationale.
+                const batteryPowerW = selectLiveBatteryPowerW(mpptBatteryPowerW, batteryData);
                 // Feed the calibration driver's synchronous power cache. No-op when calibration
                 // was never configured.
                 if (batteryPowerW !== undefined && this.calibrationDriver) {

package/dist/cjs/sunspec-devices.d.cts

@@ -215,6 +215,24 @@ export declare function detectFeaturesFromRegisters(batteryData: SunspecBatteryD
  *   the full detected set to preserve the old all-or-nothing semantics on
  *   upgrade.
  */
+/**
+ * Pick the live battery power, in preference order:
+ *
+ *   1. Model 160 (MPPT) `StCha 3` / `StDisCha 4` — direct DC-link reading,
+ *      passed in as the already-summed `mpptBatteryPowerW`.
+ *   2. Model 802 `w` (offset 47) — surfaced as `chargePower` / `dischargePower`
+ *      by the Model 802 path of `SunspecModbusClient.readBatteryData`.
+ *   3. `undefined` — no reliable live source on this device.
+ *
+ * The Model 124 path of `readBatteryData` no longer manufactures
+ * `chargePower` / `dischargePower` from `inWRte × wChaMax` (a commanded rate
+ * cap, not a live measurement). So whenever this function sees
+ * `chargePower` / `dischargePower` defined, they came from Model 802.
+ *
+ * Exported as a free function so the preference logic can be unit-tested
+ * without the full `SunspecBattery` scaffold.
+ */
+export declare function selectLiveBatteryPowerW(mpptBatteryPowerW: number | undefined, batteryData: SunspecBatteryData | null): number | undefined;
 export declare function filterFeaturesByCalibrationResult(detected: EnyoBatteryFeature[], result: CalibrationResult | undefined, controllable: readonly EnyoBatteryFeature[]): EnyoBatteryFeature[];
 /**
  * Sunspec Battery implementation

package/dist/cjs/sunspec-modbus-client.cjs

@@ -1596,16 +1596,17 @@ class SunspecModbusClient {
                     voltage: this.applyScaleFactor(inBatVRaw, scaleFactors.InBatV_SF, 'uint16'),
                     status: !this.isUnimplementedValue(chaStRaw, 'enum16') ? chaStRaw : undefined
                 };
-                // Calculate charge/discharge power if rates are available
-                if (data.inWRte !== undefined && data.wChaMax !== undefined) {
-                    data.chargePower = (data.inWRte / 100) * data.wChaMax;
-                    console.debug(`Calculated Charge Power: (inWRte: ${data.inWRte}, wChaMax: ${data.wChaMax}) ${data.chargePower?.toFixed(2)} W`);
-                }
-                if (data.outWRte !== undefined && data.wChaMax !== undefined) {
-                    // Assuming WDisChaMax is similar to WChaMax for simplicity
-                    data.dischargePower = Math.abs((data.outWRte / 100) * data.wChaMax);
-                    console.debug(`Calculated Discharge Power (inWRte: ${data.outWRte}, wChaMax: ${data.wChaMax}): ${data.dischargePower?.toFixed(2)} W`);
-                }
+                // chargePower / dischargePower used to be derived from
+                // `(inWRte  / 100) * wChaMax` and `(outWRte / 100) * wChaMax`
+                // here. That formula uses Model 124's COMMANDED RATE CAPS — not
+                // a live measurement — and produces e.g. 5000 W of "charging"
+                // for an idle battery with inWRte = 100 % and a 5 kW nameplate.
+                // Live battery power must come from a real source: Model 160
+                // StCha 3 / StDisCha 4 (see SunspecBattery.extractBatteryPower
+                // FromMPPT) or Model 802 `w` at offset 47 (the Model 802 branch
+                // of this method, just below). Model-124-only devices should
+                // publish "no signal" rather than the commanded cap.
+                // See plans/please-review-the-implementation-groovy-thacker.md.
                 // Single-line JSON debug dump — Node's default formatter would split
                 // the object across many lines; stringify keeps the whole snapshot
                 // on one log entry so it stays grep-able and round-trippable.

package/dist/cjs/version.cjs

@@ -9,7 +9,7 @@ exports.getSdkVersion = getSdkVersion;
 /**
  * Current version of the enyo Energy App SDK.
  */
-exports.SDK_VERSION = '0.0.75';
+exports.SDK_VERSION = '0.0.76';
 /**
  * Gets the current SDK version.
  * @returns The semantic version string of the SDK

package/dist/cjs/version.d.cts

@@ -5,7 +5,7 @@
 /**
  * Current version of the enyo Energy App SDK.
  */
-export declare const SDK_VERSION = "0.0.75";
+export declare const SDK_VERSION = "0.0.76";
 /**
  * Gets the current SDK version.
  * @returns The semantic version string of the SDK

package/dist/sunspec-devices.d.ts

@@ -215,6 +215,24 @@ export declare function detectFeaturesFromRegisters(batteryData: SunspecBatteryD
  *   the full detected set to preserve the old all-or-nothing semantics on
  *   upgrade.
  */
+/**
+ * Pick the live battery power, in preference order:
+ *
+ *   1. Model 160 (MPPT) `StCha 3` / `StDisCha 4` — direct DC-link reading,
+ *      passed in as the already-summed `mpptBatteryPowerW`.
+ *   2. Model 802 `w` (offset 47) — surfaced as `chargePower` / `dischargePower`
+ *      by the Model 802 path of `SunspecModbusClient.readBatteryData`.
+ *   3. `undefined` — no reliable live source on this device.
+ *
+ * The Model 124 path of `readBatteryData` no longer manufactures
+ * `chargePower` / `dischargePower` from `inWRte × wChaMax` (a commanded rate
+ * cap, not a live measurement). So whenever this function sees
+ * `chargePower` / `dischargePower` defined, they came from Model 802.
+ *
+ * Exported as a free function so the preference logic can be unit-tested
+ * without the full `SunspecBattery` scaffold.
+ */
+export declare function selectLiveBatteryPowerW(mpptBatteryPowerW: number | undefined, batteryData: SunspecBatteryData | null): number | undefined;
 export declare function filterFeaturesByCalibrationResult(detected: EnyoBatteryFeature[], result: CalibrationResult | undefined, controllable: readonly EnyoBatteryFeature[]): EnyoBatteryFeature[];
 /**
  * Sunspec Battery implementation

package/dist/sunspec-devices.js

@@ -845,6 +845,35 @@ export function detectFeaturesFromRegisters(batteryData) {
  *   the full detected set to preserve the old all-or-nothing semantics on
  *   upgrade.
  */
+/**
+ * Pick the live battery power, in preference order:
+ *
+ *   1. Model 160 (MPPT) `StCha 3` / `StDisCha 4` — direct DC-link reading,
+ *      passed in as the already-summed `mpptBatteryPowerW`.
+ *   2. Model 802 `w` (offset 47) — surfaced as `chargePower` / `dischargePower`
+ *      by the Model 802 path of `SunspecModbusClient.readBatteryData`.
+ *   3. `undefined` — no reliable live source on this device.
+ *
+ * The Model 124 path of `readBatteryData` no longer manufactures
+ * `chargePower` / `dischargePower` from `inWRte × wChaMax` (a commanded rate
+ * cap, not a live measurement). So whenever this function sees
+ * `chargePower` / `dischargePower` defined, they came from Model 802.
+ *
+ * Exported as a free function so the preference logic can be unit-tested
+ * without the full `SunspecBattery` scaffold.
+ */
+export function selectLiveBatteryPowerW(mpptBatteryPowerW, batteryData) {
+    if (mpptBatteryPowerW !== undefined) {
+        return mpptBatteryPowerW;
+    }
+    if (!batteryData) {
+        return undefined;
+    }
+    if (batteryData.chargePower === undefined && batteryData.dischargePower === undefined) {
+        return undefined;
+    }
+    return (batteryData.chargePower ?? 0) - (batteryData.dischargePower ?? 0);
+}
 export function filterFeaturesByCalibrationResult(detected, result, controllable) {
     if (!result || result.state !== 'calibrated') {
         return detected.filter(f => !controllable.includes(f));
@@ -1108,17 +1137,8 @@ export class SunspecBattery extends BaseSunspecDevice {
                 return messages;
             }
             if (batteryData) {
-                const advancedBatteryModel = this.sunspecClient.findModel(this.unitId, 801);
-                const batteryBaseModel = this.sunspecClient.findModel(this.unitId, SunspecModelId.BatteryBase);
-                // Determine battery power: prefer model 802 w field, then MPPT extraction, then undefined
-                let batteryPowerW;
-                if (batteryBaseModel && (batteryData.chargePower !== undefined || batteryData.dischargePower !== undefined)) {
-                    // Model 802 provides power directly: positive = charge, negative = discharge
-                    batteryPowerW = (batteryData.chargePower || 0) - (batteryData.dischargePower || 0);
-                }
-                else if (!advancedBatteryModel) {
-                    batteryPowerW = mpptBatteryPowerW;
-                }
+                // See `selectLiveBatteryPowerW` for the source-preference rationale.
+                const batteryPowerW = selectLiveBatteryPowerW(mpptBatteryPowerW, batteryData);
                 // Feed the calibration driver's synchronous power cache. No-op when calibration
                 // was never configured.
                 if (batteryPowerW !== undefined && this.calibrationDriver) {

package/dist/sunspec-modbus-client.js

@@ -1591,16 +1591,17 @@ export class SunspecModbusClient {
                     voltage: this.applyScaleFactor(inBatVRaw, scaleFactors.InBatV_SF, 'uint16'),
                     status: !this.isUnimplementedValue(chaStRaw, 'enum16') ? chaStRaw : undefined
                 };
-                // Calculate charge/discharge power if rates are available
-                if (data.inWRte !== undefined && data.wChaMax !== undefined) {
-                    data.chargePower = (data.inWRte / 100) * data.wChaMax;
-                    console.debug(`Calculated Charge Power: (inWRte: ${data.inWRte}, wChaMax: ${data.wChaMax}) ${data.chargePower?.toFixed(2)} W`);
-                }
-                if (data.outWRte !== undefined && data.wChaMax !== undefined) {
-                    // Assuming WDisChaMax is similar to WChaMax for simplicity
-                    data.dischargePower = Math.abs((data.outWRte / 100) * data.wChaMax);
-                    console.debug(`Calculated Discharge Power (inWRte: ${data.outWRte}, wChaMax: ${data.wChaMax}): ${data.dischargePower?.toFixed(2)} W`);
-                }
+                // chargePower / dischargePower used to be derived from
+                // `(inWRte  / 100) * wChaMax` and `(outWRte / 100) * wChaMax`
+                // here. That formula uses Model 124's COMMANDED RATE CAPS — not
+                // a live measurement — and produces e.g. 5000 W of "charging"
+                // for an idle battery with inWRte = 100 % and a 5 kW nameplate.
+                // Live battery power must come from a real source: Model 160
+                // StCha 3 / StDisCha 4 (see SunspecBattery.extractBatteryPower
+                // FromMPPT) or Model 802 `w` at offset 47 (the Model 802 branch
+                // of this method, just below). Model-124-only devices should
+                // publish "no signal" rather than the commanded cap.
+                // See plans/please-review-the-implementation-groovy-thacker.md.
                 // Single-line JSON debug dump — Node's default formatter would split
                 // the object across many lines; stringify keeps the whole snapshot
                 // on one log entry so it stays grep-able and round-trippable.

package/dist/version.d.ts

@@ -5,7 +5,7 @@
 /**
  * Current version of the enyo Energy App SDK.
  */
-export declare const SDK_VERSION = "0.0.75";
+export declare const SDK_VERSION = "0.0.76";
 /**
  * Gets the current SDK version.
  * @returns The semantic version string of the SDK

package/dist/version.js

@@ -5,7 +5,7 @@
 /**
  * Current version of the enyo Energy App SDK.
  */
-export const SDK_VERSION = '0.0.75';
+export const SDK_VERSION = '0.0.76';
 /**
  * Gets the current SDK version.
  * @returns The semantic version string of the SDK

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enyo-energy/sunspec-sdk",
-  "version": "0.0.75",
+  "version": "0.0.76",
   "description": "enyo Energy Sunspec SDK",
   "type": "module",
   "main": "dist/index.js",