@enyo-energy/sunspec-sdk 0.0.69 → 0.0.71

package/dist/calibration-snapshot-service.d.ts

@@ -0,0 +1,67 @@
+import { EnergyAppStorage } from "@enyo-energy/energy-app-sdk/dist/packages/energy-app-storage.js";
+import type { SunspecBatteryControls, SunspecInverterControls } from "./sunspec-interfaces.js";
+export type CalibrationDeviceType = "inverter" | "battery";
+/**
+ * Persisted snapshot of a device's writable control registers, taken at the start of a
+ * calibration. Used to roll the device back when calibration ends.
+ *
+ * `modifiedFields` records which control-block field names were touched by *other* write
+ * commands (SetInverterFeedInLimitV1, StartStorageGridChargeV1, etc.) while the calibration
+ * was active — on stop, only those fields are written back, leaving fields the calibration
+ * itself didn't disturb alone.
+ */
+export interface CalibrationSnapshot {
+    applianceId: string;
+    deviceType: CalibrationDeviceType;
+    unitId: number;
+    startedAtIso: string;
+    inverterControls?: SunspecInverterControls;
+    batteryControls?: SunspecBatteryControls;
+    modifiedFields: string[];
+}
+/** Calibration is capped at 5 minutes of wall time, including across restarts. */
+export declare const CALIBRATION_AUTO_STOP_MS: number;
+export type CalibrationRestoreReason = "stop" | "auto";
+export type CalibrationRestoreCallback = (snapshot: CalibrationSnapshot, reason: CalibrationRestoreReason) => Promise<void>;
+/**
+ * Per-appliance service that snapshots a SunSpec device's writable control registers when a
+ * calibration starts, tracks which registers other commands mutate while it is active, and
+ * restores those registers when calibration stops (either explicitly or via the 5-minute
+ * auto-stop timer).
+ *
+ * Snapshots are persisted via `EnergyAppStorage` so a crash/restart mid-calibration does not
+ * leave the device in a calibration state without a rollback. On `initialize()`, any stored
+ * snapshot is reloaded; the auto-stop deadline is computed from `startedAtIso` so total
+ * calibration time remains capped at `autoStopMs` across restarts.
+ */
+export declare class CalibrationSnapshotService {
+    private readonly storage;
+    private readonly applianceId;
+    private readonly onRestore;
+    private readonly autoStopMs;
+    private snapshot?;
+    private autoStopTimer?;
+    constructor(storage: EnergyAppStorage, applianceId: string, onRestore: CalibrationRestoreCallback, autoStopMs?: number);
+    private storageKey;
+    initialize(): Promise<void>;
+    isCalibrating(): boolean;
+    getSnapshot(): CalibrationSnapshot | undefined;
+    startCalibration(input: {
+        deviceType: CalibrationDeviceType;
+        unitId: number;
+        inverterControls?: SunspecInverterControls;
+        batteryControls?: SunspecBatteryControls;
+    }): Promise<void>;
+    recordModification(fields: string[]): Promise<void>;
+    /**
+     * Clear the timer, remove the snapshot from memory + storage, and return the snapshot so
+     * the caller can restore the modified registers. Returns undefined if no calibration was
+     * active.
+     */
+    stopCalibration(): Promise<CalibrationSnapshot | undefined>;
+    private remainingMs;
+    private scheduleAutoStop;
+    private clearAutoStopTimer;
+    private fireAutoStop;
+    private persist;
+}

package/dist/calibration-snapshot-service.js

