@enyo-energy/sunspec-sdk 0.0.70 → 0.0.72

package/dist/sunspec-devices.d.ts

@@ -1,10 +1,11 @@
-import { type IRetryConfig, type SunspecBatteryBaseData, SunspecBatteryCapability, type SunspecBatteryControls, type SunspecInverterData, SunspecInverterCapability, SunspecMeterCapability, SunspecStorageMode } from "./sunspec-interfaces.js";
+import { type IRetryConfig, type SunspecBatteryBaseData, SunspecBatteryCapability, type SunspecBatteryControls, type SunspecBatteryFeatureMode, type SunspecInverterData, SunspecInverterCapability, SunspecMeterCapability, SunspecStorageMode } from "./sunspec-interfaces.js";
 import { ApplianceManager, EnergyApp } from "@enyo-energy/energy-app-sdk";
 import { type EnyoAppliance, type EnyoApplianceErrorCode, EnyoApplianceName } from "@enyo-energy/energy-app-sdk/dist/types/enyo-appliance.js";
 import { EnyoNetworkDevice } from "@enyo-energy/energy-app-sdk/dist/types/enyo-network-device.js";
 import { SunspecModbusClient } from "./sunspec-modbus-client.js";
 import { ConnectionRetryManager } from "./connection-retry-manager.js";
 import { EnyoCommandAcknowledgeAnswerEnum, EnyoDataBusMessage, EnyoDataBusMessageEnum, EnyoDataBusMessageResolution } from "@enyo-energy/energy-app-sdk/dist/types/enyo-data-bus-value.js";
+import { BatteryCalibrator, type BatteryCalibratorConfig, type CalibrationResultStore, type CalibrationSnapshot, type RestoreReason, SnapshotService } from "@enyo-energy/appliance-calibration";
 import { 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
      */