@enyo-energy/sunspec-sdk 0.0.71 → 0.0.73

package/dist/cjs/sunspec-battery-feature-calibrator.cjs

@@ -0,0 +1,350 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SunspecBatteryFeatureCalibrator = void 0;
+exports.decodeFeatureResults = decodeFeatureResults;
+const appliance_calibration_1 = require("@enyo-energy/appliance-calibration");
+const enyo_battery_appliance_js_1 = require("@enyo-energy/energy-app-sdk/dist/types/enyo-battery-appliance.js");
+const sunspec_interfaces_js_1 = require("./sunspec-interfaces.cjs");
+/**
+ * SoC band each probe needs to operate in. Outside the band the probe returns
+ * `not-supported` instead of running — there's no useful signal when the
+ * battery has no headroom (or no energy) for the test.
+ */
+const CHARGE_PROBE_MAX_SOC_PCT = 90;
+const DISCHARGE_PROBE_MIN_SOC_PCT = 20;
+/**
+ * `inWRte` / `outWRte` value used by the limit probes. Combined with
+ * `wChaMax = testPowerW`, the expected observed power is half of `testPowerW`.
+ */
+const LIMIT_PROBE_RATE_PERCENT = 50;
+/**
+ * SunSpec-specific calibrator that exercises each of the four controllable
+ * battery features individually and records per-feature outcomes in the
+ * library's existing `CalibrationResult.notes` field (JSON-encoded).
+ *
+ * Sequence per session:
+ *
+ *   1. captureSnapshot — read writable Model 124 registers.
+ *   2. snapshotService.startCalibration — arms auto-restore.
+ *   3. enterCalibrationMode — driver no-op for SunSpec (returns "accepted").
+ *   4. probeGridCharge      → battery power AND grid power rise above threshold.
+ *   5. probeChargeLimitation → inWRte=50, observe charge power ≈ testPowerW/2.
+ *   6. probeDischargeLimitation → outWRte=50, observe discharge power ≈ testPowerW/2.
+ *   7. probeGridDischarge   → storCtlMod=DISCHARGE, observe meter export.
+ *   8. exitCalibrationMode + snapshotService.stopCalibration → restoreFromSnapshot fires.
+ *
+ * Charge probes run before discharge probes so the battery has energy to
+ * discharge with. Each probe ends with the registers reset to a neutral
+ * state (storCtlMod=AUTO, chaGriSet=PV, inWRte/outWRte=100, wChaMax=snapshot)
+ * so the next probe starts cleanly even though the snapshot service's
+ * restore only fires at the very end.
+ *
+ * The aggregated `CalibrationResult.state` is:
+ *
+ * - `calibrated` if at least one probe passed,
+ * - `not-supported` if every probe was `not-supported` (e.g. SoC out of band
+ *   for both charge AND discharge),
+ * - `failed` otherwise.
+ *
+ * `isCalibrated(applianceId)` therefore reads as "the SDK probed this device
+ * and at least something is controllable" — keep using it as the broad
+ * command-emission gate. The per-feature breakdown in `notes` is what
+ * `SunspecBattery.resolveAdvertisedFeatures` consults to decide which
+ * controllable features to publish.
+ */
+class SunspecBatteryFeatureCalibrator extends appliance_calibration_1.BatteryCalibrator {
+    sunspecDriver;
+    sunspecClient;
+    unitId;
+    readBatteryData;
+    probeConfig;
+    probeClock;
+    // Local refs to the same instances the parent stores privately. We keep
+    // our own copies because the parent's fields aren't accessible from a
+    // subclass.
+    probeSnapshotService;
+    probeResultStore;
+    isProbeRunning = false;
+    constructor(options) {
+        super(options);
+        this.sunspecDriver = options.driver;
+        this.sunspecClient = options.sunspecClient;
+        this.unitId = options.unitId;
+        this.readBatteryData = options.readBatteryData;
+        this.probeConfig = { ...appliance_calibration_1.DEFAULT_BATTERY_CALIBRATOR_CONFIG, ...options.config };
+        this.probeSnapshotService = options.snapshotService;
+        this.probeResultStore = options.resultStore;
+        this.probeClock = options.clock ?? {
+            now: () => Date.now(),
+            sleep: (ms) => new Promise(resolve => setTimeout(resolve, ms)),
+        };
+    }
+    async runCalibration() {
+        if (this.isProbeRunning) {
+            throw new Error(`Battery calibration already in progress for ${this.applianceId}`);
+        }
+        this.isProbeRunning = true;
+        const recordedAtIso = new Date(this.probeClock.now()).toISOString();
+        console.log(`[SunspecBatteryFeatureCalibrator ${this.applianceId}] Starting per-feature calibration`);
+        let snapshotStarted = false;
+        try {
+            const snapshot = await this.sunspecDriver.captureSnapshot();
+            await this.probeSnapshotService.startCalibration(snapshot);
+            snapshotStarted = true;
+            const enterAck = await this.sunspecDriver.enterCalibrationMode();
+            if (enterAck !== "accepted") {
+                return await this.persistResult({
+                    state: enterAck === "not-supported" ? "not-supported" : "failed",
+                    recordedAtIso,
+                    notes: `enterCalibrationMode returned ${enterAck}`,
+                });
+            }
+            const batteryData = await this.readBatteryData();
+            const soc = batteryData?.soc ?? batteryData?.chaState;
+            const featureResults = {};
+            const diagnostics = {};
+            // Charge probes first so the battery has energy to discharge later.
+            const probes = [
+                { feature: enyo_battery_appliance_js_1.EnyoBatteryFeature.GridCharging, run: () => this.probeGridCharge(soc, snapshot) },
+                { feature: enyo_battery_appliance_js_1.EnyoBatteryFeature.ChargeLimitation, run: () => this.probeChargeLimitation(soc, snapshot) },
+                { feature: enyo_battery_appliance_js_1.EnyoBatteryFeature.DischargeLimitation, run: () => this.probeDischargeLimitation(soc, snapshot) },
+                { feature: enyo_battery_appliance_js_1.EnyoBatteryFeature.GridDischarging, run: () => this.probeGridDischarge(soc, snapshot) },
+            ];
+            for (const probe of probes) {
+                const outcome = await probe.run();
+                featureResults[probe.feature] = outcome.verdict;
+                diagnostics[probe.feature] = outcome.note;
+            }
+            const verdicts = Object.values(featureResults);
+            const aggregate = verdicts.includes('passed') ? 'calibrated'
+                : verdicts.length > 0 && verdicts.every(v => v === 'not-supported') ? 'not-supported'
+                    : 'failed';
+            const payload = { featureResults, diagnostics };
+            return await this.persistResult({
+                state: aggregate,
+                recordedAtIso,
+                notes: JSON.stringify(payload),
+            });
+        }
+        catch (error) {
+            console.error(`[SunspecBatteryFeatureCalibrator ${this.applianceId}] Unexpected error: ${error}`);
+            return await this.persistResult({
+                state: 'failed',
+                recordedAtIso,
+                notes: `Unexpected error: ${error instanceof Error ? error.message : String(error)}`,
+            });
+        }
+        finally {
+            if (snapshotStarted) {
+                try {
+                    await this.sunspecDriver.exitCalibrationMode();
+                }
+                catch (e) {
+                    console.warn(`[SunspecBatteryFeatureCalibrator ${this.applianceId}] exitCalibrationMode failed: ${e}`);
+                }
+                try {
+                    await this.probeSnapshotService.stopCalibration();
+                }
+                catch (e) {
+                    console.warn(`[SunspecBatteryFeatureCalibrator ${this.applianceId}] snapshotService.stopCalibration failed: ${e}`);
+                }
+            }
+            this.isProbeRunning = false;
+        }
+    }
+    // ---------------------------------------------------------------------
+    // Probes
+    // ---------------------------------------------------------------------
+    async probeGridCharge(soc, snapshot) {
+        if (soc !== undefined && soc >= CHARGE_PROBE_MAX_SOC_PCT) {
+            return { verdict: 'not-supported', note: `SoC too high for charge probe (${soc}%)` };
+        }
+        const baselineBatW = this.sunspecDriver.readBatteryPowerW() ?? 0;
+        const baselineGridW = this.sunspecDriver.readGridPowerW() ?? 0;
+        const wrote = await this.sunspecClient.writeBatteryControls(this.unitId, {
+            chaGriSet: sunspec_interfaces_js_1.SunspecChargeSource.GRID,
+            wChaMax: this.probeConfig.testPowerW,
+            inWRte: 100,
+            storCtlMod: sunspec_interfaces_js_1.SunspecStorageControlMode.CHARGE,
+        });
+        if (!wrote) {
+            return { verdict: 'failed', note: 'writeBatteryControls returned false for grid charge' };
+        }
+        const ok = await this.waitForCondition((batW, gridW) => batW - baselineBatW > this.probeConfig.responseThresholdW
+            && gridW - baselineGridW > this.probeConfig.responseThresholdW);
+        await this.resetToNeutral(snapshot);
+        if (!ok) {
+            return { verdict: 'failed', note: 'battery and/or grid power did not rise within timeout' };
+        }
+        return { verdict: 'passed', note: `battery rose ≥${this.probeConfig.responseThresholdW}W with grid supplying` };
+    }
+    async probeChargeLimitation(soc, snapshot) {
+        if (soc !== undefined && soc >= CHARGE_PROBE_MAX_SOC_PCT) {
+            return { verdict: 'not-supported', note: `SoC too high for charge limit probe (${soc}%)` };
+        }
+        const baselineBatW = this.sunspecDriver.readBatteryPowerW() ?? 0;
+        const wrote = await this.sunspecClient.writeBatteryControls(this.unitId, {
+            chaGriSet: sunspec_interfaces_js_1.SunspecChargeSource.GRID,
+            wChaMax: this.probeConfig.testPowerW,
+            inWRte: LIMIT_PROBE_RATE_PERCENT,
+            storCtlMod: sunspec_interfaces_js_1.SunspecStorageControlMode.CHARGE,
+        });
+        if (!wrote) {
+            return { verdict: 'failed', note: 'writeBatteryControls returned false for charge limit' };
+        }
+        const expectedW = this.probeConfig.testPowerW * (LIMIT_PROBE_RATE_PERCENT / 100);
+        const tolerance = this.probeConfig.responseThresholdW;
+        const ok = await this.waitForCondition((batW) => {
+            const observed = batW - baselineBatW;
+            return Math.abs(observed - expectedW) < tolerance;
+        });
+        await this.resetToNeutral(snapshot);
+        if (!ok) {
+            return { verdict: 'failed', note: `charge limit ignored — expected ~${expectedW}W, observed never settled within ±${tolerance}W` };
+        }
+        return { verdict: 'passed', note: `charge held within ±${tolerance}W of ${expectedW}W (50% of testPowerW)` };
+    }
+    async probeDischargeLimitation(soc, snapshot) {
+        if (soc !== undefined && soc <= DISCHARGE_PROBE_MIN_SOC_PCT) {
+            return { verdict: 'not-supported', note: `SoC too low for discharge limit probe (${soc}%)` };
+        }
+        const baselineBatW = this.sunspecDriver.readBatteryPowerW() ?? 0;
+        const wrote = await this.sunspecClient.writeBatteryControls(this.unitId, {
+            chaGriSet: sunspec_interfaces_js_1.SunspecChargeSource.PV,
+            wChaMax: this.probeConfig.testPowerW,
+            outWRte: LIMIT_PROBE_RATE_PERCENT,
+            storCtlMod: sunspec_interfaces_js_1.SunspecStorageControlMode.DISCHARGE,
+        });
+        if (!wrote) {
+            return { verdict: 'failed', note: 'writeBatteryControls returned false for discharge limit' };
+        }
+        const expectedW = this.probeConfig.testPowerW * (LIMIT_PROBE_RATE_PERCENT / 100);
+        const tolerance = this.probeConfig.responseThresholdW;
+        const ok = await this.waitForCondition((batW) => {
+            const dischargeW = baselineBatW - batW; // discharge → batW drops → dischargeW positive
+            return Math.abs(dischargeW - expectedW) < tolerance;
+        });
+        await this.resetToNeutral(snapshot);
+        if (!ok) {
+            return { verdict: 'failed', note: `discharge limit ignored — expected ~${expectedW}W, observed never settled within ±${tolerance}W` };
+        }
+        return { verdict: 'passed', note: `discharge held within ±${tolerance}W of ${expectedW}W (50% of testPowerW)` };
+    }
+    async probeGridDischarge(soc, snapshot) {
+        if (soc !== undefined && soc <= DISCHARGE_PROBE_MIN_SOC_PCT) {
+            return { verdict: 'not-supported', note: `SoC too low for grid discharge probe (${soc}%)` };
+        }
+        const baselineBatW = this.sunspecDriver.readBatteryPowerW() ?? 0;
+        const baselineGridW = this.sunspecDriver.readGridPowerW() ?? 0;
+        const wrote = await this.sunspecClient.writeBatteryControls(this.unitId, {
+            chaGriSet: sunspec_interfaces_js_1.SunspecChargeSource.PV,
+            wChaMax: this.probeConfig.testPowerW,
+            outWRte: 100,
+            storCtlMod: sunspec_interfaces_js_1.SunspecStorageControlMode.DISCHARGE,
+        });
+        if (!wrote) {
+            return { verdict: 'failed', note: 'writeBatteryControls returned false for grid discharge' };
+        }
+        const dischargeOk = await this.waitForCondition((batW) => baselineBatW - batW > this.probeConfig.responseThresholdW);
+        if (!dischargeOk) {
+            await this.resetToNeutral(snapshot);
+            return { verdict: 'failed', note: 'battery did not discharge within timeout' };
+        }
+        // Battery is now discharging. Check whether the meter shows reverse flow (export).
+        const exportOk = await this.waitForCondition((_batW, gridW) => baselineGridW - gridW > this.probeConfig.responseThresholdW);
+        await this.resetToNeutral(snapshot);
+        if (!exportOk) {
+            return { verdict: 'failed', note: 'discharge observed but no grid export — local load may have consumed it' };
+        }
+        return { verdict: 'passed', note: `discharge produced ≥${this.probeConfig.responseThresholdW}W of grid export` };
+    }
+    // ---------------------------------------------------------------------
+    // Helpers
+    // ---------------------------------------------------------------------
+    /**
+     * Reset to a neutral state between probes — chaGriSet=PV, storCtlMod=AUTO,
+     * rate limits cleared, wChaMax back to the captured baseline. The final
+     * restore via `snapshotService.stopCalibration` still runs and is what
+     * brings the device back to its pre-calibration register set.
+     */
+    async resetToNeutral(snapshot) {
+        try {
+            await this.sunspecClient.writeBatteryControls(this.unitId, {
+                storCtlMod: sunspec_interfaces_js_1.SunspecStorageControlMode.CHARGE | sunspec_interfaces_js_1.SunspecStorageControlMode.DISCHARGE,
+                chaGriSet: sunspec_interfaces_js_1.SunspecChargeSource.PV,
+                wChaMax: snapshot.wChaMax,
+                inWRte: 100,
+                outWRte: 100,
+            });
+        }
+        catch (e) {
+            console.warn(`[SunspecBatteryFeatureCalibrator ${this.applianceId}] resetToNeutral failed: ${e}`);
+        }
+        // Give the battery a moment to settle before the next probe samples baseline.
+        await this.probeClock.sleep(this.probeConfig.pollIntervalMs);
+    }
+    async waitForCondition(predicate) {
+        const deadline = this.probeClock.now() + this.probeConfig.responseTimeoutMs;
+        while (this.probeClock.now() < deadline) {
+            const batW = this.sunspecDriver.readBatteryPowerW() ?? 0;
+            const gridW = this.sunspecDriver.readGridPowerW() ?? 0;
+            if (predicate(batW, gridW))
+                return true;
+            await this.probeClock.sleep(this.probeConfig.pollIntervalMs);
+        }
+        return false;
+    }
+    async persistResult(result) {
+        await this.probeResultStore.save(this.applianceId, result);
+        return result;
+    }
+}
+exports.SunspecBatteryFeatureCalibrator = SunspecBatteryFeatureCalibrator;
+/**
+ * Decode the per-feature payload that the orchestrator JSON-encodes into
+ * `CalibrationResult.notes`. Returns the set of controllable features whose
+ * verdict is `passed`. Robust to:
+ *
+ * - `notes === undefined` (no calibration recorded yet)
+ * - non-JSON `notes` (legacy results from before this scheme)
+ * - missing `featureResults` field
+ * - unknown feature keys
+ * - bogus verdict strings
+ *
+ * No `as` casts at the use site — the JSON parse boundary uses `unknown` and
+ * narrows via `typeof` / `Object.entries`. Each candidate key is compared
+ * against the typed `SUNSPEC_CONTROLLABLE_FEATURES` whitelist so unknown keys
+ * are dropped without any `Record<string, unknown>` indirection. Matches the
+ * CLAUDE.md "JSON-parsing interop" exception rules.
+ */
+function decodeFeatureResults(notes) {
+    const passed = new Set();
+    if (!notes)
+        return passed;
+    let parsed;
+    try {
+        parsed = JSON.parse(notes);
+    }
+    catch {
+        return passed;
+    }
+    if (typeof parsed !== 'object' || parsed === null)
+        return passed;
+    let featureResults;
+    for (const [k, v] of Object.entries(parsed)) {
+        if (k === 'featureResults') {
+            featureResults = v;
+            break;
+        }
+    }
+    if (typeof featureResults !== 'object' || featureResults === null)
+        return passed;
+    for (const [key, value] of Object.entries(featureResults)) {
+        if (value !== 'passed')
+            continue;
+        const match = sunspec_interfaces_js_1.SUNSPEC_CONTROLLABLE_FEATURES.find(f => f === key);
+        if (match)
+            passed.add(match);
+    }
+    return passed;
+}