@@ -0,0 +1,160 @@
+/** Calibration is capped at 5 minutes of wall time, including across restarts. */
+export const CALIBRATION_AUTO_STOP_MS = 5 * 60 * 1000;
+/**
+ * Per-appliance service that snapshots a SunSpec device's writable control registers when a
+ * calibration starts, tracks which registers other commands mutate while it is active, and
+ * restores those registers when calibration stops (either explicitly or via the 5-minute
+ * auto-stop timer).
+ *
+ * Snapshots are persisted via `EnergyAppStorage` so a crash/restart mid-calibration does not
+ * leave the device in a calibration state without a rollback. On `initialize()`, any stored
+ * snapshot is reloaded; the auto-stop deadline is computed from `startedAtIso` so total
+ * calibration time remains capped at `autoStopMs` across restarts.
+ */
+export class CalibrationSnapshotService {
+    storage;
+    applianceId;
+    onRestore;
+    autoStopMs;
+    snapshot;
+    autoStopTimer;
+    constructor(storage, applianceId, onRestore, autoStopMs = CALIBRATION_AUTO_STOP_MS) {
+        this.storage = storage;
+        this.applianceId = applianceId;
+        this.onRestore = onRestore;
+        this.autoStopMs = autoStopMs;
+    }
+    storageKey() {
+        return `sunspec-calibration-snapshot-${this.applianceId}`;
+    }
+    async initialize() {
+        try {
+            const loaded = await this.storage.load(this.storageKey());
+            if (!loaded) {
+                return;
+            }
+            this.snapshot = loaded;
+            console.log(`CalibrationSnapshotService ${this.applianceId}: loaded persisted snapshot (started ${loaded.startedAtIso}, modifiedFields=[${loaded.modifiedFields.join(', ')}])`);
+            const remainingMs = this.remainingMs(loaded);
+            if (remainingMs <= 0) {
+                console.warn(`CalibrationSnapshotService ${this.applianceId}: snapshot exceeded ${this.autoStopMs}ms deadline — auto-restoring immediately`);
+                await this.fireAutoStop();
+            }
+            else {
+                this.scheduleAutoStop(remainingMs);
+            }
+        }
+        catch (error) {
+            console.error(`CalibrationSnapshotService ${this.applianceId}: failed to load persisted snapshot: ${error}`);
+        }
+    }
+    isCalibrating() {
+        return this.snapshot !== undefined;
+    }
+    getSnapshot() {
+        return this.snapshot;
+    }
+    async startCalibration(input) {
+        this.clearAutoStopTimer();
+        this.snapshot = {
+            applianceId: this.applianceId,
+            deviceType: input.deviceType,
+            unitId: input.unitId,
+            startedAtIso: new Date().toISOString(),
+            inverterControls: input.inverterControls,
+            batteryControls: input.batteryControls,
+            modifiedFields: [],
+        };
+        await this.persist();
+        this.scheduleAutoStop(this.autoStopMs);
+        console.log(`CalibrationSnapshotService ${this.applianceId}: calibration started for ${input.deviceType} (auto-stop in ${this.autoStopMs}ms)`);
+    }
+    async recordModification(fields) {
+        if (!this.snapshot) {
+            return;
+        }
+        let added = false;
+        for (const field of fields) {
+            if (!this.snapshot.modifiedFields.includes(field)) {
+                this.snapshot.modifiedFields.push(field);
+                added = true;
+            }
+        }
+        if (added) {
+            await this.persist();
+            console.log(`CalibrationSnapshotService ${this.applianceId}: tracked modified fields [${this.snapshot.modifiedFields.join(', ')}]`);
+        }
+    }
+    /**
+     * Clear the timer, remove the snapshot from memory + storage, and return the snapshot so
+     * the caller can restore the modified registers. Returns undefined if no calibration was
+     * active.
+     */
+    async stopCalibration() {
+        this.clearAutoStopTimer();
+        const snap = this.snapshot;
+        this.snapshot = undefined;
+        if (snap) {
+            try {
+                await this.storage.remove(this.storageKey());
+            }
+            catch (error) {
+                console.error(`CalibrationSnapshotService ${this.applianceId}: failed to remove persisted snapshot: ${error}`);
+            }
+        }
+        return snap;
+    }
+    remainingMs(snap) {
+        const startedAtMs = Date.parse(snap.startedAtIso);
+        if (Number.isNaN(startedAtMs)) {
+            return this.autoStopMs;
+        }
+        return startedAtMs + this.autoStopMs - Date.now();
+    }
+    scheduleAutoStop(delayMs) {
+        this.clearAutoStopTimer();
+        this.autoStopTimer = setTimeout(() => {
+            void this.fireAutoStop();
+        }, delayMs);
+        if (typeof this.autoStopTimer.unref === "function") {
+            this.autoStopTimer.unref();
+        }
+    }
+    clearAutoStopTimer() {
+        if (this.autoStopTimer) {
+            clearTimeout(this.autoStopTimer);
+            this.autoStopTimer = undefined;
+        }
+    }
+    async fireAutoStop() {
+        const snap = this.snapshot;
+        this.snapshot = undefined;
+        this.clearAutoStopTimer();
+        if (!snap) {
+            return;
+        }
+        try {
+            await this.storage.remove(this.storageKey());
+        }
+        catch (error) {
+            console.error(`CalibrationSnapshotService ${this.applianceId}: failed to remove persisted snapshot during auto-stop: ${error}`);
+        }
+        try {
+            await this.onRestore(snap, "auto");
+        }
+        catch (error) {
+            console.error(`CalibrationSnapshotService ${this.applianceId}: auto-stop restore failed: ${error}`);
+        }
+    }
+    async persist() {
+        if (!this.snapshot) {
+            return;
+        }
+        try {
+            await this.storage.save(this.storageKey(), this.snapshot);
+        }
+        catch (error) {
+            console.error(`CalibrationSnapshotService ${this.applianceId}: failed to persist snapshot: ${error}`);
+        }
+    }
+}

