@enyo-energy/sunspec-sdk 0.0.83 → 0.0.85

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

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

package/dist/cjs/sunspec-devices.cjs

@@ -343,7 +343,16 @@ class SunspecInverter extends BaseSunspecDevice {
     capabilities;
     /** Emit a connection-lost faulted status after this many consecutive failed reconnect attempts. */
     static CONNECTION_FAULT_THRESHOLD = 3;
+    /**
+     * Require this many consecutive operatingState=7 (FAULT) reads before
+     * reporting Faulted. Debounces transient single-poll FAULT reads (e.g. a
+     * DC-coupled battery disturbing a string) that would otherwise oscillate
+     * the appliance status. Recovery is immediate (counter resets on the first
+     * non-fault read).
+     */
+    static OPERATING_FAULT_THRESHOLD = 3;
     storage;
+    consecutiveOperatingFaults = 0;
     errorState = { activeCodes: [], lastStatus: 'healthy' };
     snapshotService;
     // Whether we've emitted a status update at least once since (re)connecting.
@@ -656,7 +665,15 @@ class SunspecInverter extends BaseSunspecDevice {
         // fault; MPPT (4), SLEEPING (2) and the other states are normal. This
         // is re-evaluated every poll so a producing inverter (operatingState=4,
         // no error bits) reports Healthy even if it was previously faulted.
-        const operatingFault = data.operatingState === sunspec_interfaces_js_1.SunspecInverterOperatingState.FAULT;
+        //
+        // A single FAULT read is debounced: we only treat it as a fault after
+        // OPERATING_FAULT_THRESHOLD consecutive FAULT polls, so a transient
+        // wobble (e.g. a faulted DC-coupled battery on a string) does not
+        // oscillate the status. Recovery is immediate — the counter resets on
+        // the first non-fault read. Event-register error bits stay immediate.
+        const operatingFaultRaw = data.operatingState === sunspec_interfaces_js_1.SunspecInverterOperatingState.FAULT;
+        this.consecutiveOperatingFaults = operatingFaultRaw ? this.consecutiveOperatingFaults + 1 : 0;
+        const operatingFault = this.consecutiveOperatingFaults >= SunspecInverter.OPERATING_FAULT_THRESHOLD;
         const newStatus = (codeIds.length > 0 || operatingFault)
             ? enyo_appliance_js_1.EnyoApplianceStatusEnum.Faulted
             : enyo_appliance_js_1.EnyoApplianceStatusEnum.Healthy;
@@ -772,7 +789,10 @@ class SunspecInverter extends BaseSunspecDevice {
             // Only include strings with valid data
             if (mppt.dcVoltage !== undefined || mppt.dcPower !== undefined) {
                 result.push({
-                    index: index + 1,
+                    // Use the stable physical module position so a string keeps
+                    // its identity when an earlier module drops out of a poll.
+                    // Fall back to array position if the field is absent.
+                    index: mppt.moduleNumber ?? (index + 1),
                     name: mppt.stringId,
                     state: this.mapMPPTOperatingState(mppt.operatingState),
                     current: mppt.dcCurrent,
@@ -1676,6 +1696,20 @@ class SunspecMeter extends BaseSunspecDevice {
         super(energyApp, name, networkDevice, sunspecClient, applianceManager, unitId, port, baseAddress, retryConfig, appliance, useTls);
         this.capabilities = capabilities;
     }
+    /**
+     * The specific meter model instance this meter reads, when its unit hosts more than one
+     * embedded meter (e.g. a SolarEdge SE16K with the inverter + multiple meters on unit 1).
+     * When set, identity and telemetry are read from THIS block and its own preceding Common
+     * block rather than the unit's first/only meter. Unset → legacy single-meter behavior.
+     */
+    meterModel;
+    /**
+     * Bind this meter to a specific discovered meter model instance (from
+     * {@link SunspecModbusClient.findModels}). Call before {@link connect}.
+     */
+    bindMeterModel(model) {
+        this.meterModel = model;
+    }
     /**
      * Connect to the meter and create/update the appliance
      */
@@ -1683,7 +1717,8 @@ class SunspecMeter extends BaseSunspecDevice {
         // Connect with specific unit ID for meter
         await this.ensureConnected();
         // Check if meter models exist (int+SF: 201/203/204, float: 211/212/213/214)
-        const hasMeter = this.sunspecClient.findModel(this.unitId, sunspec_interfaces_js_1.SunspecModelId.Meter3Phase) !== undefined ||
+        const hasMeter = this.meterModel !== undefined ||
+            this.sunspecClient.findModel(this.unitId, sunspec_interfaces_js_1.SunspecModelId.Meter3Phase) !== undefined ||
             this.sunspecClient.findModel(this.unitId, sunspec_interfaces_js_1.SunspecModelId.MeterWye) !== undefined ||
             this.sunspecClient.findModel(this.unitId, sunspec_interfaces_js_1.SunspecModelId.MeterSinglePhase) !== undefined ||
             this.sunspecClient.findModel(this.unitId, sunspec_interfaces_js_1.SunspecModelId.Meter3PhaseWyeFloat) !== undefined ||
@@ -1693,8 +1728,12 @@ class SunspecMeter extends BaseSunspecDevice {
         if (!hasMeter) {
             throw new Error('No meter model found in device');
         }
-        // Get device info
-        const commonData = await this.sunspecClient.readCommonBlock(this.unitId);
+        // Get device info. For a bound meter instance, read ITS own Common block (the one
+        // preceding its meter model) so the appliance gets the meter's own manufacturer/model/
+        // serial — not the inverter's or a sibling meter's (the unit's first Common).
+        const commonData = this.meterModel
+            ? await this.sunspecClient.readCommonBlockForModel(this.unitId, this.meterModel)
+            : await this.sunspecClient.readCommonBlock(this.unitId);
         // Create or update appliance (skip if an existing appliance was provided)
         if (!this.applianceId) {
             try {
@@ -1768,8 +1807,8 @@ class SunspecMeter extends BaseSunspecDevice {
         const messages = [];
         const timestamp = new Date();
         try {
-            // Read meter data
-            const meterData = await this.sunspecClient.readMeterData(this.unitId);
+            // Read meter data (from the bound instance when this unit hosts multiple meters)
+            const meterData = await this.sunspecClient.readMeterData(this.unitId, this.meterModel);
             // SDK readers swallow modbus errors and return null; detect that here so the
             // appliance is marked offline and the retry manager starts its backoff.
             if (await this.markOfflineIfUnhealthy()) {

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

@@ -3,6 +3,7 @@ import { ApplianceManager, EnergyApp } from "@enyo-energy/energy-app-sdk";
 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 { SunspecModel } from "./sunspec-interfaces.cjs";
 import { ConnectionRetryManager } from "./connection-retry-manager.cjs";
 import { EnyoCommandAcknowledgeAnswerEnum, EnyoDataBusMessage, EnyoDataBusMessageEnum, EnyoDataBusMessageResolution } from "@enyo-energy/energy-app-sdk/dist/types/enyo-data-bus-value.js";
 import { BatteryCalibrator, type BatteryCalibratorConfig, type CalibrationResult, type CalibrationResultStore, type CalibrationSnapshot, type RestoreReason, SnapshotService } from "@enyo-energy/appliance-calibration";
@@ -128,7 +129,16 @@ export declare class SunspecInverter extends BaseSunspecDevice {
     private readonly capabilities;
     /** Emit a connection-lost faulted status after this many consecutive failed reconnect attempts. */
     private static readonly CONNECTION_FAULT_THRESHOLD;
+    /**
+     * Require this many consecutive operatingState=7 (FAULT) reads before
+     * reporting Faulted. Debounces transient single-poll FAULT reads (e.g. a
+     * DC-coupled battery disturbing a string) that would otherwise oscillate
+     * the appliance status. Recovery is immediate (counter resets on the first
+     * non-fault read).
+     */
+    private static readonly OPERATING_FAULT_THRESHOLD;
     private storage?;
+    private consecutiveOperatingFaults;
     private errorState;
     private snapshotService?;
     private statusReassertedThisSession;
@@ -469,6 +479,18 @@ export declare class SunspecBattery extends BaseSunspecDevice {
 export declare class SunspecMeter extends BaseSunspecDevice {
     private readonly capabilities;
     constructor(energyApp: EnergyApp, name: EnyoApplianceName[], networkDevice: EnyoNetworkDevice, sunspecClient: SunspecModbusClient, applianceManager: ApplianceManager, unitId?: number, port?: number, baseAddress?: number, capabilities?: SunspecMeterCapability[], retryConfig?: IRetryConfig, appliance?: EnyoAppliance, useTls?: boolean);
+    /**
+     * The specific meter model instance this meter reads, when its unit hosts more than one
+     * embedded meter (e.g. a SolarEdge SE16K with the inverter + multiple meters on unit 1).
+     * When set, identity and telemetry are read from THIS block and its own preceding Common
+     * block rather than the unit's first/only meter. Unset → legacy single-meter behavior.
+     */
+    private meterModel?;
+    /**
+     * Bind this meter to a specific discovered meter model instance (from
+     * {@link SunspecModbusClient.findModels}). Call before {@link connect}.
+     */
+    bindMeterModel(model: SunspecModel): void;
     /**
      * Connect to the meter and create/update the appliance
      */

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

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

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

@@ -83,7 +83,15 @@ class SunspecModbusClient {
     // many unit IDs share that client (each unit ID is one EnergyAppModbusInstance underneath).
     modbusInstances = new Map();
     faultTolerantReaders = new Map();
+    // First-instance-wins directory (lowest address per model id). SunSpec allows a model id to
+    // repeat on one unit — most notably Common (id 1), which appears once per logical device
+    // (inverter, then each embedded meter). Keyed lookups want the PRIMARY (first) instance, so
+    // findModel/readCommonBlock resolve to the device's own block, not a later meter's.
     discoveredModelsByUnit = new Map();
+    // Full address-ordered list of every discovered instance, including repeats. Used by
+    // findModels()/readCommonBlockForModel() to enumerate multiple meters and pair each meter
+    // block with its own preceding Common block.
+    discoveredModelListByUnit = new Map();
     connectionHealth;
     modbusDataTypeConverter;
     connectionParams = null;
@@ -306,6 +314,7 @@ class SunspecModbusClient {
         this.modbusInstances.delete(unitId);
         this.faultTolerantReaders.delete(unitId);
         this.discoveredModelsByUnit.delete(unitId);
+        this.discoveredModelListByUnit.delete(unitId);
         if (instance) {
             try {
                 await instance.disconnect();
@@ -376,6 +385,17 @@ class SunspecModbusClient {
         }
         return m;
     }
+    /**
+     * Get (or create) the address-ordered list of every discovered model instance for a unit.
+     */
+    getModelList(unitId) {
+        let list = this.discoveredModelListByUnit.get(unitId);
+        if (!list) {
+            list = [];
+            this.discoveredModelListByUnit.set(unitId, list);
+        }
+        return list;
+    }
     /**
      * Enable or disable automatic reconnection
      */
@@ -473,6 +493,8 @@ class SunspecModbusClient {
         const instance = this.getInstance(unitId);
         const models = this.getModelsMap(unitId);
         models.clear();
+        const modelList = this.getModelList(unitId);
+        modelList.length = 0;
         const maxAddress = 50000; // Safety limit
         let currentAddress = 0;
         console.log(`Starting Sunspec model discovery for unit ${unitId}...`);
@@ -514,7 +536,13 @@ class SunspecModbusClient {
                     address: currentAddress,
                     length: modelLength
                 };
-                models.set(modelId, model);
+                // Keep the FIRST (lowest-address) instance per id in the keyed directory so
+                // findModel() resolves to the device's own block. Record every instance —
+                // including repeats like a meter's Common (id 1) — in the ordered list.
+                if (!models.has(modelId)) {
+                    models.set(modelId, model);
+                }
+                modelList.push(model);
                 // Per-model discovery step. The end-of-discovery summary below is the
                 // info-level outcome; the per-model walk is debug-only.
                 console.debug(`Discovered Model ${modelId} at address ${currentAddress} with length ${modelLength} (unit ${unitId})`);
@@ -525,7 +553,9 @@ class SunspecModbusClient {
         catch (error) {
             console.error(`Error during model discovery at address ${currentAddress} (unit ${unitId}): ${error}`);
         }
-        console.log(`Discovery complete for unit ${unitId}. Found ${models.size} models: [${[...models.keys()].sort((a, b) => a - b).join(', ')}]`);
+        // Report every instance in address order so repeated ids (e.g. two Common blocks, or
+        // multiple meters) are visible — models.size would hide them behind the unique keys.
+        console.log(`Discovery complete for unit ${unitId}. Found ${modelList.length} model instance(s): [${modelList.map(m => m.id).join(', ')}]`);
         return models;
     }
     /**
@@ -534,6 +564,17 @@ class SunspecModbusClient {
     findModel(unitId, modelId) {
         return this.discoveredModelsByUnit.get(unitId)?.get(modelId);
     }
+    /**
+     * Find every instance of a model id on a unit, in ascending address order.
+     *
+     * SunSpec permits a model id to repeat on a single unit — e.g. SolarEdge SE16K-class
+     * inverters expose the inverter, then one or more embedded meters, on the same Modbus unit,
+     * each meter advertising its own meter model (203/204/...) and its own Common block (id 1).
+     * `findModel` only returns the first instance; use this to enumerate them all.
+     */
+    findModels(unitId, modelId) {
+        return (this.discoveredModelListByUnit.get(unitId) ?? []).filter(m => m.id === modelId);
+    }
     /**
      * Check if a value is "unimplemented" according to Sunspec specification
      * Returns true if the value represents an unimplemented/not applicable register
@@ -1213,6 +1254,10 @@ class SunspecModbusClient {
                         (data.dcCurrent !== undefined ||
                             data.dcVoltage !== undefined ||
                             data.dcPower !== undefined)) {
+                        // Stamp the stable 1-based module position so downstream
+                        // string identity does not shift when an earlier module
+                        // drops out of a poll (e.g. transient undefined reads).
+                        data.moduleNumber = i;
                         mpptData.push(data);
                     }
                 }
@@ -1728,8 +1773,17 @@ class SunspecModbusClient {
             // governing parameters are already in place when the device
             // transitions into the new mode.
             if (controls.storCtlMod !== undefined) {
-                await this.writeRegisterValue(unitId, baseAddr + 5, controls.storCtlMod, 'uint16');
-                console.debug(`Set storage control mode to 0x${controls.storCtlMod.toString(16)}`);
+                // storCtlMod = 0 is rejected with Modbus Exception code 3 (Illegal Data Value)
+                // by some devices (e.g. Fronius GEN24). 0 means "no external control" per the
+                // SunSpec spec, but Fronius firmware requires at least one bit to be set.
+                // Mapping 0 -> CHARGE | DISCHARGE returns the battery to autonomous
+                // self-managed operation on all known SunSpec devices (matches the neutral
+                // reset state used in sunspec-battery-feature-calibrator.ts).
+                const safeMode = controls.storCtlMod === 0
+                    ? sunspec_interfaces_js_1.SunspecStorageControlMode.CHARGE | sunspec_interfaces_js_1.SunspecStorageControlMode.DISCHARGE
+                    : controls.storCtlMod;
+                await this.writeRegisterValue(unitId, baseAddr + 5, safeMode, 'uint16');
+                console.debug(`Set storage control mode to 0x${safeMode.toString(16)}`);
             }
             console.debug('Battery controls written successfully');
             return true;
@@ -1834,7 +1888,16 @@ class SunspecModbusClient {
      * When a device advertises BOTH encodings, picks the family with more discovered models
      * for this unit (see getPreferredEncoding). Never reads both.
      */
-    async readMeterData(unitId) {
+    async readMeterData(unitId, meterModel) {
+        // When a specific meter instance is given (a unit with multiple embedded meters), read
+        // exactly that block — don't let findModel pick the first/only directory entry.
+        if (meterModel) {
+            console.debug(`Using bound meter Model ${meterModel.id} at address ${meterModel.address} (length ${meterModel.length}) on unit ${unitId}`);
+            const floatIds = [211, 212, 213, 214];
+            return floatIds.includes(meterModel.id)
+                ? this.readFloatMeterData(unitId, meterModel, meterModel.id)
+                : this.readIntSfMeterData(unitId, meterModel);
+        }
         const preferred = this.getPreferredEncoding(unitId);
         const tryFloat = async () => {
             const floatIds = [213, 214, 212, 211];
@@ -1992,7 +2055,12 @@ class SunspecModbusClient {
         }
     }
     /**
-     * Read common block data (Model 1)
+     * Read common block data (Model 1).
+     *
+     * Resolves to the unit's FIRST Common block — the leading device's own identity (the
+     * inverter on a SolarEdge SE16K-class unit). When a unit embeds meters, each meter has its
+     * own later Common block; read those with {@link readCommonBlockForModel} so a meter reports
+     * its own manufacturer/model/serial instead of the inverter's (or a sibling meter's).
      */
     async readCommonBlock(unitId) {
         const model = this.findModel(unitId, sunspec_interfaces_js_1.SunspecModelId.Common);
@@ -2002,6 +2070,31 @@ class SunspecModbusClient {
             console.debug(`Common block model not found on unit ${unitId}`);
             return null;
         }
+        return this.readCommonBlockAt(unitId, model);
+    }
+    /**
+     * Read the Common (id 1) block that belongs to a specific device model — the Common instance
+     * immediately preceding the model's address. SunSpec lays out each logical device as
+     * `Common → device model(s)`, so a meter's identity is the Common block right before its meter
+     * model. Falls back to the unit's first Common when none precedes (shouldn't happen for a
+     * well-formed map). Used to give each embedded meter its own appliance identity.
+     */
+    async readCommonBlockForModel(unitId, deviceModel) {
+        const preceding = this.findModels(unitId, sunspec_interfaces_js_1.SunspecModelId.Common)
+            .filter(c => c.address <= deviceModel.address)
+            .sort((a, b) => a.address - b.address)
+            .pop();
+        const model = preceding ?? this.findModel(unitId, sunspec_interfaces_js_1.SunspecModelId.Common);
+        if (!model) {
+            console.debug(`Common block model not found on unit ${unitId} for model ${deviceModel.id}@${deviceModel.address}`);
+            return null;
+        }
+        return this.readCommonBlockAt(unitId, model);
+    }
+    /**
+     * Decode a given Common (Model 1) block instance into identity fields.
+     */
+    async readCommonBlockAt(unitId, model) {
         console.debug(`Reading Common Block - Model address: ${model.address} (unit ${unitId})`);
         try {
             // Read entire model block in a single Modbus call

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

@@ -37,6 +37,7 @@ export declare class SunspecModbusClient {
     private modbusInstances;
     private faultTolerantReaders;
     private discoveredModelsByUnit;
+    private discoveredModelListByUnit;
     private connectionHealth;
     private modbusDataTypeConverter;
     private connectionParams;
@@ -128,6 +129,10 @@ export declare class SunspecModbusClient {
      * Get (or create) the discovered-models map for a unit.
      */
     private getModelsMap;
+    /**
+     * Get (or create) the address-ordered list of every discovered model instance for a unit.
+     */
+    private getModelList;
     /**
      * Enable or disable automatic reconnection
      */
@@ -153,6 +158,15 @@ export declare class SunspecModbusClient {
      * Find a specific model by ID for a given unit
      */
     findModel(unitId: number, modelId: number): SunspecModel | undefined;
+    /**
+     * Find every instance of a model id on a unit, in ascending address order.
+     *
+     * SunSpec permits a model id to repeat on a single unit — e.g. SolarEdge SE16K-class
+     * inverters expose the inverter, then one or more embedded meters, on the same Modbus unit,
+     * each meter advertising its own meter model (203/204/...) and its own Common block (id 1).
+     * `findModel` only returns the first instance; use this to enumerate them all.
+     */
+    findModels(unitId: number, modelId: number): SunspecModel[];
     /**
      * Check if a value is "unimplemented" according to Sunspec specification
      * Returns true if the value represents an unimplemented/not applicable register
@@ -337,7 +351,7 @@ export declare class SunspecModbusClient {
      * When a device advertises BOTH encodings, picks the family with more discovered models
      * for this unit (see getPreferredEncoding). Never reads both.
      */
-    readMeterData(unitId: number): Promise<SunspecMeterData | null>;
+    readMeterData(unitId: number, meterModel?: SunspecModel): Promise<SunspecMeterData | null>;
     /**
      * Read meter data from an int+SF variant model (201/203/204). Extracted from the original
      * readMeterData body so the preferred-encoding dispatcher above can branch cleanly without
@@ -362,9 +376,26 @@ export declare class SunspecModbusClient {
      */
     private readFloatMeterData;
     /**
-     * Read common block data (Model 1)
+     * Read common block data (Model 1).
+     *
+     * Resolves to the unit's FIRST Common block — the leading device's own identity (the
+     * inverter on a SolarEdge SE16K-class unit). When a unit embeds meters, each meter has its
+     * own later Common block; read those with {@link readCommonBlockForModel} so a meter reports
+     * its own manufacturer/model/serial instead of the inverter's (or a sibling meter's).
      */
     readCommonBlock(unitId: number): Promise<any>;
+    /**
+     * Read the Common (id 1) block that belongs to a specific device model — the Common instance
+     * immediately preceding the model's address. SunSpec lays out each logical device as
+     * `Common → device model(s)`, so a meter's identity is the Common block right before its meter
+     * model. Falls back to the unit's first Common when none precedes (shouldn't happen for a
+     * well-formed map). Used to give each embedded meter its own appliance identity.
+     */
+    readCommonBlockForModel(unitId: number, deviceModel: SunspecModel): Promise<any>;
+    /**
+     * Decode a given Common (Model 1) block instance into identity fields.
+     */
+    private readCommonBlockAt;
     /**
      * Get serial number from device
      */

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

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

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

package/dist/sunspec-devices.d.ts

@@ -3,6 +3,7 @@ import { ApplianceManager, EnergyApp } from "@enyo-energy/energy-app-sdk";
 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 { SunspecModel } from "./sunspec-interfaces.js";
 import { ConnectionRetryManager } from "./connection-retry-manager.js";
 import { EnyoCommandAcknowledgeAnswerEnum, EnyoDataBusMessage, EnyoDataBusMessageEnum, EnyoDataBusMessageResolution } from "@enyo-energy/energy-app-sdk/dist/types/enyo-data-bus-value.js";
 import { BatteryCalibrator, type BatteryCalibratorConfig, type CalibrationResult, type CalibrationResultStore, type CalibrationSnapshot, type RestoreReason, SnapshotService } from "@enyo-energy/appliance-calibration";
@@ -128,7 +129,16 @@ export declare class SunspecInverter extends BaseSunspecDevice {
     private readonly capabilities;
     /** Emit a connection-lost faulted status after this many consecutive failed reconnect attempts. */
     private static readonly CONNECTION_FAULT_THRESHOLD;
+    /**
+     * Require this many consecutive operatingState=7 (FAULT) reads before
+     * reporting Faulted. Debounces transient single-poll FAULT reads (e.g. a
+     * DC-coupled battery disturbing a string) that would otherwise oscillate
+     * the appliance status. Recovery is immediate (counter resets on the first
+     * non-fault read).
+     */
+    private static readonly OPERATING_FAULT_THRESHOLD;
     private storage?;
+    private consecutiveOperatingFaults;
     private errorState;
     private snapshotService?;
     private statusReassertedThisSession;
@@ -469,6 +479,18 @@ export declare class SunspecBattery extends BaseSunspecDevice {
 export declare class SunspecMeter extends BaseSunspecDevice {
     private readonly capabilities;
     constructor(energyApp: EnergyApp, name: EnyoApplianceName[], networkDevice: EnyoNetworkDevice, sunspecClient: SunspecModbusClient, applianceManager: ApplianceManager, unitId?: number, port?: number, baseAddress?: number, capabilities?: SunspecMeterCapability[], retryConfig?: IRetryConfig, appliance?: EnyoAppliance, useTls?: boolean);
+    /**
+     * The specific meter model instance this meter reads, when its unit hosts more than one
+     * embedded meter (e.g. a SolarEdge SE16K with the inverter + multiple meters on unit 1).
+     * When set, identity and telemetry are read from THIS block and its own preceding Common
+     * block rather than the unit's first/only meter. Unset → legacy single-meter behavior.
+     */
+    private meterModel?;
+    /**
+     * Bind this meter to a specific discovered meter model instance (from
+     * {@link SunspecModbusClient.findModels}). Call before {@link connect}.
+     */
+    bindMeterModel(model: SunspecModel): void;
     /**
      * Connect to the meter and create/update the appliance
      */

package/dist/sunspec-devices.js

@@ -336,7 +336,16 @@ export class SunspecInverter extends BaseSunspecDevice {
     capabilities;
     /** Emit a connection-lost faulted status after this many consecutive failed reconnect attempts. */
     static CONNECTION_FAULT_THRESHOLD = 3;
+    /**
+     * Require this many consecutive operatingState=7 (FAULT) reads before
+     * reporting Faulted. Debounces transient single-poll FAULT reads (e.g. a
+     * DC-coupled battery disturbing a string) that would otherwise oscillate
+     * the appliance status. Recovery is immediate (counter resets on the first
+     * non-fault read).
+     */
+    static OPERATING_FAULT_THRESHOLD = 3;
     storage;
+    consecutiveOperatingFaults = 0;
     errorState = { activeCodes: [], lastStatus: 'healthy' };
     snapshotService;
     // Whether we've emitted a status update at least once since (re)connecting.
@@ -649,7 +658,15 @@ export class SunspecInverter extends BaseSunspecDevice {
         // fault; MPPT (4), SLEEPING (2) and the other states are normal. This
         // is re-evaluated every poll so a producing inverter (operatingState=4,
         // no error bits) reports Healthy even if it was previously faulted.
-        const operatingFault = data.operatingState === SunspecInverterOperatingState.FAULT;
+        //
+        // A single FAULT read is debounced: we only treat it as a fault after
+        // OPERATING_FAULT_THRESHOLD consecutive FAULT polls, so a transient
+        // wobble (e.g. a faulted DC-coupled battery on a string) does not
+        // oscillate the status. Recovery is immediate — the counter resets on
+        // the first non-fault read. Event-register error bits stay immediate.
+        const operatingFaultRaw = data.operatingState === SunspecInverterOperatingState.FAULT;
+        this.consecutiveOperatingFaults = operatingFaultRaw ? this.consecutiveOperatingFaults + 1 : 0;
+        const operatingFault = this.consecutiveOperatingFaults >= SunspecInverter.OPERATING_FAULT_THRESHOLD;
         const newStatus = (codeIds.length > 0 || operatingFault)
             ? EnyoApplianceStatusEnum.Faulted
             : EnyoApplianceStatusEnum.Healthy;
@@ -765,7 +782,10 @@ export class SunspecInverter extends BaseSunspecDevice {
             // Only include strings with valid data
             if (mppt.dcVoltage !== undefined || mppt.dcPower !== undefined) {
                 result.push({
-                    index: index + 1,
+                    // Use the stable physical module position so a string keeps
+                    // its identity when an earlier module drops out of a poll.
+                    // Fall back to array position if the field is absent.
+                    index: mppt.moduleNumber ?? (index + 1),
                     name: mppt.stringId,
                     state: this.mapMPPTOperatingState(mppt.operatingState),
                     current: mppt.dcCurrent,
@@ -1667,6 +1687,20 @@ export class SunspecMeter extends BaseSunspecDevice {
         super(energyApp, name, networkDevice, sunspecClient, applianceManager, unitId, port, baseAddress, retryConfig, appliance, useTls);
         this.capabilities = capabilities;
     }
+    /**
+     * The specific meter model instance this meter reads, when its unit hosts more than one
+     * embedded meter (e.g. a SolarEdge SE16K with the inverter + multiple meters on unit 1).
+     * When set, identity and telemetry are read from THIS block and its own preceding Common
+     * block rather than the unit's first/only meter. Unset → legacy single-meter behavior.
+     */
+    meterModel;
+    /**
+     * Bind this meter to a specific discovered meter model instance (from
+     * {@link SunspecModbusClient.findModels}). Call before {@link connect}.
+     */
+    bindMeterModel(model) {
+        this.meterModel = model;
+    }
     /**
      * Connect to the meter and create/update the appliance
      */
@@ -1674,7 +1708,8 @@ export class SunspecMeter extends BaseSunspecDevice {
         // Connect with specific unit ID for meter
         await this.ensureConnected();
         // Check if meter models exist (int+SF: 201/203/204, float: 211/212/213/214)
-        const hasMeter = this.sunspecClient.findModel(this.unitId, SunspecModelId.Meter3Phase) !== undefined ||
+        const hasMeter = this.meterModel !== undefined ||
+            this.sunspecClient.findModel(this.unitId, SunspecModelId.Meter3Phase) !== undefined ||
             this.sunspecClient.findModel(this.unitId, SunspecModelId.MeterWye) !== undefined ||
             this.sunspecClient.findModel(this.unitId, SunspecModelId.MeterSinglePhase) !== undefined ||
             this.sunspecClient.findModel(this.unitId, SunspecModelId.Meter3PhaseWyeFloat) !== undefined ||
@@ -1684,8 +1719,12 @@ export class SunspecMeter extends BaseSunspecDevice {
         if (!hasMeter) {
             throw new Error('No meter model found in device');
         }
-        // Get device info
-        const commonData = await this.sunspecClient.readCommonBlock(this.unitId);
+        // Get device info. For a bound meter instance, read ITS own Common block (the one
+        // preceding its meter model) so the appliance gets the meter's own manufacturer/model/
+        // serial — not the inverter's or a sibling meter's (the unit's first Common).
+        const commonData = this.meterModel
+            ? await this.sunspecClient.readCommonBlockForModel(this.unitId, this.meterModel)
+            : await this.sunspecClient.readCommonBlock(this.unitId);
         // Create or update appliance (skip if an existing appliance was provided)
         if (!this.applianceId) {
             try {
@@ -1759,8 +1798,8 @@ export class SunspecMeter extends BaseSunspecDevice {
         const messages = [];
         const timestamp = new Date();
         try {
-            // Read meter data
-            const meterData = await this.sunspecClient.readMeterData(this.unitId);
+            // Read meter data (from the bound instance when this unit hosts multiple meters)
+            const meterData = await this.sunspecClient.readMeterData(this.unitId, this.meterModel);
             // SDK readers swallow modbus errors and return null; detect that here so the
             // appliance is marked offline and the retry manager starts its backoff.
             if (await this.markOfflineIfUnhealthy()) {

package/dist/sunspec-interfaces.d.ts

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

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

@@ -37,6 +37,7 @@ export declare class SunspecModbusClient {
     private modbusInstances;
     private faultTolerantReaders;
     private discoveredModelsByUnit;
+    private discoveredModelListByUnit;
     private connectionHealth;
     private modbusDataTypeConverter;
     private connectionParams;
@@ -128,6 +129,10 @@ export declare class SunspecModbusClient {
      * Get (or create) the discovered-models map for a unit.
      */
     private getModelsMap;
+    /**
+     * Get (or create) the address-ordered list of every discovered model instance for a unit.
+     */
+    private getModelList;
     /**
      * Enable or disable automatic reconnection
      */
@@ -153,6 +158,15 @@ export declare class SunspecModbusClient {
      * Find a specific model by ID for a given unit
      */
     findModel(unitId: number, modelId: number): SunspecModel | undefined;
+    /**
+     * Find every instance of a model id on a unit, in ascending address order.
+     *
+     * SunSpec permits a model id to repeat on a single unit — e.g. SolarEdge SE16K-class
+     * inverters expose the inverter, then one or more embedded meters, on the same Modbus unit,
+     * each meter advertising its own meter model (203/204/...) and its own Common block (id 1).
+     * `findModel` only returns the first instance; use this to enumerate them all.
+     */
+    findModels(unitId: number, modelId: number): SunspecModel[];
     /**
      * Check if a value is "unimplemented" according to Sunspec specification
      * Returns true if the value represents an unimplemented/not applicable register
@@ -337,7 +351,7 @@ export declare class SunspecModbusClient {
      * When a device advertises BOTH encodings, picks the family with more discovered models
      * for this unit (see getPreferredEncoding). Never reads both.
      */
-    readMeterData(unitId: number): Promise<SunspecMeterData | null>;
+    readMeterData(unitId: number, meterModel?: SunspecModel): Promise<SunspecMeterData | null>;
     /**
      * Read meter data from an int+SF variant model (201/203/204). Extracted from the original
      * readMeterData body so the preferred-encoding dispatcher above can branch cleanly without
@@ -362,9 +376,26 @@ export declare class SunspecModbusClient {
      */
     private readFloatMeterData;
     /**
-     * Read common block data (Model 1)
+     * Read common block data (Model 1).
+     *
+     * Resolves to the unit's FIRST Common block — the leading device's own identity (the
+     * inverter on a SolarEdge SE16K-class unit). When a unit embeds meters, each meter has its
+     * own later Common block; read those with {@link readCommonBlockForModel} so a meter reports
+     * its own manufacturer/model/serial instead of the inverter's (or a sibling meter's).
      */
     readCommonBlock(unitId: number): Promise<any>;
+    /**
+     * Read the Common (id 1) block that belongs to a specific device model — the Common instance
+     * immediately preceding the model's address. SunSpec lays out each logical device as
+     * `Common → device model(s)`, so a meter's identity is the Common block right before its meter
+     * model. Falls back to the unit's first Common when none precedes (shouldn't happen for a
+     * well-formed map). Used to give each embedded meter its own appliance identity.
+     */
+    readCommonBlockForModel(unitId: number, deviceModel: SunspecModel): Promise<any>;
+    /**
+     * Decode a given Common (Model 1) block instance into identity fields.
+     */
+    private readCommonBlockAt;
     /**
      * Get serial number from device
      */

package/dist/sunspec-modbus-client.js

@@ -78,7 +78,15 @@ export class SunspecModbusClient {
     // many unit IDs share that client (each unit ID is one EnergyAppModbusInstance underneath).
     modbusInstances = new Map();
     faultTolerantReaders = new Map();
+    // First-instance-wins directory (lowest address per model id). SunSpec allows a model id to
+    // repeat on one unit — most notably Common (id 1), which appears once per logical device
+    // (inverter, then each embedded meter). Keyed lookups want the PRIMARY (first) instance, so
+    // findModel/readCommonBlock resolve to the device's own block, not a later meter's.
     discoveredModelsByUnit = new Map();
+    // Full address-ordered list of every discovered instance, including repeats. Used by
+    // findModels()/readCommonBlockForModel() to enumerate multiple meters and pair each meter
+    // block with its own preceding Common block.
+    discoveredModelListByUnit = new Map();
     connectionHealth;
     modbusDataTypeConverter;
     connectionParams = null;
@@ -301,6 +309,7 @@ export class SunspecModbusClient {
         this.modbusInstances.delete(unitId);
         this.faultTolerantReaders.delete(unitId);
         this.discoveredModelsByUnit.delete(unitId);
+        this.discoveredModelListByUnit.delete(unitId);
         if (instance) {
             try {
                 await instance.disconnect();
@@ -371,6 +380,17 @@ export class SunspecModbusClient {
         }
         return m;
     }
+    /**
+     * Get (or create) the address-ordered list of every discovered model instance for a unit.
+     */
+    getModelList(unitId) {
+        let list = this.discoveredModelListByUnit.get(unitId);
+        if (!list) {
+            list = [];
+            this.discoveredModelListByUnit.set(unitId, list);
+        }
+        return list;
+    }
     /**
      * Enable or disable automatic reconnection
      */
@@ -468,6 +488,8 @@ export class SunspecModbusClient {
         const instance = this.getInstance(unitId);
         const models = this.getModelsMap(unitId);
         models.clear();
+        const modelList = this.getModelList(unitId);
+        modelList.length = 0;
         const maxAddress = 50000; // Safety limit
         let currentAddress = 0;
         console.log(`Starting Sunspec model discovery for unit ${unitId}...`);
@@ -509,7 +531,13 @@ export class SunspecModbusClient {
                     address: currentAddress,
                     length: modelLength
                 };
-                models.set(modelId, model);
+                // Keep the FIRST (lowest-address) instance per id in the keyed directory so
+                // findModel() resolves to the device's own block. Record every instance —
+                // including repeats like a meter's Common (id 1) — in the ordered list.
+                if (!models.has(modelId)) {
+                    models.set(modelId, model);
+                }
+                modelList.push(model);
                 // Per-model discovery step. The end-of-discovery summary below is the
                 // info-level outcome; the per-model walk is debug-only.
                 console.debug(`Discovered Model ${modelId} at address ${currentAddress} with length ${modelLength} (unit ${unitId})`);
@@ -520,7 +548,9 @@ export class SunspecModbusClient {
         catch (error) {
             console.error(`Error during model discovery at address ${currentAddress} (unit ${unitId}): ${error}`);
         }
-        console.log(`Discovery complete for unit ${unitId}. Found ${models.size} models: [${[...models.keys()].sort((a, b) => a - b).join(', ')}]`);
+        // Report every instance in address order so repeated ids (e.g. two Common blocks, or
+        // multiple meters) are visible — models.size would hide them behind the unique keys.
+        console.log(`Discovery complete for unit ${unitId}. Found ${modelList.length} model instance(s): [${modelList.map(m => m.id).join(', ')}]`);
         return models;
     }
     /**
@@ -529,6 +559,17 @@ export class SunspecModbusClient {
     findModel(unitId, modelId) {
         return this.discoveredModelsByUnit.get(unitId)?.get(modelId);
     }
+    /**
+     * Find every instance of a model id on a unit, in ascending address order.
+     *
+     * SunSpec permits a model id to repeat on a single unit — e.g. SolarEdge SE16K-class
+     * inverters expose the inverter, then one or more embedded meters, on the same Modbus unit,
+     * each meter advertising its own meter model (203/204/...) and its own Common block (id 1).
+     * `findModel` only returns the first instance; use this to enumerate them all.
+     */
+    findModels(unitId, modelId) {
+        return (this.discoveredModelListByUnit.get(unitId) ?? []).filter(m => m.id === modelId);
+    }
     /**
      * Check if a value is "unimplemented" according to Sunspec specification
      * Returns true if the value represents an unimplemented/not applicable register
@@ -1208,6 +1249,10 @@ export class SunspecModbusClient {
                         (data.dcCurrent !== undefined ||
                             data.dcVoltage !== undefined ||
                             data.dcPower !== undefined)) {
+                        // Stamp the stable 1-based module position so downstream
+                        // string identity does not shift when an earlier module
+                        // drops out of a poll (e.g. transient undefined reads).
+                        data.moduleNumber = i;
                         mpptData.push(data);
                     }
                 }
@@ -1723,8 +1768,17 @@ export class SunspecModbusClient {
             // governing parameters are already in place when the device
             // transitions into the new mode.
             if (controls.storCtlMod !== undefined) {
-                await this.writeRegisterValue(unitId, baseAddr + 5, controls.storCtlMod, 'uint16');
-                console.debug(`Set storage control mode to 0x${controls.storCtlMod.toString(16)}`);
+                // storCtlMod = 0 is rejected with Modbus Exception code 3 (Illegal Data Value)
+                // by some devices (e.g. Fronius GEN24). 0 means "no external control" per the
+                // SunSpec spec, but Fronius firmware requires at least one bit to be set.
+                // Mapping 0 -> CHARGE | DISCHARGE returns the battery to autonomous
+                // self-managed operation on all known SunSpec devices (matches the neutral
+                // reset state used in sunspec-battery-feature-calibrator.ts).
+                const safeMode = controls.storCtlMod === 0
+                    ? SunspecStorageControlMode.CHARGE | SunspecStorageControlMode.DISCHARGE
+                    : controls.storCtlMod;
+                await this.writeRegisterValue(unitId, baseAddr + 5, safeMode, 'uint16');
+                console.debug(`Set storage control mode to 0x${safeMode.toString(16)}`);
             }
             console.debug('Battery controls written successfully');
             return true;
@@ -1829,7 +1883,16 @@ export class SunspecModbusClient {
      * When a device advertises BOTH encodings, picks the family with more discovered models
      * for this unit (see getPreferredEncoding). Never reads both.
      */
-    async readMeterData(unitId) {
+    async readMeterData(unitId, meterModel) {
+        // When a specific meter instance is given (a unit with multiple embedded meters), read
+        // exactly that block — don't let findModel pick the first/only directory entry.
+        if (meterModel) {
+            console.debug(`Using bound meter Model ${meterModel.id} at address ${meterModel.address} (length ${meterModel.length}) on unit ${unitId}`);
+            const floatIds = [211, 212, 213, 214];
+            return floatIds.includes(meterModel.id)
+                ? this.readFloatMeterData(unitId, meterModel, meterModel.id)
+                : this.readIntSfMeterData(unitId, meterModel);
+        }
         const preferred = this.getPreferredEncoding(unitId);
         const tryFloat = async () => {
             const floatIds = [213, 214, 212, 211];
@@ -1987,7 +2050,12 @@ export class SunspecModbusClient {
         }
     }
     /**
-     * Read common block data (Model 1)
+     * Read common block data (Model 1).
+     *
+     * Resolves to the unit's FIRST Common block — the leading device's own identity (the
+     * inverter on a SolarEdge SE16K-class unit). When a unit embeds meters, each meter has its
+     * own later Common block; read those with {@link readCommonBlockForModel} so a meter reports
+     * its own manufacturer/model/serial instead of the inverter's (or a sibling meter's).
      */
     async readCommonBlock(unitId) {
         const model = this.findModel(unitId, SunspecModelId.Common);
@@ -1997,6 +2065,31 @@ export class SunspecModbusClient {
             console.debug(`Common block model not found on unit ${unitId}`);
             return null;
         }
+        return this.readCommonBlockAt(unitId, model);
+    }
+    /**
+     * Read the Common (id 1) block that belongs to a specific device model — the Common instance
+     * immediately preceding the model's address. SunSpec lays out each logical device as
+     * `Common → device model(s)`, so a meter's identity is the Common block right before its meter
+     * model. Falls back to the unit's first Common when none precedes (shouldn't happen for a
+     * well-formed map). Used to give each embedded meter its own appliance identity.
+     */
+    async readCommonBlockForModel(unitId, deviceModel) {
+        const preceding = this.findModels(unitId, SunspecModelId.Common)
+            .filter(c => c.address <= deviceModel.address)
+            .sort((a, b) => a.address - b.address)
+            .pop();
+        const model = preceding ?? this.findModel(unitId, SunspecModelId.Common);
+        if (!model) {
+            console.debug(`Common block model not found on unit ${unitId} for model ${deviceModel.id}@${deviceModel.address}`);
+            return null;
+        }
+        return this.readCommonBlockAt(unitId, model);
+    }
+    /**
+     * Decode a given Common (Model 1) block instance into identity fields.
+     */
+    async readCommonBlockAt(unitId, model) {
         console.debug(`Reading Common Block - Model address: ${model.address} (unit ${unitId})`);
         try {
             // Read entire model block in a single Modbus call

package/dist/version.d.ts

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