@enyo-energy/sunspec-sdk 0.0.81 → 0.0.83

package/dist/cjs/sunspec-devices.cjs

@@ -107,6 +107,15 @@ class BaseSunspecDevice {
     dataBus;
     retryManager;
     consecutiveReconnectFailures = 0;
+    /**
+     * True once {@link markOffline} has set the appliance state to Offline and
+     * it has not yet been re-asserted Connected. Used by
+     * {@link reassertConnectedIfRecovered} to heal the shared-socket case: when
+     * a sibling device on the same unit wins the reconnect race, this device's
+     * readData() sees isConnected() === true and skips tryReconnect(), so it
+     * would otherwise stay Offline forever despite reading data fine.
+     */
+    appliedOffline = false;
     /**
      * Prefix used when persisting calibration snapshots via the library's
      * {@link SnapshotService}. Kept identical to the key the SDK used before
@@ -181,6 +190,7 @@ class BaseSunspecDevice {
                 if (this.applianceId) {
                     await this.applianceManager.updateApplianceState(this.applianceId, enyo_appliance_js_1.EnyoApplianceConnectionType.Connector, enyo_appliance_js_1.EnyoApplianceStateEnum.Connected);
                 }
+                this.appliedOffline = false;
                 await this.onConnectionRestored();
                 const postStats = this.sunspecClient.getConnectionStats();
                 console.log(`${this.constructor.name} ${this.applianceId}: Reconnection successful after ${attempt} attempt(s) (opens=${postStats.opens}, closes=${postStats.closes}, openUnits=${postStats.openUnits})`);
@@ -249,12 +259,46 @@ class BaseSunspecDevice {
         if (this.applianceId) {
             try {
                 await this.applianceManager.updateApplianceState(this.applianceId, enyo_appliance_js_1.EnyoApplianceConnectionType.Connector, enyo_appliance_js_1.EnyoApplianceStateEnum.Offline);
+                this.appliedOffline = true;
             }
             catch (error) {
                 console.error(`${this.constructor.name} ${this.applianceId}: Failed to mark appliance offline: ${error}`);
             }
         }
     }
+    /**
+     * Heal the shared-socket recovery gap. When several devices share one
+     * SunspecModbusClient on the same unit (e.g. a Fronius GEN24 inverter and
+     * its battery), only the device that detects !isConnected() first runs
+     * tryReconnect() — and that is the only path that flips the appliance back
+     * to Connected. Siblings then see isConnected() === true on their next
+     * readData() and skip tryReconnect() entirely, so without this they would
+     * stay Offline forever despite reading data fine.
+     *
+     * Call this on the success path of readData() (after the
+     * markOfflineIfUnhealthy() guard has confirmed the unit is healthy). It is
+     * a cheap no-op unless this device was previously marked offline.
+     */
+    async reassertConnectedIfRecovered() {
+        if (!this.appliedOffline || !this.applianceId) {
+            return;
+        }
+        if (!this.sunspecClient.isHealthy(this.unitId)) {
+            return;
+        }
+        console.log(`${this.constructor.name} ${this.applianceId}: connection recovered via shared socket — re-asserting Connected`);
+        try {
+            await this.applianceManager.updateApplianceState(this.applianceId, enyo_appliance_js_1.EnyoApplianceConnectionType.Connector, enyo_appliance_js_1.EnyoApplianceStateEnum.Connected);
+        }
+        catch (error) {
+            console.error(`${this.constructor.name} ${this.applianceId}: Failed to re-assert Connected: ${error}`);
+            return;
+        }
+        this.appliedOffline = false;
+        this.retryManager.reset();
+        this.consecutiveReconnectFailures = 0;
+        await this.onConnectionRestored();
+    }
     sendCommandAcknowledge(messageId, acknowledgeMessage, answer, rejectionReason) {
         if (!this.dataBus || !this.applianceId) {
             return;
@@ -302,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;
@@ -350,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 },
@@ -376,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,
@@ -420,6 +477,10 @@ class SunspecInverter extends BaseSunspecDevice {
             if (await this.markOfflineIfUnhealthy()) {
                 return messages;
             }
+            // Healthy read: if a sibling on the same shared socket reconnected us
+            // (so our own tryReconnect() never ran), flip our appliance state back
+            // to Connected. No-op unless this device is still marked offline.
+            await this.reassertConnectedIfRecovered();
             if (inverterData) {
                 const pvPowerW = dcStrings.reduce((sum, s) => sum + (s.powerW || 0), 0);
                 console.debug(`Got PV Power from DC strings: ${pvPowerW}W`);
@@ -590,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,
@@ -608,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();
     }
@@ -1183,6 +1258,10 @@ class SunspecBattery extends BaseSunspecDevice {
             if (await this.markOfflineIfUnhealthy()) {
                 return messages;
             }
+            // Healthy read: if a sibling on the same shared socket reconnected us
+            // (so our own tryReconnect() never ran), flip our appliance state back
+            // to Connected. No-op unless this device is still marked offline.
+            await this.reassertConnectedIfRecovered();
             if (batteryData) {
                 // See `selectLiveBatteryPowerW` for the source-preference rationale.
                 const batteryPowerW = selectLiveBatteryPowerW(mpptBatteryPowerW, batteryData);
@@ -1696,6 +1775,10 @@ class SunspecMeter extends BaseSunspecDevice {
             if (await this.markOfflineIfUnhealthy()) {
                 return messages;
             }
+            // Healthy read: if a sibling on the same shared socket reconnected us
+            // (so our own tryReconnect() never ran), flip our appliance state back
+            // to Connected. No-op unless this device is still marked offline.
+            await this.reassertConnectedIfRecovered();
             if (meterData) {
                 const meterMessage = {
                     id: (0, node_crypto_1.randomUUID)(),

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

@@ -27,6 +27,15 @@ export declare abstract class BaseSunspecDevice {
     protected dataBus?: EnergyAppDataBus;
     protected retryManager: ConnectionRetryManager;
     protected consecutiveReconnectFailures: number;
+    /**
+     * True once {@link markOffline} has set the appliance state to Offline and
+     * it has not yet been re-asserted Connected. Used by
+     * {@link reassertConnectedIfRecovered} to heal the shared-socket case: when
+     * a sibling device on the same unit wins the reconnect race, this device's
+     * readData() sees isConnected() === true and skips tryReconnect(), so it
+     * would otherwise stay Offline forever despite reading data fine.
+     */
+    private appliedOffline;
     /**
      * Prefix used when persisting calibration snapshots via the library's
      * {@link SnapshotService}. Kept identical to the key the SDK used before
@@ -90,6 +99,20 @@ export declare abstract class BaseSunspecDevice {
      * connection after the backoff interval. Then update appliance state.
      */
     protected markOffline(): Promise<void>;
+    /**
+     * Heal the shared-socket recovery gap. When several devices share one
+     * SunspecModbusClient on the same unit (e.g. a Fronius GEN24 inverter and
+     * its battery), only the device that detects !isConnected() first runs
+     * tryReconnect() — and that is the only path that flips the appliance back
+     * to Connected. Siblings then see isConnected() === true on their next
+     * readData() and skip tryReconnect() entirely, so without this they would
+     * stay Offline forever despite reading data fine.
+     *
+     * Call this on the success path of readData() (after the
+     * markOfflineIfUnhealthy() guard has confirmed the unit is healthy). It is
+     * a cheap no-op unless this device was previously marked offline.
+     */
+    protected reassertConnectedIfRecovered(): Promise<void>;
     protected sendCommandAcknowledge(messageId: string, acknowledgeMessage: EnyoDataBusMessageEnum | string, answer: EnyoCommandAcknowledgeAnswerEnum, rejectionReason?: string): void;
     /**
      * Build a typed {@link SnapshotService} bound to this appliance's calibration storage,
@@ -108,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.81';
+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.81";
+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

@@ -27,6 +27,15 @@ export declare abstract class BaseSunspecDevice {
     protected dataBus?: EnergyAppDataBus;
     protected retryManager: ConnectionRetryManager;
     protected consecutiveReconnectFailures: number;
+    /**
+     * True once {@link markOffline} has set the appliance state to Offline and
+     * it has not yet been re-asserted Connected. Used by
+     * {@link reassertConnectedIfRecovered} to heal the shared-socket case: when
+     * a sibling device on the same unit wins the reconnect race, this device's
+     * readData() sees isConnected() === true and skips tryReconnect(), so it
+     * would otherwise stay Offline forever despite reading data fine.
+     */
+    private appliedOffline;
     /**
      * Prefix used when persisting calibration snapshots via the library's
      * {@link SnapshotService}. Kept identical to the key the SDK used before
@@ -90,6 +99,20 @@ export declare abstract class BaseSunspecDevice {
      * connection after the backoff interval. Then update appliance state.
      */
     protected markOffline(): Promise<void>;
+    /**
+     * Heal the shared-socket recovery gap. When several devices share one
+     * SunspecModbusClient on the same unit (e.g. a Fronius GEN24 inverter and
+     * its battery), only the device that detects !isConnected() first runs
+     * tryReconnect() — and that is the only path that flips the appliance back
+     * to Connected. Siblings then see isConnected() === true on their next
+     * readData() and skip tryReconnect() entirely, so without this they would
+     * stay Offline forever despite reading data fine.
+     *
+     * Call this on the success path of readData() (after the
+     * markOfflineIfUnhealthy() guard has confirmed the unit is healthy). It is
+     * a cheap no-op unless this device was previously marked offline.
+     */
+    protected reassertConnectedIfRecovered(): Promise<void>;
     protected sendCommandAcknowledge(messageId: string, acknowledgeMessage: EnyoDataBusMessageEnum | string, answer: EnyoCommandAcknowledgeAnswerEnum, rejectionReason?: string): void;
     /**
      * Build a typed {@link SnapshotService} bound to this appliance's calibration storage,
@@ -108,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";
@@ -101,6 +101,15 @@ export class BaseSunspecDevice {
     dataBus;
     retryManager;
     consecutiveReconnectFailures = 0;
+    /**
+     * True once {@link markOffline} has set the appliance state to Offline and
+     * it has not yet been re-asserted Connected. Used by
+     * {@link reassertConnectedIfRecovered} to heal the shared-socket case: when
+     * a sibling device on the same unit wins the reconnect race, this device's
+     * readData() sees isConnected() === true and skips tryReconnect(), so it
+     * would otherwise stay Offline forever despite reading data fine.
+     */
+    appliedOffline = false;
     /**
      * Prefix used when persisting calibration snapshots via the library's
      * {@link SnapshotService}. Kept identical to the key the SDK used before
@@ -175,6 +184,7 @@ export class BaseSunspecDevice {
                 if (this.applianceId) {
                     await this.applianceManager.updateApplianceState(this.applianceId, EnyoApplianceConnectionType.Connector, EnyoApplianceStateEnum.Connected);
                 }
+                this.appliedOffline = false;
                 await this.onConnectionRestored();
                 const postStats = this.sunspecClient.getConnectionStats();
                 console.log(`${this.constructor.name} ${this.applianceId}: Reconnection successful after ${attempt} attempt(s) (opens=${postStats.opens}, closes=${postStats.closes}, openUnits=${postStats.openUnits})`);
@@ -243,12 +253,46 @@ export class BaseSunspecDevice {
         if (this.applianceId) {
             try {
                 await this.applianceManager.updateApplianceState(this.applianceId, EnyoApplianceConnectionType.Connector, EnyoApplianceStateEnum.Offline);
+                this.appliedOffline = true;
             }
             catch (error) {
                 console.error(`${this.constructor.name} ${this.applianceId}: Failed to mark appliance offline: ${error}`);
             }
         }
     }
+    /**
+     * Heal the shared-socket recovery gap. When several devices share one
+     * SunspecModbusClient on the same unit (e.g. a Fronius GEN24 inverter and
+     * its battery), only the device that detects !isConnected() first runs
+     * tryReconnect() — and that is the only path that flips the appliance back
+     * to Connected. Siblings then see isConnected() === true on their next
+     * readData() and skip tryReconnect() entirely, so without this they would
+     * stay Offline forever despite reading data fine.
+     *
+     * Call this on the success path of readData() (after the
+     * markOfflineIfUnhealthy() guard has confirmed the unit is healthy). It is
+     * a cheap no-op unless this device was previously marked offline.
+     */
+    async reassertConnectedIfRecovered() {
+        if (!this.appliedOffline || !this.applianceId) {
+            return;
+        }
+        if (!this.sunspecClient.isHealthy(this.unitId)) {
+            return;
+        }
+        console.log(`${this.constructor.name} ${this.applianceId}: connection recovered via shared socket — re-asserting Connected`);
+        try {
+            await this.applianceManager.updateApplianceState(this.applianceId, EnyoApplianceConnectionType.Connector, EnyoApplianceStateEnum.Connected);
+        }
+        catch (error) {
+            console.error(`${this.constructor.name} ${this.applianceId}: Failed to re-assert Connected: ${error}`);
+            return;
+        }
+        this.appliedOffline = false;
+        this.retryManager.reset();
+        this.consecutiveReconnectFailures = 0;
+        await this.onConnectionRestored();
+    }
     sendCommandAcknowledge(messageId, acknowledgeMessage, answer, rejectionReason) {
         if (!this.dataBus || !this.applianceId) {
             return;
@@ -295,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;
@@ -343,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 },
@@ -369,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,
@@ -413,6 +470,10 @@ export class SunspecInverter extends BaseSunspecDevice {
             if (await this.markOfflineIfUnhealthy()) {
                 return messages;
             }
+            // Healthy read: if a sibling on the same shared socket reconnected us
+            // (so our own tryReconnect() never ran), flip our appliance state back
+            // to Connected. No-op unless this device is still marked offline.
+            await this.reassertConnectedIfRecovered();
             if (inverterData) {
                 const pvPowerW = dcStrings.reduce((sum, s) => sum + (s.powerW || 0), 0);
                 console.debug(`Got PV Power from DC strings: ${pvPowerW}W`);
@@ -583,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,
@@ -601,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();
     }
@@ -1175,6 +1250,10 @@ export class SunspecBattery extends BaseSunspecDevice {
             if (await this.markOfflineIfUnhealthy()) {
                 return messages;
             }
+            // Healthy read: if a sibling on the same shared socket reconnected us
+            // (so our own tryReconnect() never ran), flip our appliance state back
+            // to Connected. No-op unless this device is still marked offline.
+            await this.reassertConnectedIfRecovered();
             if (batteryData) {
                 // See `selectLiveBatteryPowerW` for the source-preference rationale.
                 const batteryPowerW = selectLiveBatteryPowerW(mpptBatteryPowerW, batteryData);
@@ -1687,6 +1766,10 @@ export class SunspecMeter extends BaseSunspecDevice {
             if (await this.markOfflineIfUnhealthy()) {
                 return messages;
             }
+            // Healthy read: if a sibling on the same shared socket reconnected us
+            // (so our own tryReconnect() never ran), flip our appliance state back
+            // to Connected. No-op unless this device is still marked offline.
+            await this.reassertConnectedIfRecovered();
             if (meterData) {
                 const meterMessage = {
                     id: randomUUID(),

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.81";
+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.81';
+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.81",
+  "version": "0.0.83",
   "description": "enyo Energy Sunspec SDK",
   "type": "module",
   "main": "dist/index.js",
@@ -41,7 +41,7 @@
   },
   "dependencies": {
     "@enyo-energy/appliance-calibration": "0.0.2",
-    "@enyo-energy/energy-app-sdk": "^0.0.159"
+    "@enyo-energy/energy-app-sdk": "^0.0.160"
   },
   "volta": {
     "node": "22.17.0"