@enyo-energy/sunspec-sdk 0.0.28 → 0.0.30

package/dist/cjs/connection-retry-manager.cjs

@@ -0,0 +1,125 @@
+"use strict";
+/**
+ * Connection Retry Manager with Exponential Backoff
+ *
+ * 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)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConnectionRetryManager = void 0;
+const sunspec_interfaces_js_1 = require("./sunspec-interfaces.cjs");
+class ConnectionRetryManager {
+    config;
+    currentAttempt = 0;
+    pendingRetryTimeout = null;
+    isRetrying = false;
+    constructor(config) {
+        this.config = { ...sunspec_interfaces_js_1.DEFAULT_RETRY_CONFIG, ...config };
+    }
+    /**
+     * Calculate the next delay using exponential backoff
+     * Formula: min(initialDelayMs * backoffFactor^attempt, maxDelayMs)
+     */
+    getNextDelay() {
+        const delay = this.config.initialDelayMs * Math.pow(this.config.backoffFactor, this.currentAttempt);
+        return Math.min(delay, this.config.maxDelayMs);
+    }
+    /**
+     * Reset the retry state on successful connection
+     */
+    reset() {
+        this.currentAttempt = 0;
+        this.isRetrying = false;
+        this.cancelPendingRetry();
+    }
+    /**
+     * Check if we should retry based on max attempts
+     * Returns true if we haven't exceeded maxAttempts or if maxAttempts is -1 (infinite)
+     */
+    shouldRetry() {
+        if (this.config.maxAttempts === -1) {
+            return true;
+        }
+        return this.currentAttempt < this.config.maxAttempts;
+    }
+    /**
+     * Get the current attempt number (0-indexed)
+     */
+    getCurrentAttempt() {
+        return this.currentAttempt;
+    }
+    /**
+     * Get the max attempts configuration
+     */
+    getMaxAttempts() {
+        return this.config.maxAttempts;
+    }
+    /**
+     * Check if a retry is currently in progress
+     */
+    isRetryInProgress() {
+        return this.isRetrying;
+    }
+    /**
+     * Schedule a reconnection attempt with exponential backoff delay
+     * Returns a promise that resolves when the callback completes
+     */
+    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;
+        }
+        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);
+        });
+    }
+    /**
+     * Cancel any pending retry attempt
+     */
+    cancelPendingRetry() {
+        if (this.pendingRetryTimeout) {
+            clearTimeout(this.pendingRetryTimeout);
+            this.pendingRetryTimeout = null;
+            this.isRetrying = false;
+            console.log('Pending retry cancelled.');
+        }
+    }
+    /**
+     * Get the current configuration
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+}
+exports.ConnectionRetryManager = ConnectionRetryManager;

package/dist/cjs/connection-retry-manager.d.cts

@@ -0,0 +1,53 @@
+/**
+ * Connection Retry Manager with Exponential Backoff
+ *
+ * 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)
+ */
+import { IRetryConfig } from './sunspec-interfaces.cjs';
+export declare class ConnectionRetryManager {
+    private config;
+    private currentAttempt;
+    private pendingRetryTimeout;
+    private isRetrying;
+    constructor(config?: Partial<IRetryConfig>);
+    /**
+     * Calculate the next delay using exponential backoff
+     * Formula: min(initialDelayMs * backoffFactor^attempt, maxDelayMs)
+     */
+    getNextDelay(): number;
+    /**
+     * Reset the retry state on successful connection
+     */
+    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)
+     */
+    shouldRetry(): boolean;
+    /**
+     * Get the current attempt number (0-indexed)
+     */
+    getCurrentAttempt(): number;
+    /**
+     * Get the max attempts configuration
+     */
+    getMaxAttempts(): number;
+    /**
+     * Check if a retry is currently in progress
+     */
+    isRetryInProgress(): boolean;
+    /**
+     * Schedule a reconnection attempt with exponential backoff delay
+     * Returns a promise that resolves when the callback completes
+     */
+    scheduleRetry(callback: () => Promise<boolean>): Promise<boolean>;
+    /**
+     * Cancel any pending retry attempt
+     */
+    cancelPendingRetry(): void;
+    /**
+     * Get the current configuration
+     */
+    getConfig(): IRetryConfig;
+}

