@enyo-energy/sunspec-sdk 0.0.70 → 0.0.71

package/dist/cjs/sunspec-devices.cjs

@@ -6,6 +6,7 @@ const node_crypto_1 = require("node:crypto");
 const enyo_appliance_js_1 = require("@enyo-energy/energy-app-sdk/dist/types/enyo-appliance.js");
 const connection_retry_manager_js_1 = require("./connection-retry-manager.cjs");
 const enyo_data_bus_value_js_1 = require("@enyo-energy/energy-app-sdk/dist/types/enyo-data-bus-value.js");
+const calibration_snapshot_service_js_1 = require("./calibration-snapshot-service.cjs");
 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");
@@ -99,6 +100,7 @@ class BaseSunspecDevice {
     dataBus;
     retryManager;
     consecutiveReconnectFailures = 0;
+    calibrationService;
     constructor(energyApp, name, networkDevice, sunspecClient, applianceManager, unitId = 1, port = 502, baseAddress = 40000, retryConfig, appliance, useTls) {
         this.energyApp = energyApp;
         this.name = name;
@@ -252,6 +254,27 @@ class BaseSunspecDevice {
         console.log(`${this.constructor.name} ${this.applianceId}: sending ${answer} for ${acknowledgeMessage} (messageId=${messageId}${rejectionReason ? `, reason=${rejectionReason}` : ''})`);
         this.dataBus.sendMessage([ackMessage]);
     }
+    /**
+     * Lazily construct and initialize the per-appliance CalibrationSnapshotService. Reloads
+     * any persisted snapshot from storage so an in-flight calibration survives restarts.
+     * Idempotent — subsequent calls are no-ops once the service exists.
+     */
+    async initCalibrationService(deviceType) {
+        if (this.calibrationService || !this.applianceId) {
+            return;
+        }
+        this.calibrationService = new calibration_snapshot_service_js_1.CalibrationSnapshotService(this.energyApp.useStorage(), this.applianceId, (snapshot, reason) => this.restoreFromCalibrationSnapshot(snapshot, reason));
+        await this.calibrationService.initialize();
+        console.log(`${this.constructor.name} ${this.applianceId}: calibration service initialized (${deviceType})`);
+    }
+    /**
+     * Subclasses implement how to write the modified fields of a snapshot back to the device.
+     * Called both on explicit StopCalibrationV1 and when the 5-minute auto-stop fires.
+     */
+    async restoreFromCalibrationSnapshot(_snapshot, _reason) {
+        // Default: subclasses override. Base implementation is a no-op so meter and other
+        // non-controllable devices don't need to implement it.
+    }
 }
 exports.BaseSunspecDevice = BaseSunspecDevice;
 /**
@@ -675,8 +698,16 @@ class SunspecInverter extends BaseSunspecDevice {
         if (this.dataBusListenerId) {
             return;
         }
+        // Fire and forget — calibration service hydration must not block listening setup.
+        // Listener registration before await ensures we don't miss messages that arrive
+        // during initial load.
+        void this.initCalibrationService('inverter');
         this.dataBus = this.energyApp.useDataBus();
-        this.dataBusListenerId = this.dataBus.listenForMessages([enyo_data_bus_value_js_1.EnyoDataBusMessageEnum.SetInverterFeedInLimitV1], (entry) => this.handleInverterCommand(entry));
+        this.dataBusListenerId = this.dataBus.listenForMessages([
+            enyo_data_bus_value_js_1.EnyoDataBusMessageEnum.SetInverterFeedInLimitV1,
+            enyo_data_bus_value_js_1.EnyoDataBusMessageEnum.StartCalibrationV1,
+            enyo_data_bus_value_js_1.EnyoDataBusMessageEnum.StopCalibrationV1,
+        ], (entry) => this.handleInverterCommand(entry));
         console.log(`Inverter ${this.applianceId}: started data bus listening (listener ${this.dataBusListenerId})`);
     }
     /**
@@ -696,8 +727,16 @@ class SunspecInverter extends BaseSunspecDevice {
         }
         void (async () => {
             try {
-                if (entry.message === enyo_data_bus_value_js_1.EnyoDataBusMessageEnum.SetInverterFeedInLimitV1) {
-                    await this.handleSetFeedInLimit(entry);
+                switch (entry.message) {
+                    case enyo_data_bus_value_js_1.EnyoDataBusMessageEnum.SetInverterFeedInLimitV1:
+                        await this.handleSetFeedInLimit(entry);
+                        break;
+                    case enyo_data_bus_value_js_1.EnyoDataBusMessageEnum.StartCalibrationV1:
+                        await this.handleStartCalibration(entry);
+                        break;
+                    case enyo_data_bus_value_js_1.EnyoDataBusMessageEnum.StopCalibrationV1:
+                        await this.handleStopCalibration(entry);
+                        break;
                 }
             }
             catch (error) {
@@ -721,8 +760,93 @@ class SunspecInverter extends BaseSunspecDevice {
             this.sendCommandAcknowledge(msg.id, msg.message, enyo_data_bus_value_js_1.EnyoCommandAcknowledgeAnswerEnum.Rejected, 'Failed to set feed-in limit');
             return;
         }
+        // setFeedInLimit writes WMaxLimPct + WMaxLim_Ena (see SunspecModbusClient.setFeedInLimit).
+        // Record both so an active calibration can roll them back on stop.
+        await this.calibrationService?.recordModification(['WMaxLimPct', 'WMaxLim_Ena']);
         this.sendCommandAcknowledge(msg.id, msg.message, enyo_data_bus_value_js_1.EnyoCommandAcknowledgeAnswerEnum.Accepted);
     }
+    async handleStartCalibration(msg) {
+        if (!this.isConnected() || !this.applianceId) {
+            this.sendCommandAcknowledge(msg.id, msg.message, enyo_data_bus_value_js_1.EnyoCommandAcknowledgeAnswerEnum.Rejected, 'Not connected');
+            return;
+        }
+        if (!this.calibrationService) {
+            await this.initCalibrationService('inverter');
+        }
+        if (!this.calibrationService) {
+            this.sendCommandAcknowledge(msg.id, msg.message, enyo_data_bus_value_js_1.EnyoCommandAcknowledgeAnswerEnum.Rejected, 'Calibration service unavailable');
+            return;
+        }
+        if (this.calibrationService.isCalibrating()) {
+            console.log(`Inverter ${this.applianceId}: calibration already active — ack idempotently`);
+            this.sendCommandAcknowledge(msg.id, msg.message, enyo_data_bus_value_js_1.EnyoCommandAcknowledgeAnswerEnum.Accepted);
+            return;
+        }
+        console.log(`Inverter ${this.applianceId}: handling StartCalibrationV1`);
+        const controls = await this.sunspecClient.readInverterControls(this.unitId);
+        if (!controls) {
+            this.sendCommandAcknowledge(msg.id, msg.message, enyo_data_bus_value_js_1.EnyoCommandAcknowledgeAnswerEnum.Rejected, 'Failed to read inverter controls for snapshot');
+            return;
+        }
+        try {
+            await this.calibrationService.startCalibration({
+                deviceType: 'inverter',
+                unitId: this.unitId,
+                inverterControls: controls,
+            });
+        }
+        catch (error) {
+            this.sendCommandAcknowledge(msg.id, msg.message, enyo_data_bus_value_js_1.EnyoCommandAcknowledgeAnswerEnum.Rejected, `Failed to persist snapshot: ${error}`);
+            return;
+        }
+        this.sendCommandAcknowledge(msg.id, msg.message, enyo_data_bus_value_js_1.EnyoCommandAcknowledgeAnswerEnum.Accepted);
+    }
+    async handleStopCalibration(msg) {
+        if (!this.applianceId) {
+            this.sendCommandAcknowledge(msg.id, msg.message, enyo_data_bus_value_js_1.EnyoCommandAcknowledgeAnswerEnum.Rejected, 'Not initialized');
+            return;
+        }
+        console.log(`Inverter ${this.applianceId}: handling StopCalibrationV1`);
+        const snapshot = await this.calibrationService?.stopCalibration();
+        if (!snapshot) {
+            // No active calibration — treat as a no-op success.
+            this.sendCommandAcknowledge(msg.id, msg.message, enyo_data_bus_value_js_1.EnyoCommandAcknowledgeAnswerEnum.Accepted);
+            return;
+        }
+        try {
+            await this.restoreFromCalibrationSnapshot(snapshot, 'stop');
+        }
+        catch (error) {
+            this.sendCommandAcknowledge(msg.id, msg.message, enyo_data_bus_value_js_1.EnyoCommandAcknowledgeAnswerEnum.Rejected, `Failed to restore registers: ${error}`);
+            return;
+        }
+        this.sendCommandAcknowledge(msg.id, msg.message, enyo_data_bus_value_js_1.EnyoCommandAcknowledgeAnswerEnum.Accepted);
+    }
+    async restoreFromCalibrationSnapshot(snapshot, reason) {
+        if (snapshot.deviceType !== 'inverter' || !snapshot.inverterControls) {
+            return;
+        }
+        const source = snapshot.inverterControls;
+        const partial = {};
+        // Whitelist of inverter fields that writeInverterControls actually writes (Model 123).
+        // Iterating a typed const list keeps the projection type-safe and bounds the rollback
+        // to fields the SDK knows how to restore.
+        const WRITABLE_INVERTER_FIELDS = ['Conn', 'WMaxLimPct', 'WMaxLim_Ena', 'OutPFSet', 'OutPFSet_Ena'];
+        for (const field of WRITABLE_INVERTER_FIELDS) {
+            if (snapshot.modifiedFields.includes(field) && source[field] !== undefined) {
+                partial[field] = source[field];
+            }
+        }
+        if (Object.keys(partial).length === 0) {
+            console.log(`Inverter ${this.applianceId}: calibration ${reason} — no modified fields to restore`);
+            return;
+        }
+        console.log(`Inverter ${this.applianceId}: calibration ${reason} — restoring [${Object.keys(partial).join(', ')}]`);
+        const ok = await this.sunspecClient.writeInverterControls(snapshot.unitId, partial);
+        if (!ok) {
+            throw new Error('writeInverterControls returned false');
+        }
+    }
 }
 exports.SunspecInverter = SunspecInverter;
 /**
@@ -1167,12 +1291,16 @@ class SunspecBattery extends BaseSunspecDevice {
         if (this.dataBusListenerId) {
             return;
         }
+        // Fire and forget — calibration service hydration must not block listening setup.
+        void this.initCalibrationService('battery');
         this.dataBus = this.energyApp.useDataBus();
         this.dataBusListenerId = this.dataBus.listenForMessages([
             enyo_data_bus_value_js_1.EnyoDataBusMessageEnum.StartStorageGridChargeV1,
             enyo_data_bus_value_js_1.EnyoDataBusMessageEnum.StopStorageGridChargeV1,
             enyo_data_bus_value_js_1.EnyoDataBusMessageEnum.SetStorageDischargeLimitV1,
-            enyo_data_bus_value_js_1.EnyoDataBusMessageEnum.SetStorageChargeLimitV1
+            enyo_data_bus_value_js_1.EnyoDataBusMessageEnum.SetStorageChargeLimitV1,
+            enyo_data_bus_value_js_1.EnyoDataBusMessageEnum.StartCalibrationV1,
+            enyo_data_bus_value_js_1.EnyoDataBusMessageEnum.StopCalibrationV1,
         ], (entry) => this.handleStorageCommand(entry));
         console.log(`Battery ${this.applianceId}: started data bus listening (listener ${this.dataBusListenerId})`);
     }
@@ -1206,6 +1334,12 @@ class SunspecBattery extends BaseSunspecDevice {
                     case enyo_data_bus_value_js_1.EnyoDataBusMessageEnum.SetStorageChargeLimitV1:
                         await this.handleSetChargeLimit(entry);
                         break;
+                    case enyo_data_bus_value_js_1.EnyoDataBusMessageEnum.StartCalibrationV1:
+                        await this.handleStartCalibration(entry);
+                        break;
+                    case enyo_data_bus_value_js_1.EnyoDataBusMessageEnum.StopCalibrationV1:
+                        await this.handleStopCalibration(entry);
+                        break;
                 }
             }
             catch (error) {
@@ -1246,6 +1380,7 @@ class SunspecBattery extends BaseSunspecDevice {
             this.sendCommandAcknowledge(msg.id, msg.message, enyo_data_bus_value_js_1.EnyoCommandAcknowledgeAnswerEnum.Rejected, 'Failed to set storage mode to charge');
             return;
         }
+        await this.calibrationService?.recordModification(['chaGriSet', 'wChaMax', 'storCtlMod']);
         this.sendCommandAcknowledge(msg.id, msg.message, enyo_data_bus_value_js_1.EnyoCommandAcknowledgeAnswerEnum.Accepted);
     }
     async handleStopGridCharge(msg) {
@@ -1272,6 +1407,7 @@ class SunspecBattery extends BaseSunspecDevice {
             this.sendCommandAcknowledge(msg.id, msg.message, enyo_data_bus_value_js_1.EnyoCommandAcknowledgeAnswerEnum.Rejected, 'Failed to set storage mode to auto');
             return;
         }
+        await this.calibrationService?.recordModification(['chaGriSet', 'storCtlMod']);
         this.sendCommandAcknowledge(msg.id, msg.message, enyo_data_bus_value_js_1.EnyoCommandAcknowledgeAnswerEnum.Accepted);
     }
     async handleSetDischargeLimit(msg) {
@@ -1296,6 +1432,7 @@ class SunspecBattery extends BaseSunspecDevice {
             this.sendCommandAcknowledge(msg.id, msg.message, enyo_data_bus_value_js_1.EnyoCommandAcknowledgeAnswerEnum.Rejected, 'Failed to set discharge limit');
             return;
         }
+        await this.calibrationService?.recordModification(['outWRte']);
         this.sendCommandAcknowledge(msg.id, msg.message, enyo_data_bus_value_js_1.EnyoCommandAcknowledgeAnswerEnum.Accepted);
     }
     async handleSetChargeLimit(msg) {
@@ -1320,8 +1457,88 @@ class SunspecBattery extends BaseSunspecDevice {
             this.sendCommandAcknowledge(msg.id, msg.message, enyo_data_bus_value_js_1.EnyoCommandAcknowledgeAnswerEnum.Rejected, 'Failed to set charge limit');
             return;
         }
+        await this.calibrationService?.recordModification(['inWRte']);
         this.sendCommandAcknowledge(msg.id, msg.message, enyo_data_bus_value_js_1.EnyoCommandAcknowledgeAnswerEnum.Accepted);
     }
+    async handleStartCalibration(msg) {
+        if (!this.isConnected() || !this.applianceId) {
+            this.sendCommandAcknowledge(msg.id, msg.message, enyo_data_bus_value_js_1.EnyoCommandAcknowledgeAnswerEnum.Rejected, 'Not connected');
+            return;
+        }
+        if (!this.calibrationService) {
+            await this.initCalibrationService('battery');
+        }
+        if (!this.calibrationService) {
+            this.sendCommandAcknowledge(msg.id, msg.message, enyo_data_bus_value_js_1.EnyoCommandAcknowledgeAnswerEnum.Rejected, 'Calibration service unavailable');
+            return;
+        }
+        if (this.calibrationService.isCalibrating()) {
+            console.log(`Battery ${this.applianceId}: calibration already active — ack idempotently`);
+            this.sendCommandAcknowledge(msg.id, msg.message, enyo_data_bus_value_js_1.EnyoCommandAcknowledgeAnswerEnum.Accepted);
+            return;
+        }
+        console.log(`Battery ${this.applianceId}: handling StartCalibrationV1`);
+        const controls = await this.sunspecClient.readBatteryControls(this.unitId);
+        if (!controls) {
+            this.sendCommandAcknowledge(msg.id, msg.message, enyo_data_bus_value_js_1.EnyoCommandAcknowledgeAnswerEnum.Rejected, 'Failed to read battery controls for snapshot');
+            return;
+        }
+        try {
+            await this.calibrationService.startCalibration({
+                deviceType: 'battery',
+                unitId: this.unitId,
+                batteryControls: controls,
+            });
+        }
+        catch (error) {
+            this.sendCommandAcknowledge(msg.id, msg.message, enyo_data_bus_value_js_1.EnyoCommandAcknowledgeAnswerEnum.Rejected, `Failed to persist snapshot: ${error}`);
+            return;
+        }
+        this.sendCommandAcknowledge(msg.id, msg.message, enyo_data_bus_value_js_1.EnyoCommandAcknowledgeAnswerEnum.Accepted);
+    }
+    async handleStopCalibration(msg) {
+        if (!this.applianceId) {
+            this.sendCommandAcknowledge(msg.id, msg.message, enyo_data_bus_value_js_1.EnyoCommandAcknowledgeAnswerEnum.Rejected, 'Not initialized');
+            return;
+        }
+        console.log(`Battery ${this.applianceId}: handling StopCalibrationV1`);
+        const snapshot = await this.calibrationService?.stopCalibration();
+        if (!snapshot) {
+            this.sendCommandAcknowledge(msg.id, msg.message, enyo_data_bus_value_js_1.EnyoCommandAcknowledgeAnswerEnum.Accepted);
+            return;
+        }
+        try {
+            await this.restoreFromCalibrationSnapshot(snapshot, 'stop');
+        }
+        catch (error) {
+            this.sendCommandAcknowledge(msg.id, msg.message, enyo_data_bus_value_js_1.EnyoCommandAcknowledgeAnswerEnum.Rejected, `Failed to restore registers: ${error}`);
+            return;
+        }
+        this.sendCommandAcknowledge(msg.id, msg.message, enyo_data_bus_value_js_1.EnyoCommandAcknowledgeAnswerEnum.Accepted);
+    }
+    async restoreFromCalibrationSnapshot(snapshot, reason) {
+        if (snapshot.deviceType !== 'battery' || !snapshot.batteryControls) {
+            return;
+        }
+        const source = snapshot.batteryControls;
+        const partial = {};
+        // Whitelist of battery fields that writeBatteryControls actually writes (Model 124).
+        const WRITABLE_BATTERY_FIELDS = ['storCtlMod', 'chaGriSet', 'wChaMax', 'inWRte', 'outWRte', 'minRsvPct'];
+        for (const field of WRITABLE_BATTERY_FIELDS) {
+            if (snapshot.modifiedFields.includes(field) && source[field] !== undefined) {
+                partial[field] = source[field];
+            }
+        }
+        if (Object.keys(partial).length === 0) {
+            console.log(`Battery ${this.applianceId}: calibration ${reason} — no modified fields to restore`);
+            return;
+        }
+        console.log(`Battery ${this.applianceId}: calibration ${reason} — restoring [${Object.keys(partial).join(', ')}]`);
+        const ok = await this.sunspecClient.writeBatteryControls(snapshot.unitId, partial);
+        if (!ok) {
+            throw new Error('writeBatteryControls returned false');
+        }
+    }
 }
 exports.SunspecBattery = SunspecBattery;
 /**
@@ -1397,11 +1614,13 @@ class SunspecMeter extends BaseSunspecDevice {
                 console.error(`Failed to update meter appliance: ${error}`);
             }
         }
+        this.startDataBusListening();
     }
     /**
      * Disconnect from the meter and update appliance state
      */
     async disconnect() {
+        this.stopDataBusListening();
         if (this.applianceId) {
             try {
                 await this.applianceManager.updateApplianceState(this.applianceId, enyo_appliance_js_1.EnyoApplianceConnectionType.Connector, enyo_appliance_js_1.EnyoApplianceStateEnum.Offline);
@@ -1413,6 +1632,35 @@ class SunspecMeter extends BaseSunspecDevice {
         // Close just this meter's unit; other devices on the same network device stay open.
         await this.sunspecClient.disconnectUnit(this.unitId);
     }
+    /**
+     * Meter does not implement calibration; it only subscribes to Start/StopCalibrationV1 to
+     * answer NotSupported (per the data-bus contract that every command must be acknowledged).
+     */
+    startDataBusListening() {
+        if (this.dataBusListenerId) {
+            return;
+        }
+        this.dataBus = this.energyApp.useDataBus();
+        this.dataBusListenerId = this.dataBus.listenForMessages([
+            enyo_data_bus_value_js_1.EnyoDataBusMessageEnum.StartCalibrationV1,
+            enyo_data_bus_value_js_1.EnyoDataBusMessageEnum.StopCalibrationV1,
+        ], (entry) => this.handleMeterCommand(entry));
+        console.log(`Meter ${this.applianceId}: started data bus listening (listener ${this.dataBusListenerId})`);
+    }
+    stopDataBusListening() {
+        if (this.dataBusListenerId && this.dataBus) {
+            this.dataBus.unsubscribe(this.dataBusListenerId);
+            console.log(`Meter ${this.applianceId}: stopped data bus listening (listener ${this.dataBusListenerId})`);
+        }
+        this.dataBusListenerId = undefined;
+        this.dataBus = undefined;
+    }
+    handleMeterCommand(entry) {
+        if (entry.applianceId !== this.applianceId) {
+            return;
+        }
+        this.sendCommandAcknowledge(entry.id, entry.message, enyo_data_bus_value_js_1.EnyoCommandAcknowledgeAnswerEnum.NotSupported, 'Meter does not support calibration');
+    }
     /**
      * Update meter data and return data bus messages
      */

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

@@ -5,6 +5,7 @@ import { EnyoNetworkDevice } from "@enyo-energy/energy-app-sdk/dist/types/enyo-n
 import { SunspecModbusClient } from "./sunspec-modbus-client.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 { type CalibrationDeviceType, type CalibrationRestoreReason, type CalibrationSnapshot, CalibrationSnapshotService } from "./calibration-snapshot-service.cjs";
 import { EnergyAppDataBus } from "@enyo-energy/energy-app-sdk/dist/packages/energy-app-data-bus.js";
 /**
  * Base abstract class for all Sunspec devices
@@ -25,6 +26,7 @@ export declare abstract class BaseSunspecDevice {
     protected dataBus?: EnergyAppDataBus;
     protected retryManager: ConnectionRetryManager;
     protected consecutiveReconnectFailures: number;
+    protected calibrationService?: CalibrationSnapshotService;
     constructor(energyApp: EnergyApp, name: EnyoApplianceName[], networkDevice: EnyoNetworkDevice, sunspecClient: SunspecModbusClient, applianceManager: ApplianceManager, unitId?: number, port?: number, baseAddress?: number, retryConfig?: IRetryConfig, appliance?: EnyoAppliance, useTls?: boolean | undefined);
     /**
      * Connect to the device and create/update the appliance
@@ -77,6 +79,17 @@ export declare abstract class BaseSunspecDevice {
      */
     protected markOffline(): Promise<void>;
     protected sendCommandAcknowledge(messageId: string, acknowledgeMessage: EnyoDataBusMessageEnum | string, answer: EnyoCommandAcknowledgeAnswerEnum, rejectionReason?: string): void;
+    /**
+     * Lazily construct and initialize the per-appliance CalibrationSnapshotService. Reloads
+     * any persisted snapshot from storage so an in-flight calibration survives restarts.
+     * Idempotent — subsequent calls are no-ops once the service exists.
+     */
+    protected initCalibrationService(deviceType: CalibrationDeviceType): Promise<void>;
+    /**
+     * Subclasses implement how to write the modified fields of a snapshot back to the device.
+     * Called both on explicit StopCalibrationV1 and when the 5-minute auto-stop fires.
+     */
+    protected restoreFromCalibrationSnapshot(_snapshot: CalibrationSnapshot, _reason: CalibrationRestoreReason): Promise<void>;
 }
 /**
  * Sunspec Inverter implementation using dynamic model discovery
@@ -156,6 +169,9 @@ export declare class SunspecInverter extends BaseSunspecDevice {
     stopDataBusListening(): void;
     private handleInverterCommand;
     private handleSetFeedInLimit;
+    private handleStartCalibration;
+    private handleStopCalibration;
+    protected restoreFromCalibrationSnapshot(snapshot: CalibrationSnapshot, reason: CalibrationRestoreReason): Promise<void>;
 }
 /**
  * Sunspec Battery implementation
@@ -288,6 +304,9 @@ export declare class SunspecBattery extends BaseSunspecDevice {
     private handleStopGridCharge;
     private handleSetDischargeLimit;
     private handleSetChargeLimit;
+    private handleStartCalibration;
+    private handleStopCalibration;
+    protected restoreFromCalibrationSnapshot(snapshot: CalibrationSnapshot, reason: CalibrationRestoreReason): Promise<void>;
 }
 /**
  * Sunspec Meter implementation
@@ -303,6 +322,13 @@ export declare class SunspecMeter extends BaseSunspecDevice {
      * Disconnect from the meter and update appliance state
      */
     disconnect(): Promise<void>;
+    /**
+     * Meter does not implement calibration; it only subscribes to Start/StopCalibrationV1 to
+     * answer NotSupported (per the data-bus contract that every command must be acknowledged).
+     */
+    startDataBusListening(): void;
+    stopDataBusListening(): void;
+    private handleMeterCommand;
     /**
      * Update meter data and return data bus messages
      */

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

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export * from './sunspec-interfaces.js';
 export * from './sunspec-devices.js';
 export * from './sunspec-modbus-client.js';
+export * from './calibration-snapshot-service.js';
 export { ConnectionRetryManager } from './connection-retry-manager.js';
 export { SDK_VERSION, getSdkVersion } from './version.js';

package/dist/index.js

@@ -1,5 +1,6 @@
 export * from './sunspec-interfaces.js';
 export * from './sunspec-devices.js';
 export * from './sunspec-modbus-client.js';
+export * from './calibration-snapshot-service.js';
 export { ConnectionRetryManager } from './connection-retry-manager.js';
 export { SDK_VERSION, getSdkVersion } from './version.js';

package/dist/sunspec-devices.d.ts

@@ -5,6 +5,7 @@ import { EnyoNetworkDevice } from "@enyo-energy/energy-app-sdk/dist/types/enyo-n
 import { SunspecModbusClient } from "./sunspec-modbus-client.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 { type CalibrationDeviceType, type CalibrationRestoreReason, type CalibrationSnapshot, CalibrationSnapshotService } from "./calibration-snapshot-service.js";
 import { EnergyAppDataBus } from "@enyo-energy/energy-app-sdk/dist/packages/energy-app-data-bus.js";
 /**
  * Base abstract class for all Sunspec devices
@@ -25,6 +26,7 @@ export declare abstract class BaseSunspecDevice {
     protected dataBus?: EnergyAppDataBus;
     protected retryManager: ConnectionRetryManager;
     protected consecutiveReconnectFailures: number;
+    protected calibrationService?: CalibrationSnapshotService;
     constructor(energyApp: EnergyApp, name: EnyoApplianceName[], networkDevice: EnyoNetworkDevice, sunspecClient: SunspecModbusClient, applianceManager: ApplianceManager, unitId?: number, port?: number, baseAddress?: number, retryConfig?: IRetryConfig, appliance?: EnyoAppliance, useTls?: boolean | undefined);
     /**
      * Connect to the device and create/update the appliance
@@ -77,6 +79,17 @@ export declare abstract class BaseSunspecDevice {
      */
     protected markOffline(): Promise<void>;
     protected sendCommandAcknowledge(messageId: string, acknowledgeMessage: EnyoDataBusMessageEnum | string, answer: EnyoCommandAcknowledgeAnswerEnum, rejectionReason?: string): void;
+    /**
+     * Lazily construct and initialize the per-appliance CalibrationSnapshotService. Reloads
+     * any persisted snapshot from storage so an in-flight calibration survives restarts.
+     * Idempotent — subsequent calls are no-ops once the service exists.
+     */
+    protected initCalibrationService(deviceType: CalibrationDeviceType): Promise<void>;
+    /**
+     * Subclasses implement how to write the modified fields of a snapshot back to the device.
+     * Called both on explicit StopCalibrationV1 and when the 5-minute auto-stop fires.
+     */
+    protected restoreFromCalibrationSnapshot(_snapshot: CalibrationSnapshot, _reason: CalibrationRestoreReason): Promise<void>;
 }
 /**
  * Sunspec Inverter implementation using dynamic model discovery
@@ -156,6 +169,9 @@ export declare class SunspecInverter extends BaseSunspecDevice {
     stopDataBusListening(): void;
     private handleInverterCommand;
     private handleSetFeedInLimit;
+    private handleStartCalibration;
+    private handleStopCalibration;
+    protected restoreFromCalibrationSnapshot(snapshot: CalibrationSnapshot, reason: CalibrationRestoreReason): Promise<void>;
 }
 /**
  * Sunspec Battery implementation
@@ -288,6 +304,9 @@ export declare class SunspecBattery extends BaseSunspecDevice {
     private handleStopGridCharge;
     private handleSetDischargeLimit;
     private handleSetChargeLimit;
+    private handleStartCalibration;
+    private handleStopCalibration;
+    protected restoreFromCalibrationSnapshot(snapshot: CalibrationSnapshot, reason: CalibrationRestoreReason): Promise<void>;
 }
 /**
  * Sunspec Meter implementation
@@ -303,6 +322,13 @@ export declare class SunspecMeter extends BaseSunspecDevice {
      * Disconnect from the meter and update appliance state
      */
     disconnect(): Promise<void>;
+    /**
+     * Meter does not implement calibration; it only subscribes to Start/StopCalibrationV1 to
+     * answer NotSupported (per the data-bus contract that every command must be acknowledged).
+     */
+    startDataBusListening(): void;
+    stopDataBusListening(): void;
+    private handleMeterCommand;
     /**
      * Update meter data and return data bus messages
      */