@enyo-energy/sunspec-sdk 0.0.48 → 0.0.50

package/dist/cjs/sunspec-devices.cjs

@@ -9,6 +9,77 @@ const enyo_data_bus_value_js_1 = require("@enyo-energy/energy-app-sdk/dist/types
 const enyo_source_enum_js_1 = require("@enyo-energy/energy-app-sdk/dist/types/enyo-source.enum.js");
 const enyo_meter_appliance_js_1 = require("@enyo-energy/energy-app-sdk/dist/types/enyo-meter-appliance.js");
 const enyo_battery_appliance_js_1 = require("@enyo-energy/energy-app-sdk/dist/types/enyo-battery-appliance.js");
+/**
+ * Translated messages (en, de) for the standard SunSpec inverter Evt1 bits.
+ * Consumers can render these directly to end users; if no entry matches a
+ * locale, the SDK contract is to fall back to the machine-readable `code`.
+ */
+const SUNSPEC_INVERTER_EVENT1_MESSAGES = {
+    [sunspec_interfaces_js_1.SunspecInverterEvent1.GROUND_FAULT]: [
+        { language: 'en', message: 'Ground fault detected' },
+        { language: 'de', message: 'Erdschluss erkannt' },
+    ],
+    [sunspec_interfaces_js_1.SunspecInverterEvent1.DC_OVER_VOLT]: [
+        { language: 'en', message: 'DC over-voltage' },
+        { language: 'de', message: 'DC-Überspannung' },
+    ],
+    [sunspec_interfaces_js_1.SunspecInverterEvent1.AC_DISCONNECT]: [
+        { language: 'en', message: 'AC disconnect open' },
+        { language: 'de', message: 'AC-Trennschalter offen' },
+    ],
+    [sunspec_interfaces_js_1.SunspecInverterEvent1.DC_DISCONNECT]: [
+        { language: 'en', message: 'DC disconnect open' },
+        { language: 'de', message: 'DC-Trennschalter offen' },
+    ],
+    [sunspec_interfaces_js_1.SunspecInverterEvent1.GRID_DISCONNECT]: [
+        { language: 'en', message: 'Grid disconnected' },
+        { language: 'de', message: 'Netz getrennt' },
+    ],
+    [sunspec_interfaces_js_1.SunspecInverterEvent1.CABINET_OPEN]: [
+        { language: 'en', message: 'Cabinet open' },
+        { language: 'de', message: 'Gehäuse offen' },
+    ],
+    [sunspec_interfaces_js_1.SunspecInverterEvent1.MANUAL_SHUTDOWN]: [
+        { language: 'en', message: 'Manual shutdown' },
+        { language: 'de', message: 'Manuelle Abschaltung' },
+    ],
+    [sunspec_interfaces_js_1.SunspecInverterEvent1.OVER_TEMP]: [
+        { language: 'en', message: 'Over temperature' },
+        { language: 'de', message: 'Übertemperatur' },
+    ],
+    [sunspec_interfaces_js_1.SunspecInverterEvent1.OVER_FREQUENCY]: [
+        { language: 'en', message: 'AC frequency above limit' },
+        { language: 'de', message: 'AC-Frequenz zu hoch' },
+    ],
+    [sunspec_interfaces_js_1.SunspecInverterEvent1.UNDER_FREQUENCY]: [
+        { language: 'en', message: 'AC frequency below limit' },
+        { language: 'de', message: 'AC-Frequenz zu niedrig' },
+    ],
+    [sunspec_interfaces_js_1.SunspecInverterEvent1.AC_OVER_VOLT]: [
+        { language: 'en', message: 'AC over-voltage' },
+        { language: 'de', message: 'AC-Überspannung' },
+    ],
+    [sunspec_interfaces_js_1.SunspecInverterEvent1.AC_UNDER_VOLT]: [
+        { language: 'en', message: 'AC under-voltage' },
+        { language: 'de', message: 'AC-Unterspannung' },
+    ],
+    [sunspec_interfaces_js_1.SunspecInverterEvent1.BLOWN_STRING_FUSE]: [
+        { language: 'en', message: 'Blown string fuse' },
+        { language: 'de', message: 'Strangsicherung defekt' },
+    ],
+    [sunspec_interfaces_js_1.SunspecInverterEvent1.UNDER_TEMP]: [
+        { language: 'en', message: 'Under temperature' },
+        { language: 'de', message: 'Untertemperatur' },
+    ],
+    [sunspec_interfaces_js_1.SunspecInverterEvent1.MEMORY_LOSS]: [
+        { language: 'en', message: 'Memory loss' },
+        { language: 'de', message: 'Speicherverlust' },
+    ],
+    [sunspec_interfaces_js_1.SunspecInverterEvent1.HW_TEST_FAILURE]: [
+        { language: 'en', message: 'Hardware self-test failed' },
+        { language: 'de', message: 'Hardware-Selbsttest fehlgeschlagen' },
+    ],
+};
 /**
  * Base abstract class for all Sunspec devices
  */
@@ -26,6 +97,7 @@ class BaseSunspecDevice {
     dataBusListenerId;
     dataBus;
     retryManager;
+    consecutiveReconnectFailures = 0;
     constructor(energyApp, name, networkDevice, sunspecClient, applianceManager, unitId = 1, port = 502, baseAddress = 40000, retryConfig, appliance) {
         this.energyApp = energyApp;
         this.name = name;
@@ -84,6 +156,7 @@ class BaseSunspecDevice {
                 // Re-discover models after reconnect
                 await this.sunspecClient.discoverModels(this.baseAddress);
                 this.retryManager.reset();
+                this.consecutiveReconnectFailures = 0;
                 // Update appliance state to Connected
                 if (this.applianceId) {
                     await this.applianceManager.updateApplianceState(this.applianceId, enyo_appliance_js_1.EnyoApplianceConnectionType.Connector, enyo_appliance_js_1.EnyoApplianceStateEnum.Connected);
@@ -92,12 +165,23 @@ class BaseSunspecDevice {
                 console.log(`${this.constructor.name} ${this.applianceId}: Reconnection successful after ${attempt} attempt(s) (opens=${postStats.opens}, closes=${postStats.closes}, current=${postStats.currentlyOpen})`);
                 return true;
             }
+            this.consecutiveReconnectFailures += 1;
+            await this.onConnectionFailure(this.consecutiveReconnectFailures);
         }
         catch (error) {
             console.error(`${this.constructor.name} ${this.applianceId}: Reconnect attempt #${attempt} failed: ${error}`);
+            this.consecutiveReconnectFailures += 1;
+            await this.onConnectionFailure(this.consecutiveReconnectFailures);
         }
         return false;
     }
+    /**
+     * Hook for subclasses to react to a failed reconnect attempt. Called once
+     * per failed attempt with the running consecutive-failure count.
+     */
+    async onConnectionFailure(_consecutiveFailures) {
+        // Default: no-op. SunspecInverter overrides to publish a faulted status.
+    }
     /**
      * Mark the device as offline: close the underlying socket so the next readData()
      * cycle sees isConnected() === false and tryReconnect() can establish a fresh
@@ -152,6 +236,10 @@ exports.BaseSunspecDevice = BaseSunspecDevice;
  */
 class SunspecInverter extends BaseSunspecDevice {
     capabilities;
+    /** Emit a connection-lost faulted status after this many consecutive failed reconnect attempts. */
+    static CONNECTION_FAULT_THRESHOLD = 3;
+    storage;
+    errorState = { activeCodes: [], lastStatus: 'healthy' };
     constructor(energyApp, name, networkDevice, sunspecClient, applianceManager, unitId = 1, port = 502, baseAddress = 40000, capabilities = [], retryConfig, appliance) {
         super(energyApp, name, networkDevice, sunspecClient, applianceManager, unitId, port, baseAddress, retryConfig, appliance);
         this.capabilities = capabilities;
@@ -221,6 +309,7 @@ class SunspecInverter extends BaseSunspecDevice {
         if (mpptModel) {
             console.log(`MPPT model found for inverter ${this.networkDevice.hostname}`);
         }
+        await this.loadErrorState();
         this.startDataBusListening();
     }
     async disconnect() {
@@ -246,7 +335,7 @@ class SunspecInverter extends BaseSunspecDevice {
             const dcStrings = this.mapMPPTToStrings(mpptDataList);
             if (inverterData) {
                 const pvPowerW = dcStrings.reduce((sum, s) => sum + (s.powerW || 0), 0);
-                console.log(`Got PV Power from DC strings: ${pvPowerW}W`);
+                console.debug(`Got PV Power from DC strings: ${pvPowerW}W`);
                 const inverterMessage = {
                     id: (0, node_crypto_1.randomUUID)(),
                     message: enyo_data_bus_value_js_1.EnyoDataBusMessageEnum.InverterValuesUpdateV1,
@@ -268,7 +357,12 @@ class SunspecInverter extends BaseSunspecDevice {
                     }
                 };
                 messages.push(inverterMessage);
+                const statusMessage = await this.detectAndEmitStatusTransition(inverterData, timestamp);
+                if (statusMessage) {
+                    messages.push(statusMessage);
+                }
             }
+            this.consecutiveReconnectFailures = 0;
             if (this.applianceId) {
                 const appliance = await this.applianceManager.findApplianceById(this.applianceId);
                 await this.applianceManager.updateAppliance(this.applianceId, {
@@ -286,6 +380,166 @@ class SunspecInverter extends BaseSunspecDevice {
         }
         return messages;
     }
+    /**
+     * Decode all active error bits from the inverter event registers into
+     * `EnyoApplianceErrorCode`s. Override in a subclass to customize the
+     * mapping wholesale, or override the per-register helpers
+     * (`mapEvt1Bit`, `mapEvt2Bit`, `mapVendorEventBit`) to customize a
+     * specific register — typical use-case is vendor-specific bit names.
+     */
+    decodeActiveErrors(data) {
+        const codes = [];
+        const codeIds = [];
+        const collect = (raw, mapper) => {
+            const value = raw ?? 0;
+            for (let bit = 0; bit < 32; bit++) {
+                if ((value & (1 << bit)) === 0)
+                    continue;
+                const code = mapper(bit);
+                if (!code)
+                    continue;
+                codes.push(code);
+                codeIds.push(code.code);
+            }
+        };
+        collect(data.events, (bit) => this.mapEvt1Bit(bit));
+        collect(data.events2, (bit) => this.mapEvt2Bit(bit));
+        collect(data.vendorEvents1, (bit) => this.mapVendorEventBit(1, bit));
+        collect(data.vendorEvents2, (bit) => this.mapVendorEventBit(2, bit));
+        collect(data.vendorEvents3, (bit) => this.mapVendorEventBit(3, bit));
+        collect(data.vendorEvents4, (bit) => this.mapVendorEventBit(4, bit));
+        codeIds.sort();
+        return { codes, codeIds };
+    }
+    /**
+     * Map a set bit in the standard Evt1 register to an error code with
+     * de/en translations. Override to customize standard-bit translations.
+     */
+    mapEvt1Bit(bit) {
+        const named = sunspec_interfaces_js_1.SunspecInverterEvent1[bit];
+        if (!named) {
+            return { code: `inverter_event1_bit_${bit}` };
+        }
+        const messages = SUNSPEC_INVERTER_EVENT1_MESSAGES[bit];
+        return messages ? { code: named, messages } : { code: named };
+    }
+    /**
+     * Map a set bit in the Evt2 register. Reserved in the SunSpec spec, so
+     * the default returns `undefined` — Evt2 bits are not treated as errors.
+     * Override in a vendor-specific subclass to opt specific bits in as
+     * errors.
+     */
+    mapEvt2Bit(_bit) {
+        return undefined;
+    }
+    /**
+     * Map a set bit in one of the four vendor-specific event registers.
+     * Vendor bits are not standardized and many are informational rather
+     * than faults, so the default returns `undefined` and no error code is
+     * emitted. Override in a vendor-specific subclass to opt specific bits
+     * in as errors.
+     */
+    mapVendorEventBit(_registerIndex, _bit) {
+        return undefined;
+    }
+    hasErrorSetChanged(newCodeIds) {
+        const prev = this.errorState.activeCodes;
+        if (prev.length !== newCodeIds.length)
+            return true;
+        for (let i = 0; i < prev.length; i++) {
+            if (prev[i] !== newCodeIds[i])
+                return true;
+        }
+        return false;
+    }
+    buildStatusMessage(status, errorCodes, timestamp) {
+        return {
+            id: (0, node_crypto_1.randomUUID)(),
+            message: enyo_data_bus_value_js_1.EnyoDataBusMessageEnum.ApplianceStateUpdateV1,
+            type: 'message',
+            source: enyo_source_enum_js_1.EnyoSourceEnum.Device,
+            applianceId: this.applianceId,
+            timestampIso: timestamp.toISOString(),
+            data: {
+                status,
+                errorCodes,
+            }
+        };
+    }
+    storageKey() {
+        return `sunspec-inverter-error-state-${this.applianceId}`;
+    }
+    async loadErrorState() {
+        try {
+            this.storage = this.energyApp.useStorage();
+            const loaded = await this.storage.load(this.storageKey());
+            if (loaded) {
+                this.errorState = loaded;
+                console.log(`Inverter ${this.applianceId}: loaded persisted error state (lastStatus=${loaded.lastStatus}, codes=[${loaded.activeCodes.join(', ')}])`);
+            }
+        }
+        catch (error) {
+            console.error(`Inverter ${this.applianceId}: failed to load persisted error state: ${error}`);
+        }
+    }
+    async persistErrorState() {
+        if (!this.storage)
+            return;
+        try {
+            await this.storage.save(this.storageKey(), this.errorState);
+        }
+        catch (error) {
+            console.error(`Inverter ${this.applianceId}: failed to persist error state: ${error}`);
+        }
+    }
+    async detectAndEmitStatusTransition(data, timestamp) {
+        if (!this.applianceId)
+            return undefined;
+        const { codes, codeIds } = this.decodeActiveErrors(data);
+        const recoveringFromConnectionLoss = this.errorState.lastStatus === 'connection_lost';
+        if (!recoveringFromConnectionLoss && !this.hasErrorSetChanged(codeIds)) {
+            return undefined;
+        }
+        const newStatus = codeIds.length === 0
+            ? enyo_appliance_js_1.EnyoApplianceStatusEnum.Healthy
+            : enyo_appliance_js_1.EnyoApplianceStatusEnum.Faulted;
+        this.errorState = {
+            evt1: data.events,
+            evt2: data.events2,
+            evtVnd1: data.vendorEvents1,
+            evtVnd2: data.vendorEvents2,
+            evtVnd3: data.vendorEvents3,
+            evtVnd4: data.vendorEvents4,
+            activeCodes: codeIds,
+            lastStatus: newStatus === enyo_appliance_js_1.EnyoApplianceStatusEnum.Healthy ? 'healthy' : 'faulted',
+        };
+        await this.persistErrorState();
+        console.log(`Inverter ${this.applianceId}: status transition -> ${newStatus} (codes=[${codeIds.join(', ')}])`);
+        return this.buildStatusMessage(newStatus, codes, timestamp);
+    }
+    async onConnectionFailure(consecutiveFailures) {
+        if (!this.applianceId || !this.dataBus)
+            return;
+        if (consecutiveFailures < SunspecInverter.CONNECTION_FAULT_THRESHOLD)
+            return;
+        if (this.errorState.lastStatus === 'connection_lost')
+            return;
+        const errorCodes = [{
+                code: sunspec_interfaces_js_1.SUNSPEC_CONNECTION_LOST_CODE,
+                messages: [
+                    { language: 'en', message: 'Modbus connection to inverter lost' },
+                    { language: 'de', message: 'Modbus-Verbindung zum Wechselrichter verloren' },
+                ]
+            }];
+        const message = this.buildStatusMessage(enyo_appliance_js_1.EnyoApplianceStatusEnum.Faulted, errorCodes, new Date());
+        this.errorState = {
+            activeCodes: [sunspec_interfaces_js_1.SUNSPEC_CONNECTION_LOST_CODE],
+            lastStatus: 'connection_lost',
+        };
+        await this.persistErrorState();
+        console.log(`Inverter ${this.applianceId}: emitting faulted (${sunspec_interfaces_js_1.SUNSPEC_CONNECTION_LOST_CODE}) after ${consecutiveFailures} consecutive reconnect failures`);
+        this.dataBus.sendMessage([message]);
+    }
     mapOperatingState(state) {
         if (!state)
             return enyo_data_bus_value_js_1.EnyoInverterStateEnum.Off;

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

@@ -1,6 +1,6 @@
-import { type IRetryConfig, type SunspecBatteryBaseData, SunspecBatteryCapability, type SunspecBatteryControls, SunspecInverterCapability, SunspecMeterCapability, SunspecStorageMode } from "./sunspec-interfaces.cjs";
+import { type IRetryConfig, type SunspecBatteryBaseData, SunspecBatteryCapability, type SunspecBatteryControls, type SunspecInverterData, SunspecInverterCapability, SunspecMeterCapability, SunspecStorageMode } from "./sunspec-interfaces.cjs";
 import { ApplianceManager, EnergyApp } from "@enyo-energy/energy-app-sdk";
-import { type EnyoAppliance, EnyoApplianceName } from "@enyo-energy/energy-app-sdk/dist/types/enyo-appliance.js";
+import { type EnyoAppliance, type EnyoApplianceErrorCode, EnyoApplianceName } from "@enyo-energy/energy-app-sdk/dist/types/enyo-appliance.js";
 import { EnyoNetworkDevice } from "@enyo-energy/energy-app-sdk/dist/types/enyo-network-device.js";
 import { SunspecModbusClient } from "./sunspec-modbus-client.cjs";
 import { ConnectionRetryManager } from "./connection-retry-manager.cjs";
@@ -23,6 +23,7 @@ export declare abstract class BaseSunspecDevice {
     protected dataBusListenerId?: string;
     protected dataBus?: EnergyAppDataBus;
     protected retryManager: ConnectionRetryManager;
+    protected consecutiveReconnectFailures: number;
     constructor(energyApp: EnergyApp, name: EnyoApplianceName[], networkDevice: EnyoNetworkDevice, sunspecClient: SunspecModbusClient, applianceManager: ApplianceManager, unitId?: number, port?: number, baseAddress?: number, retryConfig?: IRetryConfig, appliance?: EnyoAppliance);
     /**
      * Connect to the device and create/update the appliance
@@ -53,6 +54,11 @@ export declare abstract class BaseSunspecDevice {
      * Returns true if reconnection succeeded.
      */
     protected tryReconnect(): Promise<boolean>;
+    /**
+     * Hook for subclasses to react to a failed reconnect attempt. Called once
+     * per failed attempt with the running consecutive-failure count.
+     */
+    protected onConnectionFailure(_consecutiveFailures: number): Promise<void>;
     /**
      * Mark the device as offline: close the underlying socket so the next readData()
      * cycle sees isConnected() === false and tryReconnect() can establish a fresh
@@ -66,10 +72,52 @@ export declare abstract class BaseSunspecDevice {
  */
 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;
+    private storage?;
+    private errorState;
     constructor(energyApp: EnergyApp, name: EnyoApplianceName[], networkDevice: EnyoNetworkDevice, sunspecClient: SunspecModbusClient, applianceManager: ApplianceManager, unitId?: number, port?: number, baseAddress?: number, capabilities?: SunspecInverterCapability[], retryConfig?: IRetryConfig, appliance?: EnyoAppliance);
     connect(): Promise<void>;
     disconnect(): Promise<void>;
     readData(clockId: string, resolution: '10s' | '30s' | '1m' | '15m'): Promise<EnyoDataBusMessage[]>;
+    /**
+     * Decode all active error bits from the inverter event registers into
+     * `EnyoApplianceErrorCode`s. Override in a subclass to customize the
+     * mapping wholesale, or override the per-register helpers
+     * (`mapEvt1Bit`, `mapEvt2Bit`, `mapVendorEventBit`) to customize a
+     * specific register — typical use-case is vendor-specific bit names.
+     */
+    protected decodeActiveErrors(data: SunspecInverterData): {
+        codes: EnyoApplianceErrorCode[];
+        codeIds: string[];
+    };
+    /**
+     * Map a set bit in the standard Evt1 register to an error code with
+     * de/en translations. Override to customize standard-bit translations.
+     */
+    protected mapEvt1Bit(bit: number): EnyoApplianceErrorCode | undefined;
+    /**
+     * Map a set bit in the Evt2 register. Reserved in the SunSpec spec, so
+     * the default returns `undefined` — Evt2 bits are not treated as errors.
+     * Override in a vendor-specific subclass to opt specific bits in as
+     * errors.
+     */
+    protected mapEvt2Bit(_bit: number): EnyoApplianceErrorCode | undefined;
+    /**
+     * Map a set bit in one of the four vendor-specific event registers.
+     * Vendor bits are not standardized and many are informational rather
+     * than faults, so the default returns `undefined` and no error code is
+     * emitted. Override in a vendor-specific subclass to opt specific bits
+     * in as errors.
+     */
+    protected mapVendorEventBit(_registerIndex: 1 | 2 | 3 | 4, _bit: number): EnyoApplianceErrorCode | undefined;
+    private hasErrorSetChanged;
+    private buildStatusMessage;
+    private storageKey;
+    private loadErrorState;
+    private persistErrorState;
+    private detectAndEmitStatusTransition;
+    protected onConnectionFailure(consecutiveFailures: number): Promise<void>;
     private mapOperatingState;
     /**
      * Map MPPT data to DC string structure for data bus

package/dist/cjs/sunspec-interfaces.cjs

@@ -3,7 +3,7 @@
  * SunSpec block interfaces with block numbers
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SunspecMeterCapability = 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.SunspecModelId = exports.DEFAULT_RETRY_CONFIG = void 0;
+exports.SunspecMeterCapability = 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.DEFAULT_RETRY_CONFIG = {
     phases: [
         { intervalMs: 10_000, durationMs: 60_000 }, // Phase 1: every 10s for 1 minute
@@ -33,6 +33,34 @@ var SunspecModelId;
     SunspecModelId[SunspecModelId["Controls"] = 123] = "Controls";
     SunspecModelId[SunspecModelId["EndMarker"] = 65535] = "EndMarker";
 })(SunspecModelId || (exports.SunspecModelId = SunspecModelId = {}));
+/**
+ * Inverter Event 1 bit positions for Model 101/103
+ * Offset 40-41: Evt1 - Inverter event bitfield
+ */
+var SunspecInverterEvent1;
+(function (SunspecInverterEvent1) {
+    SunspecInverterEvent1[SunspecInverterEvent1["GROUND_FAULT"] = 0] = "GROUND_FAULT";
+    SunspecInverterEvent1[SunspecInverterEvent1["DC_OVER_VOLT"] = 1] = "DC_OVER_VOLT";
+    SunspecInverterEvent1[SunspecInverterEvent1["AC_DISCONNECT"] = 2] = "AC_DISCONNECT";
+    SunspecInverterEvent1[SunspecInverterEvent1["DC_DISCONNECT"] = 3] = "DC_DISCONNECT";
+    SunspecInverterEvent1[SunspecInverterEvent1["GRID_DISCONNECT"] = 4] = "GRID_DISCONNECT";
+    SunspecInverterEvent1[SunspecInverterEvent1["CABINET_OPEN"] = 5] = "CABINET_OPEN";
+    SunspecInverterEvent1[SunspecInverterEvent1["MANUAL_SHUTDOWN"] = 6] = "MANUAL_SHUTDOWN";
+    SunspecInverterEvent1[SunspecInverterEvent1["OVER_TEMP"] = 7] = "OVER_TEMP";
+    SunspecInverterEvent1[SunspecInverterEvent1["OVER_FREQUENCY"] = 8] = "OVER_FREQUENCY";
+    SunspecInverterEvent1[SunspecInverterEvent1["UNDER_FREQUENCY"] = 9] = "UNDER_FREQUENCY";
+    SunspecInverterEvent1[SunspecInverterEvent1["AC_OVER_VOLT"] = 10] = "AC_OVER_VOLT";
+    SunspecInverterEvent1[SunspecInverterEvent1["AC_UNDER_VOLT"] = 11] = "AC_UNDER_VOLT";
+    SunspecInverterEvent1[SunspecInverterEvent1["BLOWN_STRING_FUSE"] = 12] = "BLOWN_STRING_FUSE";
+    SunspecInverterEvent1[SunspecInverterEvent1["UNDER_TEMP"] = 13] = "UNDER_TEMP";
+    SunspecInverterEvent1[SunspecInverterEvent1["MEMORY_LOSS"] = 14] = "MEMORY_LOSS";
+    SunspecInverterEvent1[SunspecInverterEvent1["HW_TEST_FAILURE"] = 15] = "HW_TEST_FAILURE";
+})(SunspecInverterEvent1 || (exports.SunspecInverterEvent1 = SunspecInverterEvent1 = {}));
+/**
+ * Error code emitted when the modbus connection has been lost for several
+ * consecutive reconnect attempts.
+ */
+exports.SUNSPEC_CONNECTION_LOST_CODE = 'modbus_connection_lost';
 /**
  * MPPT Operating State values for Model 160
  * These represent the DC module/string operating states

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

@@ -110,6 +110,48 @@ export interface SunspecInverterData extends SunspecBlock {
     vendorEvents3?: number;
     vendorEvents4?: number;
 }
+/**
+ * Inverter Event 1 bit positions for Model 101/103
+ * Offset 40-41: Evt1 - Inverter event bitfield
+ */
+export declare enum SunspecInverterEvent1 {
+    GROUND_FAULT = 0,
+    DC_OVER_VOLT = 1,
+    AC_DISCONNECT = 2,
+    DC_DISCONNECT = 3,
+    GRID_DISCONNECT = 4,
+    CABINET_OPEN = 5,
+    MANUAL_SHUTDOWN = 6,
+    OVER_TEMP = 7,
+    OVER_FREQUENCY = 8,
+    UNDER_FREQUENCY = 9,
+    AC_OVER_VOLT = 10,
+    AC_UNDER_VOLT = 11,
+    BLOWN_STRING_FUSE = 12,
+    UNDER_TEMP = 13,
+    MEMORY_LOSS = 14,
+    HW_TEST_FAILURE = 15
+}
+/**
+ * Error code emitted when the modbus connection has been lost for several
+ * consecutive reconnect attempts.
+ */
+export declare const SUNSPEC_CONNECTION_LOST_CODE = "modbus_connection_lost";
+/**
+ * Persisted error state for a SunSpec inverter, written to storage so the
+ * status reporter can detect transitions across process restarts and avoid
+ * re-emitting `faulted` for the same already-known errors.
+ */
+export interface SunspecInverterPersistedErrorState {
+    evt1?: number;
+    evt2?: number;
+    evtVnd1?: number;
+    evtVnd2?: number;
+    evtVnd3?: number;
+    evtVnd4?: number;
+    activeCodes: string[];
+    lastStatus: 'healthy' | 'faulted' | 'connection_lost';
+}
 /**
  * MPPT data structure based on Model 160
  *

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

package/dist/sunspec-devices.d.ts

@@ -1,6 +1,6 @@
-import { type IRetryConfig, type SunspecBatteryBaseData, SunspecBatteryCapability, type SunspecBatteryControls, SunspecInverterCapability, SunspecMeterCapability, SunspecStorageMode } from "./sunspec-interfaces.js";
+import { type IRetryConfig, type SunspecBatteryBaseData, SunspecBatteryCapability, type SunspecBatteryControls, type SunspecInverterData, SunspecInverterCapability, SunspecMeterCapability, SunspecStorageMode } from "./sunspec-interfaces.js";
 import { ApplianceManager, EnergyApp } from "@enyo-energy/energy-app-sdk";
-import { type EnyoAppliance, EnyoApplianceName } from "@enyo-energy/energy-app-sdk/dist/types/enyo-appliance.js";
+import { type EnyoAppliance, type EnyoApplianceErrorCode, EnyoApplianceName } from "@enyo-energy/energy-app-sdk/dist/types/enyo-appliance.js";
 import { EnyoNetworkDevice } from "@enyo-energy/energy-app-sdk/dist/types/enyo-network-device.js";
 import { SunspecModbusClient } from "./sunspec-modbus-client.js";
 import { ConnectionRetryManager } from "./connection-retry-manager.js";
@@ -23,6 +23,7 @@ export declare abstract class BaseSunspecDevice {
     protected dataBusListenerId?: string;
     protected dataBus?: EnergyAppDataBus;
     protected retryManager: ConnectionRetryManager;
+    protected consecutiveReconnectFailures: number;
     constructor(energyApp: EnergyApp, name: EnyoApplianceName[], networkDevice: EnyoNetworkDevice, sunspecClient: SunspecModbusClient, applianceManager: ApplianceManager, unitId?: number, port?: number, baseAddress?: number, retryConfig?: IRetryConfig, appliance?: EnyoAppliance);
     /**
      * Connect to the device and create/update the appliance
@@ -53,6 +54,11 @@ export declare abstract class BaseSunspecDevice {
      * Returns true if reconnection succeeded.
      */
     protected tryReconnect(): Promise<boolean>;
+    /**
+     * Hook for subclasses to react to a failed reconnect attempt. Called once
+     * per failed attempt with the running consecutive-failure count.
+     */
+    protected onConnectionFailure(_consecutiveFailures: number): Promise<void>;
     /**
      * Mark the device as offline: close the underlying socket so the next readData()
      * cycle sees isConnected() === false and tryReconnect() can establish a fresh
@@ -66,10 +72,52 @@ export declare abstract class BaseSunspecDevice {
  */
 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;
+    private storage?;
+    private errorState;
     constructor(energyApp: EnergyApp, name: EnyoApplianceName[], networkDevice: EnyoNetworkDevice, sunspecClient: SunspecModbusClient, applianceManager: ApplianceManager, unitId?: number, port?: number, baseAddress?: number, capabilities?: SunspecInverterCapability[], retryConfig?: IRetryConfig, appliance?: EnyoAppliance);
     connect(): Promise<void>;
     disconnect(): Promise<void>;
     readData(clockId: string, resolution: '10s' | '30s' | '1m' | '15m'): Promise<EnyoDataBusMessage[]>;
+    /**
+     * Decode all active error bits from the inverter event registers into
+     * `EnyoApplianceErrorCode`s. Override in a subclass to customize the
+     * mapping wholesale, or override the per-register helpers
+     * (`mapEvt1Bit`, `mapEvt2Bit`, `mapVendorEventBit`) to customize a
+     * specific register — typical use-case is vendor-specific bit names.
+     */
+    protected decodeActiveErrors(data: SunspecInverterData): {
+        codes: EnyoApplianceErrorCode[];
+        codeIds: string[];
+    };
+    /**
+     * Map a set bit in the standard Evt1 register to an error code with
+     * de/en translations. Override to customize standard-bit translations.
+     */
+    protected mapEvt1Bit(bit: number): EnyoApplianceErrorCode | undefined;
+    /**
+     * Map a set bit in the Evt2 register. Reserved in the SunSpec spec, so
+     * the default returns `undefined` — Evt2 bits are not treated as errors.
+     * Override in a vendor-specific subclass to opt specific bits in as
+     * errors.
+     */
+    protected mapEvt2Bit(_bit: number): EnyoApplianceErrorCode | undefined;
+    /**
+     * Map a set bit in one of the four vendor-specific event registers.
+     * Vendor bits are not standardized and many are informational rather
+     * than faults, so the default returns `undefined` and no error code is
+     * emitted. Override in a vendor-specific subclass to opt specific bits
+     * in as errors.
+     */
+    protected mapVendorEventBit(_registerIndex: 1 | 2 | 3 | 4, _bit: number): EnyoApplianceErrorCode | undefined;
+    private hasErrorSetChanged;
+    private buildStatusMessage;
+    private storageKey;
+    private loadErrorState;
+    private persistErrorState;
+    private detectAndEmitStatusTransition;
+    protected onConnectionFailure(consecutiveFailures: number): Promise<void>;
     private mapOperatingState;
     /**
      * Map MPPT data to DC string structure for data bus

package/dist/sunspec-devices.js

@@ -1,11 +1,82 @@
-import { SunspecBatteryChargeState, SunspecInverterCapability, SunspecModelId, SunspecMPPTOperatingState, SunspecStorageMode } from "./sunspec-interfaces.js";
+import { SunspecBatteryChargeState, SunspecInverterCapability, SunspecInverterEvent1, SunspecModelId, SunspecMPPTOperatingState, SunspecStorageMode, SUNSPEC_CONNECTION_LOST_CODE } from "./sunspec-interfaces.js";
 import { randomUUID } from "node:crypto";
-import { EnyoApplianceConnectionType, EnyoApplianceStateEnum, EnyoApplianceTopologyFeatureEnum, EnyoApplianceTypeEnum } from "@enyo-energy/energy-app-sdk/dist/types/enyo-appliance.js";
+import { EnyoApplianceConnectionType, EnyoApplianceStateEnum, EnyoApplianceStatusEnum, EnyoApplianceTopologyFeatureEnum, EnyoApplianceTypeEnum } from "@enyo-energy/energy-app-sdk/dist/types/enyo-appliance.js";
 import { ConnectionRetryManager } from "./connection-retry-manager.js";
 import { EnyoBatteryStateEnum, EnyoCommandAcknowledgeAnswerEnum, EnyoDataBusMessageEnum, EnyoInverterStateEnum, EnyoStringStateEnum } from "@enyo-energy/energy-app-sdk/dist/types/enyo-data-bus-value.js";
 import { EnyoSourceEnum } from "@enyo-energy/energy-app-sdk/dist/types/enyo-source.enum.js";
 import { EnyoMeterApplianceAvailableFeaturesEnum } from "@enyo-energy/energy-app-sdk/dist/types/enyo-meter-appliance.js";
 import { EnyoBatteryFeature, EnyoBatteryStorageMode } from "@enyo-energy/energy-app-sdk/dist/types/enyo-battery-appliance.js";
+/**
+ * Translated messages (en, de) for the standard SunSpec inverter Evt1 bits.
+ * Consumers can render these directly to end users; if no entry matches a
+ * locale, the SDK contract is to fall back to the machine-readable `code`.
+ */
+const SUNSPEC_INVERTER_EVENT1_MESSAGES = {
+    [SunspecInverterEvent1.GROUND_FAULT]: [
+        { language: 'en', message: 'Ground fault detected' },
+        { language: 'de', message: 'Erdschluss erkannt' },
+    ],
+    [SunspecInverterEvent1.DC_OVER_VOLT]: [
+        { language: 'en', message: 'DC over-voltage' },
+        { language: 'de', message: 'DC-Überspannung' },
+    ],
+    [SunspecInverterEvent1.AC_DISCONNECT]: [
+        { language: 'en', message: 'AC disconnect open' },
+        { language: 'de', message: 'AC-Trennschalter offen' },
+    ],
+    [SunspecInverterEvent1.DC_DISCONNECT]: [
+        { language: 'en', message: 'DC disconnect open' },
+        { language: 'de', message: 'DC-Trennschalter offen' },
+    ],
+    [SunspecInverterEvent1.GRID_DISCONNECT]: [
+        { language: 'en', message: 'Grid disconnected' },
+        { language: 'de', message: 'Netz getrennt' },
+    ],
+    [SunspecInverterEvent1.CABINET_OPEN]: [
+        { language: 'en', message: 'Cabinet open' },
+        { language: 'de', message: 'Gehäuse offen' },
+    ],
+    [SunspecInverterEvent1.MANUAL_SHUTDOWN]: [
+        { language: 'en', message: 'Manual shutdown' },
+        { language: 'de', message: 'Manuelle Abschaltung' },
+    ],
+    [SunspecInverterEvent1.OVER_TEMP]: [
+        { language: 'en', message: 'Over temperature' },
+        { language: 'de', message: 'Übertemperatur' },
+    ],
+    [SunspecInverterEvent1.OVER_FREQUENCY]: [
+        { language: 'en', message: 'AC frequency above limit' },
+        { language: 'de', message: 'AC-Frequenz zu hoch' },
+    ],
+    [SunspecInverterEvent1.UNDER_FREQUENCY]: [
+        { language: 'en', message: 'AC frequency below limit' },
+        { language: 'de', message: 'AC-Frequenz zu niedrig' },
+    ],
+    [SunspecInverterEvent1.AC_OVER_VOLT]: [
+        { language: 'en', message: 'AC over-voltage' },
+        { language: 'de', message: 'AC-Überspannung' },
+    ],
+    [SunspecInverterEvent1.AC_UNDER_VOLT]: [
+        { language: 'en', message: 'AC under-voltage' },
+        { language: 'de', message: 'AC-Unterspannung' },
+    ],
+    [SunspecInverterEvent1.BLOWN_STRING_FUSE]: [
+        { language: 'en', message: 'Blown string fuse' },
+        { language: 'de', message: 'Strangsicherung defekt' },
+    ],
+    [SunspecInverterEvent1.UNDER_TEMP]: [
+        { language: 'en', message: 'Under temperature' },
+        { language: 'de', message: 'Untertemperatur' },
+    ],
+    [SunspecInverterEvent1.MEMORY_LOSS]: [
+        { language: 'en', message: 'Memory loss' },
+        { language: 'de', message: 'Speicherverlust' },
+    ],
+    [SunspecInverterEvent1.HW_TEST_FAILURE]: [
+        { language: 'en', message: 'Hardware self-test failed' },
+        { language: 'de', message: 'Hardware-Selbsttest fehlgeschlagen' },
+    ],
+};
 /**
  * Base abstract class for all Sunspec devices
  */
@@ -23,6 +94,7 @@ export class BaseSunspecDevice {
     dataBusListenerId;
     dataBus;
     retryManager;
+    consecutiveReconnectFailures = 0;
     constructor(energyApp, name, networkDevice, sunspecClient, applianceManager, unitId = 1, port = 502, baseAddress = 40000, retryConfig, appliance) {
         this.energyApp = energyApp;
         this.name = name;
@@ -81,6 +153,7 @@ export class BaseSunspecDevice {
                 // Re-discover models after reconnect
                 await this.sunspecClient.discoverModels(this.baseAddress);
                 this.retryManager.reset();
+                this.consecutiveReconnectFailures = 0;
                 // Update appliance state to Connected
                 if (this.applianceId) {
                     await this.applianceManager.updateApplianceState(this.applianceId, EnyoApplianceConnectionType.Connector, EnyoApplianceStateEnum.Connected);
@@ -89,12 +162,23 @@ export class BaseSunspecDevice {
                 console.log(`${this.constructor.name} ${this.applianceId}: Reconnection successful after ${attempt} attempt(s) (opens=${postStats.opens}, closes=${postStats.closes}, current=${postStats.currentlyOpen})`);
                 return true;
             }
+            this.consecutiveReconnectFailures += 1;
+            await this.onConnectionFailure(this.consecutiveReconnectFailures);
         }
         catch (error) {
             console.error(`${this.constructor.name} ${this.applianceId}: Reconnect attempt #${attempt} failed: ${error}`);
+            this.consecutiveReconnectFailures += 1;
+            await this.onConnectionFailure(this.consecutiveReconnectFailures);
         }
         return false;
     }
+    /**
+     * Hook for subclasses to react to a failed reconnect attempt. Called once
+     * per failed attempt with the running consecutive-failure count.
+     */
+    async onConnectionFailure(_consecutiveFailures) {
+        // Default: no-op. SunspecInverter overrides to publish a faulted status.
+    }
     /**
      * Mark the device as offline: close the underlying socket so the next readData()
      * cycle sees isConnected() === false and tryReconnect() can establish a fresh
@@ -148,6 +232,10 @@ export class BaseSunspecDevice {
  */
 export class SunspecInverter extends BaseSunspecDevice {
     capabilities;
+    /** Emit a connection-lost faulted status after this many consecutive failed reconnect attempts. */
+    static CONNECTION_FAULT_THRESHOLD = 3;
+    storage;
+    errorState = { activeCodes: [], lastStatus: 'healthy' };
     constructor(energyApp, name, networkDevice, sunspecClient, applianceManager, unitId = 1, port = 502, baseAddress = 40000, capabilities = [], retryConfig, appliance) {
         super(energyApp, name, networkDevice, sunspecClient, applianceManager, unitId, port, baseAddress, retryConfig, appliance);
         this.capabilities = capabilities;
@@ -217,6 +305,7 @@ export class SunspecInverter extends BaseSunspecDevice {
         if (mpptModel) {
             console.log(`MPPT model found for inverter ${this.networkDevice.hostname}`);
         }
+        await this.loadErrorState();
         this.startDataBusListening();
     }
     async disconnect() {
@@ -242,7 +331,7 @@ export class SunspecInverter extends BaseSunspecDevice {
             const dcStrings = this.mapMPPTToStrings(mpptDataList);
             if (inverterData) {
                 const pvPowerW = dcStrings.reduce((sum, s) => sum + (s.powerW || 0), 0);
-                console.log(`Got PV Power from DC strings: ${pvPowerW}W`);
+                console.debug(`Got PV Power from DC strings: ${pvPowerW}W`);
                 const inverterMessage = {
                     id: randomUUID(),
                     message: EnyoDataBusMessageEnum.InverterValuesUpdateV1,
@@ -264,7 +353,12 @@ export class SunspecInverter extends BaseSunspecDevice {
                     }
                 };
                 messages.push(inverterMessage);
+                const statusMessage = await this.detectAndEmitStatusTransition(inverterData, timestamp);
+                if (statusMessage) {
+                    messages.push(statusMessage);
+                }
             }
+            this.consecutiveReconnectFailures = 0;
             if (this.applianceId) {
                 const appliance = await this.applianceManager.findApplianceById(this.applianceId);
                 await this.applianceManager.updateAppliance(this.applianceId, {
@@ -282,6 +376,166 @@ export class SunspecInverter extends BaseSunspecDevice {
         }
         return messages;
     }
+    /**
+     * Decode all active error bits from the inverter event registers into
+     * `EnyoApplianceErrorCode`s. Override in a subclass to customize the
+     * mapping wholesale, or override the per-register helpers
+     * (`mapEvt1Bit`, `mapEvt2Bit`, `mapVendorEventBit`) to customize a
+     * specific register — typical use-case is vendor-specific bit names.
+     */
+    decodeActiveErrors(data) {
+        const codes = [];
+        const codeIds = [];
+        const collect = (raw, mapper) => {
+            const value = raw ?? 0;
+            for (let bit = 0; bit < 32; bit++) {
+                if ((value & (1 << bit)) === 0)
+                    continue;
+                const code = mapper(bit);
+                if (!code)
+                    continue;
+                codes.push(code);
+                codeIds.push(code.code);
+            }
+        };
+        collect(data.events, (bit) => this.mapEvt1Bit(bit));
+        collect(data.events2, (bit) => this.mapEvt2Bit(bit));
+        collect(data.vendorEvents1, (bit) => this.mapVendorEventBit(1, bit));
+        collect(data.vendorEvents2, (bit) => this.mapVendorEventBit(2, bit));
+        collect(data.vendorEvents3, (bit) => this.mapVendorEventBit(3, bit));
+        collect(data.vendorEvents4, (bit) => this.mapVendorEventBit(4, bit));
+        codeIds.sort();
+        return { codes, codeIds };
+    }
+    /**
+     * Map a set bit in the standard Evt1 register to an error code with
+     * de/en translations. Override to customize standard-bit translations.
+     */
+    mapEvt1Bit(bit) {
+        const named = SunspecInverterEvent1[bit];
+        if (!named) {
+            return { code: `inverter_event1_bit_${bit}` };
+        }
+        const messages = SUNSPEC_INVERTER_EVENT1_MESSAGES[bit];
+        return messages ? { code: named, messages } : { code: named };
+    }
+    /**
+     * Map a set bit in the Evt2 register. Reserved in the SunSpec spec, so
+     * the default returns `undefined` — Evt2 bits are not treated as errors.
+     * Override in a vendor-specific subclass to opt specific bits in as
+     * errors.
+     */
+    mapEvt2Bit(_bit) {
+        return undefined;
+    }
+    /**
+     * Map a set bit in one of the four vendor-specific event registers.
+     * Vendor bits are not standardized and many are informational rather
+     * than faults, so the default returns `undefined` and no error code is
+     * emitted. Override in a vendor-specific subclass to opt specific bits
+     * in as errors.
+     */
+    mapVendorEventBit(_registerIndex, _bit) {
+        return undefined;
+    }
+    hasErrorSetChanged(newCodeIds) {
+        const prev = this.errorState.activeCodes;
+        if (prev.length !== newCodeIds.length)
+            return true;
+        for (let i = 0; i < prev.length; i++) {
+            if (prev[i] !== newCodeIds[i])
+                return true;
+        }
+        return false;
+    }
+    buildStatusMessage(status, errorCodes, timestamp) {
+        return {
+            id: randomUUID(),
+            message: EnyoDataBusMessageEnum.ApplianceStateUpdateV1,
+            type: 'message',
+            source: EnyoSourceEnum.Device,
+            applianceId: this.applianceId,
+            timestampIso: timestamp.toISOString(),
+            data: {
+                status,
+                errorCodes,
+            }
+        };
+    }
+    storageKey() {
+        return `sunspec-inverter-error-state-${this.applianceId}`;
+    }
+    async loadErrorState() {
+        try {
+            this.storage = this.energyApp.useStorage();
+            const loaded = await this.storage.load(this.storageKey());
+            if (loaded) {
+                this.errorState = loaded;
+                console.log(`Inverter ${this.applianceId}: loaded persisted error state (lastStatus=${loaded.lastStatus}, codes=[${loaded.activeCodes.join(', ')}])`);
+            }
+        }
+        catch (error) {
+            console.error(`Inverter ${this.applianceId}: failed to load persisted error state: ${error}`);
+        }
+    }
+    async persistErrorState() {
+        if (!this.storage)
+            return;
+        try {
+            await this.storage.save(this.storageKey(), this.errorState);
+        }
+        catch (error) {
+            console.error(`Inverter ${this.applianceId}: failed to persist error state: ${error}`);
+        }
+    }
+    async detectAndEmitStatusTransition(data, timestamp) {
+        if (!this.applianceId)
+            return undefined;
+        const { codes, codeIds } = this.decodeActiveErrors(data);
+        const recoveringFromConnectionLoss = this.errorState.lastStatus === 'connection_lost';
+        if (!recoveringFromConnectionLoss && !this.hasErrorSetChanged(codeIds)) {
+            return undefined;
+        }
+        const newStatus = codeIds.length === 0
+            ? EnyoApplianceStatusEnum.Healthy
+            : EnyoApplianceStatusEnum.Faulted;
+        this.errorState = {
+            evt1: data.events,
+            evt2: data.events2,
+            evtVnd1: data.vendorEvents1,
+            evtVnd2: data.vendorEvents2,
+            evtVnd3: data.vendorEvents3,
+            evtVnd4: data.vendorEvents4,
+            activeCodes: codeIds,
+            lastStatus: newStatus === EnyoApplianceStatusEnum.Healthy ? 'healthy' : 'faulted',
+        };
+        await this.persistErrorState();
+        console.log(`Inverter ${this.applianceId}: status transition -> ${newStatus} (codes=[${codeIds.join(', ')}])`);
+        return this.buildStatusMessage(newStatus, codes, timestamp);
+    }
+    async onConnectionFailure(consecutiveFailures) {
+        if (!this.applianceId || !this.dataBus)
+            return;
+        if (consecutiveFailures < SunspecInverter.CONNECTION_FAULT_THRESHOLD)
+            return;
+        if (this.errorState.lastStatus === 'connection_lost')
+            return;
+        const errorCodes = [{
+                code: SUNSPEC_CONNECTION_LOST_CODE,
+                messages: [
+                    { language: 'en', message: 'Modbus connection to inverter lost' },
+                    { language: 'de', message: 'Modbus-Verbindung zum Wechselrichter verloren' },
+                ]
+            }];
+        const message = this.buildStatusMessage(EnyoApplianceStatusEnum.Faulted, errorCodes, new Date());
+        this.errorState = {
+            activeCodes: [SUNSPEC_CONNECTION_LOST_CODE],
+            lastStatus: 'connection_lost',
+        };
+        await this.persistErrorState();
+        console.log(`Inverter ${this.applianceId}: emitting faulted (${SUNSPEC_CONNECTION_LOST_CODE}) after ${consecutiveFailures} consecutive reconnect failures`);
+        this.dataBus.sendMessage([message]);
+    }
     mapOperatingState(state) {
         if (!state)
             return EnyoInverterStateEnum.Off;

package/dist/sunspec-interfaces.d.ts

@@ -110,6 +110,48 @@ export interface SunspecInverterData extends SunspecBlock {
     vendorEvents3?: number;
     vendorEvents4?: number;
 }
+/**
+ * Inverter Event 1 bit positions for Model 101/103
+ * Offset 40-41: Evt1 - Inverter event bitfield
+ */
+export declare enum SunspecInverterEvent1 {
+    GROUND_FAULT = 0,
+    DC_OVER_VOLT = 1,
+    AC_DISCONNECT = 2,
+    DC_DISCONNECT = 3,
+    GRID_DISCONNECT = 4,
+    CABINET_OPEN = 5,
+    MANUAL_SHUTDOWN = 6,
+    OVER_TEMP = 7,
+    OVER_FREQUENCY = 8,
+    UNDER_FREQUENCY = 9,
+    AC_OVER_VOLT = 10,
+    AC_UNDER_VOLT = 11,
+    BLOWN_STRING_FUSE = 12,
+    UNDER_TEMP = 13,
+    MEMORY_LOSS = 14,
+    HW_TEST_FAILURE = 15
+}
+/**
+ * Error code emitted when the modbus connection has been lost for several
+ * consecutive reconnect attempts.
+ */
+export declare const SUNSPEC_CONNECTION_LOST_CODE = "modbus_connection_lost";
+/**
+ * Persisted error state for a SunSpec inverter, written to storage so the
+ * status reporter can detect transitions across process restarts and avoid
+ * re-emitting `faulted` for the same already-known errors.
+ */
+export interface SunspecInverterPersistedErrorState {
+    evt1?: number;
+    evt2?: number;
+    evtVnd1?: number;
+    evtVnd2?: number;
+    evtVnd3?: number;
+    evtVnd4?: number;
+    activeCodes: string[];
+    lastStatus: 'healthy' | 'faulted' | 'connection_lost';
+}
 /**
  * MPPT data structure based on Model 160
  *

package/dist/sunspec-interfaces.js

@@ -30,6 +30,34 @@ export var SunspecModelId;
     SunspecModelId[SunspecModelId["Controls"] = 123] = "Controls";
     SunspecModelId[SunspecModelId["EndMarker"] = 65535] = "EndMarker";
 })(SunspecModelId || (SunspecModelId = {}));
+/**
+ * Inverter Event 1 bit positions for Model 101/103
+ * Offset 40-41: Evt1 - Inverter event bitfield
+ */
+export var SunspecInverterEvent1;
+(function (SunspecInverterEvent1) {
+    SunspecInverterEvent1[SunspecInverterEvent1["GROUND_FAULT"] = 0] = "GROUND_FAULT";
+    SunspecInverterEvent1[SunspecInverterEvent1["DC_OVER_VOLT"] = 1] = "DC_OVER_VOLT";
+    SunspecInverterEvent1[SunspecInverterEvent1["AC_DISCONNECT"] = 2] = "AC_DISCONNECT";
+    SunspecInverterEvent1[SunspecInverterEvent1["DC_DISCONNECT"] = 3] = "DC_DISCONNECT";
+    SunspecInverterEvent1[SunspecInverterEvent1["GRID_DISCONNECT"] = 4] = "GRID_DISCONNECT";
+    SunspecInverterEvent1[SunspecInverterEvent1["CABINET_OPEN"] = 5] = "CABINET_OPEN";
+    SunspecInverterEvent1[SunspecInverterEvent1["MANUAL_SHUTDOWN"] = 6] = "MANUAL_SHUTDOWN";
+    SunspecInverterEvent1[SunspecInverterEvent1["OVER_TEMP"] = 7] = "OVER_TEMP";
+    SunspecInverterEvent1[SunspecInverterEvent1["OVER_FREQUENCY"] = 8] = "OVER_FREQUENCY";
+    SunspecInverterEvent1[SunspecInverterEvent1["UNDER_FREQUENCY"] = 9] = "UNDER_FREQUENCY";
+    SunspecInverterEvent1[SunspecInverterEvent1["AC_OVER_VOLT"] = 10] = "AC_OVER_VOLT";
+    SunspecInverterEvent1[SunspecInverterEvent1["AC_UNDER_VOLT"] = 11] = "AC_UNDER_VOLT";
+    SunspecInverterEvent1[SunspecInverterEvent1["BLOWN_STRING_FUSE"] = 12] = "BLOWN_STRING_FUSE";
+    SunspecInverterEvent1[SunspecInverterEvent1["UNDER_TEMP"] = 13] = "UNDER_TEMP";
+    SunspecInverterEvent1[SunspecInverterEvent1["MEMORY_LOSS"] = 14] = "MEMORY_LOSS";
+    SunspecInverterEvent1[SunspecInverterEvent1["HW_TEST_FAILURE"] = 15] = "HW_TEST_FAILURE";
+})(SunspecInverterEvent1 || (SunspecInverterEvent1 = {}));
+/**
+ * Error code emitted when the modbus connection has been lost for several
+ * consecutive reconnect attempts.
+ */
+export const SUNSPEC_CONNECTION_LOST_CODE = 'modbus_connection_lost';
 /**
  * MPPT Operating State values for Model 160
  * These represent the DC module/string operating states

package/dist/version.d.ts

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