@enyo-energy/sunspec-sdk 0.0.72 → 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-devices.cjs

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SunspecMeter = exports.SunspecBattery = exports.SunspecInverter = exports.BaseSunspecDevice = void 0;
+exports.detectFeaturesFromRegisters = detectFeaturesFromRegisters;
+exports.filterFeaturesByCalibrationResult = filterFeaturesByCalibrationResult;
 const sunspec_interfaces_js_1 = require("./sunspec-interfaces.cjs");
 const node_crypto_1 = require("node:crypto");
 const enyo_appliance_js_1 = require("@enyo-energy/energy-app-sdk/dist/types/enyo-appliance.js");
@@ -864,6 +866,54 @@ class SunspecInverter extends BaseSunspecDevice {
     }
 }
 exports.SunspecInverter = SunspecInverter;
+/**
+ * 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)
+ */
+function detectFeaturesFromRegisters(batteryData) {
+    const features = [];
+    if (batteryData?.chaGriSet !== undefined)
+        features.push(enyo_battery_appliance_js_1.EnyoBatteryFeature.GridCharging);
+    if (batteryData?.wChaMax !== undefined)
+        features.push(enyo_battery_appliance_js_1.EnyoBatteryFeature.ChargeLimitation);
+    if (batteryData?.outWRte !== undefined)
+        features.push(enyo_battery_appliance_js_1.EnyoBatteryFeature.DischargeLimitation);
+    if (batteryData?.storCtlMod !== undefined)
+        features.push(enyo_battery_appliance_js_1.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.
+ */
+function filterFeaturesByCalibrationResult(detected, result, controllable) {
+    if (!result || result.state !== 'calibrated') {
+        return detected.filter(f => !controllable.includes(f));
+    }
+    const passed = (0, sunspec_battery_feature_calibrator_js_1.decodeFeatureResults)(result.notes);
+    if (passed.size === 0)
+        return detected;
+    return detected.filter(f => !controllable.includes(f) || passed.has(f));
+}
 /**
  * Sunspec Battery implementation
  */
@@ -939,14 +989,7 @@ class SunspecBattery extends BaseSunspecDevice {
      * {@link resolveAdvertisedFeatures}.
      */
     detectFromRegisters(batteryData) {
-        const features = [];
-        if (batteryData?.chaGriSet !== undefined) {
-            features.push(enyo_battery_appliance_js_1.EnyoBatteryFeature.GridCharging);
-        }
-        if (batteryData?.wChaMax !== undefined) {
-            features.push(enyo_battery_appliance_js_1.EnyoBatteryFeature.ChargeLimitation);
-        }
-        return features;
+        return detectFeaturesFromRegisters(batteryData);
     }
     /**
      * Resolve `appliance.battery.features` for the configured mode. Called on
@@ -964,18 +1007,10 @@ class SunspecBattery extends BaseSunspecDevice {
                 return intersect(this.detectFromRegisters(batteryData));
             case sunspec_interfaces_js_1.SunspecBatteryFeatureModeKind.CalibrationBased: {
                 const detected = intersect(this.detectFromRegisters(batteryData));
-                if (!this.applianceId || !this.calibrationResultStore) {
-                    return detected.filter(f => !SunspecBattery.CONTROLLABLE_FEATURES.includes(f));
-                }
-                const result = this.calibrationResultStore.getResult(this.applianceId);
-                if (!result || result.state !== 'calibrated') {
-                    return detected.filter(f => !SunspecBattery.CONTROLLABLE_FEATURES.includes(f));
-                }
-                // Per-feature gating: only publish controllable features whose
-                // probe passed during the last calibration. See
-                // `decodeFeatureResults` and `SunspecBatteryFeatureCalibrator`.
-                const passed = (0, sunspec_battery_feature_calibrator_js_1.decodeFeatureResults)(result.notes);
-                return detected.filter(f => !SunspecBattery.CONTROLLABLE_FEATURES.includes(f) || passed.has(f));
+                const result = this.applianceId
+                    ? this.calibrationResultStore?.getResult(this.applianceId)
+                    : undefined;
+                return filterFeaturesByCalibrationResult(detected, result, SunspecBattery.CONTROLLABLE_FEATURES);
             }
         }
     }

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

@@ -1,11 +1,12 @@
-import { type IRetryConfig, type SunspecBatteryBaseData, SunspecBatteryCapability, type SunspecBatteryControls, type SunspecBatteryFeatureMode, type SunspecInverterData, SunspecInverterCapability, SunspecMeterCapability, SunspecStorageMode } from "./sunspec-interfaces.cjs";
+import { type IRetryConfig, type SunspecBatteryBaseData, SunspecBatteryCapability, type SunspecBatteryControls, type SunspecBatteryData, type SunspecBatteryFeatureMode, type SunspecInverterData, SunspecInverterCapability, SunspecMeterCapability, SunspecStorageMode } from "./sunspec-interfaces.cjs";
 import { ApplianceManager, EnergyApp } from "@enyo-energy/energy-app-sdk";
 import { type EnyoAppliance, type EnyoApplianceErrorCode, EnyoApplianceName } from "@enyo-energy/energy-app-sdk/dist/types/enyo-appliance.js";
 import { EnyoNetworkDevice } from "@enyo-energy/energy-app-sdk/dist/types/enyo-network-device.js";
 import { SunspecModbusClient } from "./sunspec-modbus-client.cjs";
 import { ConnectionRetryManager } from "./connection-retry-manager.cjs";
 import { EnyoCommandAcknowledgeAnswerEnum, EnyoDataBusMessage, EnyoDataBusMessageEnum, EnyoDataBusMessageResolution } from "@enyo-energy/energy-app-sdk/dist/types/enyo-data-bus-value.js";
-import { BatteryCalibrator, type BatteryCalibratorConfig, type CalibrationResultStore, type CalibrationSnapshot, type RestoreReason, SnapshotService } from "@enyo-energy/appliance-calibration";
+import { BatteryCalibrator, type BatteryCalibratorConfig, type CalibrationResult, type CalibrationResultStore, type CalibrationSnapshot, type RestoreReason, SnapshotService } from "@enyo-energy/appliance-calibration";
+import { EnyoBatteryFeature } from "@enyo-energy/energy-app-sdk/dist/types/enyo-battery-appliance.js";
 import { EnergyAppDataBus } from "@enyo-energy/energy-app-sdk/dist/packages/energy-app-data-bus.js";
 /**
  * Base abstract class for all Sunspec devices
@@ -188,6 +189,35 @@ export declare class SunspecInverter extends BaseSunspecDevice {
      */
     private restoreInverterSnapshot;
 }
+/**
+ * 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 declare function detectFeaturesFromRegisters(batteryData: SunspecBatteryData | null): EnyoBatteryFeature[];
+/**
+ * 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 declare function filterFeaturesByCalibrationResult(detected: EnyoBatteryFeature[], result: CalibrationResult | undefined, controllable: readonly EnyoBatteryFeature[]): EnyoBatteryFeature[];
 /**
  * Sunspec Battery implementation
  */

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.72';
+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.72";
+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-devices.d.ts

@@ -1,11 +1,12 @@
-import { type IRetryConfig, type SunspecBatteryBaseData, SunspecBatteryCapability, type SunspecBatteryControls, type SunspecBatteryFeatureMode, type SunspecInverterData, SunspecInverterCapability, SunspecMeterCapability, SunspecStorageMode } from "./sunspec-interfaces.js";
+import { type IRetryConfig, type SunspecBatteryBaseData, SunspecBatteryCapability, type SunspecBatteryControls, type SunspecBatteryData, type SunspecBatteryFeatureMode, type SunspecInverterData, SunspecInverterCapability, SunspecMeterCapability, SunspecStorageMode } from "./sunspec-interfaces.js";
 import { ApplianceManager, EnergyApp } from "@enyo-energy/energy-app-sdk";
 import { type EnyoAppliance, type EnyoApplianceErrorCode, EnyoApplianceName } from "@enyo-energy/energy-app-sdk/dist/types/enyo-appliance.js";
 import { EnyoNetworkDevice } from "@enyo-energy/energy-app-sdk/dist/types/enyo-network-device.js";
 import { SunspecModbusClient } from "./sunspec-modbus-client.js";
 import { ConnectionRetryManager } from "./connection-retry-manager.js";
 import { EnyoCommandAcknowledgeAnswerEnum, EnyoDataBusMessage, EnyoDataBusMessageEnum, EnyoDataBusMessageResolution } from "@enyo-energy/energy-app-sdk/dist/types/enyo-data-bus-value.js";
-import { BatteryCalibrator, type BatteryCalibratorConfig, type CalibrationResultStore, type CalibrationSnapshot, type RestoreReason, SnapshotService } from "@enyo-energy/appliance-calibration";
+import { BatteryCalibrator, type BatteryCalibratorConfig, type CalibrationResult, type CalibrationResultStore, type CalibrationSnapshot, type RestoreReason, SnapshotService } from "@enyo-energy/appliance-calibration";
+import { EnyoBatteryFeature } from "@enyo-energy/energy-app-sdk/dist/types/enyo-battery-appliance.js";
 import { EnergyAppDataBus } from "@enyo-energy/energy-app-sdk/dist/packages/energy-app-data-bus.js";
 /**
  * Base abstract class for all Sunspec devices
@@ -188,6 +189,35 @@ export declare class SunspecInverter extends BaseSunspecDevice {
      */
     private restoreInverterSnapshot;
 }
+/**
+ * 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 declare function detectFeaturesFromRegisters(batteryData: SunspecBatteryData | null): EnyoBatteryFeature[];
+/**
+ * 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 declare function filterFeaturesByCalibrationResult(detected: EnyoBatteryFeature[], result: CalibrationResult | undefined, controllable: readonly EnyoBatteryFeature[]): EnyoBatteryFeature[];
 /**
  * Sunspec Battery implementation
  */

package/dist/sunspec-devices.js

@@ -859,6 +859,54 @@ export class SunspecInverter extends BaseSunspecDevice {
         }
     }
 }