package/dist/cjs/index.cjs

@@ -14,10 +14,12 @@ 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 = void 0;
+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);
+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; } });

package/dist/cjs/index.d.cts

@@ -1,4 +1,5 @@
 export * from './sunspec-interfaces.cjs';
 export * from './sunspec-devices.cjs';
 export * from './sunspec-modbus-client.cjs';
+export { ConnectionRetryManager } from './connection-retry-manager.cjs';
 export { SDK_VERSION, getSdkVersion } from './version.cjs';

package/dist/cjs/sunspec-devices.cjs

@@ -31,15 +31,19 @@ class BaseSunspecDevice {
     sunspecClient;
     applianceManager;
     unitId;
+    port;
+    baseAddress;
     applianceId;
     lastUpdateTime = 0;
-    constructor(energyApp, name, networkDevice, sunspecClient, applianceManager, unitId = 1) {
+    constructor(energyApp, name, networkDevice, sunspecClient, applianceManager, unitId = 1, port = 502, baseAddress = 40000) {
         this.energyApp = energyApp;
         this.name = name;
         this.networkDevice = networkDevice;
         this.sunspecClient = sunspecClient;
         this.applianceManager = applianceManager;
         this.unitId = unitId;
+        this.port = port;
+        this.baseAddress = baseAddress;
     }
     /**
      * Check if the device is connected
@@ -55,8 +59,10 @@ class BaseSunspecDevice {
      */
     async ensureConnected() {
         if (!this.sunspecClient.isConnected()) {
-            await this.sunspecClient.connect(this.networkDevice.ipAddress, 502, this.unitId);
-            await this.sunspecClient.discoverModels();
+            await this.sunspecClient.connect(this.networkDevice.hostname, // primary
+            this.port, this.unitId, this.networkDevice.ipAddress // secondary fallback
+            );
+            await this.sunspecClient.discoverModels(this.baseAddress);
         }
     }
 }
@@ -68,8 +74,10 @@ class SunspecInverter extends BaseSunspecDevice {
     async connect() {
         // Ensure Sunspec client is connected
         if (!this.sunspecClient.isConnected()) {
-            await this.sunspecClient.connect(this.networkDevice.ipAddress, 502, this.unitId);
-            await this.sunspecClient.discoverModels();
+            await this.sunspecClient.connect(this.networkDevice.hostname, // primary
+            this.port, this.unitId, this.networkDevice.ipAddress // secondary fallback
+            );
+            await this.sunspecClient.discoverModels(this.baseAddress);
         }
         // Get device info from common block
         const commonData = await this.sunspecClient.readCommonBlock();
@@ -241,6 +249,8 @@ exports.SunspecInverter = SunspecInverter;
  * Sunspec Battery implementation
  */
 class SunspecBattery extends BaseSunspecDevice {
+    dataBusListenerId;
+    dataBus;
     /**
      * Connect to the battery and create/update the appliance
      */
@@ -284,12 +294,14 @@ class SunspecBattery extends BaseSunspecDevice {
                 }
             });
             console.log(`Sunspec Battery connected: ${this.networkDevice.hostname} (${this.applianceId})`);
+            this.startDataBusListening();
         }
         catch (error) {
             console.error(`Failed to create battery appliance: ${error}`);
         }
     }
     async disconnect() {
+        this.stopDataBusListening();
         if (this.applianceId) {
             await this.applianceManager.updateApplianceState(this.applianceId, enyo_appliance_js_1.EnyoApplianceConnectionType.Connector, enyo_appliance_js_1.EnyoApplianceStateEnum.Offline);
         }
@@ -558,6 +570,155 @@ class SunspecBattery extends BaseSunspecDevice {
         }
         return controls.chaGriSet === 1; // 1 = GRID, 0 = PV
     }