package/dist/cjs/calibration-snapshot-service.cjs

@@ -0,0 +1,164 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CalibrationSnapshotService = exports.CALIBRATION_AUTO_STOP_MS = void 0;
+/** Calibration is capped at 5 minutes of wall time, including across restarts. */
+exports.CALIBRATION_AUTO_STOP_MS = 5 * 60 * 1000;
+/**
+ * Per-appliance service that snapshots a SunSpec device's writable control registers when a
+ * calibration starts, tracks which registers other commands mutate while it is active, and
+ * restores those registers when calibration stops (either explicitly or via the 5-minute
+ * auto-stop timer).
+ *
+ * Snapshots are persisted via `EnergyAppStorage` so a crash/restart mid-calibration does not
+ * leave the device in a calibration state without a rollback. On `initialize()`, any stored
+ * snapshot is reloaded; the auto-stop deadline is computed from `startedAtIso` so total
+ * calibration time remains capped at `autoStopMs` across restarts.
+ */
+class CalibrationSnapshotService {
+    storage;
+    applianceId;
+    onRestore;
+    autoStopMs;
+    snapshot;
+    autoStopTimer;
+    constructor(storage, applianceId, onRestore, autoStopMs = exports.CALIBRATION_AUTO_STOP_MS) {
+        this.storage = storage;
+        this.applianceId = applianceId;
+        this.onRestore = onRestore;
+        this.autoStopMs = autoStopMs;
+    }
+    storageKey() {
+        return `sunspec-calibration-snapshot-${this.applianceId}`;
+    }
+    async initialize() {
+        try {
+            const loaded = await this.storage.load(this.storageKey());
+            if (!loaded) {
+                return;
+            }
+            this.snapshot = loaded;
+            console.log(`CalibrationSnapshotService ${this.applianceId}: loaded persisted snapshot (started ${loaded.startedAtIso}, modifiedFields=[${loaded.modifiedFields.join(', ')}])`);
+            const remainingMs = this.remainingMs(loaded);
+            if (remainingMs <= 0) {
+                console.warn(`CalibrationSnapshotService ${this.applianceId}: snapshot exceeded ${this.autoStopMs}ms deadline — auto-restoring immediately`);
+                await this.fireAutoStop();
+            }
+            else {
+                this.scheduleAutoStop(remainingMs);
+            }
+        }
+        catch (error) {
+            console.error(`CalibrationSnapshotService ${this.applianceId}: failed to load persisted snapshot: ${error}`);
+        }
+    }
+    isCalibrating() {
+        return this.snapshot !== undefined;
+    }
+    getSnapshot() {
+        return this.snapshot;
+    }
+    async startCalibration(input) {
+        this.clearAutoStopTimer();
+        this.snapshot = {
+            applianceId: this.applianceId,
+            deviceType: input.deviceType,
+            unitId: input.unitId,
+            startedAtIso: new Date().toISOString(),
+            inverterControls: input.inverterControls,
+            batteryControls: input.batteryControls,
+            modifiedFields: [],
+        };
+        await this.persist();
+        this.scheduleAutoStop(this.autoStopMs);
+        console.log(`CalibrationSnapshotService ${this.applianceId}: calibration started for ${input.deviceType} (auto-stop in ${this.autoStopMs}ms)`);
+    }
+    async recordModification(fields) {
+        if (!this.snapshot) {
+            return;
+        }
+        let added = false;
+        for (const field of fields) {
+            if (!this.snapshot.modifiedFields.includes(field)) {
+                this.snapshot.modifiedFields.push(field);
+                added = true;
+            }
+        }
+        if (added) {
+            await this.persist();
+            console.log(`CalibrationSnapshotService ${this.applianceId}: tracked modified fields [${this.snapshot.modifiedFields.join(', ')}]`);
+        }
+    }
+    /**
+     * Clear the timer, remove the snapshot from memory + storage, and return the snapshot so
+     * the caller can restore the modified registers. Returns undefined if no calibration was
+     * active.
+     */
+    async stopCalibration() {
+        this.clearAutoStopTimer();
+        const snap = this.snapshot;
+        this.snapshot = undefined;
+        if (snap) {
+            try {
+                await this.storage.remove(this.storageKey());
+            }
+            catch (error) {
+                console.error(`CalibrationSnapshotService ${this.applianceId}: failed to remove persisted snapshot: ${error}`);
+            }
+        }
+        return snap;
+    }
+    remainingMs(snap) {
+        const startedAtMs = Date.parse(snap.startedAtIso);
+        if (Number.isNaN(startedAtMs)) {
+            return this.autoStopMs;
+        }
+        return startedAtMs + this.autoStopMs - Date.now();
+    }
+    scheduleAutoStop(delayMs) {
+        this.clearAutoStopTimer();
+        this.autoStopTimer = setTimeout(() => {
+            void this.fireAutoStop();
+        }, delayMs);
+        if (typeof this.autoStopTimer.unref === "function") {
+            this.autoStopTimer.unref();
+        }
+    }
+    clearAutoStopTimer() {
+        if (this.autoStopTimer) {
+            clearTimeout(this.autoStopTimer);
+            this.autoStopTimer = undefined;
+        }
+    }
+    async fireAutoStop() {
+        const snap = this.snapshot;
+        this.snapshot = undefined;
+        this.clearAutoStopTimer();
+        if (!snap) {
+            return;
+        }
+        try {
+            await this.storage.remove(this.storageKey());
+        }
+        catch (error) {
+            console.error(`CalibrationSnapshotService ${this.applianceId}: failed to remove persisted snapshot during auto-stop: ${error}`);
+        }
+        try {
+            await this.onRestore(snap, "auto");
+        }
+        catch (error) {
+            console.error(`CalibrationSnapshotService ${this.applianceId}: auto-stop restore failed: ${error}`);
+        }
+    }
+    async persist() {
+        if (!this.snapshot) {
+            return;
+        }
+        try {
+            await this.storage.save(this.storageKey(), this.snapshot);
+        }
+        catch (error) {
+            console.error(`CalibrationSnapshotService ${this.applianceId}: failed to persist snapshot: ${error}`);
+        }
+    }
+}
+exports.CalibrationSnapshotService = CalibrationSnapshotService;

