@enyo-energy/sunspec-sdk 0.0.31 → 0.0.33

package/dist/cjs/sunspec-modbus-client.d.cts

@@ -16,9 +16,8 @@
  * - pad: 0x8000 (always returns this value)
  * - string: all registers 0x0000 (NULL)
  */
-import { type SunspecInverterControls, type SunspecInverterData, type SunspecInverterSettings, type SunspecMeterData, type SunspecModel, type SunspecMPPTData, type SunspecBatteryData, type SunspecBatteryControls, SunspecStorageMode, type IRetryConfig } from "./sunspec-interfaces.cjs";
-import { ConnectionRetryManager } from "./connection-retry-manager.cjs";
-import { IConnectionHealth } from "@enyo-energy/energy-app-sdk/dist/implementations/modbus/interfaces.js";
+import { type SunspecInverterControls, type SunspecInverterData, type SunspecInverterSettings, type SunspecMeterData, type SunspecModel, type SunspecMPPTData, type SunspecBatteryData, type SunspecBatteryBaseData, type SunspecBatteryControls, SunspecStorageMode } from "./sunspec-interfaces.cjs";
+import { EnergyAppModbusDataType, IConnectionHealth } from "@enyo-energy/energy-app-sdk/dist/implementations/modbus/interfaces.js";
 import { EnergyApp } from "@enyo-energy/energy-app-sdk";
 export declare class SunspecModbusClient {
     private energyApp;
@@ -29,9 +28,8 @@ export declare class SunspecModbusClient {
     private faultTolerantReader;
     private modbusDataTypeConverter;
     private connectionParams;
-    private retryManager;
     private autoReconnectEnabled;
-    constructor(energyApp: EnergyApp, retryConfig?: Partial<IRetryConfig>);
+    constructor(energyApp: EnergyApp);
     /**
      * Connect to Modbus device
      * @param host Primary host (hostname) to connect to
@@ -55,11 +53,6 @@ export declare class SunspecModbusClient {
      * Returns true if successful, false otherwise
      */
     private attemptConnection;
-    /**
-     * Check connection health and trigger automatic reconnection if unhealthy
-     * Returns true if connection is healthy or was successfully restored
-     */
-    ensureHealthyConnection(): Promise<boolean>;
     /**
      * Enable or disable automatic reconnection
      */
@@ -68,10 +61,6 @@ export declare class SunspecModbusClient {
      * Check if auto-reconnect is enabled
      */
     isAutoReconnectEnabled(): boolean;
-    /**
-     * Get the retry manager for advanced configuration
-     */
-    getRetryManager(): ConnectionRetryManager;
     /**
      * Detect the base address and addressing mode (0-based or 1-based) for SunSpec
      */
@@ -119,13 +108,13 @@ export declare class SunspecModbusClient {
     /**
      * Helper to read register value(s) using the fault-tolerant reader with data type conversion
      */
-    private readRegisterValue;
+    readRegisterValue(address: number, quantity: number | undefined, dataType: EnergyAppModbusDataType): Promise<number | string | number[]>;
     /**
      * Helper to write register value(s)
      */
-    private writeRegisterValue;
+    writeRegisterValue(address: number, value: number | number[], dataType?: EnergyAppModbusDataType): Promise<boolean>;
     /**
-     * Read inverter data from Model 103 (Three Phase)
+     * Read inverter data from Model 101 (Single Phase) / Model 103 (Three Phase)
      */
     readInverterData(): Promise<SunspecInverterData | null>;
     /**
@@ -140,10 +129,10 @@ export declare class SunspecModbusClient {
      * Apply scale factor to a value
      * Returns undefined if the value is unimplemented or scale factor is out of range
      */
-    private applyScaleFactor;
+    applyScaleFactor(value: number, scaleFactor: number, dataType?: 'uint16' | 'int16' | 'acc32', fieldName?: string, offset?: number, modelId?: number): number | undefined;
+    logRegisterRead(modelId: number, offset: number, fieldName: string, rawValue: number | string | undefined, dataType?: string): void;
     /**
-     * Read MPPT Scale Factors for a specific module
-     * Returns the scale factors for DC Current, DC Voltage, DC Power, and DC Energy
+     * Read scale factors from Model 160 (MPPT)
      *
      * MPPT Model 160 Scale Factor Register Offsets (relative to module start):
      * - DCA_SF (Current Scale Factor): Offset 2
@@ -164,7 +153,7 @@ export declare class SunspecModbusClient {
      */
     readMPPTData(moduleId?: number): Promise<SunspecMPPTData | null>;
     /**
-     * Read all available MPPT strings
+     * Read all MPPT strings from Model 160 (Multiple MPPT)
      */
     readAllMPPTData(): Promise<SunspecMPPTData[]>;
     /**
@@ -174,7 +163,23 @@ export declare class SunspecModbusClient {
      */
     private mapBatteryChargeState;
     /**
-     * Read battery data from Model 124 (Basic Storage Controls)
+     * Map battery type to human-readable name (Model 802)
+     */
+    private mapBatteryType;
+    /**
+     * Map battery bank state to human-readable name (Model 802)
+     */
+    private mapBatteryBankState;
+    /**
+     * Read Model 802 scale factors (offsets 52-63)
+     */
+    private readBatteryBaseScaleFactors;
+    /**
+     * Read battery base data from Model 802 (Battery Base)
+     */
+    readBatteryBaseData(): Promise<SunspecBatteryBaseData | null>;
+    /**
+     * Read battery data from Model 124 (Basic Storage) with fallback to Model 802 / Model 803
      */
     readBatteryData(): Promise<SunspecBatteryData | null>;
     /**
@@ -190,11 +195,11 @@ export declare class SunspecModbusClient {
      */
     enableGridCharging(enable: boolean): Promise<boolean>;
     /**
-     * Read current battery control settings
+     * Read battery control settings from Model 124 (Basic Storage Controls)
      */
     readBatteryControls(): Promise<SunspecBatteryControls | null>;
     /**
-     * Read meter data (Model 203 for 3-phase)
+     * Read meter data from Model 201 (Single Phase) / Model 203 (Three Phase) / Model 204 (Split Phase)
      */
     readMeterData(): Promise<SunspecMeterData | null>;
     /**
@@ -218,11 +223,11 @@ export declare class SunspecModbusClient {
      */
     getConnectionHealth(): IConnectionHealth;
     /**
-     * Read Block 121 - Inverter Basic Settings
+     * Read inverter settings from Model 121 (Inverter Settings)
      */
     readInverterSettings(): Promise<SunspecInverterSettings | null>;
     /**
-     * Read Block 123 - Immediate Inverter Controls
+     * Read inverter controls from Model 123 (Immediate Inverter Controls)
      */
     readInverterControls(): Promise<SunspecInverterControls | null>;
     /**
@@ -230,7 +235,18 @@ export declare class SunspecModbusClient {
      */
     writeInverterSettings(settings: Partial<SunspecInverterSettings>): Promise<boolean>;
     /**
-     * Write Block 123 - Immediate Inverter Controls
+     * Write inverter controls to Model 123 (Immediate Inverter Controls)
      */
     writeInverterControls(controls: Partial<SunspecInverterControls>): Promise<boolean>;
+    /**
+     * Set the inverter feed-in power limit using Model 123 (Immediate Inverter Controls)
+     *
+     * When limitW is a number, reads WMax from Model 121, computes percentage,
+     * writes WMaxLimPct and enables WMaxLim_Ena.
+     * When limitW is null, disables the limit by setting WMaxLim_Ena = DISABLED.
+     *
+     * @param limitW - Power limit in Watts, or null to remove the limit
+     * @returns true if successful, false otherwise
+     */
+    setFeedInLimit(limitW: number | null): Promise<boolean>;
 }

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

package/dist/connection-retry-manager.d.ts

@@ -1,53 +1,58 @@
 /**
- * Connection Retry Manager with Exponential Backoff
+ * Connection Retry Manager with Tiered Schedule
  *
- * Manages automatic connection retries with configurable exponential backoff.
- * Backoff sequence (with defaults): 1s → 1.5s → 2.25s → 3.375s → 5.06s → 7.59s → 11.39s → 17.09s → 25.63s → 30s (capped)
+ * Poll-based retry manager — no timers or setTimeout loops.
+ * Called on each readData() cycle; determines whether enough time has elapsed
+ * to attempt a reconnection based on the current retry phase.
+ *
+ * Default schedule:
+ * - Phase 1: every 10s for 1 minute
+ * - Phase 2: every 30s for 2 minutes
+ * - Phase 3: every 1m for 5 minutes
+ * - Phase 4: every 5m forever
  */
-import { IRetryConfig } from './sunspec-interfaces.js';
+import { IRetryConfig, IRetryPhase } from './sunspec-interfaces.js';
 export declare class ConnectionRetryManager {
     private config;
-    private currentAttempt;
-    private pendingRetryTimeout;
-    private isRetrying;
-    constructor(config?: Partial<IRetryConfig>);
+    private disconnectedSince;
+    private lastAttemptTime;
+    private attemptCount;
+    constructor(config?: IRetryConfig);
     /**
-     * Calculate the next delay using exponential backoff
-     * Formula: min(initialDelayMs * backoffFactor^attempt, maxDelayMs)
+     * Mark the connection as disconnected. Sets the timestamp if not already set.
      */
-    getNextDelay(): number;
+    markDisconnected(): void;
     /**
-     * Reset the retry state on successful connection
+     * Reset all retry state (call on successful reconnect).
      */
     reset(): void;
     /**
-     * Check if we should retry based on max attempts
-     * Returns true if we haven't exceeded maxAttempts or if maxAttempts is -1 (infinite)
+     * Determine which retry phase we're currently in based on elapsed time since disconnect.
      */
-    shouldRetry(): boolean;
+    getCurrentPhase(): IRetryPhase;
     /**
-     * Get the current attempt number (0-indexed)
+     * Check if we should attempt a reconnection now.
+     * Called on every readData() poll cycle.
      */
-    getCurrentAttempt(): number;
+    shouldAttemptNow(): boolean;
     /**
-     * Get the max attempts configuration
+     * Record that an attempt was just made.
      */
-    getMaxAttempts(): number;
+    recordAttempt(): void;
     /**
-     * Check if a retry is currently in progress
+     * Get the number of reconnection attempts made.
      */
-    isRetryInProgress(): boolean;
+    getAttemptCount(): number;
     /**
-     * Schedule a reconnection attempt with exponential backoff delay
-     * Returns a promise that resolves when the callback completes
+     * Get milliseconds elapsed since disconnect was first detected.
      */
-    scheduleRetry(callback: () => Promise<boolean>): Promise<boolean>;
+    getElapsedMs(): number;
     /**
-     * Cancel any pending retry attempt
+     * Check if the manager is currently tracking a disconnection.
      */
-    cancelPendingRetry(): void;
+    isDisconnected(): boolean;
     /**
-     * Get the current configuration
+     * Get the current configuration.
      */
     getConfig(): IRetryConfig;
 }

package/dist/connection-retry-manager.js

@@ -1,119 +1,102 @@
 /**
- * Connection Retry Manager with Exponential Backoff
+ * Connection Retry Manager with Tiered Schedule
  *
- * Manages automatic connection retries with configurable exponential backoff.
- * Backoff sequence (with defaults): 1s → 1.5s → 2.25s → 3.375s → 5.06s → 7.59s → 11.39s → 17.09s → 25.63s → 30s (capped)
+ * Poll-based retry manager — no timers or setTimeout loops.
+ * Called on each readData() cycle; determines whether enough time has elapsed
+ * to attempt a reconnection based on the current retry phase.
+ *
+ * Default schedule:
+ * - Phase 1: every 10s for 1 minute
+ * - Phase 2: every 30s for 2 minutes
+ * - Phase 3: every 1m for 5 minutes
+ * - Phase 4: every 5m forever
  */
 import { DEFAULT_RETRY_CONFIG } from './sunspec-interfaces.js';
 export class ConnectionRetryManager {
     config;
-    currentAttempt = 0;
-    pendingRetryTimeout = null;
-    isRetrying = false;
+    disconnectedSince = null;
+    lastAttemptTime = 0;
+    attemptCount = 0;
     constructor(config) {
-        this.config = { ...DEFAULT_RETRY_CONFIG, ...config };
+        this.config = config ?? DEFAULT_RETRY_CONFIG;
     }
     /**
-     * Calculate the next delay using exponential backoff
-     * Formula: min(initialDelayMs * backoffFactor^attempt, maxDelayMs)
+     * Mark the connection as disconnected. Sets the timestamp if not already set.
      */
-    getNextDelay() {
-        const delay = this.config.initialDelayMs * Math.pow(this.config.backoffFactor, this.currentAttempt);
-        return Math.min(delay, this.config.maxDelayMs);
+    markDisconnected() {
+        if (this.disconnectedSince === null) {
+            this.disconnectedSince = Date.now();
+        }
     }
     /**
-     * Reset the retry state on successful connection
+     * Reset all retry state (call on successful reconnect).
      */
     reset() {
-        this.currentAttempt = 0;
-        this.isRetrying = false;
-        this.cancelPendingRetry();
+        this.disconnectedSince = null;
+        this.lastAttemptTime = 0;
+        this.attemptCount = 0;
     }
     /**
-     * Check if we should retry based on max attempts
-     * Returns true if we haven't exceeded maxAttempts or if maxAttempts is -1 (infinite)
+     * Determine which retry phase we're currently in based on elapsed time since disconnect.
      */
-    shouldRetry() {
-        if (this.config.maxAttempts === -1) {
-            return true;
+    getCurrentPhase() {
+        const elapsed = this.getElapsedMs();
+        let cumulativeDuration = 0;
+        for (const phase of this.config.phases) {
+            if (phase.durationMs === 0) {
+                // This is the final "forever" phase
+                return phase;
+            }
+            cumulativeDuration += phase.durationMs;
+            if (elapsed < cumulativeDuration) {
+                return phase;
+            }
         }
-        return this.currentAttempt < this.config.maxAttempts;
+        // Fallback: return last phase
+        return this.config.phases[this.config.phases.length - 1];
     }
     /**
-     * Get the current attempt number (0-indexed)
+     * Check if we should attempt a reconnection now.
+     * Called on every readData() poll cycle.
      */
-    getCurrentAttempt() {
-        return this.currentAttempt;
+    shouldAttemptNow() {
+        if (this.disconnectedSince === null) {
+            return false;
+        }
+        const now = Date.now();
+        const phase = this.getCurrentPhase();
+        return (now - this.lastAttemptTime) >= phase.intervalMs;
     }
     /**
-     * Get the max attempts configuration
+     * Record that an attempt was just made.
      */
-    getMaxAttempts() {
-        return this.config.maxAttempts;
+    recordAttempt() {
+        this.lastAttemptTime = Date.now();
+        this.attemptCount++;
     }
     /**
-     * Check if a retry is currently in progress
+     * Get the number of reconnection attempts made.
      */
-    isRetryInProgress() {
-        return this.isRetrying;
+    getAttemptCount() {
+        return this.attemptCount;
     }
     /**
-     * Schedule a reconnection attempt with exponential backoff delay
-     * Returns a promise that resolves when the callback completes
+     * Get milliseconds elapsed since disconnect was first detected.
      */
-    async scheduleRetry(callback) {
-        if (!this.shouldRetry()) {
-            console.log(`Max retry attempts (${this.config.maxAttempts}) reached. Giving up.`);
-            return false;
-        }
-        if (this.isRetrying) {
-            console.log('Retry already in progress, skipping duplicate request.');
-            return false;
+    getElapsedMs() {
+        if (this.disconnectedSince === null) {
+            return 0;
         }
-        this.isRetrying = true;
-        const delay = this.getNextDelay();
-        const attemptNumber = this.currentAttempt + 1;
-        const maxAttemptsStr = this.config.maxAttempts === -1 ? '∞' : this.config.maxAttempts.toString();
-        console.log(`Scheduling reconnection attempt ${attemptNumber}/${maxAttemptsStr} in ${delay}ms`);
-        return new Promise((resolve) => {
-            this.pendingRetryTimeout = setTimeout(async () => {
-                this.pendingRetryTimeout = null;
-                this.currentAttempt++;
-                try {
-                    console.log(`Attempting reconnection (attempt ${attemptNumber}/${maxAttemptsStr})...`);
-                    const success = await callback();
-                    if (success) {
-                        console.log('Reconnection successful!');
-                        this.reset();
-                        resolve(true);
-                    }
-                    else {
-                        console.log('Reconnection attempt failed.');
-                        this.isRetrying = false;
-                        resolve(false);
-                    }
-                }
-                catch (error) {
-                    console.error(`Reconnection attempt failed with error: ${error}`);
-                    this.isRetrying = false;
-                    resolve(false);
-                }
-            }, delay);
-        });
+        return Date.now() - this.disconnectedSince;
     }
     /**
-     * Cancel any pending retry attempt
+     * Check if the manager is currently tracking a disconnection.
      */
-    cancelPendingRetry() {
-        if (this.pendingRetryTimeout) {
-            clearTimeout(this.pendingRetryTimeout);
-            this.pendingRetryTimeout = null;
-            this.isRetrying = false;
-            console.log('Pending retry cancelled.');
-        }
+    isDisconnected() {
+        return this.disconnectedSince !== null;
     }
     /**
-     * Get the current configuration
+     * Get the current configuration.
      */
     getConfig() {
         return { ...this.config };

package/dist/sunspec-devices.d.ts

@@ -1,9 +1,22 @@
-import { type SunspecBatteryControls, SunspecStorageMode } from "./sunspec-interfaces.js";
+import { type SunspecBatteryBaseData, type SunspecBatteryControls, SunspecStorageMode, SunspecInverterCapability, SunspecBatteryCapability, SunspecMeterCapability } from "./sunspec-interfaces.js";
 import { ApplianceManager, EnergyApp } from "@enyo-energy/energy-app-sdk";
 import { 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 { EnyoDataBusMessage, EnyoDataBusMessageResolution } from "@enyo-energy/energy-app-sdk/dist/types/enyo-data-bus-value.js";
+import { ConnectionRetryManager } from "./connection-retry-manager.js";
+import { type IRetryConfig } from "./sunspec-interfaces.js";
+import { EnyoCommandAcknowledgeAnswerEnum, EnyoDataBusMessage, EnyoDataBusMessageEnum, EnyoDataBusMessageResolution } from "@enyo-energy/energy-app-sdk/dist/types/enyo-data-bus-value.js";
+import { EnergyAppDataBus } from "@enyo-energy/energy-app-sdk/dist/packages/energy-app-data-bus.js";
+export declare const ENYO_DATA_BUS_SET_INVERTER_FEED_IN_LIMIT_V1 = "SetInverterFeedInLimitV1";
+export interface EnyoDataBusSetInverterFeedInLimitV1 {
+    id: string;
+    type: 'message';
+    message: string;
+    applianceId: string;
+    data: {
+        feedInLimitW: number | null;
+    };
+}
 /**
  * Base abstract class for all Sunspec devices
  */
@@ -18,7 +31,10 @@ export declare abstract class BaseSunspecDevice {
     protected readonly baseAddress: number;
     protected applianceId?: string;
     protected lastUpdateTime: number;
-    constructor(energyApp: EnergyApp, name: EnyoApplianceName[], networkDevice: EnyoNetworkDevice, sunspecClient: SunspecModbusClient, applianceManager: ApplianceManager, unitId?: number, port?: number, baseAddress?: number);
+    protected dataBusListenerId?: string;
+    protected dataBus?: EnergyAppDataBus;
+    protected retryManager: ConnectionRetryManager;
+    constructor(energyApp: EnergyApp, name: EnyoApplianceName[], networkDevice: EnyoNetworkDevice, sunspecClient: SunspecModbusClient, applianceManager: ApplianceManager, unitId?: number, port?: number, baseAddress?: number, retryConfig?: IRetryConfig);
     /**
      * Connect to the device and create/update the appliance
      */
@@ -42,11 +58,24 @@ export declare abstract class BaseSunspecDevice {
      * Ensure the Sunspec client is connected and models are discovered
      */
     protected ensureConnected(): Promise<void>;
+    /**
+     * Attempt a reconnection if the tiered retry schedule allows it.
+     * Called from readData() when the device is disconnected.
+     * Returns true if reconnection succeeded.
+     */
+    protected tryReconnect(): Promise<boolean>;
+    /**
+     * Mark the device as offline: update appliance state and start tracking disconnection.
+     */
+    protected markOffline(): Promise<void>;
+    protected sendCommandAcknowledge(messageId: string, acknowledgeMessage: EnyoDataBusMessageEnum | string, answer: EnyoCommandAcknowledgeAnswerEnum, rejectionReason?: string): void;
 }
 /**
  * Sunspec Inverter implementation using dynamic model discovery
  */
 export declare class SunspecInverter extends BaseSunspecDevice {
+    private readonly capabilities;
+    constructor(energyApp: EnergyApp, name: EnyoApplianceName[], networkDevice: EnyoNetworkDevice, sunspecClient: SunspecModbusClient, applianceManager: ApplianceManager, unitId?: number, port?: number, baseAddress?: number, capabilities?: SunspecInverterCapability[], retryConfig?: IRetryConfig);
     connect(): Promise<void>;
     disconnect(): Promise<void>;
     isConnected(): boolean;
@@ -59,13 +88,24 @@ export declare class SunspecInverter extends BaseSunspecDevice {
     private mapMPPTToStrings;
     private mapMPPTOperatingState;
     private mapDcStringToApplianceMetadata;
+    /**
+     * Start listening for inverter commands on the data bus.
+     * Idempotent — does nothing if already listening.
+     */
+    startDataBusListening(): void;
+    /**
+     * Stop listening for inverter commands on the data bus.
+     */
+    stopDataBusListening(): void;
+    private handleInverterCommand;
+    private handleSetFeedInLimit;
 }
 /**
  * Sunspec Battery implementation
  */
 export declare class SunspecBattery extends BaseSunspecDevice {
-    private dataBusListenerId?;
-    private dataBus?;
+    private readonly capabilities;
+    constructor(energyApp: EnergyApp, name: EnyoApplianceName[], networkDevice: EnyoNetworkDevice, sunspecClient: SunspecModbusClient, applianceManager: ApplianceManager, unitId?: number, port?: number, baseAddress?: number, capabilities?: SunspecBatteryCapability[], retryConfig?: IRetryConfig);
     /**
      * Connect to the battery and create/update the appliance
      */
@@ -130,6 +170,15 @@ export declare class SunspecBattery extends BaseSunspecDevice {
      * @returns Promise<SunspecBatteryControls | null> - Current control settings or null if error
      */
     getBatteryControls(): Promise<SunspecBatteryControls | null>;
+    /**
+     * Read full battery base data from Model 802
+     *
+     * Returns the complete Model 802 data structure with all fields,
+     * including nameplate, SoC/health, status, events, voltage, current, and power.
+     *
+     * @returns Promise<SunspecBatteryBaseData | null> - Full model 802 data or null if not available
+     */
+    readBatteryBaseData(): Promise<SunspecBatteryBaseData | null>;
     /**
      * Write custom battery control settings
      *
@@ -167,12 +216,13 @@ export declare class SunspecBattery extends BaseSunspecDevice {
     private handleStartGridCharge;
     private handleStopGridCharge;
     private handleSetDischargeLimit;
-    private sendCommandAcknowledge;
 }
 /**
  * Sunspec Meter implementation
  */
 export declare class SunspecMeter extends BaseSunspecDevice {
+    private readonly capabilities;
+    constructor(energyApp: EnergyApp, name: EnyoApplianceName[], networkDevice: EnyoNetworkDevice, sunspecClient: SunspecModbusClient, applianceManager: ApplianceManager, unitId?: number, port?: number, baseAddress?: number, capabilities?: SunspecMeterCapability[], retryConfig?: IRetryConfig);
     /**
      * Connect to the meter and create/update the appliance
      */