@enyo-energy/sunspec-sdk 0.0.70 → 0.0.71

package/dist/sunspec-devices.js

@@ -3,6 +3,7 @@ import { randomUUID } from "node:crypto";
 import { EnyoApplianceConnectionType, EnyoApplianceStateEnum, EnyoApplianceStatusEnum, EnyoApplianceTopologyFeatureEnum, EnyoApplianceTypeEnum } from "@enyo-energy/energy-app-sdk/dist/types/enyo-appliance.js";
 import { ConnectionRetryManager } from "./connection-retry-manager.js";
 import { EnyoBatteryStateEnum, EnyoCommandAcknowledgeAnswerEnum, EnyoDataBusMessageEnum, EnyoInverterStateEnum, EnyoStringStateEnum } from "@enyo-energy/energy-app-sdk/dist/types/enyo-data-bus-value.js";
+import { CalibrationSnapshotService } from "./calibration-snapshot-service.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";
@@ -96,6 +97,7 @@ export 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;
@@ -249,6 +251,27 @@ export 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 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.
+    }
 }
 /**
  * Sunspec Inverter implementation using dynamic model discovery
@@ -671,8 +694,16 @@ export 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([EnyoDataBusMessageEnum.SetInverterFeedInLimitV1], (entry) => this.handleInverterCommand(entry));
+        this.dataBusListenerId = this.dataBus.listenForMessages([
+            EnyoDataBusMessageEnum.SetInverterFeedInLimitV1,
+            EnyoDataBusMessageEnum.StartCalibrationV1,
+            EnyoDataBusMessageEnum.StopCalibrationV1,
+        ], (entry) => this.handleInverterCommand(entry));
         console.log(`Inverter ${this.applianceId}: started data bus listening (listener ${this.dataBusListenerId})`);
     }
     /**
@@ -692,8 +723,16 @@ export class SunspecInverter extends BaseSunspecDevice {
         }
         void (async () => {
             try {
-                if (entry.message === EnyoDataBusMessageEnum.SetInverterFeedInLimitV1) {
-                    await this.handleSetFeedInLimit(entry);
+                switch (entry.message) {
+                    case EnyoDataBusMessageEnum.SetInverterFeedInLimitV1:
+                        await this.handleSetFeedInLimit(entry);
+                        break;
+                    case EnyoDataBusMessageEnum.StartCalibrationV1:
+                        await this.handleStartCalibration(entry);
+                        break;
+                    case EnyoDataBusMessageEnum.StopCalibrationV1:
+                        await this.handleStopCalibration(entry);
+                        break;
                 }
             }
             catch (error) {
@@ -717,8 +756,93 @@ export class SunspecInverter extends BaseSunspecDevice {
             this.sendCommandAcknowledge(msg.id, msg.message, 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, EnyoCommandAcknowledgeAnswerEnum.Accepted);
     }
+    async handleStartCalibration(msg) {
+        if (!this.isConnected() || !this.applianceId) {
+            this.sendCommandAcknowledge(msg.id, msg.message, EnyoCommandAcknowledgeAnswerEnum.Rejected, 'Not connected');
+            return;
+        }
+        if (!this.calibrationService) {
+            await this.initCalibrationService('inverter');
+        }
+        if (!this.calibrationService) {
+            this.sendCommandAcknowledge(msg.id, msg.message, 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, 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, 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, EnyoCommandAcknowledgeAnswerEnum.Rejected, `Failed to persist snapshot: ${error}`);
+            return;
+        }
+        this.sendCommandAcknowledge(msg.id, msg.message, EnyoCommandAcknowledgeAnswerEnum.Accepted);
+    }
+    async handleStopCalibration(msg) {
+        if (!this.applianceId) {
+            this.sendCommandAcknowledge(msg.id, msg.message, 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, EnyoCommandAcknowledgeAnswerEnum.Accepted);
+            return;
+        }
+        try {
+            await this.restoreFromCalibrationSnapshot(snapshot, 'stop');
+        }
+        catch (error) {
+            this.sendCommandAcknowledge(msg.id, msg.message, EnyoCommandAcknowledgeAnswerEnum.Rejected, `Failed to restore registers: ${error}`);
+            return;
+        }
+        this.sendCommandAcknowledge(msg.id, msg.message, 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');
+        }
+    }
 }
 /**
  * Sunspec Battery implementation
@@ -1162,12 +1286,16 @@ export 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([
             EnyoDataBusMessageEnum.StartStorageGridChargeV1,
             EnyoDataBusMessageEnum.StopStorageGridChargeV1,
             EnyoDataBusMessageEnum.SetStorageDischargeLimitV1,
-            EnyoDataBusMessageEnum.SetStorageChargeLimitV1
+            EnyoDataBusMessageEnum.SetStorageChargeLimitV1,
+            EnyoDataBusMessageEnum.StartCalibrationV1,
+            EnyoDataBusMessageEnum.StopCalibrationV1,
         ], (entry) => this.handleStorageCommand(entry));
         console.log(`Battery ${this.applianceId}: started data bus listening (listener ${this.dataBusListenerId})`);
     }
@@ -1201,6 +1329,12 @@ export class SunspecBattery extends BaseSunspecDevice {
                     case EnyoDataBusMessageEnum.SetStorageChargeLimitV1:
                         await this.handleSetChargeLimit(entry);
                         break;
+                    case EnyoDataBusMessageEnum.StartCalibrationV1:
+                        await this.handleStartCalibration(entry);
+                        break;
+                    case EnyoDataBusMessageEnum.StopCalibrationV1:
+                        await this.handleStopCalibration(entry);
+                        break;
                 }
             }
             catch (error) {
@@ -1241,6 +1375,7 @@ export class SunspecBattery extends BaseSunspecDevice {
             this.sendCommandAcknowledge(msg.id, msg.message, EnyoCommandAcknowledgeAnswerEnum.Rejected, 'Failed to set storage mode to charge');
             return;
         }
+        await this.calibrationService?.recordModification(['chaGriSet', 'wChaMax', 'storCtlMod']);
         this.sendCommandAcknowledge(msg.id, msg.message, EnyoCommandAcknowledgeAnswerEnum.Accepted);
     }
     async handleStopGridCharge(msg) {
@@ -1267,6 +1402,7 @@ export class SunspecBattery extends BaseSunspecDevice {
             this.sendCommandAcknowledge(msg.id, msg.message, EnyoCommandAcknowledgeAnswerEnum.Rejected, 'Failed to set storage mode to auto');
             return;
         }
+        await this.calibrationService?.recordModification(['chaGriSet', 'storCtlMod']);
         this.sendCommandAcknowledge(msg.id, msg.message, EnyoCommandAcknowledgeAnswerEnum.Accepted);
     }
     async handleSetDischargeLimit(msg) {
@@ -1291,6 +1427,7 @@ export class SunspecBattery extends BaseSunspecDevice {
             this.sendCommandAcknowledge(msg.id, msg.message, EnyoCommandAcknowledgeAnswerEnum.Rejected, 'Failed to set discharge limit');
             return;
         }
+        await this.calibrationService?.recordModification(['outWRte']);
         this.sendCommandAcknowledge(msg.id, msg.message, EnyoCommandAcknowledgeAnswerEnum.Accepted);
     }
     async handleSetChargeLimit(msg) {
@@ -1315,8 +1452,88 @@ export class SunspecBattery extends BaseSunspecDevice {
             this.sendCommandAcknowledge(msg.id, msg.message, EnyoCommandAcknowledgeAnswerEnum.Rejected, 'Failed to set charge limit');
             return;
         }
+        await this.calibrationService?.recordModification(['inWRte']);
         this.sendCommandAcknowledge(msg.id, msg.message, EnyoCommandAcknowledgeAnswerEnum.Accepted);
     }
+    async handleStartCalibration(msg) {
+        if (!this.isConnected() || !this.applianceId) {
+            this.sendCommandAcknowledge(msg.id, msg.message, EnyoCommandAcknowledgeAnswerEnum.Rejected, 'Not connected');
+            return;
+        }
+        if (!this.calibrationService) {
+            await this.initCalibrationService('battery');
+        }
+        if (!this.calibrationService) {
+            this.sendCommandAcknowledge(msg.id, msg.message, 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, 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, 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, EnyoCommandAcknowledgeAnswerEnum.Rejected, `Failed to persist snapshot: ${error}`);
+            return;
+        }
+        this.sendCommandAcknowledge(msg.id, msg.message, EnyoCommandAcknowledgeAnswerEnum.Accepted);
+    }
+    async handleStopCalibration(msg) {
+        if (!this.applianceId) {
+            this.sendCommandAcknowledge(msg.id, msg.message, 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, EnyoCommandAcknowledgeAnswerEnum.Accepted);
+            return;
+        }
+        try {
+            await this.restoreFromCalibrationSnapshot(snapshot, 'stop');
+        }
+        catch (error) {
+            this.sendCommandAcknowledge(msg.id, msg.message, EnyoCommandAcknowledgeAnswerEnum.Rejected, `Failed to restore registers: ${error}`);
+            return;
+        }
+        this.sendCommandAcknowledge(msg.id, msg.message, 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');
+        }
+    }
 }
 /**
  * Sunspec Meter implementation
@@ -1391,11 +1608,13 @@ export 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, EnyoApplianceConnectionType.Connector, EnyoApplianceStateEnum.Offline);
@@ -1407,6 +1626,35 @@ export 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([
+            EnyoDataBusMessageEnum.StartCalibrationV1,
+            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, EnyoCommandAcknowledgeAnswerEnum.NotSupported, 'Meter does not support calibration');
+    }
     /**
      * Update meter data and return data bus messages
      */

package/dist/version.d.ts

@@ -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/version.js

@@ -5,7 +5,7 @@
 /**
  * Current version of the enyo Energy App SDK.
  */
-export const SDK_VERSION = '0.0.70';
+export const SDK_VERSION = '0.0.71';
 /**
  * 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.70",
+  "version": "0.0.71",
   "description": "enyo Energy Sunspec SDK",
   "type": "module",
   "main": "dist/index.js",
@@ -37,7 +37,7 @@
     "typescript": "^5.8.3"
   },
   "dependencies": {
-    "@enyo-energy/energy-app-sdk": "^0.0.136"
+    "@enyo-energy/energy-app-sdk": "^0.0.137"
   },
   "volta": {
     "node": "22.17.0"