+    /**
+     * Start listening for storage commands on the data bus.
+     * Idempotent — does nothing if already listening.
+     */
+    startDataBusListening() {
+        if (this.dataBusListenerId) {
+            return;
+        }
+        this.dataBus = this.energyApp.useDataBus();
+        this.dataBusListenerId = this.dataBus.listenForMessages([
+            enyo_data_bus_value_js_1.EnyoDataBusMessageEnum.StartStorageGridChargeV1,
+            enyo_data_bus_value_js_1.EnyoDataBusMessageEnum.StopStorageGridChargeV1,
+            enyo_data_bus_value_js_1.EnyoDataBusMessageEnum.SetStorageDischargeLimitV1
+        ], (entry) => this.handleStorageCommand(entry));
+        console.log(`Battery ${this.applianceId}: started data bus listening (listener ${this.dataBusListenerId})`);
+    }
+    /**
+     * Stop listening for storage commands on the data bus.
+     */
+    stopDataBusListening() {
+        if (this.dataBusListenerId && this.dataBus) {
+            this.dataBus.unsubscribe(this.dataBusListenerId);
+            console.log(`Battery ${this.applianceId}: stopped data bus listening (listener ${this.dataBusListenerId})`);
+        }
+        this.dataBusListenerId = undefined;
+        this.dataBus = undefined;
+    }
+    handleStorageCommand(entry) {
+        if (entry.applianceId !== this.applianceId) {
+            return;
+        }
+        void (async () => {
+            try {
+                switch (entry.message) {
+                    case enyo_data_bus_value_js_1.EnyoDataBusMessageEnum.StartStorageGridChargeV1:
+                        await this.handleStartGridCharge(entry);
+                        break;
+                    case enyo_data_bus_value_js_1.EnyoDataBusMessageEnum.StopStorageGridChargeV1:
+                        await this.handleStopGridCharge(entry);
+                        break;
+                    case enyo_data_bus_value_js_1.EnyoDataBusMessageEnum.SetStorageDischargeLimitV1:
+                        await this.handleSetDischargeLimit(entry);
+                        break;
+                }
+            }
+            catch (error) {
+                console.error(`Battery ${this.applianceId}: error handling ${entry.message}:`, error);
+            }
+        })();
+    }
+    async handleStartGridCharge(msg) {
+        if (!this.isConnected() || !this.applianceId) {
+            this.sendCommandAcknowledge(msg.id, msg.message, enyo_data_bus_value_js_1.EnyoCommandAcknowledgeAnswerEnum.Rejected, "Not connected");
+            return;
+        }
+        console.log(`Battery ${this.applianceId}: handling StartStorageGridChargeV1 (powerLimitW=${msg.data.powerLimitW})`);
+        // Read current state for logging and rollback
+        const controls = await this.getBatteryControls();
+        console.log(`Battery ${this.applianceId}: current state - chaGriSet=${controls?.chaGriSet}, wChaMax=${controls?.wChaMax}, storCtlMod=${controls?.storCtlMod}`);
+        const originalChaGriSet = controls?.chaGriSet;
+        const originalWChaMax = controls?.wChaMax;
+        // Step 1: Enable grid charging (Register 17: chaGriSet=GRID)
+        const step1 = await this.enableGridCharging(true);
+        if (!step1) {
+            this.sendCommandAcknowledge(msg.id, msg.message, enyo_data_bus_value_js_1.EnyoCommandAcknowledgeAnswerEnum.Rejected, 'Failed to enable grid charging');
+            return;
+        }
+        // Step 2: Set charging power (Register 2: wChaMax)
+        const step2 = await this.setChargingPower(msg.data.powerLimitW);
+        if (!step2) {
+            // Rollback step 1
+            await this.writeBatteryControls({ chaGriSet: originalChaGriSet });
+            this.sendCommandAcknowledge(msg.id, msg.message, enyo_data_bus_value_js_1.EnyoCommandAcknowledgeAnswerEnum.Rejected, 'Failed to set charging power');
+            return;
+        }
+        // Step 3: Set storage mode to CHARGE (Register 5: storCtlMod=0x0001)
+        const step3 = await this.setStorageMode(sunspec_interfaces_js_1.SunspecStorageMode.CHARGE);
+        if (!step3) {
+            // Rollback steps 1+2
+            await this.writeBatteryControls({ chaGriSet: originalChaGriSet, wChaMax: originalWChaMax });
+            this.sendCommandAcknowledge(msg.id, msg.message, enyo_data_bus_value_js_1.EnyoCommandAcknowledgeAnswerEnum.Rejected, 'Failed to set storage mode to charge');
+            return;
+        }
+        this.sendCommandAcknowledge(msg.id, msg.message, enyo_data_bus_value_js_1.EnyoCommandAcknowledgeAnswerEnum.Accepted);
+    }
+    async handleStopGridCharge(msg) {
+        if (!this.isConnected() || !this.applianceId) {
+            this.sendCommandAcknowledge(msg.id, msg.message, enyo_data_bus_value_js_1.EnyoCommandAcknowledgeAnswerEnum.NotSupported);
+            return;
+        }
+        console.log(`Battery ${this.applianceId}: handling StopStorageGridChargeV1`);
+        // Read current state for logging and rollback
+        const controls = await this.getBatteryControls();
+        console.log(`Battery ${this.applianceId}: current state - chaGriSet=${controls?.chaGriSet}, storCtlMod=${controls?.storCtlMod}`);
+        const originalChaGriSet = controls?.chaGriSet;
+        // Step 1: Disable grid charging (Register 17: chaGriSet=PV)
+        const step1 = await this.enableGridCharging(false);
+        if (!step1) {
+            this.sendCommandAcknowledge(msg.id, msg.message, enyo_data_bus_value_js_1.EnyoCommandAcknowledgeAnswerEnum.Rejected, 'Failed to disable grid charging');
+            return;
+        }
+        // Step 2: Set storage mode to AUTO (Register 5: storCtlMod=0x0003)
+        const step2 = await this.setStorageMode(sunspec_interfaces_js_1.SunspecStorageMode.AUTO);
+        if (!step2) {
+            // Rollback step 1
+            await this.writeBatteryControls({ chaGriSet: originalChaGriSet });
+            this.sendCommandAcknowledge(msg.id, msg.message, enyo_data_bus_value_js_1.EnyoCommandAcknowledgeAnswerEnum.Rejected, 'Failed to set storage mode to auto');
+            return;
+        }
+        this.sendCommandAcknowledge(msg.id, msg.message, enyo_data_bus_value_js_1.EnyoCommandAcknowledgeAnswerEnum.Accepted);
+    }
+    async handleSetDischargeLimit(msg) {
+        if (!this.isConnected() || !this.applianceId) {
+            this.sendCommandAcknowledge(msg.id, msg.message, enyo_data_bus_value_js_1.EnyoCommandAcknowledgeAnswerEnum.NotSupported);
+            return;
+        }
+        console.log(`Battery ${this.applianceId}: handling SetStorageDischargeLimitV1 (dischargeLimitPercent=${msg.data.dischargeLimitPercent})`);
+        // Read current state for logging
+        const controls = await this.getBatteryControls();
+        console.log(`Battery ${this.applianceId}: current state - outWRte=${controls?.outWRte}`);
+        // Set discharge limit (Register 12: outWRte)
+        const success = await this.writeBatteryControls({ outWRte: msg.data.dischargeLimitPercent });
+        if (!success) {
+            this.sendCommandAcknowledge(msg.id, msg.message, enyo_data_bus_value_js_1.EnyoCommandAcknowledgeAnswerEnum.Rejected, 'Failed to set discharge limit');
+            return;
+        }
+        this.sendCommandAcknowledge(msg.id, msg.message, enyo_data_bus_value_js_1.EnyoCommandAcknowledgeAnswerEnum.Accepted);
+    }
+    sendCommandAcknowledge(messageId, acknowledgeMessage, answer, rejectionReason) {
+        if (!this.dataBus || !this.applianceId) {
+            return;
+        }
+        const ackMessage = {
+            id: (0, node_crypto_1.randomUUID)(),
+            message: enyo_data_bus_value_js_1.EnyoDataBusMessageEnum.CommandAcknowledgeV1,
+            type: 'answer',
+            source: enyo_source_enum_js_1.EnyoSourceEnum.Device,
+            applianceId: this.applianceId,
+            timestampIso: new Date().toISOString(),
+            data: {
+                messageId,
+                acknowledgeMessage,
+                answer,
+                rejectionReason
+            }
+        };
+        console.log(`Battery ${this.applianceId}: sending ${answer} for ${acknowledgeMessage} (messageId=${messageId}${rejectionReason ? `, reason=${rejectionReason}` : ''})`);
+        this.dataBus.sendMessage([ackMessage]);
+    }
 }
 exports.SunspecBattery = SunspecBattery;
 /**

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

@@ -14,9 +14,11 @@ export declare abstract class BaseSunspecDevice {
     protected readonly sunspecClient: SunspecModbusClient;
     protected readonly applianceManager: ApplianceManager;
     protected readonly unitId: number;
+    protected readonly port: number;
+    protected readonly baseAddress: number;
     protected applianceId?: string;
     protected lastUpdateTime: number;
-    constructor(energyApp: EnergyApp, name: EnyoApplianceName[], networkDevice: EnyoNetworkDevice, sunspecClient: SunspecModbusClient, applianceManager: ApplianceManager, unitId?: number);
+    constructor(energyApp: EnergyApp, name: EnyoApplianceName[], networkDevice: EnyoNetworkDevice, sunspecClient: SunspecModbusClient, applianceManager: ApplianceManager, unitId?: number, port?: number, baseAddress?: number);
     /**
      * Connect to the device and create/update the appliance
      */