package/dist/cjs/sunspec-battery-feature-calibrator.d.cts

@@ -0,0 +1,89 @@
+import { BatteryCalibrator, type BatteryCalibratorOptions, type CalibrationResult } from "@enyo-energy/appliance-calibration";
+import { EnyoBatteryFeature } from "@enyo-energy/energy-app-sdk/dist/types/enyo-battery-appliance.js";
+import { BatteryControlsClient } from "./sunspec-battery-schedule-handler.cjs";
+import { type SunspecBatteryControls, type SunspecBatteryData } from "./sunspec-interfaces.cjs";
+export interface SunspecBatteryFeatureCalibratorOptions extends BatteryCalibratorOptions<SunspecBatteryControls> {
+    sunspecClient: BatteryControlsClient;
+    unitId: number;
+    /** Pulls the latest battery data so the orchestrator can pre-check SoC. */
+    readBatteryData: () => Promise<SunspecBatteryData | null>;
+}
+/**
+ * SunSpec-specific calibrator that exercises each of the four controllable
+ * battery features individually and records per-feature outcomes in the
+ * library's existing `CalibrationResult.notes` field (JSON-encoded).
+ *
+ * Sequence per session:
+ *
+ *   1. captureSnapshot — read writable Model 124 registers.
+ *   2. snapshotService.startCalibration — arms auto-restore.
+ *   3. enterCalibrationMode — driver no-op for SunSpec (returns "accepted").
+ *   4. probeGridCharge      → battery power AND grid power rise above threshold.
+ *   5. probeChargeLimitation → inWRte=50, observe charge power ≈ testPowerW/2.
+ *   6. probeDischargeLimitation → outWRte=50, observe discharge power ≈ testPowerW/2.
+ *   7. probeGridDischarge   → storCtlMod=DISCHARGE, observe meter export.
+ *   8. exitCalibrationMode + snapshotService.stopCalibration → restoreFromSnapshot fires.
+ *
+ * Charge probes run before discharge probes so the battery has energy to
+ * discharge with. Each probe ends with the registers reset to a neutral
+ * state (storCtlMod=AUTO, chaGriSet=PV, inWRte/outWRte=100, wChaMax=snapshot)
+ * so the next probe starts cleanly even though the snapshot service's
+ * restore only fires at the very end.
+ *
+ * The aggregated `CalibrationResult.state` is:
+ *
+ * - `calibrated` if at least one probe passed,
+ * - `not-supported` if every probe was `not-supported` (e.g. SoC out of band
+ *   for both charge AND discharge),
+ * - `failed` otherwise.
+ *
+ * `isCalibrated(applianceId)` therefore reads as "the SDK probed this device
+ * and at least something is controllable" — keep using it as the broad
+ * command-emission gate. The per-feature breakdown in `notes` is what
+ * `SunspecBattery.resolveAdvertisedFeatures` consults to decide which
+ * controllable features to publish.
+ */
+export declare class SunspecBatteryFeatureCalibrator extends BatteryCalibrator<SunspecBatteryControls> {
+    private readonly sunspecDriver;
+    private readonly sunspecClient;
+    private readonly unitId;
+    private readonly readBatteryData;
+    private readonly probeConfig;
+    private readonly probeClock;
+    private readonly probeSnapshotService;
+    private readonly probeResultStore;
+    private isProbeRunning;
+    constructor(options: SunspecBatteryFeatureCalibratorOptions);
+    runCalibration(): Promise<CalibrationResult>;
+    private probeGridCharge;
+    private probeChargeLimitation;
+    private probeDischargeLimitation;
+    private probeGridDischarge;
+    /**
+     * Reset to a neutral state between probes — chaGriSet=PV, storCtlMod=AUTO,
+     * rate limits cleared, wChaMax back to the captured baseline. The final
+     * restore via `snapshotService.stopCalibration` still runs and is what
+     * brings the device back to its pre-calibration register set.
+     */
+    private resetToNeutral;
+    private waitForCondition;
+    private persistResult;
+}
+/**
+ * Decode the per-feature payload that the orchestrator JSON-encodes into
+ * `CalibrationResult.notes`. Returns the set of controllable features whose
+ * verdict is `passed`. Robust to:
+ *
+ * - `notes === undefined` (no calibration recorded yet)
+ * - non-JSON `notes` (legacy results from before this scheme)
+ * - missing `featureResults` field
+ * - unknown feature keys
+ * - bogus verdict strings
+ *
+ * No `as` casts at the use site — the JSON parse boundary uses `unknown` and
+ * narrows via `typeof` / `Object.entries`. Each candidate key is compared
+ * against the typed `SUNSPEC_CONTROLLABLE_FEATURES` whitelist so unknown keys
+ * are dropped without any `Record<string, unknown>` indirection. Matches the
+ * CLAUDE.md "JSON-parsing interop" exception rules.
+ */
+export declare function decodeFeatureResults(notes: string | undefined): Set<EnyoBatteryFeature>;

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

