@enyo-energy/sunspec-sdk 0.0.51 → 0.0.54

package/dist/sunspec-modbus-client.d.ts

@@ -19,23 +19,38 @@
 import { type SunspecInverterControls, type SunspecInverterData, type SunspecInverterSettings, type SunspecMeterData, type SunspecModel, type SunspecMPPTData, type SunspecBatteryData, type SunspecBatteryBaseData, type SunspecBatteryControls, SunspecStorageMode } from "./sunspec-interfaces.js";
 import { EnergyAppModbusDataType, IConnectionHealth } from "@enyo-energy/energy-app-sdk/dist/implementations/modbus/interfaces.js";
 import { EnergyApp } from "@enyo-energy/energy-app-sdk";
+/**
+ * Get (or create) the singleton SunspecModbusClient for this network device.
+ * Increments the refcount; pair with `releaseSunspecClient` on teardown.
+ */
+export declare function getOrCreateSunspecClient(energyApp: EnergyApp, host: string, port?: number): SunspecModbusClient;
+/**
+ * Release a refcount on the network-device client. When the last consumer releases,
+ * the client is fully disconnected (all units closed) and removed from the registry.
+ *
+ * Releasing more times than acquired is a programming error and is logged; the count
+ * is clamped at zero so repeat releases are no-ops.
+ */
+export declare function releaseSunspecClient(host: string, port?: number): Promise<void>;
 export declare class SunspecModbusClient {
     private energyApp;
-    private modbusClient;
-    private discoveredModels;
-    private connected;
+    private modbusInstances;
+    private faultTolerantReaders;
+    private discoveredModelsByUnit;
     private connectionHealth;
-    private faultTolerantReader;
     private modbusDataTypeConverter;
     private connectionParams;
+    private knownUnits;
     private autoReconnectEnabled;
     private openCount;
     private closeCount;
-    private currentlyOpen;
     private operationChain;
     constructor(energyApp: EnergyApp);
     /**
-     * Connect to Modbus device
+     * Connect to a Modbus device unit. Multiple unit IDs on the same network device share this
+     * client; calling connect() with different unit IDs adds each as a separately-managed unit.
+     * The first call locks in the host/port for this client; later calls for a different host
+     * are rejected.
      * @param host Primary host (hostname) to connect to
      * @param port Modbus port (default 502)
      * @param unitId Modbus unit ID (default 1)
@@ -43,33 +58,47 @@ export declare class SunspecModbusClient {
      */
     connect(host: string, port?: number, unitId?: number, secondaryHost?: string): Promise<void>;
     /**
-     * Disconnect from Modbus device.
+     * Disconnect from all units of this network device.
      *
-     * Note: connection parameters are preserved so reconnect() can be called afterwards.
-     * They will be overwritten by the next connect() call anyway.
+     * Note: connection parameters and the set of known units are preserved so reconnect() can
+     * be called afterwards. They will be overwritten by the next connect() call anyway.
      */
     disconnect(): Promise<void>;
     /**
-     * Reconnect using stored connection parameters
-     * First tries primaryHost (hostname), then falls back to secondaryHost (ipAddress) if available
-     * Returns true if reconnection was successful, false otherwise
+     * Disconnect a single unit on this network device. Other units on the same device stay open.
+     */
+    disconnectUnit(unitId: number): Promise<void>;
+    /**
+     * Reconnect every previously-known unit on this network device using stored connection
+     * parameters. First tries primaryHost (hostname), then falls back to secondaryHost
+     * (ipAddress) if available. Returns true only if every known unit reconnected successfully.
      */
     reconnect(): Promise<boolean>;
     /**
-     * Attempt to establish a connection to a specific host. Caller must hold the connection lock.
-     * Returns true if successful, false otherwise.
+     * Reconnect a single previously-known unit on this network device. Other units on the
+     * same client stay open. Useful when one device's polling loop detects a dropped
+     * connection and only needs to recover its own unit, not thrash siblings.
+     *
+     * Returns true if the unit reconnected successfully (on primary or secondary host).
+     */
+    reconnectUnit(unitId: number): Promise<boolean>;
+    /**
+     * Attempt to (re)open every requested unit on a specific host. Caller must hold the
+     * connection lock. Closes any pre-existing per-unit instances first. Returns true only
+     * if every unit succeeded.
      */
     private attemptConnection;
     /**
-     * Open a new Modbus socket and wire up the fault-tolerant reader. On any failure, the
-     * just-opened socket (if any) is closed so we never leak. Caller must hold the connection
-     * lock and ensure no prior socket is open (use _closeSocket first).
+     * Open a new Modbus instance for one unit ID and wire up its fault-tolerant reader.
+     * On any failure, the just-opened instance (if any) is closed so we never leak. Caller must
+     * hold the connection lock and ensure the unit is not already open.
      */
-    private _openSocket;
+    private _openUnit;
     /**
-     * Close the current Modbus socket if any. Idempotent. Caller must hold the connection lock.
+     * Close the Modbus instance for a single unit. Idempotent. Caller must hold the
+     * connection lock.
      */
-    private _closeSocket;
+    private _closeUnit;
     /**
      * Run `fn` with exclusive access to connection-state transitions. Subsequent calls queue
      * behind any in-flight one. A rejected `fn` does not poison the chain for later callers.
@@ -78,13 +107,26 @@ export declare class SunspecModbusClient {
     private recordOpen;
     private recordClose;
     /**
-     * Get cumulative open/close counts for this client. Useful for spotting connection leaks.
+     * Get cumulative open/close counts for this client (across all unit IDs). Useful for
+     * spotting connection leaks.
      */
     getConnectionStats(): {
         opens: number;
         closes: number;
-        currentlyOpen: number;
+        openUnits: number;
     };
+    /**
+     * Get the EnergyAppModbusInstance for a unit, throwing if it isn't open.
+     */
+    private getInstance;
+    /**
+     * Get the fault-tolerant reader for a unit, throwing if it isn't open.
+     */
+    private getReader;
+    /**
+     * Get (or create) the discovered-models map for a unit.
+     */
+    private getModelsMap;
     /**
      * Enable or disable automatic reconnection
      */
@@ -96,20 +138,20 @@ export declare class SunspecModbusClient {
     /**
      * Detect the base address and addressing mode (0-based or 1-based) for SunSpec
      */
-    detectSunspecBaseAddress(customBaseAddress?: number): Promise<{
+    detectSunspecBaseAddress(unitId: number, customBaseAddress?: number): Promise<{
         baseAddress: number;
         isZeroBased: boolean;
         nextAddress: number;
     }>;
     /**
-     * Discover all available Sunspec models
+     * Discover all available Sunspec models for a unit
      * Automatically detects base address (40000 or 40001) and scans from there
      */
-    discoverModels(customBaseAddress?: number): Promise<Map<number, SunspecModel>>;
+    discoverModels(unitId: number, customBaseAddress?: number): Promise<Map<number, SunspecModel>>;
     /**
-     * Find a specific model by ID
+     * Find a specific model by ID for a given unit
      */
-    findModel(modelId: number): SunspecModel | undefined;
+    findModel(unitId: number, modelId: number): SunspecModel | undefined;
     /**
      * Check if a value is "unimplemented" according to Sunspec specification
      * Returns true if the value represents an unimplemented/not applicable register
@@ -153,19 +195,34 @@ export declare class SunspecModbusClient {
     /**
      * Helper to read register value(s) using the fault-tolerant reader with data type conversion
      */
-    readRegisterValue(address: number, quantity: number | undefined, dataType: EnergyAppModbusDataType): Promise<number | string | number[]>;
+    readRegisterValue(unitId: number, address: number, quantity: number | undefined, dataType: EnergyAppModbusDataType): Promise<number | string | number[]>;
     /**
      * Helper to write register value(s)
      */
-    writeRegisterValue(address: number, value: number | number[], dataType?: EnergyAppModbusDataType): Promise<boolean>;
+    writeRegisterValue(unitId: number, address: number, value: number | number[], dataType?: EnergyAppModbusDataType): Promise<boolean>;
+    /**
+     * Read inverter data. Detects which SunSpec inverter model the device exposes —
+     * int+SF (101/103) or float (111/112/113) — by checking the discovered model directory,
+     * and dispatches to the appropriate decoder.
+     */
+    readInverterData(unitId: number): Promise<SunspecInverterData | null>;
     /**
-     * Read inverter data from Model 101 (Single Phase) / Model 103 (Three Phase)
+     * Read three-phase inverter data from Model 103 (int + scale factor encoding).
      */
-    readInverterData(): Promise<SunspecInverterData | null>;
+    private readThreePhaseInverterData_IntSF;
     /**
      * Read single phase inverter data (Model 101)
      */
     private readSinglePhaseInverterData;
+    /**
+     * Read inverter data from a float-variant model: 111 (single-phase), 112 (split-phase), or 113 (three-phase).
+     *
+     * All three models share the same SunSpec register layout — measurement fields are 32-bit IEEE 754 floats
+     * (no scale factors), status registers stay enum16, event registers stay bitfield32. Phase scope differs
+     * by model: 111 populates phase A only; 112 phases A+B; 113 all three. Unpopulated phase fields read NaN
+     * and are returned as undefined.
+     */
+    private readFloatInverterData;
     /**
      * Extract inverter scale factors from a pre-read model buffer
      */
@@ -176,6 +233,11 @@ export declare class SunspecModbusClient {
      */
     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 a float32 (IEEE 754, big-endian, 2 registers) from a model buffer.
+     * SunSpec uses NaN as the "unimplemented" sentinel for floats; returns undefined in that case.
+     */
+    private extractFloat32OrUndefined;
     /**
      * Read scale factors from Model 160 (MPPT)
      *
@@ -191,7 +253,7 @@ export declare class SunspecModbusClient {
      * Extract MPPT scale factors from a pre-read model buffer
      */
     private extractMPPTScaleFactors;
-    readMPPTScaleFactors(): Promise<{
+    readMPPTScaleFactors(unitId: number): Promise<{
         DCA_SF: number;
         DCV_SF: number;
         DCW_SF: number;
@@ -204,11 +266,11 @@ export declare class SunspecModbusClient {
     /**
      * Read MPPT data from Model 160
      */
-    readMPPTData(moduleId?: number): Promise<SunspecMPPTData | null>;
+    readMPPTData(unitId: number, moduleId?: number): Promise<SunspecMPPTData | null>;
     /**
      * Read all MPPT strings from Model 160 (Multiple MPPT)
      */
-    readAllMPPTData(): Promise<SunspecMPPTData[]>;
+    readAllMPPTData(unitId: number): Promise<SunspecMPPTData[]>;
     /**
      * Map battery charge state to human-readable name
      * @param state The numeric charge state value
@@ -230,67 +292,67 @@ export declare class SunspecModbusClient {
     /**
      * Read battery base data from Model 802 (Battery Base)
      */
-    readBatteryBaseData(): Promise<SunspecBatteryBaseData | null>;
+    readBatteryBaseData(unitId: number): Promise<SunspecBatteryBaseData | null>;
     /**
      * Read battery data from Model 124 (Basic Storage) with fallback to Model 802 / Model 803
      */
-    readBatteryData(): Promise<SunspecBatteryData | null>;
+    readBatteryData(unitId: number): Promise<SunspecBatteryData | null>;
     /**
      * Write battery control settings to Model 124
      */
-    writeBatteryControls(controls: Partial<SunspecBatteryControls>): Promise<boolean>;
+    writeBatteryControls(unitId: number, controls: Partial<SunspecBatteryControls>): Promise<boolean>;
     /**
      * Set battery storage mode (simplified interface)
      */
-    setStorageMode(mode: SunspecStorageMode): Promise<boolean>;
+    setStorageMode(unitId: number, mode: SunspecStorageMode): Promise<boolean>;
     /**
      * Enable or disable grid charging
      */
-    enableGridCharging(enable: boolean): Promise<boolean>;
+    enableGridCharging(unitId: number, enable: boolean): Promise<boolean>;
     /**
      * Read battery control settings from Model 124 (Basic Storage Controls)
      */
-    readBatteryControls(): Promise<SunspecBatteryControls | null>;
+    readBatteryControls(unitId: number): Promise<SunspecBatteryControls | null>;
     /**
      * Read meter data from Model 201 (Single Phase) / Model 203 (Three Phase) / Model 204 (Split Phase)
      */
-    readMeterData(): Promise<SunspecMeterData | null>;
+    readMeterData(unitId: number): Promise<SunspecMeterData | null>;
     /**
      * Read common block data (Model 1)
      */
-    readCommonBlock(): Promise<any>;
+    readCommonBlock(unitId: number): Promise<any>;
     /**
      * Get serial number from device
      */
-    getSerialNumber(): Promise<string | undefined>;
+    getSerialNumber(unitId: number): Promise<string | undefined>;
     /**
-     * Check if connected
+     * Check if a specific unit is connected on this network device
      */
-    isConnected(): boolean;
+    isConnected(unitId: number): boolean;
     /**
-     * Check if connection is healthy
+     * Check if a specific unit's connection is healthy
      */
-    isHealthy(): boolean;
+    isHealthy(unitId: number): boolean;
     /**
-     * Get connection health details
+     * Get connection health details (shared across all units on this network device)
      */
     getConnectionHealth(): IConnectionHealth;
     /**
      * Read inverter settings from Model 121 (Inverter Settings)
      */
-    readInverterSettings(): Promise<SunspecInverterSettings | null>;
+    readInverterSettings(unitId: number): Promise<SunspecInverterSettings | null>;
     /**
      * Read inverter controls from Model 123 (Immediate Inverter Controls)
      */
-    readInverterControls(): Promise<SunspecInverterControls | null>;
+    readInverterControls(unitId: number): Promise<SunspecInverterControls | null>;
     /**
      * Write Block 121 - Inverter Basic Settings
      */
-    writeInverterSettings(settings: Partial<SunspecInverterSettings>): Promise<boolean>;
+    writeInverterSettings(unitId: number, settings: Partial<SunspecInverterSettings>): Promise<boolean>;
     /**
      * Write inverter controls to Model 123 (Immediate Inverter Controls)
      */
-    writeInverterControls(controls: Partial<SunspecInverterControls>): Promise<boolean>;
+    writeInverterControls(unitId: number, controls: Partial<SunspecInverterControls>): Promise<boolean>;
     /**
      * Set the inverter feed-in power limit using Model 123 (Immediate Inverter Controls)
      *
@@ -301,5 +363,5 @@ export declare class SunspecModbusClient {
      * @param limitW - Power limit in Watts, or null to remove the limit
      * @returns true if successful, false otherwise
      */
-    setFeedInLimit(limitW: number | null): Promise<boolean>;
+    setFeedInLimit(unitId: number, limitW: number | null): Promise<boolean>;
 }