@enyo-energy/sunspec-sdk 0.0.73 → 0.0.74

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-modbus-client.cjs

@@ -1666,11 +1666,11 @@ class SunspecModbusClient {
         const baseAddr = model.address;
         console.log(`Writing Battery Controls to Model 124 at base address: ${baseAddr} (unit ${unitId})`);
         try {
-            // Write storage control mode (Register 5)
-            if (controls.storCtlMod !== undefined) {
-                await this.writeRegisterValue(unitId, baseAddr + 5, controls.storCtlMod, 'uint16');
-                console.log(`Set storage control mode to 0x${controls.storCtlMod.toString(16)}`);
-            }
+            // Write order: source pin and parameter writes land BEFORE the
+            // control mode so the device only "starts acting" once every
+            // value that governs the action is fresh. The reverse order
+            // leaks a Modbus RTT-sized window where storCtlMod sees stale
+            // chaGriSet / wChaMax / inWRte / outWRte.
             // Write charge source setting (Register 17)
             if (controls.chaGriSet !== undefined) {
                 await this.writeRegisterValue(unitId, baseAddr + 17, controls.chaGriSet, 'uint16');
@@ -1708,6 +1708,13 @@ class SunspecModbusClient {
                 await this.writeRegisterValue(unitId, baseAddr + 7, scaledValue, 'uint16');
                 console.log(`Set minimum reserve to ${controls.minRsvPct}% (scaled: ${scaledValue})`);
             }
+            // Storage control mode (Register 5) — written LAST so all
+            // governing parameters are already in place when the device
+            // transitions into the new mode.
+            if (controls.storCtlMod !== undefined) {
+                await this.writeRegisterValue(unitId, baseAddr + 5, controls.storCtlMod, 'uint16');
+                console.log(`Set storage control mode to 0x${controls.storCtlMod.toString(16)}`);
+            }
             console.log('Battery controls written successfully');
             return true;
         }

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

package/dist/sunspec-battery-schedule-handler.d.ts

@@ -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.js";
 /**
@@ -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/sunspec-battery-schedule-handler.js

@@ -1,5 +1,5 @@
 import { StorageScheduleHandler, } from "@enyo-energy/energy-app-sdk/dist/implementations/storage/storage-schedule-handler.js";
-import { EnyoStorageScheduleDirectionEnum } from "@enyo-energy/energy-app-sdk/dist/types/enyo-data-bus-value.js";
+import { EnyoStorageScheduleDirectionEnum, EnyoStorageScheduleModeEnum, } from "@enyo-energy/energy-app-sdk/dist/types/enyo-data-bus-value.js";
 import { SunspecChargeSource, SunspecStorageControlMode, } from "./sunspec-interfaces.js";
 /**
  * Concrete `StorageScheduleHandler` for SunSpec Model 124 batteries. The base
@@ -15,6 +15,23 @@ export class SunspecBatteryScheduleHandler extends StorageScheduleHandler {
     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;
@@ -23,19 +40,53 @@ export class SunspecBatteryScheduleHandler extends StorageScheduleHandler {
         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 === 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 => {
@@ -43,6 +94,25 @@ export class SunspecBatteryScheduleHandler extends StorageScheduleHandler {
         });
     }
     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);
@@ -53,9 +123,6 @@ export class SunspecBatteryScheduleHandler extends StorageScheduleHandler {
             catch (err) {
                 console.error(`SunspecBatteryScheduleHandler ${this.applianceIdForLog}: onRollback failed: ${err}`);
             }
-            finally {
-                this.installedWChaMax = undefined;
-            }
         })();
     }
     onError(err) {

package/dist/sunspec-modbus-client.js

@@ -1661,11 +1661,11 @@ export class SunspecModbusClient {
         const baseAddr = model.address;
         console.log(`Writing Battery Controls to Model 124 at base address: ${baseAddr} (unit ${unitId})`);
         try {
-            // Write storage control mode (Register 5)
-            if (controls.storCtlMod !== undefined) {
-                await this.writeRegisterValue(unitId, baseAddr + 5, controls.storCtlMod, 'uint16');
-                console.log(`Set storage control mode to 0x${controls.storCtlMod.toString(16)}`);
-            }
+            // Write order: source pin and parameter writes land BEFORE the
+            // control mode so the device only "starts acting" once every
+            // value that governs the action is fresh. The reverse order
+            // leaks a Modbus RTT-sized window where storCtlMod sees stale
+            // chaGriSet / wChaMax / inWRte / outWRte.
             // Write charge source setting (Register 17)
             if (controls.chaGriSet !== undefined) {
                 await this.writeRegisterValue(unitId, baseAddr + 17, controls.chaGriSet, 'uint16');
@@ -1703,6 +1703,13 @@ export class SunspecModbusClient {
                 await this.writeRegisterValue(unitId, baseAddr + 7, scaledValue, 'uint16');
                 console.log(`Set minimum reserve to ${controls.minRsvPct}% (scaled: ${scaledValue})`);
             }
+            // Storage control mode (Register 5) — written LAST so all
+            // governing parameters are already in place when the device
+            // transitions into the new mode.
+            if (controls.storCtlMod !== undefined) {
+                await this.writeRegisterValue(unitId, baseAddr + 5, controls.storCtlMod, 'uint16');
+                console.log(`Set storage control mode to 0x${controls.storCtlMod.toString(16)}`);
+            }
             console.log('Battery controls written successfully');
             return true;
         }

package/dist/version.d.ts

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