@enyo-energy/sunspec-sdk 0.0.71 → 0.0.73

package/dist/sunspec-devices.js

@@ -1,9 +1,13 @@
-import { SunspecBatteryChargeState, SunspecEnableControl, SunspecInverterCapability, SunspecInverterEvent1, SunspecModelId, SunspecMPPTOperatingState, SunspecStorageMode, SUNSPEC_CONNECTION_LOST_CODE } from "./sunspec-interfaces.js";
+import { SunspecBatteryChargeState, SunspecBatteryFeatureModeKind, SunspecEnableControl, SunspecInverterCapability, SunspecInverterEvent1, SunspecModelId, SunspecMPPTOperatingState, SunspecStorageMode, SUNSPEC_CONNECTION_LOST_CODE } from "./sunspec-interfaces.js";
 import { randomUUID } from "node:crypto";
 import { EnyoApplianceConnectionType, EnyoApplianceStateEnum, EnyoApplianceStatusEnum, EnyoApplianceTopologyFeatureEnum, EnyoApplianceTypeEnum } from "@enyo-energy/energy-app-sdk/dist/types/enyo-appliance.js";
 import { ConnectionRetryManager } from "./connection-retry-manager.js";
 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 { SnapshotService, } from "@enyo-energy/appliance-calibration";