@@ -0,0 +1,92 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SunspecBatteryScheduleHandler = void 0;
+const storage_schedule_handler_js_1 = require("@enyo-energy/energy-app-sdk/dist/implementations/storage/storage-schedule-handler.js");
+const enyo_data_bus_value_js_1 = require("@enyo-energy/energy-app-sdk/dist/types/enyo-data-bus-value.js");
+const sunspec_interfaces_js_1 = require("./sunspec-interfaces.cjs");
+/**
+ * Concrete `StorageScheduleHandler` for SunSpec Model 124 batteries. The base
+ * class owns the data-bus subscription, the 1-second tick, schedule
+ * validation, restart-safe persistence, and per-call serialization; this
+ * subclass only supplies the three lifecycle hooks plus an `onError`
+ * observer.
+ */
+class SunspecBatteryScheduleHandler extends storage_schedule_handler_js_1.StorageScheduleHandler {
+    sunspecClient;
+    unitId;
+    applianceIdForLog;
+    getSnapshotService;
+    onErrorCallback;
+    installedWChaMax;
+    constructor(opts) {
+        super(opts);
+        this.sunspecClient = opts.sunspecClient;
+        this.unitId = opts.unitId;
+        this.applianceIdForLog = opts.applianceId;
+        this.getSnapshotService = opts.getSnapshotService;
+        this.onErrorCallback = opts.onErrorCallback;
+    }
+    async onInit(_active) {
+        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 {
+            storCtlMod: controls.storCtlMod,
+            chaGriSet: controls.chaGriSet,
+            wChaMax: controls.wChaMax,
+            inWRte: controls.inWRte,
+            outWRte: controls.outWRte,
+        };
+    }
+    onChange(active, _previous) {
+        void this.applyEntry(active).catch(err => {
+            console.error(`SunspecBatteryScheduleHandler ${this.applianceIdForLog}: onChange write failed for entry ${active.indexInSchedule}: ${err}`);
+        });
+    }
+    onRollback(registers) {
+        void (async () => {
+            try {
+                await this.sunspecClient.writeBatteryControls(this.unitId, registers);
+                await this.getSnapshotService()?.recordModification([
+                    'storCtlMod', 'chaGriSet', 'wChaMax', 'inWRte', 'outWRte',
+                ]);
+            }
+            catch (err) {
+                console.error(`SunspecBatteryScheduleHandler ${this.applianceIdForLog}: onRollback failed: ${err}`);
+            }
+            finally {
+                this.installedWChaMax = undefined;
+            }
+        })();
+    }
+    onError(err) {
+        this.onErrorCallback?.(err);
+    }
+    async applyEntry(active) {
+        const { direction, powerW } = active.entry;
+        const baseline = this.installedWChaMax;
+        if (!baseline || baseline <= 0) {
+            throw new Error(`no usable wChaMax baseline (installedWChaMax=${baseline})`);
+        }
+        const pct = Math.min(100, Math.max(0, (powerW / baseline) * 100));
+        if (direction === enyo_data_bus_value_js_1.EnyoStorageScheduleDirectionEnum.Charge) {
+            await this.sunspecClient.writeBatteryControls(this.unitId, {
+                chaGriSet: sunspec_interfaces_js_1.SunspecChargeSource.GRID,
+                inWRte: pct,
+                storCtlMod: sunspec_interfaces_js_1.SunspecStorageControlMode.CHARGE,
+            });
+            await this.getSnapshotService()?.recordModification(['chaGriSet', 'inWRte', 'storCtlMod']);
+        }
+        else {
+            await this.sunspecClient.writeBatteryControls(this.unitId, {
+                chaGriSet: sunspec_interfaces_js_1.SunspecChargeSource.PV,
+                outWRte: pct,
+                storCtlMod: sunspec_interfaces_js_1.SunspecStorageControlMode.DISCHARGE,
+            });
+            await this.getSnapshotService()?.recordModification(['chaGriSet', 'outWRte', 'storCtlMod']);
+        }
+    }
+}
+exports.SunspecBatteryScheduleHandler = SunspecBatteryScheduleHandler;

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

