@enyo-energy/sunspec-sdk 0.0.84 → 0.0.86

package/dist/cjs/sunspec-battery-schedule-handler.cjs

@@ -73,22 +73,30 @@ class SunspecBatteryScheduleHandler extends storage_schedule_handler_js_1.Storag
             // baseline so the persisted snapshot continues to point at the
             // original pre-schedule state. The library will overwrite its
             // storage row with the same value — harmless.
-            this.installedWChaMax = this.originalBaseline.wChaMax;
+            const wChaMax = this.originalBaseline.wChaMax;
+            if (!wChaMax || wChaMax <= 0) {
+                throw new Error(`SunspecBatteryScheduleHandler ${this.applianceIdForLog}: cannot start schedule — originalBaseline has no usable wChaMax (got ${wChaMax})`);
+            }
+            this.installedWChaMax = wChaMax;
             return { ...this.originalBaseline };
         }
         const controls = await this.sunspecClient.readBatteryControls(this.unitId);
         if (!controls) {
             throw new Error(`SunspecBatteryScheduleHandler ${this.applianceIdForLog}: failed to read pre-schedule controls`);
         }
+        const wChaMax = controls.wChaMax;
+        if (!wChaMax || wChaMax <= 0) {
+            throw new Error(`SunspecBatteryScheduleHandler ${this.applianceIdForLog}: cannot start schedule — device did not report a usable wChaMax (got ${wChaMax})`);
+        }
         const baseline = {
             storCtlMod: controls.storCtlMod,
             chaGriSet: controls.chaGriSet,
-            wChaMax: controls.wChaMax,
+            wChaMax,
             inWRte: controls.inWRte,
             outWRte: controls.outWRte,
         };
         this.originalBaseline = baseline;
