@enyo-energy/sunspec-sdk 0.0.73 → 0.0.75

package/README.md

@@ -332,7 +332,11 @@ See [`@enyo-energy/appliance-calibration`'s README](https://www.npmjs.com/packag
 3. Activates the first entry immediately, then advances to subsequent entries as their `seconds` offsets elapse on a 1-second tick (driven by `EnergyApp.useInterval()`).
 4. Each `Charge` entry writes `chaGriSet=GRID`, `inWRte = powerW / installedWChaMax × 100`, `storCtlMod=CHARGE`.
 5. Each `Discharge` entry writes `chaGriSet=PV`, `outWRte = powerW / installedWChaMax × 100`, `storCtlMod=DISCHARGE`.
-6. On `mode: auto`, a replacement schedule, `disconnect()`, or process restart with an active schedule still persisted, the SDK restores the snapshotted pre-schedule registers via `onRollback`.
+6. Restores the snapshotted pre-schedule registers (`storCtlMod`, `chaGriSet`, `wChaMax`, `inWRte`, `outWRte`) **only on `mode: auto`, `disconnect()`, or process-restart recovery** — not when one `mode: schedule` is replaced by another. Schedule-to-schedule replacement keeps the device on the active register set and lets the new schedule's first entry take over directly, so consecutive schedules don't leak a `storCtlMod=AUTO` (`0x3`) write between them. The pre-schedule snapshot stays sticky across every replacement until one of the three terminal events fires.
+
+### Register write order
+
+`writeBatteryControls` issues each register write sequentially in this order so the device never sees a stale-parameter window when the control mode changes: `chaGriSet → wChaMax → inWRte → outWRte → minRsvPct → storCtlMod`. Source pin and the limit/rate parameters land first; the control mode is written last so the device only "starts acting" once every governing value is fresh.
 
 ### Power cap
 

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

@@ -18,6 +18,23 @@ class SunspecBatteryScheduleHandler extends storage_schedule_handler_js_1.Storag
     getSnapshotService;
     onErrorCallback;
     installedWChaMax;
+    /**
+     * Sticky pre-schedule snapshot, captured once on the first `onInit` and
+     * held across every subsequent schedule-to-schedule replacement. Cleared
+     * only when a real rollback fires (`mode: auto` from the data bus or
+     * `dispose`). Lets the eventual restore write the *true* baseline rather
+     * than the last-active-entry register set that the device happens to be
+     * in at the moment of replacement.
+     */
+    originalBaseline;
+    /**
+     * Set inside the overridden `applyMessage` when an incoming
+     * `mode: schedule` message would replace an already-running schedule.
+     * Consumed (and reset) inside `onRollback` so the base library's
+     * automatic `doReleaseSchedule → onRollback` step does not actually
+     * write the snapshot back during a replacement.
+     */
+    suppressNextRollbackWrite = false;
     constructor(opts) {
         super(opts);
         this.sunspecClient = opts.sunspecClient;
@@ -26,19 +43,53 @@ class SunspecBatteryScheduleHandler extends storage_schedule_handler_js_1.Storag
         this.getSnapshotService = opts.getSnapshotService;
         this.onErrorCallback = opts.onErrorCallback;
     }
+    /**
+     * Override the base-class data-bus router so a schedule-to-schedule
+     * replacement marks the next `onRollback` as "skip the write". The base
+     * library still owns the actual schedule lifecycle — we just steer one
+     * decision inside `onRollback`. `mode: auto` and any path that does not
+     * have an active schedule fall through unchanged, so the rollback fires
+     * normally there.
+     */
+    async applyMessage(msg) {
+        if (msg.applianceId === this.applianceIdForLog
+            && msg.data.mode === enyo_data_bus_value_js_1.EnyoStorageScheduleModeEnum.Schedule
+            && this.getActiveEntry() !== undefined) {
+            this.suppressNextRollbackWrite = true;
+        }
+        try {
+            await super.applyMessage(msg);
+        }
+        finally {
+            // Defence in depth: if the base class skipped the rollback for
+            // any reason (validation error, disposed, etc.), the flag would
+            // otherwise stay set and silently swallow the next real rollback.
+            this.suppressNextRollbackWrite = false;
+        }
+    }
     async onInit(_active) {
+        if (this.originalBaseline !== undefined) {
+            // Replacement install: keep handing the library the sticky
+            // 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;
+            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`);
         }
-        this.installedWChaMax = controls.wChaMax;
-        return {
+        const baseline = {
             storCtlMod: controls.storCtlMod,
             chaGriSet: controls.chaGriSet,
             wChaMax: controls.wChaMax,
             inWRte: controls.inWRte,
             outWRte: controls.outWRte,
         };
+        this.originalBaseline = baseline;
+        this.installedWChaMax = baseline.wChaMax;
+        return { ...baseline };
     }
     onChange(active, _previous) {
         void this.applyEntry(active).catch(err => {
@@ -46,6 +97,25 @@ class SunspecBatteryScheduleHandler extends storage_schedule_handler_js_1.Storag
         });
     }
     onRollback(registers) {
+        if (this.suppressNextRollbackWrite) {
+            // Schedule-to-schedule replacement. Do NOT write the snapshot
+            // back; the new schedule's first `onChange` will own the
+            // register state. `installedWChaMax` stays valid (set in
+            // onInit) so the very next applyEntry has a baseline to divide
+            // against — this is the fix for the
+            // "no usable wChaMax baseline (installedWChaMax=undefined)"
+            // race seen in production logs.
+            this.suppressNextRollbackWrite = false;
+            return;
+        }
+        // Real rollback (mode: auto, dispose, restart recovery). Clear the
+        // sticky baseline so the next `onInit` re-reads the device state.
+        // Important: clear synchronously here — NOT in the async finally
+        // that follows — so a concurrent `onInit` queued behind this one
+        // (impossible today, but defensive) cannot observe a half-cleared
+        // state.
+        this.originalBaseline = undefined;
+        this.installedWChaMax = undefined;
         void (async () => {
             try {
                 await this.sunspecClient.writeBatteryControls(this.unitId, registers);
@@ -56,9 +126,6 @@ class SunspecBatteryScheduleHandler extends storage_schedule_handler_js_1.Storag
             catch (err) {
                 console.error(`SunspecBatteryScheduleHandler ${this.applianceIdForLog}: onRollback failed: ${err}`);
             }
-            finally {
-                this.installedWChaMax = undefined;
-            }
         })();
     }
     onError(err) {

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

@@ -1,4 +1,5 @@
 import { StorageScheduleHandler, type ActiveStorageScheduleEntry, type StorageScheduleHandlerOptions } from "@enyo-energy/energy-app-sdk/dist/implementations/storage/storage-schedule-handler.js";
+import { type EnyoDataBusSetStorageScheduleV1 } from "@enyo-energy/energy-app-sdk/dist/types/enyo-data-bus-value.js";
 import { type SnapshotService } from "@enyo-energy/appliance-calibration";
 import { type SunspecBatteryControls } from "./sunspec-interfaces.cjs";
 /**
@@ -58,7 +59,33 @@ export declare class SunspecBatteryScheduleHandler extends StorageScheduleHandle
     private readonly getSnapshotService;
     private readonly onErrorCallback?;
     private installedWChaMax;
+    /**
+     * Sticky pre-schedule snapshot, captured once on the first `onInit` and
+     * held across every subsequent schedule-to-schedule replacement. Cleared
+     * only when a real rollback fires (`mode: auto` from the data bus or
+     * `dispose`). Lets the eventual restore write the *true* baseline rather
+     * than the last-active-entry register set that the device happens to be
+     * in at the moment of replacement.
+     */
+    private originalBaseline?;
+    /**
+     * Set inside the overridden `applyMessage` when an incoming
+     * `mode: schedule` message would replace an already-running schedule.
+     * Consumed (and reset) inside `onRollback` so the base library's
+     * automatic `doReleaseSchedule → onRollback` step does not actually
+     * write the snapshot back during a replacement.
+     */
+    private suppressNextRollbackWrite;
     constructor(opts: SunspecBatteryScheduleHandlerOptions);
+    /**
+     * Override the base-class data-bus router so a schedule-to-schedule
+     * replacement marks the next `onRollback` as "skip the write". The base
+     * library still owns the actual schedule lifecycle — we just steer one
+     * decision inside `onRollback`. `mode: auto` and any path that does not
+     * have an active schedule fall through unchanged, so the rollback fires
+     * normally there.
+     */
+    applyMessage(msg: EnyoDataBusSetStorageScheduleV1): Promise<void>;
     protected onInit(_active: ActiveStorageScheduleEntry): Promise<SunspecScheduleRegisters>;
     protected onChange(active: ActiveStorageScheduleEntry, _previous: ActiveStorageScheduleEntry | undefined): void;
     protected onRollback(registers: SunspecScheduleRegisters): void;

package/dist/cjs/sunspec-devices.cjs

@@ -711,8 +711,6 @@ class SunspecInverter extends BaseSunspecDevice {
         this.dataBus = this.energyApp.useDataBus();
         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})`);
     }
@@ -737,12 +735,6 @@ class SunspecInverter extends BaseSunspecDevice {
                     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) {
@@ -788,51 +780,6 @@ class SunspecInverter extends BaseSunspecDevice {
         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, enyo_data_bus_value_js_1.EnyoCommandAcknowledgeAnswerEnum.Rejected, 'Not connected');
-            return;
-        }
-        if (!this.snapshotService) {
-            await this.initSnapshotService();
-        }
-        if (!this.snapshotService) {
-            this.sendCommandAcknowledge(msg.id, msg.message, enyo_data_bus_value_js_1.EnyoCommandAcknowledgeAnswerEnum.Rejected, 'Snapshot service unavailable');
-            return;
-        }
-        if (this.snapshotService.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.snapshotService.startCalibration(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`);
-        // 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, enyo_data_bus_value_js_1.EnyoCommandAcknowledgeAnswerEnum.Accepted);
-    }
     /**
      * `onRestore` callback for the inverter's {@link SnapshotService}. Writes only the
      * subset of writable inverter fields that other commands actually touched during the
@@ -1371,7 +1318,10 @@ class SunspecBattery extends BaseSunspecDevice {
             console.error('Battery not connected');
             return false;
         }
-        console.log('Writing battery controls:', controls);
+        // Redundant with the modbus client's own per-write debug trace. Keep at debug
+        // so the high-level info logs (setStorageMode / enableGridCharging / etc.) stay
+        // the only info-level signal per battery-control action.
+        console.debug('Writing battery controls:', controls);
         return this.sunspecClient.writeBatteryControls(this.unitId, controls);
     }
     mapToEnyoStorageMode(storageMode) {
@@ -1469,8 +1419,6 @@ class SunspecBattery extends BaseSunspecDevice {
         this.dataBus = this.energyApp.useDataBus();
         this.dataBusListenerId = this.dataBus.listenForMessages([
             enyo_data_bus_value_js_1.EnyoDataBusMessageEnum.SetStorageScheduleV1,
-            enyo_data_bus_value_js_1.EnyoDataBusMessageEnum.StartCalibrationV1,
-            enyo_data_bus_value_js_1.EnyoDataBusMessageEnum.StopCalibrationV1,
         ], (entry) => this.handleStorageCommand(entry));
         if (!this.applianceId) {
             throw new Error("SunspecBattery.startDataBusListening: applianceId required — call connect() first.");
@@ -1509,12 +1457,6 @@ class SunspecBattery extends BaseSunspecDevice {
                     case enyo_data_bus_value_js_1.EnyoDataBusMessageEnum.SetStorageScheduleV1:
                         this.handleSetStorageScheduleAck(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) {
@@ -1554,51 +1496,6 @@ class SunspecBattery extends BaseSunspecDevice {
         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, enyo_data_bus_value_js_1.EnyoCommandAcknowledgeAnswerEnum.Rejected, 'Not connected');
-            return;
-        }
-        if (!this.snapshotService) {
-            await this.initSnapshotService();
-        }
-        if (!this.snapshotService) {
-            this.sendCommandAcknowledge(msg.id, msg.message, enyo_data_bus_value_js_1.EnyoCommandAcknowledgeAnswerEnum.Rejected, 'Snapshot service unavailable');
-            return;
-        }
-        if (this.snapshotService.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.snapshotService.startCalibration(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`);
-        // 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, enyo_data_bus_value_js_1.EnyoCommandAcknowledgeAnswerEnum.Accepted);
-    }
     /**
      * `onRestore` callback for the battery's {@link SnapshotService}. Writes only the
      * subset of writable battery fields touched during the calibration. Errors are
@@ -1704,13 +1601,11 @@ 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);
@@ -1722,35 +1617,6 @@ 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

@@ -178,8 +178,6 @@ export declare class SunspecInverter extends BaseSunspecDevice {
      * process restarts. Idempotent.
      */
     private initSnapshotService;
-    private handleStartCalibration;
-    private handleStopCalibration;
     /**
      * `onRestore` callback for the inverter's {@link SnapshotService}. Writes only the
      * subset of writable inverter fields that other commands actually touched during the
@@ -408,8 +406,6 @@ export declare class SunspecBattery extends BaseSunspecDevice {
      * process restarts. Idempotent.
      */
     private initSnapshotService;
-    private handleStartCalibration;
-    private handleStopCalibration;
     /**
      * `onRestore` callback for the battery's {@link SnapshotService}. Writes only the
      * subset of writable battery fields touched during the calibration. Errors are
@@ -432,13 +428,6 @@ 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
      */