@enyo-energy/sunspec-sdk 0.0.70 → 0.0.72

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

@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getSdkVersion = exports.SDK_VERSION = exports.ConnectionRetryManager = void 0;
+exports.CalibrationTrigger = exports.CalibrationResultStore = exports.DEFAULT_BATTERY_CALIBRATOR_CONFIG = exports.BatteryCalibrator = exports.AbstractBatteryCalibrationDriver = exports.DEFAULT_AUTO_STOP_MS = exports.SnapshotService = exports.InMemoryCalibrationStorage = exports.AbstractCalibrationStorage = exports.EnyoStorageScheduleDirectionEnum = exports.EnyoStorageScheduleModeEnum = exports.SunspecBatteryScheduleHandler = exports.decodeFeatureResults = exports.SunspecBatteryFeatureCalibrator = exports.SunspecBatteryCalibrationDriver = exports.createSunspecCalibrationStorage = exports.SunspecCalibrationStorage = exports.getSdkVersion = exports.SDK_VERSION = exports.ConnectionRetryManager = void 0;
 __exportStar(require("./sunspec-interfaces.cjs"), exports);
 __exportStar(require("./sunspec-devices.cjs"), exports);
 __exportStar(require("./sunspec-modbus-client.cjs"), exports);
@@ -23,3 +23,32 @@ Object.defineProperty(exports, "ConnectionRetryManager", { enumerable: true, get
 var version_js_1 = require("./version.cjs");
 Object.defineProperty(exports, "SDK_VERSION", { enumerable: true, get: function () { return version_js_1.SDK_VERSION; } });
 Object.defineProperty(exports, "getSdkVersion", { enumerable: true, get: function () { return version_js_1.getSdkVersion; } });
+// New calibration integration with @enyo-energy/appliance-calibration
+var sunspec_calibration_storage_js_1 = require("./sunspec-calibration-storage.cjs");
+Object.defineProperty(exports, "SunspecCalibrationStorage", { enumerable: true, get: function () { return sunspec_calibration_storage_js_1.SunspecCalibrationStorage; } });
+Object.defineProperty(exports, "createSunspecCalibrationStorage", { enumerable: true, get: function () { return sunspec_calibration_storage_js_1.createSunspecCalibrationStorage; } });
+var sunspec_battery_calibration_driver_js_1 = require("./sunspec-battery-calibration-driver.cjs");
+Object.defineProperty(exports, "SunspecBatteryCalibrationDriver", { enumerable: true, get: function () { return sunspec_battery_calibration_driver_js_1.SunspecBatteryCalibrationDriver; } });
+var sunspec_battery_feature_calibrator_js_1 = require("./sunspec-battery-feature-calibrator.cjs");
+Object.defineProperty(exports, "SunspecBatteryFeatureCalibrator", { enumerable: true, get: function () { return sunspec_battery_feature_calibrator_js_1.SunspecBatteryFeatureCalibrator; } });
+Object.defineProperty(exports, "decodeFeatureResults", { enumerable: true, get: function () { return sunspec_battery_feature_calibrator_js_1.decodeFeatureResults; } });
+var sunspec_battery_schedule_handler_js_1 = require("./sunspec-battery-schedule-handler.cjs");
+Object.defineProperty(exports, "SunspecBatteryScheduleHandler", { enumerable: true, get: function () { return sunspec_battery_schedule_handler_js_1.SunspecBatteryScheduleHandler; } });
+// Re-export the schedule message types from energy-app-sdk so consumers can
+// build/inspect SetStorageScheduleV1 messages without a second import.
+var enyo_data_bus_value_js_1 = require("@enyo-energy/energy-app-sdk/dist/types/enyo-data-bus-value.js");
+Object.defineProperty(exports, "EnyoStorageScheduleModeEnum", { enumerable: true, get: function () { return enyo_data_bus_value_js_1.EnyoStorageScheduleModeEnum; } });
+Object.defineProperty(exports, "EnyoStorageScheduleDirectionEnum", { enumerable: true, get: function () { return enyo_data_bus_value_js_1.EnyoStorageScheduleDirectionEnum; } });
+// Re-export the library symbols consumers need to wire up the trigger and gate
+// commands. Avoids a second peer dependency on @enyo-energy/appliance-calibration
+// while keeping the consumer wiring concise.
+var appliance_calibration_1 = require("@enyo-energy/appliance-calibration");
+Object.defineProperty(exports, "AbstractCalibrationStorage", { enumerable: true, get: function () { return appliance_calibration_1.AbstractCalibrationStorage; } });
+Object.defineProperty(exports, "InMemoryCalibrationStorage", { enumerable: true, get: function () { return appliance_calibration_1.InMemoryCalibrationStorage; } });
+Object.defineProperty(exports, "SnapshotService", { enumerable: true, get: function () { return appliance_calibration_1.SnapshotService; } });
+Object.defineProperty(exports, "DEFAULT_AUTO_STOP_MS", { enumerable: true, get: function () { return appliance_calibration_1.DEFAULT_AUTO_STOP_MS; } });
+Object.defineProperty(exports, "AbstractBatteryCalibrationDriver", { enumerable: true, get: function () { return appliance_calibration_1.AbstractBatteryCalibrationDriver; } });
+Object.defineProperty(exports, "BatteryCalibrator", { enumerable: true, get: function () { return appliance_calibration_1.BatteryCalibrator; } });
+Object.defineProperty(exports, "DEFAULT_BATTERY_CALIBRATOR_CONFIG", { enumerable: true, get: function () { return appliance_calibration_1.DEFAULT_BATTERY_CALIBRATOR_CONFIG; } });
+Object.defineProperty(exports, "CalibrationResultStore", { enumerable: true, get: function () { return appliance_calibration_1.CalibrationResultStore; } });
+Object.defineProperty(exports, "CalibrationTrigger", { enumerable: true, get: function () { return appliance_calibration_1.CalibrationTrigger; } });

package/dist/cjs/index.d.cts

@@ -3,3 +3,9 @@ export * from './sunspec-devices.cjs';
 export * from './sunspec-modbus-client.cjs';
 export { ConnectionRetryManager } from './connection-retry-manager.cjs';
 export { SDK_VERSION, getSdkVersion } from './version.cjs';
+export { SunspecCalibrationStorage, createSunspecCalibrationStorage } from './sunspec-calibration-storage.cjs';
+export { SunspecBatteryCalibrationDriver } from './sunspec-battery-calibration-driver.cjs';
+export { SunspecBatteryFeatureCalibrator, type SunspecBatteryFeatureCalibratorOptions, decodeFeatureResults, } from './sunspec-battery-feature-calibrator.cjs';
+export { SunspecBatteryScheduleHandler, type SunspecScheduleRegisters, type SunspecBatteryScheduleHandlerOptions, } from './sunspec-battery-schedule-handler.cjs';
+export { type EnyoDataBusSetStorageScheduleV1, type EnyoStorageScheduleEntry, EnyoStorageScheduleModeEnum, EnyoStorageScheduleDirectionEnum, } from '@enyo-energy/energy-app-sdk/dist/types/enyo-data-bus-value.js';
+export { AbstractCalibrationStorage, InMemoryCalibrationStorage, type AckResult, type CalibrationResult, type CalibrationState, type CalibrationSnapshot, type CalibrationRestoreCallback, type RestoreReason, SnapshotService, type SnapshotServiceOptions, DEFAULT_AUTO_STOP_MS, AbstractBatteryCalibrationDriver, BatteryCalibrator, type BatteryCalibratorOptions, type BatteryCalibratorConfig, DEFAULT_BATTERY_CALIBRATOR_CONFIG, CalibrationResultStore, type CalibrationResultStoreData, CalibrationTrigger, type CalibrationTriggerOptions, } from '@enyo-energy/appliance-calibration';

package/dist/cjs/sunspec-battery-calibration-driver.cjs

@@ -0,0 +1,158 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SunspecBatteryCalibrationDriver = void 0;
+const appliance_calibration_1 = require("@enyo-energy/appliance-calibration");
+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");
+/**
+ * Subset of {@link SunspecBatteryControls} that `writeBatteryControls` accepts.
+ * Used both as the calibrator's snapshot payload and as the restore whitelist.
+ */
+const WRITABLE_BATTERY_FIELDS = [
+    "storCtlMod",
+    "chaGriSet",
+    "wChaMax",
+    "inWRte",
+    "outWRte",
+    "minRsvPct",
+];
+/**
+ * Vendor seam between `@enyo-energy/appliance-calibration`'s `BatteryCalibrator`
+ * and a SunSpec battery exposed via {@link SunspecModbusClient}.
+ *
+ * Battery power is fed in by the owning {@link SunspecBattery} on every readData
+ * cycle (call {@link updateBatteryPowerCache}). Grid power is sourced from the
+ * data bus: the driver subscribes to `MeterValuesUpdateV1` for the lifetime of
+ * the calibrator and caches the latest reading. Call {@link stop} when the
+ * battery disconnects to unsubscribe.
+ */
+class SunspecBatteryCalibrationDriver extends appliance_calibration_1.AbstractBatteryCalibrationDriver {
+    sunspecClient;
+    unitId;
+    dataBus;
+    batteryPowerCache = new appliance_calibration_1.LatestValueCache();
+    gridPowerCache = new appliance_calibration_1.LatestValueCache();
+    meterListenerId;
+    constructor(sunspecClient, unitId, dataBus) {
+        super();
+        this.sunspecClient = sunspecClient;
+        this.unitId = unitId;
+        this.dataBus = dataBus;
+        this.subscribeMeterUpdates();
+    }
+    subscribeMeterUpdates() {
+        this.meterListenerId = this.dataBus.listenForMessages([enyo_data_bus_value_js_1.EnyoDataBusMessageEnum.MeterValuesUpdateV1], (entry) => {
+            if (entry.message !== enyo_data_bus_value_js_1.EnyoDataBusMessageEnum.MeterValuesUpdateV1) {
+                return;
+            }
+            const meter = entry;
+            if (meter.data.gridPowerW !== undefined) {
+                this.gridPowerCache.set(meter.data.gridPowerW);
+            }
+        });
+    }
+    /**
+     * Tear down the meter subscription. Idempotent — call from
+     * `SunspecBattery.disconnect()`.
+     */
+    stop() {
+        if (this.meterListenerId) {
+            this.dataBus.unsubscribe(this.meterListenerId);
+            this.meterListenerId = undefined;
+        }
+    }
+    /**
+     * Push the latest computed battery power (W, positive = charging into the
+     * battery) from the owning device. Called from the readData loop.
+     */
+    updateBatteryPowerCache(powerW) {
+        this.batteryPowerCache.set(powerW);
+    }
+    async captureSnapshot() {
+        const controls = await this.sunspecClient.readBatteryControls(this.unitId);
+        if (!controls) {
+            throw new Error(`SunspecBatteryCalibrationDriver: readBatteryControls returned null for unit ${this.unitId}`);
+        }
+        return controls;
+    }
+    /**
+     * Write only the fields present in the snapshot AND in the writable whitelist.
+     * Per the library's contract this is best-effort: log on failure rather than
+     * throw, because the persisted snapshot has already been removed by the time
+     * we run and any throw would silently swallow what just happened.
+     */
+    async restoreFromSnapshot(snapshot, reason) {
+        const partial = {};
+        for (const field of WRITABLE_BATTERY_FIELDS) {
+            const value = snapshot[field];
+            if (value !== undefined) {
+                partial[field] = value;
+            }
+        }
+        if (Object.keys(partial).length === 0) {
+            console.log(`SunspecBatteryCalibrationDriver ${this.unitId}: restore (${reason}) — nothing to write`);
+            return;
+        }
+        try {
+            const ok = await this.sunspecClient.writeBatteryControls(this.unitId, partial);
+            if (!ok) {
+                console.error(`SunspecBatteryCalibrationDriver ${this.unitId}: restore (${reason}) writeBatteryControls returned false for [${Object.keys(partial).join(", ")}]`);
+            }
+        }
+        catch (error) {
+            console.error(`SunspecBatteryCalibrationDriver ${this.unitId}: restore (${reason}) threw: ${error}`);
+        }
+    }
+    /**
+     * SunSpec model 124 has no explicit calibration-mode register — the
+     * snapshot / restore + storCtlMod sequence *is* the calibration protocol.
+     * Resolve immediately so the orchestrator advances to the test charge.
+     */
+    async enterCalibrationMode() {
+        return "accepted";
+    }
+    async exitCalibrationMode() {
+        return "accepted";
+    }
+    /**
+     * Drive the same 3-step sequence proven by `handleStartGridCharge` in
+     * {@link SunspecBattery}: charge cap, grid-charging enable, storage mode.
+     * Throws on any step failure so the calibrator records a `failed` result.
+     */
+    async startTestCharge(powerW) {
+        const enabledGrid = await this.sunspecClient.enableGridCharging(this.unitId, true);
+        if (!enabledGrid) {
+            throw new Error("startTestCharge: failed to enable grid charging");
+        }
+        const wroteChaMax = await this.sunspecClient.writeBatteryControls(this.unitId, { wChaMax: powerW });
+        if (!wroteChaMax) {
+            throw new Error("startTestCharge: failed to set wChaMax");
+        }
+        const setMode = await this.sunspecClient.setStorageMode(this.unitId, sunspec_interfaces_js_1.SunspecStorageMode.CHARGE);
+        if (!setMode) {
+            throw new Error("startTestCharge: failed to set storage mode CHARGE");
+        }
+    }
+    /**
+     * Hand the battery back to its normal AUTO / PV state. The snapshot
+     * service's restore takes care of returning wChaMax / inWRte / outWRte
+     * to baseline.
+     */
+    async stopTestCharge() {
+        const setMode = await this.sunspecClient.setStorageMode(this.unitId, sunspec_interfaces_js_1.SunspecStorageMode.AUTO);
+        if (!setMode) {
+            throw new Error("stopTestCharge: failed to set storage mode AUTO");
+        }
+        const disabledGrid = await this.sunspecClient.enableGridCharging(this.unitId, false);
+        if (!disabledGrid) {
+            throw new Error("stopTestCharge: failed to disable grid charging");
+        }
+    }
+    readBatteryPowerW() {
+        return this.batteryPowerCache.get();
+    }
+    readGridPowerW() {
+        return this.gridPowerCache.get();
+    }
+}
+exports.SunspecBatteryCalibrationDriver = SunspecBatteryCalibrationDriver;

package/dist/cjs/sunspec-battery-calibration-driver.d.cts

@@ -0,0 +1,63 @@
+import { AbstractBatteryCalibrationDriver, type AckResult, type RestoreReason } from "@enyo-energy/appliance-calibration";
+import type { EnergyAppDataBus } from "@enyo-energy/energy-app-sdk/dist/packages/energy-app-data-bus.js";
+import type { SunspecModbusClient } from "./sunspec-modbus-client.cjs";
+import { type SunspecBatteryControls } from "./sunspec-interfaces.cjs";
+/**
+ * Vendor seam between `@enyo-energy/appliance-calibration`'s `BatteryCalibrator`
+ * and a SunSpec battery exposed via {@link SunspecModbusClient}.
+ *
+ * Battery power is fed in by the owning {@link SunspecBattery} on every readData
+ * cycle (call {@link updateBatteryPowerCache}). Grid power is sourced from the
+ * data bus: the driver subscribes to `MeterValuesUpdateV1` for the lifetime of
+ * the calibrator and caches the latest reading. Call {@link stop} when the
+ * battery disconnects to unsubscribe.
+ */
+export declare class SunspecBatteryCalibrationDriver extends AbstractBatteryCalibrationDriver<SunspecBatteryControls> {
+    private readonly sunspecClient;
+    private readonly unitId;
+    private readonly dataBus;
+    private readonly batteryPowerCache;
+    private readonly gridPowerCache;
+    private meterListenerId?;
+    constructor(sunspecClient: SunspecModbusClient, unitId: number, dataBus: EnergyAppDataBus);
+    private subscribeMeterUpdates;
+    /**
+     * Tear down the meter subscription. Idempotent — call from
+     * `SunspecBattery.disconnect()`.
+     */
+    stop(): void;
+    /**
+     * Push the latest computed battery power (W, positive = charging into the
+     * battery) from the owning device. Called from the readData loop.
+     */
+    updateBatteryPowerCache(powerW: number): void;
+    captureSnapshot(): Promise<SunspecBatteryControls>;
+    /**
+     * Write only the fields present in the snapshot AND in the writable whitelist.
+     * Per the library's contract this is best-effort: log on failure rather than
+     * throw, because the persisted snapshot has already been removed by the time
+     * we run and any throw would silently swallow what just happened.
+     */
+    restoreFromSnapshot(snapshot: SunspecBatteryControls, reason: RestoreReason): Promise<void>;
+    /**
+     * SunSpec model 124 has no explicit calibration-mode register — the
+     * snapshot / restore + storCtlMod sequence *is* the calibration protocol.
+     * Resolve immediately so the orchestrator advances to the test charge.
+     */
+    enterCalibrationMode(): Promise<AckResult>;
+    exitCalibrationMode(): Promise<AckResult>;
+    /**
+     * Drive the same 3-step sequence proven by `handleStartGridCharge` in
+     * {@link SunspecBattery}: charge cap, grid-charging enable, storage mode.
+     * Throws on any step failure so the calibrator records a `failed` result.
+     */
+    startTestCharge(powerW: number): Promise<void>;
+    /**
+     * Hand the battery back to its normal AUTO / PV state. The snapshot
+     * service's restore takes care of returning wChaMax / inWRte / outWRte
+     * to baseline.
+     */
+    stopTestCharge(): Promise<void>;
+    readBatteryPowerW(): number | undefined;
+    readGridPowerW(): number | undefined;
+}