@enyo-energy/sunspec-sdk 0.0.70 → 0.0.72

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

@@ -1,10 +1,11 @@
-import { type IRetryConfig, type SunspecBatteryBaseData, SunspecBatteryCapability, type SunspecBatteryControls, type SunspecInverterData, SunspecInverterCapability, SunspecMeterCapability, SunspecStorageMode } from "./sunspec-interfaces.cjs";
+import { type IRetryConfig, type SunspecBatteryBaseData, SunspecBatteryCapability, type SunspecBatteryControls, 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 { EnergyAppDataBus } from "@enyo-energy/energy-app-sdk/dist/packages/energy-app-data-bus.js";
 /**
  * Base abstract class for all Sunspec devices
@@ -25,6 +26,13 @@ export declare abstract class BaseSunspecDevice {
     protected dataBus?: EnergyAppDataBus;
     protected retryManager: ConnectionRetryManager;
     protected consecutiveReconnectFailures: number;
+    /**
+     * Prefix used when persisting calibration snapshots via the library's
+     * {@link SnapshotService}. Kept identical to the key the SDK used before
+     * the migration to `@enyo-energy/appliance-calibration` so existing
+     * snapshots stored by older builds are still picked up on startup.
+     */
+    protected static readonly CALIBRATION_SNAPSHOT_KEY_PREFIX = "sunspec-calibration-snapshot-";
     constructor(energyApp: EnergyApp, name: EnyoApplianceName[], networkDevice: EnyoNetworkDevice, sunspecClient: SunspecModbusClient, applianceManager: ApplianceManager, unitId?: number, port?: number, baseAddress?: number, retryConfig?: IRetryConfig, appliance?: EnyoAppliance, useTls?: boolean | undefined);
     /**
      * Connect to the device and create/update the appliance
@@ -77,6 +85,12 @@ export declare abstract class BaseSunspecDevice {
      */
     protected markOffline(): Promise<void>;
     protected sendCommandAcknowledge(messageId: string, acknowledgeMessage: EnyoDataBusMessageEnum | string, answer: EnyoCommandAcknowledgeAnswerEnum, rejectionReason?: string): void;
+    /**
+     * Build a typed {@link SnapshotService} bound to this appliance's calibration storage,
+     * using the legacy SDK storage key prefix so prior installs upgrade seamlessly. Returns
+     * undefined if the appliance has not been registered yet.
+     */
+    protected buildSnapshotService<T>(onRestore: (snapshot: CalibrationSnapshot<T>, reason: RestoreReason) => Promise<void>): SnapshotService<T> | undefined;
 }
 /**
  * Sunspec Inverter implementation using dynamic model discovery
@@ -87,6 +101,7 @@ export declare class SunspecInverter extends BaseSunspecDevice {
     private static readonly CONNECTION_FAULT_THRESHOLD;
     private storage?;
     private errorState;
+    private snapshotService?;
     constructor(energyApp: EnergyApp, name: EnyoApplianceName[], networkDevice: EnyoNetworkDevice, sunspecClient: SunspecModbusClient, applianceManager: ApplianceManager, unitId?: number, port?: number, baseAddress?: number, capabilities?: SunspecInverterCapability[], retryConfig?: IRetryConfig, appliance?: EnyoAppliance, useTls?: boolean);
     connect(): Promise<void>;
     disconnect(): Promise<void>;
@@ -156,13 +171,77 @@ export declare class SunspecInverter extends BaseSunspecDevice {
     stopDataBusListening(): void;
     private handleInverterCommand;
     private handleSetFeedInLimit;
+    /**
+     * Lazily construct the per-appliance {@link SnapshotService}. Reloads any
+     * persisted snapshot from storage so an in-flight calibration survives
+     * process restarts. Idempotent.
+     */
+    private initSnapshotService;
+    private handleStartCalibration;
+    private handleStopCalibration;
+    /**
+     * `onRestore` callback for the inverter's {@link SnapshotService}. Writes only the
+     * subset of writable inverter fields that other commands actually touched during the
+     * calibration. Catches and logs failures rather than throwing — the snapshot has
+     * already been removed from storage by the time this runs, so a throw is unrecoverable
+     * and is best logged for operator action.
+     */
+    private restoreInverterSnapshot;
 }
 /**
  * Sunspec Battery implementation
  */
 export declare class SunspecBattery extends BaseSunspecDevice {
+    private readonly featureMode;
     private readonly capabilities;
-    constructor(energyApp: EnergyApp, name: EnyoApplianceName[], networkDevice: EnyoNetworkDevice, sunspecClient: SunspecModbusClient, applianceManager: ApplianceManager, unitId?: number, port?: number, baseAddress?: number, capabilities?: SunspecBatteryCapability[], retryConfig?: IRetryConfig, appliance?: EnyoAppliance, useTls?: boolean);
+    private snapshotService?;
+    private calibrationDriver?;
+    private batteryCalibrator?;
+    private calibrationResultStore?;
+    private scheduleHandler;
+    /**
+     * Battery features that imply outbound control writes from the host action-taker.
+     * These are stripped from `appliance.battery.features` until the calibration result
+     * store says this battery has been successfully calibrated — see
+     * {@link computeAdvertisedFeatures}.
+     */
+    private static readonly CONTROLLABLE_FEATURES;
+    constructor(energyApp: EnergyApp, name: EnyoApplianceName[], networkDevice: EnyoNetworkDevice, sunspecClient: SunspecModbusClient, applianceManager: ApplianceManager, featureMode: SunspecBatteryFeatureMode, unitId?: number, port?: number, baseAddress?: number, capabilities?: SunspecBatteryCapability[], retryConfig?: IRetryConfig, appliance?: EnyoAppliance, useTls?: boolean);
+    /**
+     * Wire the battery into `@enyo-energy/appliance-calibration`'s
+     * `BatteryCalibrator` test-charge flow. Call once after {@link connect}.
+     *
+     * Consumers own the `CalibrationResultStore` (shared across appliances so
+     * the persisted result map doesn't get clobbered) and the
+     * `CalibrationTrigger` that drives `runCalibration()` on whatever schedule
+     * makes sense for the host. Pass overrides for the calibrator's defaults
+     * (`testPowerW`, response thresholds, etc.) via `opts.config`.
+     */
+    configureCalibration(opts: {
+        resultStore: CalibrationResultStore;
+        config?: Partial<BatteryCalibratorConfig>;
+    }): BatteryCalibrator<SunspecBatteryControls>;
+    /**
+     * Detect which battery features the device's registers expose. This is the
+     * raw, register-only view; the {@link featureMode} configured at
+     * construction decides what is actually published — see
+     * {@link resolveAdvertisedFeatures}.
+     */
+    private detectFromRegisters;
+    /**
+     * Resolve `appliance.battery.features` for the configured mode. Called on
+     * every connect() and readData() cycle so that, in calibration-based mode,
+     * the controllable features appear as soon as the calibrator flips
+     * `isCalibrated` (no synchronous push).
+     */
+    private resolveAdvertisedFeatures;
+    /**
+     * Returns the per-battery `BatteryCalibrator` created by
+     * {@link configureCalibration}, or `undefined` if calibration was never
+     * configured. Consumers register the returned instance with their own
+     * `CalibrationTrigger`.
+     */
+    getBatteryCalibrator(): BatteryCalibrator<SunspecBatteryControls> | undefined;
     /**
      * Connect to the battery and create/update the appliance
      */
@@ -284,10 +363,30 @@ export declare class SunspecBattery extends BaseSunspecDevice {
      */
     stopDataBusListening(): void;
     private handleStorageCommand;
-    private handleStartGridCharge;
-    private handleStopGridCharge;
-    private handleSetDischargeLimit;
-    private handleSetChargeLimit;
+    /**
+     * Acknowledge a SetStorageScheduleV1 message. The actual schedule application
+     * is owned by `this.scheduleHandler` (subscribed independently via its own
+     * data-bus listener registered in its constructor). The ack reports "received
+     * & queued" rather than "applied" — schedule entries play out over time, and
+     * per-entry write failures land in `console.error` via the handler's
+     * onChange wrapper.
+     */
+    private handleSetStorageScheduleAck;
+    /**
+     * Lazily construct the per-appliance {@link SnapshotService}. Reloads any
+     * persisted snapshot from storage so an in-flight calibration survives
+     * process restarts. Idempotent.
+     */
+    private initSnapshotService;
+    private handleStartCalibration;
+    private handleStopCalibration;
+    /**
+     * `onRestore` callback for the battery's {@link SnapshotService}. Writes only the
+     * subset of writable battery fields touched during the calibration. Errors are
+     * caught and logged — by the time this fires the snapshot is gone from storage,
+     * so a throw would just propagate into the void.
+     */
+    private restoreBatterySnapshot;
 }
 /**
  * Sunspec Meter implementation
@@ -303,6 +402,13 @@ export declare class SunspecMeter extends BaseSunspecDevice {
      * Disconnect from the meter and update appliance state
      */
     disconnect(): Promise<void>;
+    /**
+     * Meter does not implement calibration; it only subscribes to Start/StopCalibrationV1 to
+     * answer NotSupported (per the data-bus contract that every command must be acknowledged).
+     */
+    startDataBusListening(): void;
+    stopDataBusListening(): void;
+    private handleMeterCommand;
     /**
      * Update meter data and return data bus messages
      */

package/dist/cjs/sunspec-interfaces.cjs

@@ -3,7 +3,8 @@
  * SunSpec block interfaces with block numbers
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SunspecMeterCapability = exports.SunspecBatteryCapability = exports.SunspecInverterCapability = exports.SunspecStorageMode = exports.SunspecChargeSource = exports.SunspecVArPctMode = exports.SunspecEnableControl = exports.SunspecConnectionControl = exports.SunspecStorageControlMode = exports.SunspecBatteryEvent1 = exports.SunspecBatteryBankState = exports.SunspecBatteryType = exports.SunspecBatteryControlMode = exports.SunspecBatteryChargeState = exports.SunspecMPPTOperatingState = exports.SUNSPEC_CONNECTION_LOST_CODE = exports.SunspecInverterEvent1 = exports.SunspecModelId = exports.DEFAULT_RETRY_CONFIG = void 0;
+exports.SUNSPEC_CONTROLLABLE_FEATURES = exports.SunspecMeterCapability = exports.SunspecBatteryFeatureModeKind = exports.SunspecBatteryCapability = exports.SunspecInverterCapability = exports.SunspecStorageMode = exports.SunspecChargeSource = exports.SunspecVArPctMode = exports.SunspecEnableControl = exports.SunspecConnectionControl = exports.SunspecStorageControlMode = exports.SunspecBatteryEvent1 = exports.SunspecBatteryBankState = exports.SunspecBatteryType = exports.SunspecBatteryControlMode = exports.SunspecBatteryChargeState = exports.SunspecMPPTOperatingState = exports.SUNSPEC_CONNECTION_LOST_CODE = exports.SunspecInverterEvent1 = exports.SunspecModelId = exports.DEFAULT_RETRY_CONFIG = void 0;
+const enyo_battery_appliance_js_1 = require("@enyo-energy/energy-app-sdk/dist/types/enyo-battery-appliance.js");
 exports.DEFAULT_RETRY_CONFIG = {
     phases: [
         { intervalMs: 10_000, durationMs: 60_000 }, // Phase 1: every 10s for 1 minute
@@ -257,6 +258,46 @@ var SunspecBatteryCapability;
     SunspecBatteryCapability["DischargeLimit"] = "discharge-limit";
     SunspecBatteryCapability["ChargeLimit"] = "charge-limit";
 })(SunspecBatteryCapability || (exports.SunspecBatteryCapability = SunspecBatteryCapability = {}));
+/**
+ * Selects how `SunspecBattery` populates `appliance.battery.features`.
+ *
+ * - `Disabled`: ignore the SunSpec registers and ignore calibration. The SDK
+ *   publishes whatever the consumer puts in `allowedFeatures` (omit or pass
+ *   `[]` to advertise nothing). Useful when the host already knows what the
+ *   battery can do and doesn't want the SDK to make any inference.
+ * - `RegisterBased`: publish whatever the device's registers expose. If
+ *   `allowedFeatures` is set, the published list is the intersection — the
+ *   register-detected set filtered to the allow-list. Lets the consumer hide
+ *   features that the hardware exposes but they don't want to use.
+ * - `CalibrationBased`: same as `RegisterBased`, but controllable features
+ *   (grid charging, grid discharging, charge limitation, discharge
+ *   limitation) stay hidden until `CalibrationResultStore.isCalibrated(...)`
+ *   returns true for this appliance. Requires `configureCalibration(...)` to
+ *   actually run a calibration; without it the controllable features remain
+ *   hidden forever (safe-fallback behaviour).
+ */
+var SunspecBatteryFeatureModeKind;
+(function (SunspecBatteryFeatureModeKind) {
+    SunspecBatteryFeatureModeKind["Disabled"] = "disabled";
+    SunspecBatteryFeatureModeKind["RegisterBased"] = "register-based";
+    SunspecBatteryFeatureModeKind["CalibrationBased"] = "calibration-based";
+})(SunspecBatteryFeatureModeKind || (exports.SunspecBatteryFeatureModeKind = SunspecBatteryFeatureModeKind = {}));
 var SunspecMeterCapability;
 (function (SunspecMeterCapability) {
 })(SunspecMeterCapability || (exports.SunspecMeterCapability = SunspecMeterCapability = {}));
+/**
+ * The four `EnyoBatteryFeature` values that imply outbound control writes from
+ * the host action-taker. `SunspecBattery` calibration probes each one
+ * individually so `appliance.battery.features` reflects only what the device
+ * actually honours.
+ *
+ * Exposed as `as const` (not a plain `EnyoBatteryFeature[]`) so consumers can
+ * iterate the tuple with full type narrowing — see the `WRITABLE_BATTERY_FIELDS`
+ * pattern in `sunspec-battery-calibration-driver.ts`.
+ */
+exports.SUNSPEC_CONTROLLABLE_FEATURES = [
+    enyo_battery_appliance_js_1.EnyoBatteryFeature.GridCharging,
+    enyo_battery_appliance_js_1.EnyoBatteryFeature.GridDischarging,
+    enyo_battery_appliance_js_1.EnyoBatteryFeature.ChargeLimitation,
+    enyo_battery_appliance_js_1.EnyoBatteryFeature.DischargeLimitation,
+];

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

@@ -1,6 +1,7 @@
 /**
  * SunSpec block interfaces with block numbers
  */
+import { EnyoBatteryFeature } from "@enyo-energy/energy-app-sdk/dist/types/enyo-battery-appliance.js";
 /**
  * A single phase in the tiered retry schedule
  */
@@ -616,6 +617,39 @@ export declare enum SunspecBatteryCapability {
     DischargeLimit = "discharge-limit",
     ChargeLimit = "charge-limit"
 }
+/**
+ * Selects how `SunspecBattery` populates `appliance.battery.features`.
+ *
+ * - `Disabled`: ignore the SunSpec registers and ignore calibration. The SDK
+ *   publishes whatever the consumer puts in `allowedFeatures` (omit or pass
+ *   `[]` to advertise nothing). Useful when the host already knows what the
+ *   battery can do and doesn't want the SDK to make any inference.
+ * - `RegisterBased`: publish whatever the device's registers expose. If
+ *   `allowedFeatures` is set, the published list is the intersection — the
+ *   register-detected set filtered to the allow-list. Lets the consumer hide
+ *   features that the hardware exposes but they don't want to use.
+ * - `CalibrationBased`: same as `RegisterBased`, but controllable features
+ *   (grid charging, grid discharging, charge limitation, discharge
+ *   limitation) stay hidden until `CalibrationResultStore.isCalibrated(...)`
+ *   returns true for this appliance. Requires `configureCalibration(...)` to
+ *   actually run a calibration; without it the controllable features remain
+ *   hidden forever (safe-fallback behaviour).
+ */
+export declare enum SunspecBatteryFeatureModeKind {
+    Disabled = "disabled",
+    RegisterBased = "register-based",
+    CalibrationBased = "calibration-based"
+}
+export type SunspecBatteryFeatureMode = {
+    kind: SunspecBatteryFeatureModeKind.Disabled;
+    allowedFeatures?: EnyoBatteryFeature[];
+} | {
+    kind: SunspecBatteryFeatureModeKind.RegisterBased;
+    allowedFeatures?: EnyoBatteryFeature[];
+} | {
+    kind: SunspecBatteryFeatureModeKind.CalibrationBased;
+    allowedFeatures?: EnyoBatteryFeature[];
+};
 export declare enum SunspecMeterCapability {
 }
 export interface SunspecBatteryControls {
@@ -626,3 +660,35 @@ export interface SunspecBatteryControls {
     outWRte?: number;
     minRsvPct?: number;
 }
+/**
+ * The four `EnyoBatteryFeature` values that imply outbound control writes from
+ * the host action-taker. `SunspecBattery` calibration probes each one
+ * individually so `appliance.battery.features` reflects only what the device
+ * actually honours.
+ *
+ * Exposed as `as const` (not a plain `EnyoBatteryFeature[]`) so consumers can
+ * iterate the tuple with full type narrowing — see the `WRITABLE_BATTERY_FIELDS`
+ * pattern in `sunspec-battery-calibration-driver.ts`.
+ */
+export declare const SUNSPEC_CONTROLLABLE_FEATURES: readonly [EnyoBatteryFeature.GridCharging, EnyoBatteryFeature.GridDischarging, EnyoBatteryFeature.ChargeLimitation, EnyoBatteryFeature.DischargeLimitation];
+export type SunspecControllableFeature = typeof SUNSPEC_CONTROLLABLE_FEATURES[number];
+/**
+ * Outcome of a single per-feature calibration probe.
+ *
+ * - `passed`: the SDK observed the expected register/meter response.
+ * - `failed`: the SDK wrote the registers but the response was absent or wrong.
+ * - `not-supported`: a precondition stopped the probe (battery SoC out of
+ *   range, missing telemetry, register not exposed). Distinct from `failed`
+ *   so the host can distinguish "device won't" from "we couldn't even try".
+ */
+export type SunspecFeatureVerdict = 'passed' | 'failed' | 'not-supported';
+/**
+ * Per-feature outcomes captured during one calibration session. Serialised
+ * into `CalibrationResult.notes` as JSON; decoded with runtime guards by
+ * `decodeFeatureResults` (no `as` casts at the use site).
+ */
+export interface SunspecCalibrationFeatureResults {
+    featureResults: Partial<Record<SunspecControllableFeature, SunspecFeatureVerdict>>;
+    /** Free-form per-probe diagnostics (SoC at start, observed deltas, timeouts). */
+    diagnostics?: Partial<Record<SunspecControllableFeature, string>>;
+}

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

package/dist/index.d.ts

@@ -3,3 +3,9 @@ export * from './sunspec-devices.js';
 export * from './sunspec-modbus-client.js';
 export { ConnectionRetryManager } from './connection-retry-manager.js';
 export { SDK_VERSION, getSdkVersion } from './version.js';
+export { SunspecCalibrationStorage, createSunspecCalibrationStorage } from './sunspec-calibration-storage.js';
+export { SunspecBatteryCalibrationDriver } from './sunspec-battery-calibration-driver.js';
+export { SunspecBatteryFeatureCalibrator, type SunspecBatteryFeatureCalibratorOptions, decodeFeatureResults, } from './sunspec-battery-feature-calibrator.js';
+export { SunspecBatteryScheduleHandler, type SunspecScheduleRegisters, type SunspecBatteryScheduleHandlerOptions, } from './sunspec-battery-schedule-handler.js';
+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/index.js

@@ -3,3 +3,15 @@ export * from './sunspec-devices.js';
 export * from './sunspec-modbus-client.js';
 export { ConnectionRetryManager } from './connection-retry-manager.js';
 export { SDK_VERSION, getSdkVersion } from './version.js';
+// New calibration integration with @enyo-energy/appliance-calibration
+export { SunspecCalibrationStorage, createSunspecCalibrationStorage } from './sunspec-calibration-storage.js';
+export { SunspecBatteryCalibrationDriver } from './sunspec-battery-calibration-driver.js';
+export { SunspecBatteryFeatureCalibrator, decodeFeatureResults, } from './sunspec-battery-feature-calibrator.js';
+export { SunspecBatteryScheduleHandler, } from './sunspec-battery-schedule-handler.js';
+// Re-export the schedule message types from energy-app-sdk so consumers can
+// build/inspect SetStorageScheduleV1 messages without a second import.
+export { EnyoStorageScheduleModeEnum, EnyoStorageScheduleDirectionEnum, } from '@enyo-energy/energy-app-sdk/dist/types/enyo-data-bus-value.js';
+// 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.
+export { AbstractCalibrationStorage, InMemoryCalibrationStorage, SnapshotService, DEFAULT_AUTO_STOP_MS, AbstractBatteryCalibrationDriver, BatteryCalibrator, DEFAULT_BATTERY_CALIBRATOR_CONFIG, CalibrationResultStore, CalibrationTrigger, } from '@enyo-energy/appliance-calibration';

package/dist/sunspec-battery-calibration-driver.d.ts

@@ -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.js";
+import { type SunspecBatteryControls } from "./sunspec-interfaces.js";
+/**
+ * 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;
+}

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

@@ -0,0 +1,154 @@
+import { AbstractBatteryCalibrationDriver, LatestValueCache, } from "@enyo-energy/appliance-calibration";
+import { EnyoDataBusMessageEnum, } from "@enyo-energy/energy-app-sdk/dist/types/enyo-data-bus-value.js";
+import { SunspecStorageMode } from "./sunspec-interfaces.js";
+/**
+ * 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.
+ */
+export class SunspecBatteryCalibrationDriver extends AbstractBatteryCalibrationDriver {
+    sunspecClient;
+    unitId;
+    dataBus;
+    batteryPowerCache = new LatestValueCache();
+    gridPowerCache = new LatestValueCache();
+    meterListenerId;
+    constructor(sunspecClient, unitId, dataBus) {
+        super();
+        this.sunspecClient = sunspecClient;
+        this.unitId = unitId;
+        this.dataBus = dataBus;
+        this.subscribeMeterUpdates();
+    }
+    subscribeMeterUpdates() {
+        this.meterListenerId = this.dataBus.listenForMessages([EnyoDataBusMessageEnum.MeterValuesUpdateV1], (entry) => {
+            if (entry.message !== 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, 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, 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();
+    }
+}