@@ -62,6 +64,8 @@ export declare class SunspecInverter extends BaseSunspecDevice {
  * Sunspec Battery implementation
  */
 export declare class SunspecBattery extends BaseSunspecDevice {
+    private dataBusListenerId?;
+    private dataBus?;
     /**
      * Connect to the battery and create/update the appliance
      */
@@ -150,6 +154,20 @@ export declare class SunspecBattery extends BaseSunspecDevice {
      * @returns Promise<boolean | null> - true if enabled, false if disabled, null if error
      */
     isGridChargingEnabled(): Promise<boolean | null>;
+    /**
+     * Start listening for storage commands on the data bus.
+     * Idempotent — does nothing if already listening.
+     */
+    startDataBusListening(): void;
+    /**
+     * Stop listening for storage commands on the data bus.
+     */
+    stopDataBusListening(): void;
+    private handleStorageCommand;
+    private handleStartGridCharge;
+    private handleStopGridCharge;
+    private handleSetDischargeLimit;
+    private sendCommandAcknowledge;
 }
 /**
  * Sunspec Meter implementation

package/dist/cjs/sunspec-interfaces.cjs

@@ -3,7 +3,13 @@
  * SunSpec block interfaces with block numbers
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SunspecStorageMode = exports.SunspecChargeSource = exports.SunspecVArPctMode = exports.SunspecEnableControl = exports.SunspecConnectionControl = exports.SunspecStorageControlMode = exports.SunspecBatteryChargeState = exports.SunspecMPPTOperatingState = exports.SunspecModelId = void 0;
+exports.SunspecStorageMode = exports.SunspecChargeSource = exports.SunspecVArPctMode = exports.SunspecEnableControl = exports.SunspecConnectionControl = exports.SunspecStorageControlMode = exports.SunspecBatteryChargeState = exports.SunspecMPPTOperatingState = exports.SunspecModelId = exports.DEFAULT_RETRY_CONFIG = void 0;
+exports.DEFAULT_RETRY_CONFIG = {
+    initialDelayMs: 1000,
+    maxDelayMs: 30000,
+    backoffFactor: 1.5,
+    maxAttempts: 10
+};
 /**
  * Common Sunspec Model IDs
  */

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

@@ -1,6 +1,16 @@
 /**
  * SunSpec block interfaces with block numbers
  */
+/**
+ * Configuration for connection retry with exponential backoff
+ */
+export interface IRetryConfig {
+    initialDelayMs: number;
+    maxDelayMs: number;
+    backoffFactor: number;
+    maxAttempts: number;
+}
+export declare const DEFAULT_RETRY_CONFIG: IRetryConfig;
 /**
  * Base interface for all SunSpec blocks
  */