package/dist/cjs/calibration-snapshot-service.d.cts

@@ -0,0 +1,67 @@
+import { EnergyAppStorage } from "@enyo-energy/energy-app-sdk/dist/packages/energy-app-storage.js";
+import type { SunspecBatteryControls, SunspecInverterControls } from "./sunspec-interfaces.cjs";
+export type CalibrationDeviceType = "inverter" | "battery";
+/**
+ * Persisted snapshot of a device's writable control registers, taken at the start of a
+ * calibration. Used to roll the device back when calibration ends.
+ *
+ * `modifiedFields` records which control-block field names were touched by *other* write
+ * commands (SetInverterFeedInLimitV1, StartStorageGridChargeV1, etc.) while the calibration
+ * was active — on stop, only those fields are written back, leaving fields the calibration
+ * itself didn't disturb alone.
+ */
+export interface CalibrationSnapshot {
+    applianceId: string;
+    deviceType: CalibrationDeviceType;
+    unitId: number;
+    startedAtIso: string;
+    inverterControls?: SunspecInverterControls;
+    batteryControls?: SunspecBatteryControls;
+    modifiedFields: string[];
+}
+/** Calibration is capped at 5 minutes of wall time, including across restarts. */
+export declare const CALIBRATION_AUTO_STOP_MS: number;
+export type CalibrationRestoreReason = "stop" | "auto";
+export type CalibrationRestoreCallback = (snapshot: CalibrationSnapshot, reason: CalibrationRestoreReason) => Promise<void>;
+/**
+ * Per-appliance service that snapshots a SunSpec device's writable control registers when a
+ * calibration starts, tracks which registers other commands mutate while it is active, and
+ * restores those registers when calibration stops (either explicitly or via the 5-minute
+ * auto-stop timer).
+ *
+ * Snapshots are persisted via `EnergyAppStorage` so a crash/restart mid-calibration does not
+ * leave the device in a calibration state without a rollback. On `initialize()`, any stored
+ * snapshot is reloaded; the auto-stop deadline is computed from `startedAtIso` so total
+ * calibration time remains capped at `autoStopMs` across restarts.
+ */
+export declare class CalibrationSnapshotService {
+    private readonly storage;
+    private readonly applianceId;
+    private readonly onRestore;
+    private readonly autoStopMs;
+    private snapshot?;
+    private autoStopTimer?;
+    constructor(storage: EnergyAppStorage, applianceId: string, onRestore: CalibrationRestoreCallback, autoStopMs?: number);
+    private storageKey;
+    initialize(): Promise<void>;
+    isCalibrating(): boolean;
+    getSnapshot(): CalibrationSnapshot | undefined;
+    startCalibration(input: {
+        deviceType: CalibrationDeviceType;
+        unitId: number;
+        inverterControls?: SunspecInverterControls;
+        batteryControls?: SunspecBatteryControls;
+    }): Promise<void>;
+    recordModification(fields: string[]): Promise<void>;
+    /**
+     * Clear the timer, remove the snapshot from memory + storage, and return the snapshot so
+     * the caller can restore the modified registers. Returns undefined if no calibration was
+     * active.
+     */
+    stopCalibration(): Promise<CalibrationSnapshot | undefined>;
+    private remainingMs;
+    private scheduleAutoStop;
+    private clearAutoStopTimer;
+    private fireAutoStop;
+    private persist;
+}

package/dist/cjs/index.cjs

@@ -18,6 +18,7 @@ exports.getSdkVersion = exports.SDK_VERSION = exports.ConnectionRetryManager = v
 __exportStar(require("./sunspec-interfaces.cjs"), exports);
 __exportStar(require("./sunspec-devices.cjs"), exports);
 __exportStar(require("./sunspec-modbus-client.cjs"), exports);
+__exportStar(require("./calibration-snapshot-service.cjs"), exports);
 var connection_retry_manager_js_1 = require("./connection-retry-manager.cjs");
 Object.defineProperty(exports, "ConnectionRetryManager", { enumerable: true, get: function () { return connection_retry_manager_js_1.ConnectionRetryManager; } });
 var version_js_1 = require("./version.cjs");

package/dist/cjs/index.d.cts

@@ -1,5 +1,6 @@
 export * from './sunspec-interfaces.cjs';
 export * from './sunspec-devices.cjs';
 export * from './sunspec-modbus-client.cjs';
+export * from './calibration-snapshot-service.cjs';
 export { ConnectionRetryManager } from './connection-retry-manager.cjs';
 export { SDK_VERSION, getSdkVersion } from './version.cjs';