-        this.installedWChaMax = baseline.wChaMax;
+        this.installedWChaMax = wChaMax;
         return { ...baseline };
     }
     onChange(active, _previous) {

package/dist/cjs/sunspec-devices.cjs

@@ -343,7 +343,16 @@ class SunspecInverter extends BaseSunspecDevice {
     capabilities;
     /** Emit a connection-lost faulted status after this many consecutive failed reconnect attempts. */
     static CONNECTION_FAULT_THRESHOLD = 3;
+    /**
+     * Require this many consecutive operatingState=7 (FAULT) reads before
+     * reporting Faulted. Debounces transient single-poll FAULT reads (e.g. a
+     * DC-coupled battery disturbing a string) that would otherwise oscillate
+     * the appliance status. Recovery is immediate (counter resets on the first
+     * non-fault read).
+     */
+    static OPERATING_FAULT_THRESHOLD = 3;
     storage;
+    consecutiveOperatingFaults = 0;
     errorState = { activeCodes: [], lastStatus: 'healthy' };
     snapshotService;
     // Whether we've emitted a status update at least once since (re)connecting.
@@ -656,7 +665,15 @@ class SunspecInverter extends BaseSunspecDevice {
         // fault; MPPT (4), SLEEPING (2) and the other states are normal. This
         // is re-evaluated every poll so a producing inverter (operatingState=4,
         // no error bits) reports Healthy even if it was previously faulted.
-        const operatingFault = data.operatingState === sunspec_interfaces_js_1.SunspecInverterOperatingState.FAULT;
+        //
+        // A single FAULT read is debounced: we only treat it as a fault after
+        // OPERATING_FAULT_THRESHOLD consecutive FAULT polls, so a transient
+        // wobble (e.g. a faulted DC-coupled battery on a string) does not
+        // oscillate the status. Recovery is immediate — the counter resets on
+        // the first non-fault read. Event-register error bits stay immediate.
+        const operatingFaultRaw = data.operatingState === sunspec_interfaces_js_1.SunspecInverterOperatingState.FAULT;
+        this.consecutiveOperatingFaults = operatingFaultRaw ? this.consecutiveOperatingFaults + 1 : 0;
+        const operatingFault = this.consecutiveOperatingFaults >= SunspecInverter.OPERATING_FAULT_THRESHOLD;
         const newStatus = (codeIds.length > 0 || operatingFault)
             ? enyo_appliance_js_1.EnyoApplianceStatusEnum.Faulted
             : enyo_appliance_js_1.EnyoApplianceStatusEnum.Healthy;
@@ -772,7 +789,10 @@ class SunspecInverter extends BaseSunspecDevice {
             // Only include strings with valid data
             if (mppt.dcVoltage !== undefined || mppt.dcPower !== undefined) {
                 result.push({
-                    index: index + 1,
+                    // Use the stable physical module position so a string keeps
+                    // its identity when an earlier module drops out of a poll.
+                    // Fall back to array position if the field is absent.
+                    index: mppt.moduleNumber ?? (index + 1),
                     name: mppt.stringId,
                     state: this.mapMPPTOperatingState(mppt.operatingState),
                     current: mppt.dcCurrent,

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

@@ -129,7 +129,16 @@ export declare class SunspecInverter extends BaseSunspecDevice {
     private readonly capabilities;
     /** Emit a connection-lost faulted status after this many consecutive failed reconnect attempts. */
     private static readonly CONNECTION_FAULT_THRESHOLD;
+    /**
+     * Require this many consecutive operatingState=7 (FAULT) reads before
+     * reporting Faulted. Debounces transient single-poll FAULT reads (e.g. a
+     * DC-coupled battery disturbing a string) that would otherwise oscillate
+     * the appliance status. Recovery is immediate (counter resets on the first
+     * non-fault read).
+     */
+    private static readonly OPERATING_FAULT_THRESHOLD;
     private storage?;
+    private consecutiveOperatingFaults;
     private errorState;
     private snapshotService?;
     private statusReassertedThisSession;

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

@@ -190,6 +190,7 @@ export interface SunspecInverterPersistedErrorState {
  */
 export interface SunspecMPPTData extends SunspecBlock {
     blockNumber: 160;
+    moduleNumber?: number;
     id: number;
     stringId?: string;
     dcCurrent?: number;

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

@@ -365,6 +365,20 @@ class SunspecModbusClient {
             throw new Error(`Modbus instance for unit ${unitId} not initialized — call connect(host, port, ${unitId}) first`);
         return inst;
     }
+    /**
+     * Expose this client's open Modbus connection for a unit so a co-located driver can
+     * share the SAME TCP socket instead of opening a second one. This matters for devices
+     * behind single-connection bridges (e.g. the Solax ESP32 Pocket WiFi dongle, which
+     * resets the link when a second Modbus-TCP client connects): the driver reads its own
+     * function codes (e.g. FC04 input registers) over this socket.
+     *
+     * Throws if the unit isn't open. The connection's lifecycle stays owned by this client —
+     * borrowers MUST NOT call disconnect() on the returned instance; release it via
+     * disconnectUnit(unitId) / releaseSunspecClient() as usual.
+     */
+    getModbusInstance(unitId) {
+        return this.getInstance(unitId);
+    }
     /**
      * Get the fault-tolerant reader for a unit, throwing if it isn't open.
      */
@@ -1254,6 +1268,10 @@ class SunspecModbusClient {
                         (data.dcCurrent !== undefined ||
                             data.dcVoltage !== undefined ||
                             data.dcPower !== undefined)) {
+                        // Stamp the stable 1-based module position so downstream
+                        // string identity does not shift when an earlier module
+                        // drops out of a poll (e.g. transient undefined reads).
+                        data.moduleNumber = i;
                         mpptData.push(data);
                     }
                 }
@@ -1769,8 +1787,17 @@ class SunspecModbusClient {
             // governing parameters are already in place when the device
             // transitions into the new mode.
             if (controls.storCtlMod !== undefined) {
-                await this.writeRegisterValue(unitId, baseAddr + 5, controls.storCtlMod, 'uint16');
-                console.debug(`Set storage control mode to 0x${controls.storCtlMod.toString(16)}`);
+                // storCtlMod = 0 is rejected with Modbus Exception code 3 (Illegal Data Value)
+                // by some devices (e.g. Fronius GEN24). 0 means "no external control" per the
+                // SunSpec spec, but Fronius firmware requires at least one bit to be set.
+                // Mapping 0 -> CHARGE | DISCHARGE returns the battery to autonomous
+                // self-managed operation on all known SunSpec devices (matches the neutral
+                // reset state used in sunspec-battery-feature-calibrator.ts).
+                const safeMode = controls.storCtlMod === 0
+                    ? sunspec_interfaces_js_1.SunspecStorageControlMode.CHARGE | sunspec_interfaces_js_1.SunspecStorageControlMode.DISCHARGE
+                    : controls.storCtlMod;
+                await this.writeRegisterValue(unitId, baseAddr + 5, safeMode, 'uint16');
+                console.debug(`Set storage control mode to 0x${safeMode.toString(16)}`);
             }
             console.debug('Battery controls written successfully');
             return true;

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

@@ -18,6 +18,7 @@
  */
 import { type SunspecInverterControls, type SunspecInverterData, type SunspecInverterSettings, type SunspecMeterData, type SunspecModel, type SunspecMPPTData, type SunspecBatteryData, type SunspecBatteryBaseData, type SunspecBatteryControls, SunspecStorageMode } from "./sunspec-interfaces.cjs";
 import { EnergyAppModbusDataType, IConnectionHealth } from "@enyo-energy/energy-app-sdk/dist/implementations/modbus/interfaces.js";
+import { EnergyAppModbusInstance } from "@enyo-energy/energy-app-sdk/dist/packages/energy-app-modbus.js";
 import { EnergyApp } from "@enyo-energy/energy-app-sdk";
 /**
  * Get (or create) the singleton SunspecModbusClient for this network device.
@@ -121,6 +122,18 @@ export declare class SunspecModbusClient {
      * Get the EnergyAppModbusInstance for a unit, throwing if it isn't open.
      */
     private getInstance;
+    /**
+     * Expose this client's open Modbus connection for a unit so a co-located driver can
+     * share the SAME TCP socket instead of opening a second one. This matters for devices
+     * behind single-connection bridges (e.g. the Solax ESP32 Pocket WiFi dongle, which
+     * resets the link when a second Modbus-TCP client connects): the driver reads its own
+     * function codes (e.g. FC04 input registers) over this socket.
+     *
+     * Throws if the unit isn't open. The connection's lifecycle stays owned by this client —
+     * borrowers MUST NOT call disconnect() on the returned instance; release it via
+     * disconnectUnit(unitId) / releaseSunspecClient() as usual.
+     */
+    getModbusInstance(unitId: number): EnergyAppModbusInstance;
     /**
      * Get the fault-tolerant reader for a unit, throwing if it isn't open.
      */

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.84';
+exports.SDK_VERSION = '0.0.86';
 /**
  * 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.84";
+export declare const SDK_VERSION = "0.0.86";
 /**
  * Gets the current SDK version.
  * @returns The semantic version string of the SDK

package/dist/sunspec-battery-schedule-handler.js

@@ -70,22 +70,30 @@ export class SunspecBatteryScheduleHandler extends StorageScheduleHandler {
             // baseline so the persisted snapshot continues to point at the
             // original pre-schedule state. The library will overwrite its
             // storage row with the same value — harmless.
-            this.installedWChaMax = this.originalBaseline.wChaMax;
+            const wChaMax = this.originalBaseline.wChaMax;
+            if (!wChaMax || wChaMax <= 0) {
+                throw new Error(`SunspecBatteryScheduleHandler ${this.applianceIdForLog}: cannot start schedule — originalBaseline has no usable wChaMax (got ${wChaMax})`);
+            }
+            this.installedWChaMax = wChaMax;
             return { ...this.originalBaseline };
         }
         const controls = await this.sunspecClient.readBatteryControls(this.unitId);
         if (!controls) {
             throw new Error(`SunspecBatteryScheduleHandler ${this.applianceIdForLog}: failed to read pre-schedule controls`);
         }
+        const wChaMax = controls.wChaMax;
+        if (!wChaMax || wChaMax <= 0) {
+            throw new Error(`SunspecBatteryScheduleHandler ${this.applianceIdForLog}: cannot start schedule — device did not report a usable wChaMax (got ${wChaMax})`);
+        }
         const baseline = {
             storCtlMod: controls.storCtlMod,
             chaGriSet: controls.chaGriSet,
-            wChaMax: controls.wChaMax,
+            wChaMax,
             inWRte: controls.inWRte,
             outWRte: controls.outWRte,
         };
         this.originalBaseline = baseline;
-        this.installedWChaMax = baseline.wChaMax;
+        this.installedWChaMax = wChaMax;
         return { ...baseline };
     }
     onChange(active, _previous) {

package/dist/sunspec-devices.d.ts

@@ -129,7 +129,16 @@ export declare class SunspecInverter extends BaseSunspecDevice {
     private readonly capabilities;
     /** Emit a connection-lost faulted status after this many consecutive failed reconnect attempts. */
     private static readonly CONNECTION_FAULT_THRESHOLD;
+    /**
+     * Require this many consecutive operatingState=7 (FAULT) reads before
+     * reporting Faulted. Debounces transient single-poll FAULT reads (e.g. a
+     * DC-coupled battery disturbing a string) that would otherwise oscillate
+     * the appliance status. Recovery is immediate (counter resets on the first
+     * non-fault read).
+     */
+    private static readonly OPERATING_FAULT_THRESHOLD;
     private storage?;
+    private consecutiveOperatingFaults;
     private errorState;
     private snapshotService?;
     private statusReassertedThisSession;

package/dist/sunspec-devices.js

@@ -336,7 +336,16 @@ export class SunspecInverter extends BaseSunspecDevice {
     capabilities;
     /** Emit a connection-lost faulted status after this many consecutive failed reconnect attempts. */
     static CONNECTION_FAULT_THRESHOLD = 3;
+    /**
+     * Require this many consecutive operatingState=7 (FAULT) reads before
+     * reporting Faulted. Debounces transient single-poll FAULT reads (e.g. a
+     * DC-coupled battery disturbing a string) that would otherwise oscillate
+     * the appliance status. Recovery is immediate (counter resets on the first
+     * non-fault read).
+     */
+    static OPERATING_FAULT_THRESHOLD = 3;
     storage;
+    consecutiveOperatingFaults = 0;
     errorState = { activeCodes: [], lastStatus: 'healthy' };
     snapshotService;
     // Whether we've emitted a status update at least once since (re)connecting.
@@ -649,7 +658,15 @@ export class SunspecInverter extends BaseSunspecDevice {
         // fault; MPPT (4), SLEEPING (2) and the other states are normal. This
         // is re-evaluated every poll so a producing inverter (operatingState=4,
         // no error bits) reports Healthy even if it was previously faulted.
-        const operatingFault = data.operatingState === SunspecInverterOperatingState.FAULT;
+        //
+        // A single FAULT read is debounced: we only treat it as a fault after
+        // OPERATING_FAULT_THRESHOLD consecutive FAULT polls, so a transient
+        // wobble (e.g. a faulted DC-coupled battery on a string) does not
+        // oscillate the status. Recovery is immediate — the counter resets on
+        // the first non-fault read. Event-register error bits stay immediate.
+        const operatingFaultRaw = data.operatingState === SunspecInverterOperatingState.FAULT;
+        this.consecutiveOperatingFaults = operatingFaultRaw ? this.consecutiveOperatingFaults + 1 : 0;
+        const operatingFault = this.consecutiveOperatingFaults >= SunspecInverter.OPERATING_FAULT_THRESHOLD;
         const newStatus = (codeIds.length > 0 || operatingFault)
             ? EnyoApplianceStatusEnum.Faulted
             : EnyoApplianceStatusEnum.Healthy;
@@ -765,7 +782,10 @@ export class SunspecInverter extends BaseSunspecDevice {
             // Only include strings with valid data
             if (mppt.dcVoltage !== undefined || mppt.dcPower !== undefined) {
                 result.push({
-                    index: index + 1,
+                    // Use the stable physical module position so a string keeps
+                    // its identity when an earlier module drops out of a poll.
+                    // Fall back to array position if the field is absent.
+                    index: mppt.moduleNumber ?? (index + 1),
                     name: mppt.stringId,
                     state: this.mapMPPTOperatingState(mppt.operatingState),
                     current: mppt.dcCurrent,

package/dist/sunspec-interfaces.d.ts

@@ -190,6 +190,7 @@ export interface SunspecInverterPersistedErrorState {
  */
 export interface SunspecMPPTData extends SunspecBlock {
     blockNumber: 160;
+    moduleNumber?: number;
     id: number;
     stringId?: string;
     dcCurrent?: number;

package/dist/sunspec-modbus-client.d.ts

@@ -18,6 +18,7 @@
  */
 import { type SunspecInverterControls, type SunspecInverterData, type SunspecInverterSettings, type SunspecMeterData, type SunspecModel, type SunspecMPPTData, type SunspecBatteryData, type SunspecBatteryBaseData, type SunspecBatteryControls, SunspecStorageMode } from "./sunspec-interfaces.js";
 import { EnergyAppModbusDataType, IConnectionHealth } from "@enyo-energy/energy-app-sdk/dist/implementations/modbus/interfaces.js";
+import { EnergyAppModbusInstance } from "@enyo-energy/energy-app-sdk/dist/packages/energy-app-modbus.js";
 import { EnergyApp } from "@enyo-energy/energy-app-sdk";
 /**
  * Get (or create) the singleton SunspecModbusClient for this network device.
@@ -121,6 +122,18 @@ export declare class SunspecModbusClient {
      * Get the EnergyAppModbusInstance for a unit, throwing if it isn't open.
      */
     private getInstance;
+    /**
+     * Expose this client's open Modbus connection for a unit so a co-located driver can
+     * share the SAME TCP socket instead of opening a second one. This matters for devices
+     * behind single-connection bridges (e.g. the Solax ESP32 Pocket WiFi dongle, which
+     * resets the link when a second Modbus-TCP client connects): the driver reads its own
+     * function codes (e.g. FC04 input registers) over this socket.
+     *
+     * Throws if the unit isn't open. The connection's lifecycle stays owned by this client —
+     * borrowers MUST NOT call disconnect() on the returned instance; release it via
+     * disconnectUnit(unitId) / releaseSunspecClient() as usual.
+     */
+    getModbusInstance(unitId: number): EnergyAppModbusInstance;
     /**
      * Get the fault-tolerant reader for a unit, throwing if it isn't open.
      */

package/dist/sunspec-modbus-client.js

@@ -360,6 +360,20 @@ export class SunspecModbusClient {
             throw new Error(`Modbus instance for unit ${unitId} not initialized — call connect(host, port, ${unitId}) first`);
         return inst;
     }
+    /**
+     * Expose this client's open Modbus connection for a unit so a co-located driver can
+     * share the SAME TCP socket instead of opening a second one. This matters for devices
+     * behind single-connection bridges (e.g. the Solax ESP32 Pocket WiFi dongle, which
+     * resets the link when a second Modbus-TCP client connects): the driver reads its own
+     * function codes (e.g. FC04 input registers) over this socket.
+     *
+     * Throws if the unit isn't open. The connection's lifecycle stays owned by this client —
+     * borrowers MUST NOT call disconnect() on the returned instance; release it via
+     * disconnectUnit(unitId) / releaseSunspecClient() as usual.
+     */
+    getModbusInstance(unitId) {
+        return this.getInstance(unitId);
+    }
     /**
      * Get the fault-tolerant reader for a unit, throwing if it isn't open.
      */
@@ -1249,6 +1263,10 @@ export class SunspecModbusClient {
                         (data.dcCurrent !== undefined ||
                             data.dcVoltage !== undefined ||
                             data.dcPower !== undefined)) {
+                        // Stamp the stable 1-based module position so downstream
+                        // string identity does not shift when an earlier module
+                        // drops out of a poll (e.g. transient undefined reads).
+                        data.moduleNumber = i;
                         mpptData.push(data);
                     }
                 }
@@ -1764,8 +1782,17 @@ export class SunspecModbusClient {
             // governing parameters are already in place when the device
             // transitions into the new mode.
             if (controls.storCtlMod !== undefined) {
-                await this.writeRegisterValue(unitId, baseAddr + 5, controls.storCtlMod, 'uint16');
-                console.debug(`Set storage control mode to 0x${controls.storCtlMod.toString(16)}`);
+                // storCtlMod = 0 is rejected with Modbus Exception code 3 (Illegal Data Value)
+                // by some devices (e.g. Fronius GEN24). 0 means "no external control" per the
+                // SunSpec spec, but Fronius firmware requires at least one bit to be set.
+                // Mapping 0 -> CHARGE | DISCHARGE returns the battery to autonomous
+                // self-managed operation on all known SunSpec devices (matches the neutral
+                // reset state used in sunspec-battery-feature-calibrator.ts).
+                const safeMode = controls.storCtlMod === 0
+                    ? SunspecStorageControlMode.CHARGE | SunspecStorageControlMode.DISCHARGE
+                    : controls.storCtlMod;
+                await this.writeRegisterValue(unitId, baseAddr + 5, safeMode, 'uint16');
+                console.debug(`Set storage control mode to 0x${safeMode.toString(16)}`);
             }
             console.debug('Battery controls written successfully');
             return true;

package/dist/version.d.ts

@@ -5,7 +5,7 @@
 /**
  * Current version of the enyo Energy App SDK.
  */
-export declare const SDK_VERSION = "0.0.84";
+export declare const SDK_VERSION = "0.0.86";
 /**
  * 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.84';
+export const SDK_VERSION = '0.0.86';
 /**
  * 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.84",
+  "version": "0.0.86",
   "description": "enyo Energy Sunspec SDK",
   "type": "module",
   "main": "dist/index.js",