@enyo-energy/sunspec-sdk 0.0.71 → 0.0.73

package/dist/sunspec-devices.d.ts

@@ -1,11 +1,12 @@
-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 SunspecBatteryData, 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 { type CalibrationDeviceType, type CalibrationRestoreReason, type CalibrationSnapshot, CalibrationSnapshotService } from "./calibration-snapshot-service.js";
+import { BatteryCalibrator, type BatteryCalibratorConfig, type CalibrationResult, type CalibrationResultStore, type CalibrationSnapshot, type RestoreReason, SnapshotService } from "@enyo-energy/appliance-calibration";
+import { EnyoBatteryFeature } from "@enyo-energy/energy-app-sdk/dist/types/enyo-battery-appliance.js";
 import { EnergyAppDataBus } from "@enyo-energy/energy-app-sdk/dist/packages/energy-app-data-bus.js";
 /**
  * Base abstract class for all Sunspec devices
@@ -26,7 +27,13 @@ export declare abstract class BaseSunspecDevice {
     protected dataBus?: EnergyAppDataBus;
     protected retryManager: ConnectionRetryManager;
     protected consecutiveReconnectFailures: number;
-    protected calibrationService?: CalibrationSnapshotService;
+    /**
+     * 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
@@ -80,16 +87,11 @@ export declare abstract class BaseSunspecDevice {
     protected markOffline(): Promise<void>;
     protected sendCommandAcknowledge(messageId: string, acknowledgeMessage: EnyoDataBusMessageEnum | string, answer: EnyoCommandAcknowledgeAnswerEnum, rejectionReason?: string): void;
     /**
-     * Lazily construct and initialize the per-appliance CalibrationSnapshotService. Reloads
-     * any persisted snapshot from storage so an in-flight calibration survives restarts.
-     * Idempotent — subsequent calls are no-ops once the service exists.
-     */
-    protected initCalibrationService(deviceType: CalibrationDeviceType): Promise<void>;
-    /**
-     * Subclasses implement how to write the modified fields of a snapshot back to the device.
-     * Called both on explicit StopCalibrationV1 and when the 5-minute auto-stop fires.
+     * 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 restoreFromCalibrationSnapshot(_snapshot: CalibrationSnapshot, _reason: CalibrationRestoreReason): Promise<void>;
+    protected buildSnapshotService<T>(onRestore: (snapshot: CalibrationSnapshot<T>, reason: RestoreReason) => Promise<void>): SnapshotService<T> | undefined;
 }
 /**
  * Sunspec Inverter implementation using dynamic model discovery
@@ -100,6 +102,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>;
@@ -169,16 +172,106 @@ 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;
-    protected restoreFromCalibrationSnapshot(snapshot: CalibrationSnapshot, reason: CalibrationRestoreReason): Promise<void>;
+    /**
+     * `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;
 }
+/**
+ * Pure register-presence detection — exported so it can be unit-tested
+ * without the full `SunspecBattery` scaffold. Maps each Model 124 writable
+ * register to the `EnyoBatteryFeature` it represents:
+ *
+ * - `chaGriSet`  → `GridCharging` (charge source PV/GRID)
+ * - `wChaMax`    → `ChargeLimitation` (max charge power)
+ * - `outWRte`    → `DischargeLimitation` (discharge rate %)
+ * - `storCtlMod` → `GridDischarging` (closest signal that external discharge
+ *                  control is available; the inverter decides where it goes)
+ */
+export declare function detectFeaturesFromRegisters(batteryData: SunspecBatteryData | null): EnyoBatteryFeature[];
+/**
+ * Apply the per-feature calibration filter to a register-detected set.
+ * Exported for unit-test access to the legacy-result fallback branch.
+ *
+ * The contract:
+ * - No `result` or `result.state !== 'calibrated'` → strip every controllable
+ *   feature (safe fallback while waiting for calibration).
+ * - `result.state === 'calibrated'` with a decodable per-feature payload →
+ *   publish only the controllable features whose probes passed.
+ * - `result.state === 'calibrated'` with **no** decodable payload → legacy
+ *   data (pre-feature-calibrator SDK). The new calibrator only marks
+ *   `state=calibrated` when at least one probe passes, so an empty decoded
+ *   set with `state=calibrated` unambiguously signals legacy results. Publish
+ *   the full detected set to preserve the old all-or-nothing semantics on
+ *   upgrade.
+ */
+export declare function filterFeaturesByCalibrationResult(detected: EnyoBatteryFeature[], result: CalibrationResult | undefined, controllable: readonly EnyoBatteryFeature[]): EnyoBatteryFeature[];
 /**
  * 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
      */
@@ -300,13 +393,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;
-    protected restoreFromCalibrationSnapshot(snapshot: CalibrationSnapshot, reason: CalibrationRestoreReason): Promise<void>;
+    /**
+     * `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