+import { SunspecCalibrationStorage } from "./sunspec-calibration-storage.js";
+import { SunspecBatteryCalibrationDriver } from "./sunspec-battery-calibration-driver.js";
+import { SunspecBatteryScheduleHandler } from "./sunspec-battery-schedule-handler.js";
+import { SunspecBatteryFeatureCalibrator, decodeFeatureResults } from "./sunspec-battery-feature-calibrator.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";
@@ -97,7 +101,13 @@ export class BaseSunspecDevice {
     dataBus;
     retryManager;
     consecutiveReconnectFailures = 0;
-    calibrationService;
+    /**
+     * Prefix used when persisting calibration snapshots via the library's
+     * {@link SnapshotService}. Kept identical to the key the SDK used before
+     * the migration to `@enyo-energy/appliance-calibration` so existing
+     * snapshots stored by older builds are still picked up on startup.
+     */
+    static CALIBRATION_SNAPSHOT_KEY_PREFIX = "sunspec-calibration-snapshot-";
     constructor(energyApp, name, networkDevice, sunspecClient, applianceManager, unitId = 1, port = 502, baseAddress = 40000, retryConfig, appliance, useTls) {
         this.energyApp = energyApp;
         this.name = name;
@@ -252,25 +262,18 @@ export class BaseSunspecDevice {
         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.
+     * Build a typed {@link SnapshotService} bound to this appliance's calibration storage,
+     * using the legacy SDK storage key prefix so prior installs upgrade seamlessly. Returns
+     * undefined if the appliance has not been registered yet.
      */
-    async initCalibrationService(deviceType) {
-        if (this.calibrationService || !this.applianceId) {
-            return;
+    buildSnapshotService(onRestore) {
+        if (!this.applianceId) {
+            return undefined;
         }
-        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.
+        const storage = new SunspecCalibrationStorage(this.energyApp.useStorage());
+        return new SnapshotService(storage, this.applianceId, onRestore, {
+            storageKeyPrefix: BaseSunspecDevice.CALIBRATION_SNAPSHOT_KEY_PREFIX,
+        });
     }
 }
 /**
@@ -282,6 +285,7 @@ export class SunspecInverter extends BaseSunspecDevice {
     static CONNECTION_FAULT_THRESHOLD = 3;
     storage;
     errorState = { activeCodes: [], lastStatus: 'healthy' };
+    snapshotService;
     constructor(energyApp, name, networkDevice, sunspecClient, applianceManager, unitId = 1, port = 502, baseAddress = 40000, capabilities = [], retryConfig, appliance, useTls) {
         super(energyApp, name, networkDevice, sunspecClient, applianceManager, unitId, port, baseAddress, retryConfig, appliance, useTls);
         this.capabilities = capabilities;
@@ -694,10 +698,10 @@ export class SunspecInverter extends BaseSunspecDevice {
         if (this.dataBusListenerId) {
             return;
         }
-        // Fire and forget — calibration service hydration must not block listening setup.
+        // Fire and forget — snapshot service hydration must not block listener setup.
         // Listener registration before await ensures we don't miss messages that arrive
-        // during initial load.
-        void this.initCalibrationService('inverter');
+        // during the initial load.
+        void this.initSnapshotService();
         this.dataBus = this.energyApp.useDataBus();
         this.dataBusListenerId = this.dataBus.listenForMessages([
             EnyoDataBusMessageEnum.SetInverterFeedInLimitV1,
@@ -758,22 +762,39 @@ export class SunspecInverter extends BaseSunspecDevice {
         }
         // 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']);
+        await this.snapshotService?.recordModification(['WMaxLimPct', 'WMaxLim_Ena']);
         this.sendCommandAcknowledge(msg.id, msg.message, EnyoCommandAcknowledgeAnswerEnum.Accepted);
     }
+    /**
+     * Lazily construct the per-appliance {@link SnapshotService}. Reloads any
+     * persisted snapshot from storage so an in-flight calibration survives
+     * process restarts. Idempotent.
+     */
+    async initSnapshotService() {
+        if (this.snapshotService) {
+            return;
+        }
+        const service = this.buildSnapshotService((snapshot, reason) => this.restoreInverterSnapshot(snapshot, reason));
+        if (!service) {
+            return;
+        }
+        this.snapshotService = service;
+        await this.snapshotService.initialize();
+        console.log(`Inverter ${this.applianceId}: snapshot service initialized`);
+    }
     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.snapshotService) {
+            await this.initSnapshotService();
         }
-        if (!this.calibrationService) {
-            this.sendCommandAcknowledge(msg.id, msg.message, EnyoCommandAcknowledgeAnswerEnum.Rejected, 'Calibration service unavailable');
+        if (!this.snapshotService) {
+            this.sendCommandAcknowledge(msg.id, msg.message, EnyoCommandAcknowledgeAnswerEnum.Rejected, 'Snapshot service unavailable');
             return;
         }
-        if (this.calibrationService.isCalibrating()) {
+        if (this.snapshotService.isCalibrating()) {
             console.log(`Inverter ${this.applianceId}: calibration already active — ack idempotently`);
             this.sendCommandAcknowledge(msg.id, msg.message, EnyoCommandAcknowledgeAnswerEnum.Accepted);
             return;
@@ -785,11 +806,7 @@ export class SunspecInverter extends BaseSunspecDevice {
             return;
         }
         try {
-            await this.calibrationService.startCalibration({
-                deviceType: 'inverter',
-                unitId: this.unitId,
-                inverterControls: controls,
-            });
+            await this.snapshotService.startCalibration(controls);
         }
         catch (error) {
             this.sendCommandAcknowledge(msg.id, msg.message, EnyoCommandAcknowledgeAnswerEnum.Rejected, `Failed to persist snapshot: ${error}`);
@@ -803,30 +820,23 @@ export class SunspecInverter extends BaseSunspecDevice {
             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;
-        }
+        // SnapshotService.stopCalibration fires `restoreInverterSnapshot` internally with
+        // reason="stop" before returning. Any restore failure is logged by the callback
+        // (the persisted snapshot is already gone by then — see library notes) so we
+        // always ack Accepted from here.
+        await this.snapshotService?.stopCalibration();
         this.sendCommandAcknowledge(msg.id, msg.message, EnyoCommandAcknowledgeAnswerEnum.Accepted);
     }
-    async restoreFromCalibrationSnapshot(snapshot, reason) {
-        if (snapshot.deviceType !== 'inverter' || !snapshot.inverterControls) {
-            return;
-        }
-        const source = snapshot.inverterControls;
+    /**
+     * `onRestore` callback for the inverter's {@link SnapshotService}. Writes only the
+     * subset of writable inverter fields that other commands actually touched during the
+     * calibration. Catches and logs failures rather than throwing — the snapshot has
+     * already been removed from storage by the time this runs, so a throw is unrecoverable
+     * and is best logged for operator action.
+     */
+    async restoreInverterSnapshot(snapshot, reason) {
+        const source = snapshot.payload;
         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) {
@@ -838,21 +848,174 @@ export class SunspecInverter extends BaseSunspecDevice {
             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');
+        try {
+            const ok = await this.sunspecClient.writeInverterControls(this.unitId, partial);
+            if (!ok) {
+                console.error(`Inverter ${this.applianceId}: calibration ${reason} — writeInverterControls returned false`);
+            }
+        }
+        catch (error) {
+            console.error(`Inverter ${this.applianceId}: calibration ${reason} — writeInverterControls threw: ${error}`);
         }
     }
 }
+/**
+ * Pure register-presence detection — exported so it can be unit-tested
+ * without the full `SunspecBattery` scaffold. Maps each Model 124 writable
+ * register to the `EnyoBatteryFeature` it represents:
+ *
+ * - `chaGriSet`  → `GridCharging` (charge source PV/GRID)
+ * - `wChaMax`    → `ChargeLimitation` (max charge power)
+ * - `outWRte`    → `DischargeLimitation` (discharge rate %)
+ * - `storCtlMod` → `GridDischarging` (closest signal that external discharge
+ *                  control is available; the inverter decides where it goes)
+ */
+export function detectFeaturesFromRegisters(batteryData) {
+    const features = [];
+    if (batteryData?.chaGriSet !== undefined)
+        features.push(EnyoBatteryFeature.GridCharging);
+    if (batteryData?.wChaMax !== undefined)
+        features.push(EnyoBatteryFeature.ChargeLimitation);
+    if (batteryData?.outWRte !== undefined)
+        features.push(EnyoBatteryFeature.DischargeLimitation);
+    if (batteryData?.storCtlMod !== undefined)
+        features.push(EnyoBatteryFeature.GridDischarging);
+    return features;
+}
+/**
+ * Apply the per-feature calibration filter to a register-detected set.
+ * Exported for unit-test access to the legacy-result fallback branch.
+ *
+ * The contract:
+ * - No `result` or `result.state !== 'calibrated'` → strip every controllable
+ *   feature (safe fallback while waiting for calibration).
+ * - `result.state === 'calibrated'` with a decodable per-feature payload →
+ *   publish only the controllable features whose probes passed.
+ * - `result.state === 'calibrated'` with **no** decodable payload → legacy
+ *   data (pre-feature-calibrator SDK). The new calibrator only marks
+ *   `state=calibrated` when at least one probe passes, so an empty decoded
+ *   set with `state=calibrated` unambiguously signals legacy results. Publish
+ *   the full detected set to preserve the old all-or-nothing semantics on
+ *   upgrade.
+ */
+export function filterFeaturesByCalibrationResult(detected, result, controllable) {
+    if (!result || result.state !== 'calibrated') {
+        return detected.filter(f => !controllable.includes(f));
+    }
+    const passed = decodeFeatureResults(result.notes);
+    if (passed.size === 0)
+        return detected;
+    return detected.filter(f => !controllable.includes(f) || passed.has(f));
+}
 /**
  * Sunspec Battery implementation
  */
 export class SunspecBattery extends BaseSunspecDevice {
+    featureMode;
     capabilities;
-    constructor(energyApp, name, networkDevice, sunspecClient, applianceManager, unitId = 1, port = 502, baseAddress = 40000, capabilities = [], retryConfig, appliance, useTls) {
+    snapshotService;
+    calibrationDriver;
+    batteryCalibrator;
+    calibrationResultStore;
+    scheduleHandler;
+    /**
+     * Battery features that imply outbound control writes from the host action-taker.
+     * These are stripped from `appliance.battery.features` until the calibration result
+     * store says this battery has been successfully calibrated — see
+     * {@link computeAdvertisedFeatures}.
+     */
+    static CONTROLLABLE_FEATURES = [
+        EnyoBatteryFeature.GridCharging,
+        EnyoBatteryFeature.GridDischarging,
+        EnyoBatteryFeature.ChargeLimitation,
+        EnyoBatteryFeature.DischargeLimitation,
+    ];
+    constructor(energyApp, name, networkDevice, sunspecClient, applianceManager, featureMode, unitId = 1, port = 502, baseAddress = 40000, capabilities = [], retryConfig, appliance, useTls) {
         super(energyApp, name, networkDevice, sunspecClient, applianceManager, unitId, port, baseAddress, retryConfig, appliance, useTls);
+        this.featureMode = featureMode;
         this.capabilities = capabilities;
     }
+    /**
+     * Wire the battery into `@enyo-energy/appliance-calibration`'s
+     * `BatteryCalibrator` test-charge flow. Call once after {@link connect}.
+     *
+     * Consumers own the `CalibrationResultStore` (shared across appliances so
+     * the persisted result map doesn't get clobbered) and the
+     * `CalibrationTrigger` that drives `runCalibration()` on whatever schedule
+     * makes sense for the host. Pass overrides for the calibrator's defaults
+     * (`testPowerW`, response thresholds, etc.) via `opts.config`.
+     */
+    configureCalibration(opts) {
+        if (this.featureMode.kind !== SunspecBatteryFeatureModeKind.CalibrationBased) {
+            throw new Error(`SunspecBattery.configureCalibration: featureMode is '${this.featureMode.kind}', ` +
+                `but calibration is only valid in '${SunspecBatteryFeatureModeKind.CalibrationBased}' mode. ` +
+                `Pass { kind: SunspecBatteryFeatureModeKind.CalibrationBased } to the constructor.`);
+        }
+        if (this.batteryCalibrator) {
+            return this.batteryCalibrator;
+        }
+        if (!this.applianceId) {
+            throw new Error("SunspecBattery.configureCalibration: connect() must complete first (applianceId required)");
+        }
+        if (!this.snapshotService) {
+            throw new Error("SunspecBattery.configureCalibration: snapshot service not initialized — call connect() first");
+        }
+        const driver = new SunspecBatteryCalibrationDriver(this.sunspecClient, this.unitId, this.energyApp.useDataBus());
+        this.calibrationDriver = driver;
+        this.calibrationResultStore = opts.resultStore;
+        this.batteryCalibrator = new SunspecBatteryFeatureCalibrator({
+            applianceId: this.applianceId,
+            driver,
+            sunspecClient: this.sunspecClient,
+            unitId: this.unitId,
+            readBatteryData: () => this.sunspecClient.readBatteryData(this.unitId),
+            snapshotService: this.snapshotService,
+            resultStore: opts.resultStore,
+            config: opts.config,
+        });
+        return this.batteryCalibrator;
+    }
+    /**
+     * Detect which battery features the device's registers expose. This is the
+     * raw, register-only view; the {@link featureMode} configured at
+     * construction decides what is actually published — see
+     * {@link resolveAdvertisedFeatures}.
+     */
+    detectFromRegisters(batteryData) {
+        return detectFeaturesFromRegisters(batteryData);
+    }
+    /**
+     * Resolve `appliance.battery.features` for the configured mode. Called on
+     * every connect() and readData() cycle so that, in calibration-based mode,
+     * the controllable features appear as soon as the calibrator flips
+     * `isCalibrated` (no synchronous push).
+     */
+    resolveAdvertisedFeatures(batteryData) {
+        const allow = this.featureMode.allowedFeatures;
+        const intersect = (xs) => allow ? xs.filter(f => allow.includes(f)) : xs;
+        switch (this.featureMode.kind) {
+            case SunspecBatteryFeatureModeKind.Disabled:
+                return allow ? [...allow] : [];
+            case SunspecBatteryFeatureModeKind.RegisterBased:
+                return intersect(this.detectFromRegisters(batteryData));
+            case SunspecBatteryFeatureModeKind.CalibrationBased: {
+                const detected = intersect(this.detectFromRegisters(batteryData));
+                const result = this.applianceId
+                    ? this.calibrationResultStore?.getResult(this.applianceId)
+                    : undefined;
+                return filterFeaturesByCalibrationResult(detected, result, SunspecBattery.CONTROLLABLE_FEATURES);
+            }
+        }
+    }
+    /**
+     * Returns the per-battery `BatteryCalibrator` created by
+     * {@link configureCalibration}, or `undefined` if calibration was never
+     * configured. Consumers register the returned instance with their own
+     * `CalibrationTrigger`.
+     */
+    getBatteryCalibrator() {
+        return this.batteryCalibrator;
+    }
     /**
      * Connect to the battery and create/update the appliance
      */
@@ -869,13 +1032,7 @@ export class SunspecBattery extends BaseSunspecDevice {
         const commonData = await this.sunspecClient.readCommonBlock(this.unitId);
         const batteryData = await this.sunspecClient.readBatteryData(this.unitId);
         const storageMode = this.determineStorageMode(batteryData);
-        const features = [];
-        if (batteryData?.chaGriSet !== undefined) {
-            features.push(EnyoBatteryFeature.GridCharging);
-        }
-        if (batteryData?.wChaMax !== undefined) {
-            features.push(EnyoBatteryFeature.ChargeLimitation);
-        }
+        const features = this.resolveAdvertisedFeatures(batteryData);
         const activeChargeLimitW = this.computeActiveChargeLimitW(batteryData);
         const activeDischargeLimitW = this.computeActiveDischargeLimitW(batteryData);
         // Create or update appliance (skip if an existing appliance was provided)
@@ -942,6 +1099,11 @@ export class SunspecBattery extends BaseSunspecDevice {
     }
     async disconnect() {
         this.stopDataBusListening();
+        if (this.calibrationDriver) {
+            this.calibrationDriver.stop();
+            this.calibrationDriver = undefined;
+            this.batteryCalibrator = undefined;
+        }
         if (this.applianceId) {
             try {
                 await this.applianceManager.updateApplianceState(this.applianceId, EnyoApplianceConnectionType.Connector, EnyoApplianceStateEnum.Offline);
@@ -1010,6 +1172,11 @@ export class SunspecBattery extends BaseSunspecDevice {
                 else if (!advancedBatteryModel) {
                     batteryPowerW = mpptBatteryPowerW;
                 }
+                // Feed the calibration driver's synchronous power cache. No-op when calibration
+                // was never configured.
+                if (batteryPowerW !== undefined && this.calibrationDriver) {
+                    this.calibrationDriver.updateBatteryPowerCache(batteryPowerW);
+                }
                 const batteryMessage = {
                     id: randomUUID(),
                     message: EnyoDataBusMessageEnum.BatteryValuesUpdateV1,
@@ -1033,6 +1200,9 @@ export class SunspecBattery extends BaseSunspecDevice {
             if (this.applianceId) {
                 const appliance = await this.applianceManager.findApplianceById(this.applianceId);
                 const storageMode = this.determineStorageMode(batteryData);
+                // Republish features each cycle so the controllable set appears as soon
+                // as the calibrator flips isCalibrated — see resolveAdvertisedFeatures.
+                const features = this.resolveAdvertisedFeatures(batteryData);
                 await this.applianceManager.updateAppliance(this.applianceId, {
                     battery: {
                         ...appliance?.battery,
@@ -1041,6 +1211,7 @@ export class SunspecBattery extends BaseSunspecDevice {
                         maxDischargePowerW: batteryData && batteryData.wChaMax !== undefined && batteryData.outWRte !== undefined ? batteryData.wChaMax * batteryData.outWRte : undefined,
                         activeChargeLimitW: this.computeActiveChargeLimitW(batteryData),
                         activeDischargeLimitW: this.computeActiveDischargeLimitW(batteryData),
+                        features,
                         gridChargingEnabled: batteryData?.chaGriSet === 1
                     }
                 });
@@ -1286,17 +1457,27 @@ export class SunspecBattery extends BaseSunspecDevice {
         if (this.dataBusListenerId) {
             return;
         }
-        // Fire and forget — calibration service hydration must not block listening setup.
-        void this.initCalibrationService('battery');
+        // Fire and forget — snapshot service hydration must not block listener setup.
+        void this.initSnapshotService();
         this.dataBus = this.energyApp.useDataBus();
         this.dataBusListenerId = this.dataBus.listenForMessages([
-            EnyoDataBusMessageEnum.StartStorageGridChargeV1,
-            EnyoDataBusMessageEnum.StopStorageGridChargeV1,
-            EnyoDataBusMessageEnum.SetStorageDischargeLimitV1,
-            EnyoDataBusMessageEnum.SetStorageChargeLimitV1,
+            EnyoDataBusMessageEnum.SetStorageScheduleV1,
             EnyoDataBusMessageEnum.StartCalibrationV1,
             EnyoDataBusMessageEnum.StopCalibrationV1,
         ], (entry) => this.handleStorageCommand(entry));
+        if (!this.applianceId) {
+            throw new Error("SunspecBattery.startDataBusListening: applianceId required — call connect() first.");
+        }
+        this.scheduleHandler = new SunspecBatteryScheduleHandler({
+            dataBus: this.dataBus,
+            interval: this.energyApp.useInterval(),
+            storage: this.energyApp.useStorage(),
+            applianceId: this.applianceId,
+            sunspecClient: this.sunspecClient,
+            unitId: this.unitId,
+            getSnapshotService: () => this.snapshotService,
+            onErrorCallback: (err) => console.warn(`Battery ${this.applianceId}: schedule handler rejected input: ${err.message}`),
+        });
         console.log(`Battery ${this.applianceId}: started data bus listening (listener ${this.dataBusListenerId})`);
     }
     /**
@@ -1309,6 +1490,7 @@ export class SunspecBattery extends BaseSunspecDevice {
         }
         this.dataBusListenerId = undefined;
         this.dataBus = undefined;
+        this.scheduleHandler?.dispose();
     }
     handleStorageCommand(entry) {
         if (entry.applianceId !== this.applianceId) {
@@ -1317,17 +1499,8 @@ export class SunspecBattery extends BaseSunspecDevice {
         void (async () => {
             try {
                 switch (entry.message) {
-                    case EnyoDataBusMessageEnum.StartStorageGridChargeV1:
-                        await this.handleStartGridCharge(entry);
-                        break;
-                    case EnyoDataBusMessageEnum.StopStorageGridChargeV1:
-                        await this.handleStopGridCharge(entry);
-                        break;
-                    case EnyoDataBusMessageEnum.SetStorageDischargeLimitV1:
-                        await this.handleSetDischargeLimit(entry);
-                        break;
-                    case EnyoDataBusMessageEnum.SetStorageChargeLimitV1:
-                        await this.handleSetChargeLimit(entry);
+                    case EnyoDataBusMessageEnum.SetStorageScheduleV1:
+                        this.handleSetStorageScheduleAck(entry);
                         break;
                     case EnyoDataBusMessageEnum.StartCalibrationV1:
                         await this.handleStartCalibration(entry);
@@ -1342,132 +1515,51 @@ export class SunspecBattery extends BaseSunspecDevice {
             }
         })();
     }
-    async handleStartGridCharge(msg) {
+    /**
+     * Acknowledge a SetStorageScheduleV1 message. The actual schedule application
+     * is owned by `this.scheduleHandler` (subscribed independently via its own
+     * data-bus listener registered in its constructor). The ack reports "received
+     * & queued" rather than "applied" — schedule entries play out over time, and
+     * per-entry write failures land in `console.error` via the handler's
+     * onChange wrapper.
+     */
+    handleSetStorageScheduleAck(msg) {
         if (!this.isConnected() || !this.applianceId) {
             this.sendCommandAcknowledge(msg.id, msg.message, EnyoCommandAcknowledgeAnswerEnum.Rejected, "Not connected");
             return;
         }
-        console.log(`Battery ${this.applianceId}: handling StartStorageGridChargeV1 (powerLimitW=${msg.data.powerLimitW})`);
-        // Read current state for logging and rollback
-        const controls = await this.getBatteryControls();
-        console.log(`Battery ${this.applianceId}: current state - chaGriSet=${controls?.chaGriSet}, wChaMax=${controls?.wChaMax}, storCtlMod=${controls?.storCtlMod}`);
-        const originalChaGriSet = controls?.chaGriSet;
-        const originalWChaMax = controls?.wChaMax;
-        // Step 1: Enable grid charging (Register 17: chaGriSet=GRID)
-        const step1 = await this.enableGridCharging(true);
-        if (!step1) {
-            this.sendCommandAcknowledge(msg.id, msg.message, EnyoCommandAcknowledgeAnswerEnum.Rejected, 'Failed to enable grid charging');
-            return;
-        }
-        // Step 2: Set charging power (Register 2: wChaMax)
-        const step2 = await this.setChargingPower(msg.data.powerLimitW);
-        if (!step2) {
-            // Rollback step 1
-            await this.writeBatteryControls({ chaGriSet: originalChaGriSet });
-            this.sendCommandAcknowledge(msg.id, msg.message, EnyoCommandAcknowledgeAnswerEnum.Rejected, 'Failed to set charging power');
-            return;
-        }
-        // Step 3: Set storage mode to CHARGE (Register 5: storCtlMod=0x0001)
-        const step3 = await this.setStorageMode(SunspecStorageMode.CHARGE);
-        if (!step3) {
-            // Rollback steps 1+2
-            await this.writeBatteryControls({ chaGriSet: originalChaGriSet, wChaMax: originalWChaMax });
-            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) {
-        if (!this.isConnected() || !this.applianceId) {
-            this.sendCommandAcknowledge(msg.id, msg.message, EnyoCommandAcknowledgeAnswerEnum.NotSupported);
-            return;
-        }
-        console.log(`Battery ${this.applianceId}: handling StopStorageGridChargeV1`);
-        // Read current state for logging and rollback
-        const controls = await this.getBatteryControls();
-        console.log(`Battery ${this.applianceId}: current state - chaGriSet=${controls?.chaGriSet}, storCtlMod=${controls?.storCtlMod}`);
-        const originalChaGriSet = controls?.chaGriSet;
-        // Step 1: Disable grid charging (Register 17: chaGriSet=PV)
-        const step1 = await this.enableGridCharging(false);
-        if (!step1) {
-            this.sendCommandAcknowledge(msg.id, msg.message, EnyoCommandAcknowledgeAnswerEnum.Rejected, 'Failed to disable grid charging');
-            return;
-        }
-        // Step 2: Set storage mode to AUTO (Register 5: storCtlMod=0x0003)
-        const step2 = await this.setStorageMode(SunspecStorageMode.AUTO);
-        if (!step2) {
-            // Rollback step 1
-            await this.writeBatteryControls({ chaGriSet: originalChaGriSet });
-            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) {
-        if (!this.isConnected() || !this.applianceId) {
-            this.sendCommandAcknowledge(msg.id, msg.message, EnyoCommandAcknowledgeAnswerEnum.NotSupported);
-            return;
-        }
-        console.log(`Battery ${this.applianceId}: handling SetStorageDischargeLimitV1 (dischargeLimitW=${msg.data.dischargeLimitW})`);
-        // Read current state to get wChaMax for percentage conversion
-        const controls = await this.getBatteryControls();
-        console.log(`Battery ${this.applianceId}: current state - outWRte=${controls?.outWRte}, wChaMax=${controls?.wChaMax}`);
-        if (!controls?.wChaMax) {
-            this.sendCommandAcknowledge(msg.id, msg.message, EnyoCommandAcknowledgeAnswerEnum.Rejected, 'Failed to read wChaMax for discharge limit conversion');
-            return;
-        }
-        // Convert watts to percentage of WDisChaMax (using wChaMax), clamped to 0-100%
-        const dischargeLimitPercent = Math.min(100, Math.max(0, (msg.data.dischargeLimitW / controls.wChaMax) * 100));
-        console.log(`Battery ${this.applianceId}: calculated discharge limit: ${dischargeLimitPercent.toFixed(1)}% (${msg.data.dischargeLimitW}W / ${controls.wChaMax}W)`);
-        // Set discharge limit (Register 12: outWRte)
-        const success = await this.writeBatteryControls({ outWRte: dischargeLimitPercent });
-        if (!success) {
-            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) {
-        if (!this.isConnected() || !this.applianceId) {
-            this.sendCommandAcknowledge(msg.id, msg.message, EnyoCommandAcknowledgeAnswerEnum.NotSupported);
-            return;
-        }
-        console.log(`Battery ${this.applianceId}: handling SetStorageChargeLimitV1 (chargeLimitW=${msg.data.chargeLimitW})`);
-        // Read current state to get wChaMax for percentage conversion
-        const controls = await this.getBatteryControls();
-        console.log(`Battery ${this.applianceId}: current state - inWRte=${controls?.inWRte}, wChaMax=${controls?.wChaMax}`);
-        if (!controls?.wChaMax) {
-            this.sendCommandAcknowledge(msg.id, msg.message, EnyoCommandAcknowledgeAnswerEnum.Rejected, 'Failed to read wChaMax for charge limit conversion');
+    /**
+     * Lazily construct the per-appliance {@link SnapshotService}. Reloads any
+     * persisted snapshot from storage so an in-flight calibration survives
+     * process restarts. Idempotent.
+     */
+    async initSnapshotService() {
+        if (this.snapshotService) {
             return;
         }
-        // Convert watts to percentage of WChaMax, clamped to 0-100%
-        const chargeLimitPercent = Math.min(100, Math.max(0, (msg.data.chargeLimitW / controls.wChaMax) * 100));
-        console.log(`Battery ${this.applianceId}: calculated charge limit: ${chargeLimitPercent.toFixed(1)}% (${msg.data.chargeLimitW}W / ${controls.wChaMax}W)`);
-        // Set charge limit (Register 13: inWRte)
-        const success = await this.writeBatteryControls({ inWRte: chargeLimitPercent });
-        if (!success) {
-            this.sendCommandAcknowledge(msg.id, msg.message, EnyoCommandAcknowledgeAnswerEnum.Rejected, 'Failed to set charge limit');
+        const service = this.buildSnapshotService((snapshot, reason) => this.restoreBatterySnapshot(snapshot, reason));
+        if (!service) {
             return;
         }
-        await this.calibrationService?.recordModification(['inWRte']);
-        this.sendCommandAcknowledge(msg.id, msg.message, EnyoCommandAcknowledgeAnswerEnum.Accepted);
+        this.snapshotService = service;
+        await this.snapshotService.initialize();
+        console.log(`Battery ${this.applianceId}: snapshot service initialized`);
     }
     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.snapshotService) {
+            await this.initSnapshotService();
         }
-        if (!this.calibrationService) {
-            this.sendCommandAcknowledge(msg.id, msg.message, EnyoCommandAcknowledgeAnswerEnum.Rejected, 'Calibration service unavailable');
+        if (!this.snapshotService) {
+            this.sendCommandAcknowledge(msg.id, msg.message, EnyoCommandAcknowledgeAnswerEnum.Rejected, 'Snapshot service unavailable');
             return;
         }
-        if (this.calibrationService.isCalibrating()) {
+        if (this.snapshotService.isCalibrating()) {
             console.log(`Battery ${this.applianceId}: calibration already active — ack idempotently`);
             this.sendCommandAcknowledge(msg.id, msg.message, EnyoCommandAcknowledgeAnswerEnum.Accepted);
             return;
@@ -1479,11 +1571,7 @@ export class SunspecBattery extends BaseSunspecDevice {
             return;
         }
         try {
-            await this.calibrationService.startCalibration({
-                deviceType: 'battery',
-                unitId: this.unitId,
-                batteryControls: controls,
-            });
+            await this.snapshotService.startCalibration(controls);
         }
         catch (error) {
             this.sendCommandAcknowledge(msg.id, msg.message, EnyoCommandAcknowledgeAnswerEnum.Rejected, `Failed to persist snapshot: ${error}`);
@@ -1497,27 +1585,22 @@ export class SunspecBattery extends BaseSunspecDevice {
             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;
-        }
+        // SnapshotService.stopCalibration fires `restoreBatterySnapshot` internally
+        // with reason="stop" before returning. Failures from the restore callback are
+        // logged inside the callback (the persisted snapshot is already gone — see
+        // library notes) so we always ack Accepted here.
+        await this.snapshotService?.stopCalibration();
         this.sendCommandAcknowledge(msg.id, msg.message, EnyoCommandAcknowledgeAnswerEnum.Accepted);
     }
-    async restoreFromCalibrationSnapshot(snapshot, reason) {
-        if (snapshot.deviceType !== 'battery' || !snapshot.batteryControls) {
-            return;
-        }
-        const source = snapshot.batteryControls;
+    /**
+     * `onRestore` callback for the battery's {@link SnapshotService}. Writes only the
+     * subset of writable battery fields touched during the calibration. Errors are
+     * caught and logged — by the time this fires the snapshot is gone from storage,
+     * so a throw would just propagate into the void.
+     */
+    async restoreBatterySnapshot(snapshot, reason) {
+        const source = snapshot.payload;
         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) {
@@ -1529,9 +1612,14 @@ export class SunspecBattery extends BaseSunspecDevice {
             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');
+        try {
+            const ok = await this.sunspecClient.writeBatteryControls(this.unitId, partial);
+            if (!ok) {
+                console.error(`Battery ${this.applianceId}: calibration ${reason} — writeBatteryControls returned false`);
+            }
+        }
+        catch (error) {
+            console.error(`Battery ${this.applianceId}: calibration ${reason} — writeBatteryControls threw: ${error}`);
         }
     }
 }