@@ -0,0 +1,67 @@
+import { StorageScheduleHandler, type ActiveStorageScheduleEntry, type StorageScheduleHandlerOptions } from "@enyo-energy/energy-app-sdk/dist/implementations/storage/storage-schedule-handler.js";
+import { type SnapshotService } from "@enyo-energy/appliance-calibration";
+import { type SunspecBatteryControls } from "./sunspec-interfaces.cjs";
+/**
+ * Narrow interface covering only the modbus reads/writes the schedule handler
+ * needs. The full `SunspecModbusClient` structurally satisfies this; pinning
+ * it down here keeps the handler decoupled from the rest of the client
+ * surface and makes the unit tests trivially stubbable without erasing types.
+ */
+export interface BatteryControlsClient {
+    readBatteryControls(unitId: number): Promise<SunspecBatteryControls | null>;
+    writeBatteryControls(unitId: number, controls: Partial<SunspecBatteryControls>): Promise<boolean>;
+}
+/**
+ * Narrow interface for the only `SnapshotService` method the schedule handler
+ * calls — `recordModification`. A real `SnapshotService<SunspecBatteryControls>`
+ * satisfies this structurally.
+ */
+export type BatteryModificationRecorder = Pick<SnapshotService<SunspecBatteryControls>, 'recordModification'>;
+/**
+ * Snapshot of the writable Model 124 registers taken at schedule install time
+ * and handed back to `onRollback` when the schedule completes, is replaced, or
+ * is restored after a process restart. JSON-serialisable because
+ * `EnergyAppStorage` round-trips it.
+ *
+ * The snapshotted `wChaMax` doubles as the denominator for the `inWRte` /
+ * `outWRte` percentage math inside `onChange` — we never overwrite the live
+ * register during a schedule, so the baseline stays stable across entry
+ * transitions. Consequently scheduled `powerW` is capped at the installed
+ * `wChaMax`, matching the legacy setChargeLimit / setDischargeLimit semantics.
+ */
+export interface SunspecScheduleRegisters {
+    storCtlMod?: number;
+    chaGriSet?: number;
+    wChaMax?: number;
+    inWRte?: number;
+    outWRte?: number;
+}
+export interface SunspecBatteryScheduleHandlerOptions extends StorageScheduleHandlerOptions {
+    sunspecClient: BatteryControlsClient;
+    unitId: number;
+    applianceId: string;
+    /** Lazy so the snapshot service can be initialised after the handler. */
+    getSnapshotService: () => BatteryModificationRecorder | undefined;
+    onErrorCallback?: (err: Error) => void;
+}
+/**
+ * Concrete `StorageScheduleHandler` for SunSpec Model 124 batteries. The base
+ * class owns the data-bus subscription, the 1-second tick, schedule
+ * validation, restart-safe persistence, and per-call serialization; this
+ * subclass only supplies the three lifecycle hooks plus an `onError`
+ * observer.
+ */
+export declare class SunspecBatteryScheduleHandler extends StorageScheduleHandler<SunspecScheduleRegisters> {
+    private readonly sunspecClient;
+    private readonly unitId;
+    private readonly applianceIdForLog;
+    private readonly getSnapshotService;
+    private readonly onErrorCallback?;
+    private installedWChaMax;
+    constructor(opts: SunspecBatteryScheduleHandlerOptions);
+    protected onInit(_active: ActiveStorageScheduleEntry): Promise<SunspecScheduleRegisters>;
+    protected onChange(active: ActiveStorageScheduleEntry, _previous: ActiveStorageScheduleEntry | undefined): void;
+    protected onRollback(registers: SunspecScheduleRegisters): void;
+    protected onError(err: Error): void;
+    private applyEntry;
+}