+/**
+ * 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
  */
@@ -934,14 +982,7 @@ export class SunspecBattery extends BaseSunspecDevice {
      * {@link resolveAdvertisedFeatures}.
      */
     detectFromRegisters(batteryData) {
-        const features = [];
-        if (batteryData?.chaGriSet !== undefined) {
-            features.push(EnyoBatteryFeature.GridCharging);
-        }
-        if (batteryData?.wChaMax !== undefined) {
-            features.push(EnyoBatteryFeature.ChargeLimitation);
-        }
-        return features;
+        return detectFeaturesFromRegisters(batteryData);
     }
     /**
      * Resolve `appliance.battery.features` for the configured mode. Called on
@@ -959,18 +1000,10 @@ export class SunspecBattery extends BaseSunspecDevice {
                 return intersect(this.detectFromRegisters(batteryData));
             case SunspecBatteryFeatureModeKind.CalibrationBased: {
                 const detected = intersect(this.detectFromRegisters(batteryData));
-                if (!this.applianceId || !this.calibrationResultStore) {
-                    return detected.filter(f => !SunspecBattery.CONTROLLABLE_FEATURES.includes(f));
-                }
-                const result = this.calibrationResultStore.getResult(this.applianceId);
-                if (!result || result.state !== 'calibrated') {
-                    return detected.filter(f => !SunspecBattery.CONTROLLABLE_FEATURES.includes(f));
-                }
-                // Per-feature gating: only publish controllable features whose
-                // probe passed during the last calibration. See
-                // `decodeFeatureResults` and `SunspecBatteryFeatureCalibrator`.
-                const passed = decodeFeatureResults(result.notes);
-                return detected.filter(f => !SunspecBattery.CONTROLLABLE_FEATURES.includes(f) || passed.has(f));
+                const result = this.applianceId
+                    ? this.calibrationResultStore?.getResult(this.applianceId)
+                    : undefined;
+                return filterFeaturesByCalibrationResult(detected, result, SunspecBattery.CONTROLLABLE_FEATURES);
             }
         }
     }

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.72";
+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.72';
+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.72",
+  "version": "0.0.74",
   "description": "enyo Energy Sunspec SDK",
   "type": "module",
   "main": "dist/index.js",