@enyo-energy/sunspec-sdk 0.0.71 → 0.0.72

package/README.md

@@ -5,6 +5,9 @@ SunSpec Modbus client for reading data from solar inverters, batteries, meters,
 ## Table of Contents
 
 - [Appliance Manager Integration](#appliance-manager-integration)
+- [Battery Feature Modes](#battery-feature-modes)
+- [Battery Calibration](#battery-calibration)
+- [Storage Schedule Control](#storage-schedule-control)
 - [How Addressing Works](#how-addressing-works)
 - [Bulk Register Reading](#bulk-register-reading)
 - [Data Types](#data-types)
@@ -46,6 +49,305 @@ This SDK does not configure the strategy itself — it is the consumer app's res
 
 ---
 
+## Battery Feature Modes
+
+`SunspecBattery` populates `appliance.battery.features` for every connected battery — the list the host's topology / UI reads to decide which control surfaces to render. **The consumer chooses how that list is computed** by passing a required `featureMode` argument to the `SunspecBattery` constructor. There is no default; the choice is explicit so a SunSpec device whose register surface lies (or whose responsiveness is unknown) cannot silently turn into an actionable battery from the host's point of view.
+
+Three kinds are available, exposed via the `SunspecBatteryFeatureModeKind` enum:
+
+| Kind | Calibration allowed? | What appears in `appliance.battery.features` |
+|---|---|---|
+| `Disabled` | No (`configureCalibration` throws) | Exactly the `allowedFeatures` array the consumer passes — register state is ignored. |
+| `RegisterBased` | No (`configureCalibration` throws) | Features the SunSpec registers expose. Filtered down to `allowedFeatures` if that's set. |
+| `CalibrationBased` | Yes (required for controllable features to ever appear) | Same as `RegisterBased` for read-only features. The four controllable features stay hidden until the calibration result store reports the appliance as `calibrated`. |
+
+The four features the SDK treats as **controllable** (the ones calibration gates):
+
+- `EnyoBatteryFeature.GridCharging`
+- `EnyoBatteryFeature.GridDischarging`
+- `EnyoBatteryFeature.ChargeLimitation`
+- `EnyoBatteryFeature.DischargeLimitation`
+
+Every other `EnyoBatteryFeature` is **read-only** from the SDK's perspective and is published as soon as the corresponding register is present (in `RegisterBased` and `CalibrationBased`) or as soon as the consumer lists it (in `Disabled`).
+
+### `Disabled`
+
+Picks no registers, runs no calibration. Whatever the consumer lists in `allowedFeatures` becomes the published list; omit it (or pass `[]`) to publish nothing.
+
+Use when the host has out-of-band knowledge of the battery's capabilities — e.g. a curated commissioning database — and doesn't want the SDK inferring anything from registers it may not trust. Also useful for read-only deployments: omit `allowedFeatures` and the host will treat the battery as observation-only.
+
+```ts
+import { SunspecBattery, SunspecBatteryFeatureModeKind } from '@enyo-energy/sunspec-sdk';
+import { EnyoBatteryFeature } from '@enyo-energy/energy-app-sdk';
+
+const observationOnly = new SunspecBattery(
+    app, name, networkDevice, client, applianceManager,
+    { kind: SunspecBatteryFeatureModeKind.Disabled },
+    // → appliance.battery.features = []
+);
+
+const curated = new SunspecBattery(
+    app, name, networkDevice, client, applianceManager,
+    {
+        kind: SunspecBatteryFeatureModeKind.Disabled,
+        allowedFeatures: [EnyoBatteryFeature.GridCharging],
+    },
+    // → appliance.battery.features = ['grid-charging'], regardless of what the registers say
+);
+```
+
+Calling `configureCalibration(...)` on a `Disabled` battery throws.
+
+### `RegisterBased`
+
+The SDK looks at the SunSpec Model 124 registers and publishes the features whose underlying registers are present:
+
+- `chaGriSet` register present → `EnyoBatteryFeature.GridCharging`
+- `wChaMax` register present → `EnyoBatteryFeature.ChargeLimitation`
+
+Pass `allowedFeatures` to intersect the detected set with a whitelist — useful for hiding features the device exposes but the host doesn't want exercised. The allow-list **never** adds features that the registers don't expose; it is strictly a filter.
+
+```ts
+const trustRegisters = new SunspecBattery(
+    app, name, networkDevice, client, applianceManager,
+    { kind: SunspecBatteryFeatureModeKind.RegisterBased },
+    // → appliance.battery.features reflects whichever Model 124 controls are exposed
+);
+
+const trustRegistersButHideGridCharging = new SunspecBattery(
+    app, name, networkDevice, client, applianceManager,
+    {
+        kind: SunspecBatteryFeatureModeKind.RegisterBased,
+        allowedFeatures: [EnyoBatteryFeature.ChargeLimitation],
+    },
+    // → publishes ChargeLimitation only (even if chaGriSet is present)
+);
+```
+
+Calling `configureCalibration(...)` on a `RegisterBased` battery throws.
+
+### `CalibrationBased`
+
+Same register-driven detection as `RegisterBased` for read-only features, but the four controllable features stay stripped from the published list until `CalibrationResultStore.isCalibrated(applianceId)` returns `true` for this battery. Once the verdict flips, the next `readData()` cycle republishes the full set.
+
+`configureCalibration(...)` must be called after `connect()` — without it, controllable features stay hidden forever (safe-fallback behaviour).
+
+```ts
+const verified = new SunspecBattery(
+    app, name, networkDevice, client, applianceManager,
+    { kind: SunspecBatteryFeatureModeKind.CalibrationBased },
+);
+await verified.connect();
+verified.configureCalibration({ resultStore });   // see "Battery Calibration" below
+trigger.register(verified.getBatteryCalibrator()!);
+// Until trigger.tick() runs a successful test charge, controllable features are absent.
+// After it succeeds, they reappear within one readData() cycle.
+```
+
+See [Battery Calibration](#battery-calibration) for the full wiring of `resultStore`, `trigger`, and `configureCalibration` config.
+
+### Choosing a mode
+
+| Situation | Pick |
+|---|---|
+| Battery is observation-only, or the host already knows its capabilities | `Disabled` |
+| Trust the SunSpec register surface; no responsiveness verification needed | `RegisterBased` |
+| Want a test charge to confirm the battery actually reacts before exposing controls | `CalibrationBased` |
+
+The mode is fixed for the lifetime of the `SunspecBattery` instance. To switch modes, construct a new instance.
+
+---
+
+## Battery Calibration
+
+The SDK integrates [`@enyo-energy/appliance-calibration`](https://www.npmjs.com/package/@enyo-energy/appliance-calibration) to verify that a battery actually responds to control commands before the host action-taker is allowed to send it any. The verification is a short test charge wrapped in a snapshot/restore so a hung or crashed run never leaves writable registers in a half-modified state, and the verdict (`calibrated` / `not-supported` / `failed`) is persisted per appliance so it survives restarts.
+
+The SDK owns the SunSpec-specific pieces — the snapshot service, the vendor driver, the per-battery `BatteryCalibrator`. The **consumer owns the trigger and the result store**, so scheduling, multi-tenant storage namespacing, and command gating stay configurable.
+
+### Architecture
+
+| Piece | Lives in | Who builds it |
+|---|---|---|
+| `SunspecCalibrationStorage` (adapter over `EnergyAppStorage`) | this SDK | consumer (factory: `createSunspecCalibrationStorage(app)`) |
+| `CalibrationResultStore` (persisted verdict map) | `appliance-calibration` | consumer — **one shared instance** across batteries |
+| `SnapshotService<SunspecBatteryControls>` | `appliance-calibration` | SDK (per-battery, inside `SunspecBattery`) |
+| `SunspecBatteryCalibrationDriver` | this SDK | SDK (per-battery, inside `SunspecBattery`) |
+| `BatteryCalibrator<SunspecBatteryControls>` | `appliance-calibration` | SDK — built by `configureCalibration`, exposed via `getBatteryCalibrator` |
+| `CalibrationTrigger` | `appliance-calibration` | consumer — drives `runCalibration()` on its own schedule |
+
+### Feature mode
+
+Calibration is only relevant when `SunspecBattery` is constructed with `SunspecBatteryFeatureModeKind.CalibrationBased` — that's the mode under which the SDK gates controllable features on the calibration verdict. See [Battery Feature Modes](#battery-feature-modes) above for the full mode discussion; the rest of this section assumes the calibration-based mode has been selected.
+
+### Consumer wiring
+
+```ts
+import {
+    SunspecBattery,
+    SunspecBatteryFeatureModeKind,
+    // re-exported from @enyo-energy/appliance-calibration so you don't need a second import:
+    CalibrationResultStore,
+    CalibrationTrigger,
+    createSunspecCalibrationStorage,
+} from '@enyo-energy/sunspec-sdk';
+
+// 1. One storage adapter + one result store for the whole app — sharing the result store
+//    across batteries keeps the persisted verdict map from being clobbered by per-instance writes.
+const storage     = createSunspecCalibrationStorage(app);
+const resultStore = new CalibrationResultStore(storage);
+await resultStore.initialize();
+
+// 2. One trigger that fans out across every registered calibrator.
+const trigger = new CalibrationTrigger({ resultStore });
+
+// 3. Per battery: build it with the desired feature mode, then connect,
+//    then (only in calibration-based mode) configureCalibration + register.
+for (const config of batteryConfigs) {
+    const battery = new SunspecBattery(
+        app, name, networkDevice, client, applianceManager,
+        { kind: SunspecBatteryFeatureModeKind.CalibrationBased },
+        // unitId, port, baseAddress, ...
+    );
+    await battery.connect();
+    battery.configureCalibration({
+        resultStore,
+        // Optional — override any BatteryCalibratorConfig defaults (see "Tuning" below).
+        config: { testPowerW: 300 },
+    });
+    const calibrator = battery.getBatteryCalibrator();
+    if (calibrator) {
+        trigger.register(calibrator);
+    }
+}
+
+// 4. Drive the trigger on your own cadence. tick() runs at most one calibration per call
+//    and is a no-op for any battery that already has a stored result.
+client.useInterval().createInterval('30m', () => trigger.tick());
+```
+
+### Gate commands on the calibration result
+
+In whatever code emits battery commands, check the store synchronously before sending:
+
+```ts
+if (!resultStore.isCalibrated(applianceId)) {
+    console.log(`Skipping ${applianceId}: not calibrated yet`);
+    return;
+}
+// ...send the command
+```
+
+### Per-feature probes
+
+In `calibration-based` mode the SDK runs `SunspecBatteryFeatureCalibrator` (a subclass of the library's `BatteryCalibrator`) which **exercises each of the four controllable features individually** and records the outcomes in `CalibrationResult.notes` as JSON. Only features whose probes pass land in `appliance.battery.features` after calibration.
+
+The session is one snapshot → four probes → one restore. Probes run in this order so the battery has energy to discharge with by the end:
+
+| # | Probe | What it writes | Pass condition |
+|---|---|---|---|
+| 1 | `GridCharging` | `chaGriSet=GRID`, `wChaMax=testPowerW`, `inWRte=100`, `storCtlMod=CHARGE` | Battery power AND grid power both rise above `responseThresholdW` |
+| 2 | `ChargeLimitation` | same as above with `inWRte=50` | Charge power settles within `±responseThresholdW` of `testPowerW × 0.5` |
+| 3 | `DischargeLimitation` | `chaGriSet=PV`, `outWRte=50`, `storCtlMod=DISCHARGE` | Discharge power settles within `±responseThresholdW` of `testPowerW × 0.5` |
+| 4 | `GridDischarging` | `chaGriSet=PV`, `outWRte=100`, `storCtlMod=DISCHARGE` | Battery discharges AND meter shows reverse flow above `responseThresholdW` |
+
+Each probe runs a `writeBatteryControls(...)` then polls the driver's cached battery/grid power until either the predicate passes or `responseTimeoutMs` elapses. Between probes the SDK resets to a neutral state (`storCtlMod=AUTO`, `chaGriSet=PV`, `inWRte/outWRte=100`, `wChaMax=baseline`) so each probe starts cleanly. The final `restoreFromSnapshot` (run by the `SnapshotService` on `stopCalibration`) writes the original pre-calibration register set back regardless of outcome.
+
+#### SoC preconditions
+
+Probes refuse to run outside a useful SoC band and return `not-supported` instead — distinct from `failed` so the host can tell "device won't" apart from "we couldn't even try":
+
+- Charge probes (`GridCharging`, `ChargeLimitation`) need headroom: SoC ≥ 90% → `not-supported`.
+- Discharge probes (`DischargeLimitation`, `GridDischarging`) need energy: SoC ≤ 20% → `not-supported`.
+
+#### Aggregate verdict
+
+The library's `CalibrationResult.state` (one value per appliance) is computed from the four per-feature verdicts:
+
+| Per-feature verdicts | `CalibrationResult.state` |
+|---|---|
+| At least one `passed` | `calibrated` |
+| All `not-supported` | `not-supported` |
+| Otherwise (mix of `failed` / `not-supported`) | `failed` |
+
+`isCalibrated(applianceId)` therefore reads as **"the SDK probed this device and at least something is controllable"** — keep using it as the broad command-emission gate. The per-feature breakdown stored in `notes` is what `resolveAdvertisedFeatures` consults to decide *which* controllable features to publish; `decodeFeatureResults(result.notes)` returns the passing set and is exported for consumers that want to inspect it directly.
+
+#### Other operational notes
+
+- **Republishing cadence**: the controllable features reappear on the next `readData()` cycle after the calibrator persists its result — not synchronously when calibration completes. With a typical 10s/30s/1m poll cadence the appliance metadata follows within one cycle.
+- **Defence in depth**: the feature filter is complementary to the [`isCalibrated` command-gate](#gate-commands-on-the-calibration-result), not a substitute. The consumer's action-taker should still check `resultStore.isCalibrated(applianceId)` synchronously before every command write — the filter keeps the controllable surface off the appliance until the device is verified, but a race window exists between calibration completing and the next readData cycle.
+- **GridDischarge ambiguity**: SunSpec Model 124 has no register to *force* battery output toward the grid versus toward local load. The probe drives the battery into discharge and then watches the meter for export. If the host's local load eats the discharge there will be no export and the probe records `failed` with a note explaining the likely cause. Hosts that know their grid topology can map this to "controllable, but couldn't be verified".
+
+### What `configureCalibration` does under the hood
+
+For each battery it builds:
+
+- A `SunspecBatteryCalibrationDriver` that:
+  - Snapshots writable controls via `readBatteryControls()`.
+  - Restores them via `writeBatteryControls()` (whitelist: `storCtlMod`, `chaGriSet`, `wChaMax`, `inWRte`, `outWRte`, `minRsvPct`).
+  - Runs the test charge with the same 3-step sequence as `handleStartGridCharge` (`enableGridCharging(true)`, `wChaMax = powerW`, `setStorageMode(CHARGE)`).
+  - Reads battery power from a `LatestValueCache` fed by `SunspecBattery.readData()` each cycle.
+  - Reads grid power from a `LatestValueCache` fed by a `MeterValuesUpdateV1` data-bus subscription that's live for the driver's lifetime (so the grid signal works regardless of where the meter actually comes from).
+- A `BatteryCalibrator<SunspecBatteryControls>` wired to the driver, the per-battery `SnapshotService`, and the shared `resultStore`.
+
+Battery `disconnect()` tears the driver subscription down.
+
+### What still happens through the data bus
+
+The SDK also keeps listening for `StartCalibrationV1` / `StopCalibrationV1` data-bus messages so an external orchestrator (e.g. the action-taker) can begin and end a manual calibration session. Those handlers now drive the same `SnapshotService<T>` instance from `@enyo-energy/appliance-calibration`. While a manual session is active, any concurrent `SetInverterFeedInLimitV1` / `SetStorageChargeLimitV1` / etc. call records the field it touched into `modifiedFields`, and only those fields are written back on stop (or on the 5-minute auto-stop). This works exactly as before — the change is purely the implementation underneath.
+
+### Re-running a calibration
+
+The trigger runs each battery **once** — appliances already marked `calibrated`, `not-supported`, or `failed` are skipped on every subsequent `tick()`. To force a re-run, drop the persisted result for that key:
+
+```ts
+await app.useStorage().remove('battery-calibration');   // wipes ALL results (the default key)
+```
+
+If you need targeted invalidation, snapshot the store via `resultStore.snapshot()`, mutate the map, and re-save the survivors. Periodic re-calibration is a host concern — build it on top of `calibrator.runCalibration()` directly rather than going through `CalibrationTrigger`.
+
+### Tuning
+
+Override defaults via `configureCalibration({ resultStore, config })`:
+
+| Key | Default | When to change |
+|---|---|---|
+| `testPowerW` | 500 W | Smaller batteries; PV-only sites where 500 W is visible. |
+| `responseThresholdW` | 200 W | Noisier meters; tighter tolerance for known-good devices. |
+| `ackTimeoutMs` | 10 s | Slow Modbus links. |
+| `responseTimeoutMs` | 20 s | Devices that take longer to ramp. |
+| `pollIntervalMs` | 2 s | Faster polling for short-window tests. |
+
+See [`@enyo-energy/appliance-calibration`'s README](https://www.npmjs.com/package/@enyo-energy/appliance-calibration) for the full crash-safety contract and every result-store / snapshot-service knob.
+
+---
+
+## Storage Schedule Control
+
+`SunspecBattery` reacts to a single data-bus command for control: `EnyoDataBusSetStorageScheduleV1`. The message carries a `mode` (`auto` or `schedule`) and, when `mode` is `schedule`, a sorted `relativeSchedule` of `{seconds, direction, powerW}` entries. Subscription is automatic — each battery wires its own `SunspecBatteryScheduleHandler` (extending the SDK's `StorageScheduleHandler` from `@enyo-energy/energy-app-sdk`) during `connect()`. There is no consumer setup beyond connecting the battery.
+
+### What the SDK does on receipt
+
+1. Acks the message with `Accepted` immediately ("received & queued" — schedule entries play out over time).
+2. Snapshots the writable Model 124 registers (`storCtlMod`, `chaGriSet`, `wChaMax`, `inWRte`, `outWRte`) and persists them to `EnergyAppStorage` for restart-safe rollback.
+3. Activates the first entry immediately, then advances to subsequent entries as their `seconds` offsets elapse on a 1-second tick (driven by `EnergyApp.useInterval()`).
+4. Each `Charge` entry writes `chaGriSet=GRID`, `inWRte = powerW / installedWChaMax × 100`, `storCtlMod=CHARGE`.
+5. Each `Discharge` entry writes `chaGriSet=PV`, `outWRte = powerW / installedWChaMax × 100`, `storCtlMod=DISCHARGE`.
+6. On `mode: auto`, a replacement schedule, `disconnect()`, or process restart with an active schedule still persisted, the SDK restores the snapshotted pre-schedule registers via `onRollback`.
+
+### Power cap
+
+Scheduled `powerW` is clamped to the device's installed `wChaMax` because the handler holds that value stable as the denominator for the percentage math throughout the schedule. To request more than the installed maximum, raise `wChaMax` out-of-band before sending the schedule.
+
+### Calibration coexistence
+
+Each per-entry write is recorded into the calibration `SnapshotService` (when calibration is configured), so a calibration that starts mid-schedule still restores the right register set on stop / auto-stop.
+
+### Legacy messages
+
+The earlier `StartStorageGridChargeV1` / `StopStorageGridChargeV1` / `SetStorageChargeLimitV1` / `SetStorageDischargeLimitV1` family is **no longer handled** by this SDK. Their type defs in `@enyo-energy/energy-app-sdk` are flagged `@deprecated` with pointers to `SetStorageScheduleV1`. Migrate any callers that still emit them.
+
+---
+
 ## How Addressing Works
 
 ### Base Address Detection

package/dist/cjs/index.cjs

@@ -14,13 +14,41 @@ 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);
-__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");
 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

@@ -1,6 +1,11 @@
 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';
+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;
+}