package/dist/cjs/sunspec-calibration-storage.cjs

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SunspecCalibrationStorage = void 0;
+exports.createSunspecCalibrationStorage = createSunspecCalibrationStorage;
+const appliance_calibration_1 = require("@enyo-energy/appliance-calibration");
+/**
+ * Adapter that bridges the energy-app SDK's `EnergyAppStorage` to the
+ * `AbstractCalibrationStorage` seam expected by `@enyo-energy/appliance-calibration`.
+ *
+ * The host SDK's `load()` returns `null` for missing keys; the calibration
+ * library contract requires `undefined`. This adapter normalises that single
+ * difference.
+ */
+class SunspecCalibrationStorage extends appliance_calibration_1.AbstractCalibrationStorage {
+    storage;
+    constructor(storage) {
+        super();
+        this.storage = storage;
+    }
+    async load(key) {
+        const value = await this.storage.load(key);
+        return value ?? undefined;
+    }
+    async save(key, value) {
+        // The host SDK's `save` only accepts `object`. Narrow via a runtime guard so the
+        // generic `T` reaches the call site as a checked `object` — no cast needed. The
+        // calibration library only ever persists struct-shaped state, so any non-object
+        // here is a programmer error.
+        const candidate = value;
+        if (typeof candidate !== "object" || candidate === null) {
+            throw new TypeError(`SunspecCalibrationStorage.save expects an object value, got ${candidate === null ? "null" : typeof candidate}`);
+        }
+        await this.storage.save(key, candidate);
+    }
+    async remove(key) {
+        await this.storage.remove(key);
+    }
+}
+exports.SunspecCalibrationStorage = SunspecCalibrationStorage;
+/**
+ * Construct a calibration storage adapter from the running `EnergyApp` instance.
+ * Consumers wire this once and pass the same instance into every appliance + the
+ * shared `CalibrationResultStore`.
+ */
+function createSunspecCalibrationStorage(app) {
+    return new SunspecCalibrationStorage(app.useStorage());
+}

