@enyo-energy/sunspec-sdk 0.0.82 → 0.0.83

package/dist/cjs/sunspec-devices.cjs

@@ -346,6 +346,12 @@ class SunspecInverter extends BaseSunspecDevice {
     storage;
     errorState = { activeCodes: [], lastStatus: 'healthy' };
     snapshotService;
+    // Whether we've emitted a status update at least once since (re)connecting.
+    // The persisted errorState can diverge from what the core actually shows
+    // (e.g. a faulted that was never cleared while our local state reads
+    // healthy), so we force one re-assert of the current status on the first
+    // successful read of each session to converge the core.
+    statusReassertedThisSession = false;
     constructor(energyApp, name, networkDevice, sunspecClient, applianceManager, unitId = 1, port = 502, baseAddress = 40000, capabilities = [], retryConfig, appliance, useTls) {
         super(energyApp, name, networkDevice, sunspecClient, applianceManager, unitId, port, baseAddress, retryConfig, appliance, useTls);
         this.capabilities = capabilities;
@@ -394,9 +400,13 @@ class SunspecInverter extends BaseSunspecDevice {
         else {
             try {
                 const existingAppliance = await this.applianceManager.findApplianceById(this.applianceId);
+                // Drop any previously core-stored `status` so we don't echo a
+                // stale `faulted` back through ApplianceSave — status is driven
+                // solely by ApplianceStateUpdateV1 (detectAndEmitStatusTransition).
+                const { status: _staleStatus, ...prevMetadata } = existingAppliance?.metadata ?? {};
                 await this.applianceManager.updateAppliance(this.applianceId, {
                     metadata: {
-                        ...existingAppliance?.metadata,
+                        ...prevMetadata,
                         connectionType: enyo_appliance_js_1.EnyoApplianceConnectionType.Connector,
                         state: enyo_appliance_js_1.EnyoApplianceStateEnum.Connected,
                         modbus: { unitId: this.unitId, baseAddress: this.baseAddress },
@@ -420,6 +430,9 @@ class SunspecInverter extends BaseSunspecDevice {
             console.log(`MPPT model found for inverter ${this.networkDevice.hostname}`);
         }
         await this.loadErrorState();
+        // Fresh session: force the next successful read to re-assert the true
+        // status so a stale faulted in the core is cleared on (re)start.
+        this.statusReassertedThisSession = false;
         this.startDataBusListening();
         // Cold-start recovery: if the persisted state says we were stuck in
         // connection_lost but connect() just succeeded (we read commonBlock,
@@ -638,16 +651,30 @@ class SunspecInverter extends BaseSunspecDevice {
         if (!this.applianceId || !this.dataBus)
             return;
         const { codes, codeIds } = this.decodeActiveErrors(data);
-        const recoveringFromConnectionLoss = this.errorState.lastStatus === 'connection_lost';
-        if (!recoveringFromConnectionLoss && !this.hasErrorSetChanged(codeIds)) {
+        // Status is driven by BOTH the decoded event-register error bits AND the
+        // SunSpec operating state. Only operatingState 7 (FAULT) is a genuine
+        // 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;
+        const newStatus = (codeIds.length > 0 || operatingFault)
+            ? enyo_appliance_js_1.EnyoApplianceStatusEnum.Faulted
+            : enyo_appliance_js_1.EnyoApplianceStatusEnum.Healthy;
+        const newLastStatus = newStatus === enyo_appliance_js_1.EnyoApplianceStatusEnum.Healthy ? 'healthy' : 'faulted';
+        // Emit when the effective status changed (covers faulted/connection_lost
+        // -> healthy convergence), when the active error-code set changed, or
+        // once per session to re-assert the true status to the core (clears a
+        // stale faulted that diverged from our local state). Otherwise stay
+        // quiet so we don't republish the same status every 10s poll.
+        const statusChanged = newLastStatus !== this.errorState.lastStatus;
+        const mustReassert = !this.statusReassertedThisSession;
+        if (!statusChanged && !this.hasErrorSetChanged(codeIds) && !mustReassert) {
             return;
         }
-        const newStatus = codeIds.length === 0
-            ? enyo_appliance_js_1.EnyoApplianceStatusEnum.Healthy
-            : enyo_appliance_js_1.EnyoApplianceStatusEnum.Faulted;
         const message = this.buildStatusMessage(newStatus, codes, timestamp);
-        console.log(`Inverter ${this.applianceId}: status transition -> ${newStatus} (codes=[${codeIds.join(', ')}])`);
+        console.log(`Inverter ${this.applianceId}: status transition -> ${newStatus} (codes=[${codeIds.join(', ')}], operatingState=${data.operatingState})`);
         this.dataBus.sendMessage([message]);
+        this.statusReassertedThisSession = true;
         this.errorState = {
             evt1: data.events,
             evt2: data.events2,
@@ -656,7 +683,7 @@ class SunspecInverter extends BaseSunspecDevice {
             evtVnd3: data.vendorEvents3,
             evtVnd4: data.vendorEvents4,
             activeCodes: codeIds,
-            lastStatus: newStatus === enyo_appliance_js_1.EnyoApplianceStatusEnum.Healthy ? 'healthy' : 'faulted',
+            lastStatus: newLastStatus,
         };
         await this.persistErrorState();
     }

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

@@ -131,6 +131,7 @@ export declare class SunspecInverter extends BaseSunspecDevice {
     private storage?;
     private errorState;
     private snapshotService?;
+    private statusReassertedThisSession;
     constructor(energyApp: EnergyApp, name: EnyoApplianceName[], networkDevice: EnyoNetworkDevice, sunspecClient: SunspecModbusClient, applianceManager: ApplianceManager, unitId?: number, port?: number, baseAddress?: number, capabilities?: SunspecInverterCapability[], retryConfig?: IRetryConfig, appliance?: EnyoAppliance, useTls?: boolean);
     connect(): Promise<void>;
     disconnect(): Promise<void>;

package/dist/cjs/sunspec-interfaces.cjs

@@ -3,7 +3,7 @@
  * SunSpec block interfaces with block numbers
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SUNSPEC_CONTROLLABLE_FEATURES = exports.SunspecMeterCapability = exports.SunspecBatteryFeatureModeKind = exports.SunspecBatteryCapability = exports.SunspecInverterCapability = exports.SunspecStorageMode = exports.SunspecChargeSource = exports.SunspecVArPctMode = exports.SunspecEnableControl = exports.SunspecConnectionControl = exports.SunspecStorageControlMode = exports.SunspecBatteryEvent1 = exports.SunspecBatteryBankState = exports.SunspecBatteryType = exports.SunspecBatteryControlMode = exports.SunspecBatteryChargeState = exports.SunspecMPPTOperatingState = exports.SUNSPEC_CONNECTION_LOST_CODE = exports.SunspecInverterEvent1 = exports.SunspecModelId = exports.DEFAULT_RETRY_CONFIG = void 0;
+exports.SUNSPEC_CONTROLLABLE_FEATURES = exports.SunspecMeterCapability = exports.SunspecBatteryFeatureModeKind = exports.SunspecBatteryCapability = exports.SunspecInverterCapability = exports.SunspecStorageMode = exports.SunspecChargeSource = exports.SunspecVArPctMode = exports.SunspecEnableControl = exports.SunspecConnectionControl = exports.SunspecStorageControlMode = exports.SunspecBatteryEvent1 = exports.SunspecBatteryBankState = exports.SunspecBatteryType = exports.SunspecBatteryControlMode = exports.SunspecBatteryChargeState = exports.SunspecInverterOperatingState = exports.SunspecMPPTOperatingState = exports.SUNSPEC_CONNECTION_LOST_CODE = exports.SunspecInverterEvent1 = exports.SunspecModelId = exports.DEFAULT_RETRY_CONFIG = void 0;
 const enyo_battery_appliance_js_1 = require("@enyo-energy/energy-app-sdk/dist/types/enyo-battery-appliance.js");
 exports.DEFAULT_RETRY_CONFIG = {
     phases: [
@@ -87,6 +87,22 @@ var SunspecMPPTOperatingState;
     SunspecMPPTOperatingState[SunspecMPPTOperatingState["TEST"] = 9] = "TEST";
     SunspecMPPTOperatingState[SunspecMPPTOperatingState["RESERVED_10"] = 10] = "RESERVED_10";
 })(SunspecMPPTOperatingState || (exports.SunspecMPPTOperatingState = SunspecMPPTOperatingState = {}));
+/**
+ * Inverter Operating State values (SunSpec `St`, register offset 38) for
+ * models 101/103/111/112/113. Mirrors the SunSpec spec. Only `FAULT` is a
+ * genuine fault; `SLEEPING` and `MPPT` are normal production/standby states.
+ */
+var SunspecInverterOperatingState;
+(function (SunspecInverterOperatingState) {
+    SunspecInverterOperatingState[SunspecInverterOperatingState["OFF"] = 1] = "OFF";
+    SunspecInverterOperatingState[SunspecInverterOperatingState["SLEEPING"] = 2] = "SLEEPING";
+    SunspecInverterOperatingState[SunspecInverterOperatingState["STARTING"] = 3] = "STARTING";
+    SunspecInverterOperatingState[SunspecInverterOperatingState["MPPT"] = 4] = "MPPT";
+    SunspecInverterOperatingState[SunspecInverterOperatingState["THROTTLED"] = 5] = "THROTTLED";
+    SunspecInverterOperatingState[SunspecInverterOperatingState["SHUTTING_DOWN"] = 6] = "SHUTTING_DOWN";
+    SunspecInverterOperatingState[SunspecInverterOperatingState["FAULT"] = 7] = "FAULT";
+    SunspecInverterOperatingState[SunspecInverterOperatingState["STANDBY"] = 8] = "STANDBY";
+})(SunspecInverterOperatingState || (exports.SunspecInverterOperatingState = SunspecInverterOperatingState = {}));
 /**
  * Battery Charge State values for Model 124
  */

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

@@ -222,6 +222,21 @@ export declare enum SunspecMPPTOperatingState {
     TEST = 9,
     RESERVED_10 = 10
 }
+/**
+ * Inverter Operating State values (SunSpec `St`, register offset 38) for
+ * models 101/103/111/112/113. Mirrors the SunSpec spec. Only `FAULT` is a
+ * genuine fault; `SLEEPING` and `MPPT` are normal production/standby states.
+ */
+export declare enum SunspecInverterOperatingState {
+    OFF = 1,
+    SLEEPING = 2,
+    STARTING = 3,
+    MPPT = 4,// Maximum Power Point Tracking active (producing)
+    THROTTLED = 5,// Power output is being limited
+    SHUTTING_DOWN = 6,
+    FAULT = 7,
+    STANDBY = 8
+}
 /**
  * Battery Charge State values for Model 124
  */

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

package/dist/sunspec-devices.d.ts

@@ -131,6 +131,7 @@ export declare class SunspecInverter extends BaseSunspecDevice {
     private storage?;
     private errorState;
     private snapshotService?;
+    private statusReassertedThisSession;
     constructor(energyApp: EnergyApp, name: EnyoApplianceName[], networkDevice: EnyoNetworkDevice, sunspecClient: SunspecModbusClient, applianceManager: ApplianceManager, unitId?: number, port?: number, baseAddress?: number, capabilities?: SunspecInverterCapability[], retryConfig?: IRetryConfig, appliance?: EnyoAppliance, useTls?: boolean);
     connect(): Promise<void>;
     disconnect(): Promise<void>;

package/dist/sunspec-devices.js

@@ -1,4 +1,4 @@
-import { SunspecBatteryChargeState, SunspecBatteryFeatureModeKind, SunspecEnableControl, SunspecInverterCapability, SunspecInverterEvent1, SunspecModelId, SunspecMPPTOperatingState, SunspecStorageMode, SUNSPEC_CONNECTION_LOST_CODE } from "./sunspec-interfaces.js";
+import { SunspecBatteryChargeState, SunspecBatteryFeatureModeKind, SunspecEnableControl, SunspecInverterCapability, SunspecInverterEvent1, SunspecInverterOperatingState, SunspecModelId, SunspecMPPTOperatingState, SunspecStorageMode, SUNSPEC_CONNECTION_LOST_CODE } from "./sunspec-interfaces.js";
 import { randomUUID } from "node:crypto";
 import { EnyoApplianceConnectionType, EnyoApplianceStateEnum, EnyoApplianceStatusEnum, EnyoApplianceTopologyFeatureEnum, EnyoApplianceTypeEnum } from "@enyo-energy/energy-app-sdk/dist/types/enyo-appliance.js";
 import { ConnectionRetryManager } from "./connection-retry-manager.js";
@@ -339,6 +339,12 @@ export class SunspecInverter extends BaseSunspecDevice {
     storage;
     errorState = { activeCodes: [], lastStatus: 'healthy' };
     snapshotService;
+    // Whether we've emitted a status update at least once since (re)connecting.
+    // The persisted errorState can diverge from what the core actually shows
+    // (e.g. a faulted that was never cleared while our local state reads
+    // healthy), so we force one re-assert of the current status on the first
+    // successful read of each session to converge the core.
+    statusReassertedThisSession = false;
     constructor(energyApp, name, networkDevice, sunspecClient, applianceManager, unitId = 1, port = 502, baseAddress = 40000, capabilities = [], retryConfig, appliance, useTls) {
         super(energyApp, name, networkDevice, sunspecClient, applianceManager, unitId, port, baseAddress, retryConfig, appliance, useTls);
         this.capabilities = capabilities;
@@ -387,9 +393,13 @@ export class SunspecInverter extends BaseSunspecDevice {
         else {
             try {
                 const existingAppliance = await this.applianceManager.findApplianceById(this.applianceId);
+                // Drop any previously core-stored `status` so we don't echo a
+                // stale `faulted` back through ApplianceSave — status is driven
+                // solely by ApplianceStateUpdateV1 (detectAndEmitStatusTransition).
+                const { status: _staleStatus, ...prevMetadata } = existingAppliance?.metadata ?? {};
                 await this.applianceManager.updateAppliance(this.applianceId, {
                     metadata: {
-                        ...existingAppliance?.metadata,
+                        ...prevMetadata,
                         connectionType: EnyoApplianceConnectionType.Connector,
                         state: EnyoApplianceStateEnum.Connected,
                         modbus: { unitId: this.unitId, baseAddress: this.baseAddress },
@@ -413,6 +423,9 @@ export class SunspecInverter extends BaseSunspecDevice {
             console.log(`MPPT model found for inverter ${this.networkDevice.hostname}`);
         }
         await this.loadErrorState();
+        // Fresh session: force the next successful read to re-assert the true
+        // status so a stale faulted in the core is cleared on (re)start.
+        this.statusReassertedThisSession = false;
         this.startDataBusListening();
         // Cold-start recovery: if the persisted state says we were stuck in
         // connection_lost but connect() just succeeded (we read commonBlock,
@@ -631,16 +644,30 @@ export class SunspecInverter extends BaseSunspecDevice {
         if (!this.applianceId || !this.dataBus)
             return;
         const { codes, codeIds } = this.decodeActiveErrors(data);
-        const recoveringFromConnectionLoss = this.errorState.lastStatus === 'connection_lost';
-        if (!recoveringFromConnectionLoss && !this.hasErrorSetChanged(codeIds)) {
+        // Status is driven by BOTH the decoded event-register error bits AND the
+        // SunSpec operating state. Only operatingState 7 (FAULT) is a genuine
+        // 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;
+        const newStatus = (codeIds.length > 0 || operatingFault)
+            ? EnyoApplianceStatusEnum.Faulted
+            : EnyoApplianceStatusEnum.Healthy;
+        const newLastStatus = newStatus === EnyoApplianceStatusEnum.Healthy ? 'healthy' : 'faulted';
+        // Emit when the effective status changed (covers faulted/connection_lost
+        // -> healthy convergence), when the active error-code set changed, or
+        // once per session to re-assert the true status to the core (clears a
+        // stale faulted that diverged from our local state). Otherwise stay
+        // quiet so we don't republish the same status every 10s poll.
+        const statusChanged = newLastStatus !== this.errorState.lastStatus;
+        const mustReassert = !this.statusReassertedThisSession;
+        if (!statusChanged && !this.hasErrorSetChanged(codeIds) && !mustReassert) {
             return;
         }
-        const newStatus = codeIds.length === 0
-            ? EnyoApplianceStatusEnum.Healthy
-            : EnyoApplianceStatusEnum.Faulted;
         const message = this.buildStatusMessage(newStatus, codes, timestamp);
-        console.log(`Inverter ${this.applianceId}: status transition -> ${newStatus} (codes=[${codeIds.join(', ')}])`);
+        console.log(`Inverter ${this.applianceId}: status transition -> ${newStatus} (codes=[${codeIds.join(', ')}], operatingState=${data.operatingState})`);
         this.dataBus.sendMessage([message]);
+        this.statusReassertedThisSession = true;
         this.errorState = {
             evt1: data.events,
             evt2: data.events2,
@@ -649,7 +676,7 @@ export class SunspecInverter extends BaseSunspecDevice {
             evtVnd3: data.vendorEvents3,
             evtVnd4: data.vendorEvents4,
             activeCodes: codeIds,
-            lastStatus: newStatus === EnyoApplianceStatusEnum.Healthy ? 'healthy' : 'faulted',
+            lastStatus: newLastStatus,
         };
         await this.persistErrorState();
     }

package/dist/sunspec-interfaces.d.ts

@@ -222,6 +222,21 @@ export declare enum SunspecMPPTOperatingState {
     TEST = 9,
     RESERVED_10 = 10
 }
+/**
+ * Inverter Operating State values (SunSpec `St`, register offset 38) for
+ * models 101/103/111/112/113. Mirrors the SunSpec spec. Only `FAULT` is a
+ * genuine fault; `SLEEPING` and `MPPT` are normal production/standby states.
+ */
+export declare enum SunspecInverterOperatingState {
+    OFF = 1,
+    SLEEPING = 2,
+    STARTING = 3,
+    MPPT = 4,// Maximum Power Point Tracking active (producing)
+    THROTTLED = 5,// Power output is being limited
+    SHUTTING_DOWN = 6,
+    FAULT = 7,
+    STANDBY = 8
+}
 /**
  * Battery Charge State values for Model 124
  */

package/dist/sunspec-interfaces.js

@@ -84,6 +84,22 @@ export var SunspecMPPTOperatingState;
     SunspecMPPTOperatingState[SunspecMPPTOperatingState["TEST"] = 9] = "TEST";
     SunspecMPPTOperatingState[SunspecMPPTOperatingState["RESERVED_10"] = 10] = "RESERVED_10";
 })(SunspecMPPTOperatingState || (SunspecMPPTOperatingState = {}));
+/**
+ * Inverter Operating State values (SunSpec `St`, register offset 38) for
+ * models 101/103/111/112/113. Mirrors the SunSpec spec. Only `FAULT` is a
+ * genuine fault; `SLEEPING` and `MPPT` are normal production/standby states.
+ */
+export var SunspecInverterOperatingState;
+(function (SunspecInverterOperatingState) {
+    SunspecInverterOperatingState[SunspecInverterOperatingState["OFF"] = 1] = "OFF";
+    SunspecInverterOperatingState[SunspecInverterOperatingState["SLEEPING"] = 2] = "SLEEPING";
+    SunspecInverterOperatingState[SunspecInverterOperatingState["STARTING"] = 3] = "STARTING";
+    SunspecInverterOperatingState[SunspecInverterOperatingState["MPPT"] = 4] = "MPPT";
+    SunspecInverterOperatingState[SunspecInverterOperatingState["THROTTLED"] = 5] = "THROTTLED";
+    SunspecInverterOperatingState[SunspecInverterOperatingState["SHUTTING_DOWN"] = 6] = "SHUTTING_DOWN";
+    SunspecInverterOperatingState[SunspecInverterOperatingState["FAULT"] = 7] = "FAULT";
+    SunspecInverterOperatingState[SunspecInverterOperatingState["STANDBY"] = 8] = "STANDBY";
+})(SunspecInverterOperatingState || (SunspecInverterOperatingState = {}));
 /**
  * Battery Charge State values for Model 124
  */

package/dist/version.d.ts

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