package/dist/cjs/sunspec-calibration-storage.d.cts

@@ -0,0 +1,24 @@
+import { AbstractCalibrationStorage } from "@enyo-energy/appliance-calibration";
+import { EnergyAppStorage } from "@enyo-energy/energy-app-sdk/dist/packages/energy-app-storage.js";
+import type { EnergyApp } from "@enyo-energy/energy-app-sdk";
+/**
+ * Adapter that bridges the energy-app SDK's `EnergyAppStorage` to the
+ * `AbstractCalibrationStorage` seam expected by `@enyo-energy/appliance-calibration`.
+ *
+ * The host SDK's `load()` returns `null` for missing keys; the calibration
+ * library contract requires `undefined`. This adapter normalises that single
+ * difference.
+ */
+export declare class SunspecCalibrationStorage extends AbstractCalibrationStorage {
+    private readonly storage;
+    constructor(storage: EnergyAppStorage);
+    load<T>(key: string): Promise<T | undefined>;
+    save<T>(key: string, value: T): Promise<void>;
+    remove(key: string): Promise<void>;
+}
+/**
+ * Construct a calibration storage adapter from the running `EnergyApp` instance.
+ * Consumers wire this once and pass the same instance into every appliance + the
+ * shared `CalibrationResultStore`.
+ */
+export declare function createSunspecCalibrationStorage(app: EnergyApp): SunspecCalibrationStorage;