@enyo-energy/sunspec-sdk 0.0.50 → 0.0.52

package/dist/sunspec-modbus-client.js

@@ -20,165 +20,351 @@ import { SunspecModelId, SunspecBatteryChargeState, SunspecStorageControlMode, S
 import { EnergyAppModbusConnectionHealth } from "@enyo-energy/energy-app-sdk/dist/implementations/modbus/EnergyAppModbusConnectionHealth.js";
 import { EnergyAppModbusFaultTolerantReader } from "@enyo-energy/energy-app-sdk/dist/implementations/modbus/EnergyAppModbusFaultTolerantReader.js";
 import { EnergyAppModbusDataTypeConverter } from "@enyo-energy/energy-app-sdk/dist/implementations/modbus/EnergyAppModbusDataTypeConverter.js";
+/**
+ * Module-level registry: one SunspecModbusClient per network device (host:port).
+ * Refcounted so the underlying connection only tears down when the last consumer releases.
+ */
+const CLIENT_REGISTRY = new Map();
+const registryKey = (host, port) => `${host}:${port}`;
+/**
+ * Get (or create) the singleton SunspecModbusClient for this network device.
+ * Increments the refcount; pair with `releaseSunspecClient` on teardown.
+ */
+export function getOrCreateSunspecClient(energyApp, host, port = 502) {
+    const key = registryKey(host, port);
+    let entry = CLIENT_REGISTRY.get(key);
+    if (!entry) {
+        entry = { client: new SunspecModbusClient(energyApp), refcount: 0 };
+        CLIENT_REGISTRY.set(key, entry);
+    }
+    entry.refcount++;
+    return entry.client;
+}
+/**
+ * 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 async function releaseSunspecClient(host, port = 502) {
+    const key = registryKey(host, port);
+    const entry = CLIENT_REGISTRY.get(key);
+    if (!entry)
+        return;
+    if (entry.refcount <= 0) {
+        console.warn(`releaseSunspecClient(${host}:${port}): refcount already 0 — extra release ignored`);
+        return;
+    }
+    entry.refcount--;
+    if (entry.refcount === 0) {
+        // Disconnect first, THEN remove from registry, so a concurrent getOrCreate
+        // doesn't bind a fresh client to the same host:port while sockets are still
+        // closing on the old one.
+        try {
+            await entry.client.disconnect();
+        }
+        finally {
+            // Guard against the very-unlikely case where someone re-acquired during await.
+            if (CLIENT_REGISTRY.get(key) === entry && entry.refcount === 0) {
+                CLIENT_REGISTRY.delete(key);
+            }
+        }
+    }
+}
 export class SunspecModbusClient {
     energyApp;
-    modbusClient = null;
-    discoveredModels = new Map();
-    connected = false;
+    // Per-unit Modbus instance/reader/discovered-models maps. One client = one network device,
+    // many unit IDs share that client (each unit ID is one EnergyAppModbusInstance underneath).
+    modbusInstances = new Map();
+    faultTolerantReaders = new Map();
+    discoveredModelsByUnit = new Map();
     connectionHealth;
-    faultTolerantReader = null;
     modbusDataTypeConverter;
     connectionParams = null;
+    // Per-unit known parameters so reconnect() can replay every unit ID we've seen.
+    knownUnits = new Set();
     autoReconnectEnabled = true;
     openCount = 0;
     closeCount = 0;
-    currentlyOpen = 0;
+    // Serializes connection-state transitions so concurrent callers cannot open duplicate
+    // sockets for the same unit ID while one is still alive.
+    operationChain = Promise.resolve();
     constructor(energyApp) {
         this.energyApp = energyApp;
         this.connectionHealth = new EnergyAppModbusConnectionHealth();
         this.modbusDataTypeConverter = new EnergyAppModbusDataTypeConverter();
     }
     /**
-     * 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)
      * @param secondaryHost Optional secondary host (ipAddress) for fallback during reconnection
      */
     async connect(host, port = 502, unitId = 1, secondaryHost) {
-        if (this.connected) {
-            await this.disconnect();
-        }
-        // Store connection parameters for potential reconnection
-        this.connectionParams = { primaryHost: host, secondaryHost, port, unitId };
-        this.modbusClient = await this.energyApp.useModbus().connect({
-            host,
-            port,
-            unitId,
-            timeout: 5000
+        return this.withConnectionLock(async () => {
+            if (this.connectionParams) {
+                if (this.connectionParams.primaryHost !== host || this.connectionParams.port !== port) {
+                    throw new Error(`SunspecModbusClient is bound to ${this.connectionParams.primaryHost}:${this.connectionParams.port}; ` +
+                        `cannot reuse it for ${host}:${port}. Use getOrCreateSunspecClient() per (host, port).`);
+                }
+                if (secondaryHost && !this.connectionParams.secondaryHost) {
+                    this.connectionParams.secondaryHost = secondaryHost;
+                }
+            }
+            else {
+                this.connectionParams = { primaryHost: host, secondaryHost, port };
+            }
+            this.knownUnits.add(unitId);
+            if (this.modbusInstances.has(unitId)) {
+                console.debug(`connect(): unit ${unitId} on ${host}:${port} already open, skipping`);
+                return;
+            }
+            await this._openUnit(host, port, unitId);
+            console.log(`Connected to Sunspec device at ${host}:${port} unit ${unitId} (opens=${this.openCount}, closes=${this.closeCount}, openUnits=${this.modbusInstances.size})`);
         });
-        // Create fault-tolerant reader with connection health monitoring
-        if (this.modbusClient) {
-            this.faultTolerantReader = new EnergyAppModbusFaultTolerantReader(this.modbusClient, this.connectionHealth);
-        }
-        this.connected = true;
-        this.connectionHealth.recordSuccess();
-        this.recordOpen();
-        console.log(`Connected to Sunspec device at ${host}:${port} unit ${unitId} (opens=${this.openCount}, closes=${this.closeCount}, current=${this.currentlyOpen})`);
     }
     /**
-     * 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.
      */
     async disconnect() {
-        if (this.modbusClient && this.connected) {
-            await this.modbusClient.disconnect();
-            this.modbusClient = null;
-            this.faultTolerantReader = null;
-            this.connected = false;
-            this.discoveredModels.clear();
-            this.recordClose();
+        return this.withConnectionLock(async () => {
+            if (this.modbusInstances.size === 0) {
+                return;
+            }
             const host = this.connectionParams?.primaryHost ?? 'unknown';
             const port = this.connectionParams?.port ?? 0;
-            const unitId = this.connectionParams?.unitId ?? 0;
-            console.log(`Disconnected from Sunspec device at ${host}:${port} unit ${unitId} (opens=${this.openCount}, closes=${this.closeCount}, current=${this.currentlyOpen})`);
-        }
+            const units = [...this.modbusInstances.keys()];
+            for (const unitId of units) {
+                await this._closeUnit(unitId);
+            }
+            console.log(`Disconnected from Sunspec device at ${host}:${port} units [${units.join(',')}] (opens=${this.openCount}, closes=${this.closeCount})`);
+        });
+    }
+    /**
+     * Disconnect a single unit on this network device. Other units on the same device stay open.
+     */
+    async disconnectUnit(unitId) {
+        return this.withConnectionLock(async () => {
+            if (!this.modbusInstances.has(unitId))
+                return;
+            const host = this.connectionParams?.primaryHost ?? 'unknown';
+            const port = this.connectionParams?.port ?? 0;
+            await this._closeUnit(unitId);
+            console.log(`Disconnected unit ${unitId} from Sunspec device at ${host}:${port} (opens=${this.openCount}, closes=${this.closeCount})`);
+        });
     }
     /**
-     * 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
+     * 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.
      */
     async reconnect() {
-        if (!this.connectionParams) {
-            console.error('Cannot reconnect: no connection parameters stored. Call connect() first.');
+        return this.withConnectionLock(async () => {
+            if (!this.connectionParams) {
+                console.error('Cannot reconnect: no connection parameters stored. Call connect() first.');
+                return false;
+            }
+            if (this.knownUnits.size === 0) {
+                console.error('Cannot reconnect: no known unit IDs. Call connect(unitId) at least once first.');
+                return false;
+            }
+            const { primaryHost, secondaryHost, port } = this.connectionParams;
+            const units = [...this.knownUnits];
+            console.log(`Attempting to reconnect to primary host ${primaryHost}:${port} units [${units.join(',')}]...`);
+            const primarySuccess = await this.attemptConnection(primaryHost, port, units);
+            if (primarySuccess) {
+                console.log(`Successfully reconnected to primary host ${primaryHost}:${port} units [${units.join(',')}]`);
+                return true;
+            }
+            if (secondaryHost && secondaryHost !== primaryHost) {
+                console.log(`Primary host failed, attempting secondary host ${secondaryHost}:${port} units [${units.join(',')}]...`);
+                const secondarySuccess = await this.attemptConnection(secondaryHost, port, units);
+                if (secondarySuccess) {
+                    console.log(`Successfully reconnected to secondary host ${secondaryHost}:${port} units [${units.join(',')}]`);
+                    return true;
+                }
+            }
+            console.error(`Reconnection failed to all available hosts`);
+            return false;
+        });
+    }
+    /**
+     * 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).
+     */
+    async reconnectUnit(unitId) {
+        return this.withConnectionLock(async () => {
+            if (!this.connectionParams) {
+                console.error(`Cannot reconnectUnit(${unitId}): no connection parameters stored. Call connect() first.`);
+                return false;
+            }
+            const { primaryHost, secondaryHost, port } = this.connectionParams;
+            console.log(`Attempting to reconnect unit ${unitId} on primary host ${primaryHost}:${port}...`);
+            const primarySuccess = await this.attemptConnection(primaryHost, port, [unitId]);
+            if (primarySuccess) {
+                console.log(`Successfully reconnected unit ${unitId} on primary host ${primaryHost}:${port}`);
+                return true;
+            }
+            if (secondaryHost && secondaryHost !== primaryHost) {
+                console.log(`Primary host failed for unit ${unitId}, attempting secondary host ${secondaryHost}:${port}...`);
+                const secondarySuccess = await this.attemptConnection(secondaryHost, port, [unitId]);
+                if (secondarySuccess) {
+                    console.log(`Successfully reconnected unit ${unitId} on secondary host ${secondaryHost}:${port}`);
+                    return true;
+                }
+            }
+            console.error(`Reconnection failed for unit ${unitId} on all available hosts`);
             return false;
+        });
+    }
+    /**
+     * 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.
+     */
+    async attemptConnection(host, port, units) {
+        for (const unitId of units) {
+            if (this.modbusInstances.has(unitId)) {
+                await this._closeUnit(unitId);
+            }
         }
-        const { primaryHost, secondaryHost, port, unitId } = this.connectionParams;
-        // Try primary host first
-        console.log(`Attempting to reconnect to primary host ${primaryHost}:${port} unit ${unitId}...`);
-        const primarySuccess = await this.attemptConnection(primaryHost, port, unitId);
-        if (primarySuccess) {
-            console.log(`Successfully reconnected to primary host ${primaryHost}:${port} unit ${unitId}`);
+        try {
+            for (const unitId of units) {
+                await this._openUnit(host, port, unitId);
+            }
+            console.log(`Connection attempt to ${host}:${port} units [${units.join(',')}] succeeded (opens=${this.openCount}, closes=${this.closeCount}, openUnits=${this.modbusInstances.size})`);
             return true;
         }
-        // If primary failed and secondary is available, try secondary
-        if (secondaryHost && secondaryHost !== primaryHost) {
-            console.log(`Primary host failed, attempting secondary host ${secondaryHost}:${port} unit ${unitId}...`);
-            const secondarySuccess = await this.attemptConnection(secondaryHost, port, unitId);
-            if (secondarySuccess) {
-                console.log(`Successfully reconnected to secondary host ${secondaryHost}:${port} unit ${unitId}`);
-                return true;
-            }
+        catch (error) {
+            console.error(`Connection attempt to ${host}:${port} failed: ${error}`);
+            return false;
         }
-        console.error(`Reconnection failed to all available hosts`);
-        this.connected = false;
-        return false;
     }
     /**
-     * Attempt to establish a connection to a specific host
-     * Returns true if successful, false otherwise
+     * 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.
      */
-    async attemptConnection(host, port, unitId) {
+    async _openUnit(host, port, unitId) {
+        let candidate = null;
         try {
-            // Disconnect existing connection if any
-            if (this.modbusClient) {
-                const wasConnected = this.connected;
-                try {
-                    await this.modbusClient.disconnect();
-                }
-                catch (e) {
-                    // Ignore disconnect errors during reconnection
-                }
-                this.modbusClient = null;
-                this.faultTolerantReader = null;
-                if (wasConnected) {
-                    this.connected = false;
-                    this.recordClose();
-                }
-            }
-            // Attempt connection
-            this.modbusClient = await this.energyApp.useModbus().connect({
+            candidate = await this.energyApp.useModbus().connect({
                 host,
                 port,
                 unitId,
                 timeout: 5000
             });
-            // Create fault-tolerant reader with connection health monitoring
-            if (this.modbusClient) {
-                this.faultTolerantReader = new EnergyAppModbusFaultTolerantReader(this.modbusClient, this.connectionHealth);
+            if (!candidate) {
+                throw new Error(`useModbus().connect returned null for ${host}:${port} unit ${unitId}`);
             }
-            this.connected = true;
+            const reader = new EnergyAppModbusFaultTolerantReader(candidate, this.connectionHealth);
+            this.modbusInstances.set(unitId, candidate);
+            this.faultTolerantReaders.set(unitId, reader);
             this.connectionHealth.recordSuccess();
             this.recordOpen();
-            console.log(`Connection attempt to ${host}:${port} unit ${unitId} succeeded (opens=${this.openCount}, closes=${this.closeCount}, current=${this.currentlyOpen})`);
-            return true;
         }
-        catch (error) {
-            console.error(`Connection attempt to ${host}:${port} failed: ${error}`);
-            return false;
+        catch (err) {
+            if (candidate) {
+                try {
+                    await candidate.disconnect();
+                }
+                catch { /* ignore */ }
+            }
+            this.modbusInstances.delete(unitId);
+            this.faultTolerantReaders.delete(unitId);
+            throw err;
+        }
+    }
+    /**
+     * Close the Modbus instance for a single unit. Idempotent. Caller must hold the
+     * connection lock.
+     */
+    async _closeUnit(unitId) {
+        const instance = this.modbusInstances.get(unitId);
+        const wasOpen = instance !== undefined;
+        this.modbusInstances.delete(unitId);
+        this.faultTolerantReaders.delete(unitId);
+        this.discoveredModelsByUnit.delete(unitId);
+        if (instance) {
+            try {
+                await instance.disconnect();
+            }
+            catch { /* ignore */ }
         }
+        if (wasOpen)
+            this.recordClose();
+    }
+    /**
+     * 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.
+     */
+    withConnectionLock(fn) {
+        const run = this.operationChain.then(fn, fn);
+        this.operationChain = run.catch(() => undefined);
+        return run;
     }
     recordOpen() {
         this.openCount++;
-        this.currentlyOpen++;
+        const expected = this.modbusInstances.size;
+        const delta = this.openCount - this.closeCount;
+        if (delta > expected) {
+            console.error(`SunspecModbusClient: open/close imbalance — ` +
+                `opens=${this.openCount}, closes=${this.closeCount}, instances=${expected}. ` +
+                `This indicates a code path bypassing the connection lock — please investigate.`);
+        }
     }
     recordClose() {
         this.closeCount++;
-        if (this.currentlyOpen > 0) {
-            this.currentlyOpen--;
-        }
-        else {
-            console.warn(`SunspecModbusClient: closeCount incremented while currentlyOpen was 0 — possible double-close`);
+        if (this.closeCount > this.openCount) {
+            console.warn(`SunspecModbusClient: closeCount=${this.closeCount} exceeded openCount=${this.openCount} — possible double-close`);
         }
     }
     /**
-     * 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() {
-        return { opens: this.openCount, closes: this.closeCount, currentlyOpen: this.currentlyOpen };
+        return { opens: this.openCount, closes: this.closeCount, openUnits: this.modbusInstances.size };
+    }
+    /**
+     * Get the EnergyAppModbusInstance for a unit, throwing if it isn't open.
+     */
+    getInstance(unitId) {
+        const inst = this.modbusInstances.get(unitId);
+        if (!inst)
+            throw new Error(`Modbus instance for unit ${unitId} not initialized — call connect(host, port, ${unitId}) first`);
+        return inst;
+    }
+    /**
+     * Get the fault-tolerant reader for a unit, throwing if it isn't open.
+     */
+    getReader(unitId) {
+        const reader = this.faultTolerantReaders.get(unitId);
+        if (!reader)
+            throw new Error(`Fault-tolerant reader for unit ${unitId} not initialized — call connect(host, port, ${unitId}) first`);
+        return reader;
+    }
+    /**
+     * Get (or create) the discovered-models map for a unit.
+     */
+    getModelsMap(unitId) {
+        let m = this.discoveredModelsByUnit.get(unitId);
+        if (!m) {
+            m = new Map();
+            this.discoveredModelsByUnit.set(unitId, m);
+        }
+        return m;
     }
     /**
      * Enable or disable automatic reconnection
@@ -196,16 +382,14 @@ export class SunspecModbusClient {
     /**
      * Detect the base address and addressing mode (0-based or 1-based) for SunSpec
      */
-    async detectSunspecBaseAddress(customBaseAddress) {
-        if (!this.modbusClient) {
-            throw new Error('Modbus client not initialized');
-        }
+    async detectSunspecBaseAddress(unitId, customBaseAddress) {
+        const instance = this.getInstance(unitId);
         // If custom base address provided, try it first (1-based, then 0-based variant)
         if (customBaseAddress !== undefined) {
             console.log(`Detect models for custom base address '${customBaseAddress}' ...`);
             // Try 0-based at custom address
             try {
-                const sunspecId = await this.modbusClient.readRegisterStringValue(customBaseAddress, 2);
+                const sunspecId = await instance.readRegisterStringValue(customBaseAddress, 2);
                 if (sunspecId.includes('SunS')) {
                     console.log(`Detected 0-based addressing mode (base address: ${customBaseAddress})`);
                     return {
@@ -220,7 +404,7 @@ export class SunspecModbusClient {
             }
             // Try 1-based at custom address (customBaseAddress + 1)
             try {
-                const sunspecId = await this.modbusClient.readRegisterStringValue(customBaseAddress + 1, 2);
+                const sunspecId = await instance.readRegisterStringValue(customBaseAddress + 1, 2);
                 if (sunspecId.includes('SunS')) {
                     console.log(`Detected 1-based addressing mode (base address: ${customBaseAddress + 1})`);
                     return {
@@ -237,7 +421,7 @@ export class SunspecModbusClient {
         else {
             // Try 1-based addressing first (most common)
             try {
-                const sunspecId = await this.modbusClient.readRegisterStringValue(40001, 2);
+                const sunspecId = await instance.readRegisterStringValue(40001, 2);
                 if (sunspecId.includes('SunS')) {
                     console.log('Detected 1-based addressing mode (base address: 40001)');
                     return {
@@ -252,7 +436,7 @@ export class SunspecModbusClient {
             }
             // Try 0-based addressing
             try {
-                const sunspecId = await this.modbusClient.readRegisterStringValue(40000, 2);
+                const sunspecId = await instance.readRegisterStringValue(40000, 2);
                 if (sunspecId.includes('SunS')) {
                     console.log('Detected 0-based addressing mode (base address: 40000)');
                     return {
@@ -272,27 +456,22 @@ export class SunspecModbusClient {
         throw new Error(`Device is not SunSpec compliant - "SunS" identifier not found at addresses ${addressesChecked}`);
     }
     /**
-     * Discover all available Sunspec models
+     * Discover all available Sunspec models for a unit
      * Automatically detects base address (40000 or 40001) and scans from there
      */
-    async discoverModels(customBaseAddress) {
-        if (!this.connected) {
-            throw new Error('Not connected to Modbus device');
-        }
-        this.discoveredModels.clear();
+    async discoverModels(unitId, customBaseAddress) {
+        const instance = this.getInstance(unitId);
+        const models = this.getModelsMap(unitId);
+        models.clear();
         const maxAddress = 50000; // Safety limit
         let currentAddress = 0;
-        console.log('Starting Sunspec model discovery...');
+        console.log(`Starting Sunspec model discovery for unit ${unitId}...`);
         try {
             // Detect the base address and addressing mode
-            const addressInfo = await this.detectSunspecBaseAddress(customBaseAddress);
+            const addressInfo = await this.detectSunspecBaseAddress(unitId, customBaseAddress);
             currentAddress = addressInfo.nextAddress;
             while (currentAddress < maxAddress) {
-                // Read model ID and length
-                if (!this.modbusClient) {
-                    throw new Error('Modbus client not initialized');
-                }
-                const buffer = await this.modbusClient.readHoldingRegisters(currentAddress, 2);
+                const buffer = await instance.readHoldingRegisters(currentAddress, 2);
                 const modelData = [buffer.readUInt16BE(0), buffer.readUInt16BE(2)];
                 if (!modelData || modelData.length < 2) {
                     console.log(`No data at address ${currentAddress}, ending discovery`);
@@ -311,23 +490,23 @@ export class SunspecModbusClient {
                     address: currentAddress,
                     length: modelLength
                 };
-                this.discoveredModels.set(modelId, model);
-                console.log(`Discovered Model ${modelId} at address ${currentAddress} with length ${modelLength}`);
+                models.set(modelId, model);
+                console.log(`Discovered Model ${modelId} at address ${currentAddress} with length ${modelLength} (unit ${unitId})`);
                 // Jump to next model: current address + 2 (header) + model length
                 currentAddress = currentAddress + 2 + modelLength;
             }
         }
         catch (error) {
-            console.error(`Error during model discovery at address ${currentAddress}: ${error}`);
+            console.error(`Error during model discovery at address ${currentAddress} (unit ${unitId}): ${error}`);
         }
-        console.log(`Discovery complete. Found ${this.discoveredModels.size} models`);
-        return this.discoveredModels;
+        console.log(`Discovery complete for unit ${unitId}. Found ${models.size} models`);
+        return models;
     }
     /**
-     * Find a specific model by ID
+     * Find a specific model by ID for a given unit
      */
-    findModel(modelId) {
-        return this.discoveredModels.get(modelId);
+    findModel(unitId, modelId) {
+        return this.discoveredModelsByUnit.get(unitId)?.get(modelId);
     }
     /**
      * Check if a value is "unimplemented" according to Sunspec specification
@@ -403,17 +582,15 @@ export class SunspecModbusClient {
      * Read an entire model's register block in a single Modbus call.
      * Returns a Buffer containing all registers for the model.
      */
-    async readModelBlock(model) {
-        if (!this.faultTolerantReader) {
-            throw new Error('Fault-tolerant reader not initialized');
-        }
+    async readModelBlock(unitId, model) {
+        const reader = this.getReader(unitId);
         // Read model.length + 2 registers: the 2-register header (ID + length) plus all data registers.
         // This way buffer offsets match the convention used throughout: offset 0 = model ID,
         // offset 1 = model length, offset 2 = first data register, etc.
         const totalRegisters = model.length + 2;
-        const result = await this.faultTolerantReader.readHoldingRegisters(model.address, totalRegisters);
+        const result = await reader.readHoldingRegisters(model.address, totalRegisters);
         if (!result.success || !result.value) {
-            throw new Error(`Failed to read model block ${model.id} at address ${model.address}: ${result.error?.message || 'Unknown error'}`);
+            throw new Error(`Failed to read model block ${model.id} at address ${model.address} (unit ${unitId}): ${result.error?.message || 'Unknown error'}`);
         }
         this.connectionHealth.recordSuccess();
         return result.value;
@@ -438,12 +615,10 @@ export class SunspecModbusClient {
     /**
      * Helper to read register value(s) using the fault-tolerant reader with data type conversion
      */
-    async readRegisterValue(address, quantity = 1, dataType) {
-        if (!this.faultTolerantReader) {
-            throw new Error('Fault-tolerant reader not initialized');
-        }
+    async readRegisterValue(unitId, address, quantity = 1, dataType) {
+        const reader = this.getReader(unitId);
         try {
-            const result = await this.faultTolerantReader.readHoldingRegisters(address, quantity);
+            const result = await reader.readHoldingRegisters(address, quantity);
             // Check if the read was successful
             if (!result.success || !result.value) {
                 throw new Error(`Failed to read register at address ${address}: ${result.error?.message || 'Unknown error'}`);
@@ -464,10 +639,8 @@ export class SunspecModbusClient {
     /**
      * Helper to write register value(s)
      */
-    async writeRegisterValue(address, value, dataType = 'uint16') {
-        if (!this.modbusClient) {
-            throw new Error('Modbus client not initialized');
-        }
+    async writeRegisterValue(unitId, address, value, dataType = 'uint16') {
+        const instance = this.getInstance(unitId);
         try {
             // Convert value to array of register values
             let registerValues;
@@ -496,9 +669,9 @@ export class SunspecModbusClient {
                 }
             }
             // Write to holding registers
-            await this.modbusClient.writeMultipleRegisters(address, registerValues);
+            await instance.writeMultipleRegisters(address, registerValues);
             this.connectionHealth.recordSuccess();
-            console.log(`Successfully wrote value ${value} to register ${address}`);
+            console.log(`Successfully wrote value ${value} to register ${address} (unit ${unitId})`);
             return true;
         }
         catch (error) {
@@ -510,23 +683,23 @@ export class SunspecModbusClient {
     /**
      * Read inverter data from Model 101 (Single Phase) / Model 103 (Three Phase)
      */
-    async readInverterData() {
-        const model = this.findModel(SunspecModelId.Inverter3Phase);
+    async readInverterData(unitId) {
+        const model = this.findModel(unitId, SunspecModelId.Inverter3Phase);
         if (!model) {
-            console.log('Inverter model 103 not found, trying single phase model 101');
-            const singlePhaseModel = this.findModel(SunspecModelId.InverterSinglePhase);
+            console.debug(`Inverter model 103 not found on unit ${unitId}, trying single phase model 101`);
+            const singlePhaseModel = this.findModel(unitId, SunspecModelId.InverterSinglePhase);
             if (!singlePhaseModel) {
-                console.error('No inverter model found');
+                console.error(`No inverter model found on unit ${unitId}`);
                 return null;
             }
             console.warn('IMPORTANT: Working with single-phase inverter, but 3-phase is expected!');
-            return this.readSinglePhaseInverterData(singlePhaseModel);
+            return this.readSinglePhaseInverterData(unitId, singlePhaseModel);
         }
-        console.log(`Found 3-phase inverter model 103 at address ${model.address} with length ${model.length}`);
+        console.debug(`Found 3-phase inverter model 103 at address ${model.address} with length ${model.length} (unit ${unitId})`);
         try {
             // Read entire model block in a single Modbus call
-            console.log(`Reading Inverter Data from Model ${model.id} at base address: ${model.address}`);
-            const buffer = await this.readModelBlock(model);
+            console.debug(`Reading Inverter Data from Model ${model.id} at base address: ${model.address} (unit ${unitId})`);
+            const buffer = await this.readModelBlock(unitId, model);
             // Extract all scale factors from buffer
             const scaleFactors = this.extractInverterScaleFactors(buffer);
             // Extract raw values from buffer
@@ -607,11 +780,11 @@ export class SunspecModbusClient {
     /**
      * Read single phase inverter data (Model 101)
      */
-    async readSinglePhaseInverterData(model) {
+    async readSinglePhaseInverterData(unitId, model) {
         try {
-            console.log(`Reading Single-Phase Inverter Data from Model 101 at base address: ${model.address}`);
+            console.debug(`Reading Single-Phase Inverter Data from Model 101 at base address: ${model.address} (unit ${unitId})`);
             // Read entire model block in a single Modbus call
-            const buffer = await this.readModelBlock(model);
+            const buffer = await this.readModelBlock(unitId, model);
             // Extract scale factors from buffer
             const scaleFactors = {
                 A_SF: this.extractValue(buffer, 6, 'int16'),
@@ -760,18 +933,18 @@ export class SunspecModbusClient {
         this.logRegisterRead(160, 5, 'DCWH_SF', scaleFactors.DCWH_SF, 'int16');
         return scaleFactors;
     }
-    async readMPPTScaleFactors() {
-        const model = this.findModel(SunspecModelId.MPPT);
+    async readMPPTScaleFactors(unitId) {
+        const model = this.findModel(unitId, SunspecModelId.MPPT);
         if (!model) {
-            console.log('MPPT model 160 not found');
+            console.debug(`MPPT model 160 not found on unit ${unitId}`);
             return null;
         }
         try {
-            const buffer = await this.readModelBlock(model);
+            const buffer = await this.readModelBlock(unitId, model);
             return this.extractMPPTScaleFactors(buffer);
         }
         catch (error) {
-            console.error(`Error reading MPPT scale factors: ${error}`);
+            console.error(`Error reading MPPT scale factors (unit ${unitId}): ${error}`);
             return null;
         }
     }
@@ -797,7 +970,7 @@ export class SunspecModbusClient {
             this.isUnimplementedValue(dcCurrentRaw, 'uint16') &&
             this.isUnimplementedValue(dcVoltageRaw, 'uint16') &&
             this.isUnimplementedValue(dcPowerRaw, 'uint16')) {
-            console.log(`MPPT module ${moduleId} appears to be unconnected (all values are 0xFFFF)`);
+            console.debug(`MPPT module ${moduleId} appears to be unconnected (all values are 0xFFFF)`);
             return null;
         }
         const temperatureScaleFactor = -1;
@@ -832,52 +1005,52 @@ export class SunspecModbusClient {
     /**
      * Read MPPT data from Model 160
      */
-    async readMPPTData(moduleId = 1) {
-        const model = this.findModel(SunspecModelId.MPPT);
+    async readMPPTData(unitId, moduleId = 1) {
+        const model = this.findModel(unitId, SunspecModelId.MPPT);
         if (!model) {
-            console.log('MPPT model 160 not found');
+            console.debug(`MPPT model 160 not found on unit ${unitId}`);
             return null;
         }
         try {
             // Read entire model block in a single Modbus call
-            const buffer = await this.readModelBlock(model);
+            const buffer = await this.readModelBlock(unitId, model);
             const scaleFactors = this.extractMPPTScaleFactors(buffer);
             return this.extractMPPTModuleData(buffer, model, moduleId, scaleFactors);
         }
         catch (error) {
-            console.error(`Error reading MPPT data for module ${moduleId}: ${error}`);
+            console.error(`Error reading MPPT data for module ${moduleId} (unit ${unitId}): ${error}`);
             return null;
         }
     }
     /**
      * Read all MPPT strings from Model 160 (Multiple MPPT)
      */
-    async readAllMPPTData() {
+    async readAllMPPTData(unitId) {
         const mpptData = [];
-        const model = this.findModel(SunspecModelId.MPPT);
+        const model = this.findModel(unitId, SunspecModelId.MPPT);
         if (!model) {
-            console.log('MPPT model 160 not found');
+            console.debug(`MPPT model 160 not found on unit ${unitId}`);
             return [];
         }
         try {
             // Read entire model block in a single Modbus call
-            const buffer = await this.readModelBlock(model);
+            const buffer = await this.readModelBlock(unitId, model);
             const scaleFactors = this.extractMPPTScaleFactors(buffer);
             // Read the module count from register 8
             let moduleCount = 4; // Default fallback value
             const count = this.extractValue(buffer, 8, 'uint16');
             if (!this.isUnimplementedValue(count, 'uint16') && count > 0 && count <= 20) {
                 moduleCount = count;
-                console.log(`MPPT module count from register 8: ${moduleCount}`);
+                console.debug(`MPPT module count from register 8: ${moduleCount}`);
             }
             else {
-                console.log(`Invalid or unimplemented module count (${count}), using default: ${moduleCount}`);
+                console.debug(`Invalid or unimplemented module count (${count}), using default: ${moduleCount}`);
             }
             // Extract each MPPT module from the same buffer
             for (let i = 1; i <= moduleCount; i++) {
                 try {
                     const data = this.extractMPPTModuleData(buffer, model, i, scaleFactors);
-                    console.log(`MPPT ${i} has id ${data?.id} (${data?.stringId}) with ${data?.dcPower}W`);
+                    console.debug(`MPPT ${i} has id ${data?.id} (${data?.stringId}) with ${data?.dcPower}W`);
                     if (data &&
                         (data.dcCurrent !== undefined ||
                             data.dcVoltage !== undefined ||
@@ -1022,16 +1195,16 @@ export class SunspecModbusClient {
     /**
      * Read battery base data from Model 802 (Battery Base)
      */
-    async readBatteryBaseData() {
-        const model = this.findModel(SunspecModelId.BatteryBase);
+    async readBatteryBaseData(unitId) {
+        const model = this.findModel(unitId, SunspecModelId.BatteryBase);
         if (!model) {
-            console.log('Battery Base model 802 not found');
+            console.debug(`Battery Base model 802 not found on unit ${unitId}`);
             return null;
         }
-        console.log(`Reading Battery Base Data from Model 802 at base address: ${model.address}`);
+        console.debug(`Reading Battery Base Data from Model 802 at base address: ${model.address} (unit ${unitId})`);
         try {
             // Read entire model block in a single Modbus call
-            const buffer = await this.readModelBlock(model);
+            const buffer = await this.readModelBlock(unitId, model);
             // Extract scale factors from buffer (offsets 52-63)
             const sf = this.extractBatteryBaseScaleFactors(buffer);
             // Extract raw values from buffer
@@ -1160,27 +1333,27 @@ export class SunspecModbusClient {
     /**
      * Read battery data from Model 124 (Basic Storage) with fallback to Model 802 / Model 803
      */
-    async readBatteryData() {
+    async readBatteryData(unitId) {
         // Try Model 124 first (Basic Storage Controls)
-        let model = this.findModel(SunspecModelId.Battery);
+        let model = this.findModel(unitId, SunspecModelId.Battery);
         // Fall back to other battery models if needed
         if (!model) {
-            model = this.findModel(SunspecModelId.BatteryBase);
+            model = this.findModel(unitId, SunspecModelId.BatteryBase);
         }
         if (!model) {
-            model = this.findModel(SunspecModelId.BatteryControl);
+            model = this.findModel(unitId, SunspecModelId.BatteryControl);
         }
         if (!model) {
-            console.log('No battery model found');
+            console.debug(`No battery model found on unit ${unitId}`);
             return null;
         }
-        console.log(`Reading Battery Data from Model ${model.id} at base address: ${model.address}`);
+        console.debug(`Reading Battery Data from Model ${model.id} at base address: ${model.address} (unit ${unitId})`);
         try {
             if (model.id === 124) {
                 // Model 124: Basic Storage Controls
-                console.log('Using Model 124 (Basic Storage Controls)');
+                console.debug('Using Model 124 (Basic Storage Controls)');
                 // Read entire model block in a single Modbus call
-                const buffer = await this.readModelBlock(model);
+                const buffer = await this.readModelBlock(unitId, model);
                 // Extract scale factors from buffer (offsets 18-25)
                 const scaleFactors = {
                     WChaMax_SF: this.extractValue(buffer, 18, 'int16'),
@@ -1268,20 +1441,20 @@ export class SunspecModbusClient {
                 // Calculate charge/discharge power if rates are available
                 if (data.inWRte !== undefined && data.wChaMax !== undefined) {
                     data.chargePower = (data.inWRte / 100) * data.wChaMax;
-                    console.log(`Calculated Charge Power: (inWRte: ${data.inWRte}, wChaMax: ${data.wChaMax}) ${data.chargePower?.toFixed(2)} W`);
+                    console.debug(`Calculated Charge Power: (inWRte: ${data.inWRte}, wChaMax: ${data.wChaMax}) ${data.chargePower?.toFixed(2)} W`);
                 }
                 if (data.outWRte !== undefined && data.wChaMax !== undefined) {
                     // Assuming WDisChaMax is similar to WChaMax for simplicity
                     data.dischargePower = Math.abs((data.outWRte / 100) * data.wChaMax);
-                    console.log(`Calculated Discharge Power (inWRte: ${data.outWRte}, wChaMax: ${data.wChaMax}): ${data.dischargePower?.toFixed(2)} W`);
+                    console.debug(`Calculated Discharge Power (inWRte: ${data.outWRte}, wChaMax: ${data.wChaMax}): ${data.dischargePower?.toFixed(2)} W`);
                 }
                 console.debug('[Model 124] Battery Data:', data);
                 return data;
             }
             else if (model.id === 802) {
                 // Model 802: Battery Base
-                console.log('Using Model 802 (Battery Base)');
-                const baseData = await this.readBatteryBaseData();
+                console.debug('Using Model 802 (Battery Base)');
+                const baseData = await this.readBatteryBaseData(unitId);
                 if (!baseData) {
                     return null;
                 }
@@ -1317,7 +1490,7 @@ export class SunspecModbusClient {
             }
             else {
                 // Handle other battery models (803) if needed
-                console.log(`Battery Model ${model.id} reading not yet implemented`);
+                console.debug(`Battery Model ${model.id} reading not yet implemented`);
                 return {
                     blockNumber: model.id,
                     blockAddress: model.address,
@@ -1333,55 +1506,55 @@ export class SunspecModbusClient {
     /**
      * Write battery control settings to Model 124
      */
-    async writeBatteryControls(controls) {
-        const model = this.findModel(SunspecModelId.Battery);
+    async writeBatteryControls(unitId, controls) {
+        const model = this.findModel(unitId, SunspecModelId.Battery);
         if (!model) {
-            console.error('Battery model 124 not found');
+            console.error(`Battery model 124 not found on unit ${unitId}`);
             return false;
         }
         const baseAddr = model.address;
-        console.log(`Writing Battery Controls to Model 124 at base address: ${baseAddr}`);
+        console.log(`Writing Battery Controls to Model 124 at base address: ${baseAddr} (unit ${unitId})`);
         try {
             // Write storage control mode (Register 5)
             if (controls.storCtlMod !== undefined) {
-                await this.writeRegisterValue(baseAddr + 5, controls.storCtlMod, 'uint16');
+                await this.writeRegisterValue(unitId, baseAddr + 5, controls.storCtlMod, 'uint16');
                 console.log(`Set storage control mode to 0x${controls.storCtlMod.toString(16)}`);
             }
             // Write charge source setting (Register 17)
             if (controls.chaGriSet !== undefined) {
-                await this.writeRegisterValue(baseAddr + 17, controls.chaGriSet, 'uint16');
+                await this.writeRegisterValue(unitId, baseAddr + 17, controls.chaGriSet, 'uint16');
                 console.log(`Set charge source to ${controls.chaGriSet === SunspecChargeSource.GRID ? 'GRID' : 'PV'}`);
             }
             // Write maximum charge power (Register 2) - needs scale factor
             if (controls.wChaMax !== undefined) {
                 const scaleFactorAddr = baseAddr + 18;
-                const scaleFactor = await this.readRegisterValue(scaleFactorAddr, 1, 'int16');
+                const scaleFactor = await this.readRegisterValue(unitId, scaleFactorAddr, 1, 'int16');
                 const scaledValue = Math.round(controls.wChaMax / Math.pow(10, scaleFactor));
-                await this.writeRegisterValue(baseAddr + 2, scaledValue, 'uint16');
+                await this.writeRegisterValue(unitId, baseAddr + 2, scaledValue, 'uint16');
                 console.log(`Set max charge power to ${controls.wChaMax}W (scaled: ${scaledValue})`);
             }
             // Write charge rate (Register 13) - needs scale factor
             if (controls.inWRte !== undefined) {
                 const scaleFactorAddr = baseAddr + 25;
-                const scaleFactor = await this.readRegisterValue(scaleFactorAddr, 1, 'int16');
+                const scaleFactor = await this.readRegisterValue(unitId, scaleFactorAddr, 1, 'int16');
                 const scaledValue = Math.round(controls.inWRte / Math.pow(10, scaleFactor));
-                await this.writeRegisterValue(baseAddr + 13, scaledValue, 'int16');
+                await this.writeRegisterValue(unitId, baseAddr + 13, scaledValue, 'int16');
                 console.log(`Set charge rate to ${controls.inWRte}% (scaled: ${scaledValue})`);
             }
             // Write discharge rate (Register 12) - needs scale factor
             if (controls.outWRte !== undefined) {
                 const scaleFactorAddr = baseAddr + 25;
-                const scaleFactor = await this.readRegisterValue(scaleFactorAddr, 1, 'int16');
+                const scaleFactor = await this.readRegisterValue(unitId, scaleFactorAddr, 1, 'int16');
                 const scaledValue = Math.round(controls.outWRte / Math.pow(10, scaleFactor));
-                await this.writeRegisterValue(baseAddr + 12, scaledValue, 'int16');
+                await this.writeRegisterValue(unitId, baseAddr + 12, scaledValue, 'int16');
                 console.log(`Set discharge rate to ${controls.outWRte}% (scaled: ${scaledValue})`);
             }
             // Write minimum reserve percentage (Register 7) - needs scale factor
             if (controls.minRsvPct !== undefined) {
                 const scaleFactorAddr = baseAddr + 21;
-                const scaleFactor = await this.readRegisterValue(scaleFactorAddr, 1, 'int16');
+                const scaleFactor = await this.readRegisterValue(unitId, scaleFactorAddr, 1, 'int16');
                 const scaledValue = Math.round(controls.minRsvPct / Math.pow(10, scaleFactor));
-                await this.writeRegisterValue(baseAddr + 7, scaledValue, 'uint16');
+                await this.writeRegisterValue(unitId, baseAddr + 7, scaledValue, 'uint16');
                 console.log(`Set minimum reserve to ${controls.minRsvPct}% (scaled: ${scaledValue})`);
             }
             console.log('Battery controls written successfully');
@@ -1395,7 +1568,7 @@ export class SunspecModbusClient {
     /**
      * Set battery storage mode (simplified interface)
      */
-    async setStorageMode(mode) {
+    async setStorageMode(unitId, mode) {
         let storCtlMod;
         switch (mode) {
             case SunspecStorageMode.CHARGE:
@@ -1419,29 +1592,29 @@ export class SunspecModbusClient {
                 return false;
         }
         console.log(`Setting storage mode to ${mode} (control bits: 0x${storCtlMod.toString(16)})`);
-        return this.writeBatteryControls({ storCtlMod });
+        return this.writeBatteryControls(unitId, { storCtlMod });
     }
     /**
      * Enable or disable grid charging
      */
-    async enableGridCharging(enable) {
+    async enableGridCharging(unitId, enable) {
         const chaGriSet = enable ? SunspecChargeSource.GRID : SunspecChargeSource.PV;
-        console.log(`${enable ? 'Enabling' : 'Disabling'} grid charging`);
-        return this.writeBatteryControls({ chaGriSet });
+        console.log(`${enable ? 'Enabling' : 'Disabling'} grid charging on unit ${unitId}`);
+        return this.writeBatteryControls(unitId, { chaGriSet });
     }
     /**
      * Read battery control settings from Model 124 (Basic Storage Controls)
      */
-    async readBatteryControls() {
-        const model = this.findModel(SunspecModelId.Battery);
+    async readBatteryControls(unitId) {
+        const model = this.findModel(unitId, SunspecModelId.Battery);
         if (!model) {
-            console.log('Battery model 124 not found');
+            console.log(`Battery model 124 not found on unit ${unitId}`);
             return null;
         }
-        console.log(`Reading Battery Controls from Model 124 at base address: ${model.address}`);
+        console.log(`Reading Battery Controls from Model 124 at base address: ${model.address} (unit ${unitId})`);
         try {
             // Read entire model block in a single Modbus call
-            const buffer = await this.readModelBlock(model);
+            const buffer = await this.readModelBlock(unitId, model);
             // Extract scale factors from buffer
             const scaleFactors = {
                 WChaMax_SF: this.extractValue(buffer, 18, 'int16'),
@@ -1480,22 +1653,22 @@ export class SunspecModbusClient {
     /**
      * Read meter data from Model 201 (Single Phase) / Model 203 (Three Phase) / Model 204 (Split Phase)
      */
-    async readMeterData() {
-        let model = this.findModel(SunspecModelId.Meter3Phase);
+    async readMeterData(unitId) {
+        let model = this.findModel(unitId, SunspecModelId.Meter3Phase);
         if (!model) {
-            model = this.findModel(SunspecModelId.MeterWye);
+            model = this.findModel(unitId, SunspecModelId.MeterWye);
         }
         if (!model) {
-            model = this.findModel(SunspecModelId.MeterSinglePhase);
+            model = this.findModel(unitId, SunspecModelId.MeterSinglePhase);
         }
         if (!model) {
-            console.log('No meter model found');
+            console.debug(`No meter model found on unit ${unitId}`);
             return null;
         }
-        console.log(`Reading Meter Data from Model ${model.id} at base address: ${model.address}`);
+        console.debug(`Reading Meter Data from Model ${model.id} at base address: ${model.address} (unit ${unitId})`);
         try {
             // Different meter models have different register offsets
-            console.log(`Meter is Model ${model.id}`);
+            console.debug(`Meter is Model ${model.id}`);
             let powerOffset;
             let powerSFOffset;
             let freqOffset;
@@ -1505,7 +1678,7 @@ export class SunspecModbusClient {
             let energySFOffset;
             switch (model.id) {
                 case 203: // 3-phase meter (Delta)
-                    console.log('Using Model 203 (3-Phase Meter Delta) offsets');
+                    console.debug('Using Model 203 (3-Phase Meter Delta) offsets');
                     powerOffset = 18; // W - Total Real Power (int16)
                     powerSFOffset = 22; // W_SF - Power scale factor
                     freqOffset = 16; // Hz - Frequency (uint16)
@@ -1515,7 +1688,7 @@ export class SunspecModbusClient {
                     energySFOffset = 54; // TotWh_SF - Total Energy scale factor
                     break;
                 case 204: // 3-phase meter (Wye)
-                    console.log('Using Model 204 (3-Phase Meter Wye) offsets');
+                    console.debug('Using Model 204 (3-Phase Meter Wye) offsets');
                     powerOffset = 18; // W - Total Real Power (int16)
                     powerSFOffset = 22; // W_SF - Power scale factor
                     freqOffset = 16; // Hz - Frequency (uint16)
@@ -1526,7 +1699,7 @@ export class SunspecModbusClient {
                     break;
                 case 201: // Single-phase meter
                 default:
-                    console.log('Using Model 201 (Single-Phase Meter) offsets');
+                    console.debug('Using Model 201 (Single-Phase Meter) offsets');
                     powerOffset = 18; // W - Total Real Power (int16)
                     powerSFOffset = 22; // W_SF - Power scale factor
                     freqOffset = 16; // Hz - Frequency (uint16)
@@ -1536,7 +1709,7 @@ export class SunspecModbusClient {
                     energySFOffset = 54; // TotWh_SF - Total Energy scale factor
             }
             // Read entire model block in a single Modbus call
-            const buffer = await this.readModelBlock(model);
+            const buffer = await this.readModelBlock(unitId, model);
             // Extract scale factors from buffer
             const powerSF = this.extractValue(buffer, powerSFOffset, 'int16');
             const freqSF = this.extractValue(buffer, freqSFOffset, 'int16');
@@ -1574,16 +1747,16 @@ export class SunspecModbusClient {
     /**
      * Read common block data (Model 1)
      */
-    async readCommonBlock() {
-        const model = this.findModel(SunspecModelId.Common);
+    async readCommonBlock(unitId) {
+        const model = this.findModel(unitId, SunspecModelId.Common);
         if (!model) {
-            console.error('Common block model not found');
+            console.error(`Common block model not found on unit ${unitId}`);
             return null;
         }
-        console.log(`Reading Common Block - Model address: ${model.address}`);
+        console.log(`Reading Common Block - Model address: ${model.address} (unit ${unitId})`);
         try {
             // Read entire model block in a single Modbus call
-            const buffer = await this.readModelBlock(model);
+            const buffer = await this.readModelBlock(unitId, model);
             // Common block offsets are relative to the model start (after ID and Length header,
             // but readModelBlock reads from model.address which includes the data area).
             // The offsets below are relative to the data start within the model block.
@@ -1620,24 +1793,24 @@ export class SunspecModbusClient {
     /**
      * Get serial number from device
      */
-    async getSerialNumber() {
-        const commonData = await this.readCommonBlock();
+    async getSerialNumber(unitId) {
+        const commonData = await this.readCommonBlock(unitId);
         return commonData?.serialNumber;
     }
     /**
-     * Check if connected
+     * Check if a specific unit is connected on this network device
      */
-    isConnected() {
-        return this.connected;
+    isConnected(unitId) {
+        return this.modbusInstances.has(unitId);
     }
     /**
-     * Check if connection is healthy
+     * Check if a specific unit's connection is healthy
      */
-    isHealthy() {
-        return this.connected && this.connectionHealth.isHealthy();
+    isHealthy(unitId) {
+        return this.modbusInstances.has(unitId) && this.connectionHealth.isHealthy();
     }
     /**
-     * Get connection health details
+     * Get connection health details (shared across all units on this network device)
      */
     getConnectionHealth() {
         return this.connectionHealth;
@@ -1645,15 +1818,15 @@ export class SunspecModbusClient {
     /**
      * Read inverter settings from Model 121 (Inverter Settings)
      */
-    async readInverterSettings() {
-        const model = this.findModel(SunspecModelId.Settings);
+    async readInverterSettings(unitId) {
+        const model = this.findModel(unitId, SunspecModelId.Settings);
         if (!model) {
-            console.log('Settings model 121 not found');
+            console.debug(`Settings model 121 not found on unit ${unitId}`);
             return null;
         }
         try {
             // Read entire model block in a single Modbus call
-            const buffer = await this.readModelBlock(model);
+            const buffer = await this.readModelBlock(unitId, model);
             // Extract scale factors from buffer (offsets 22-31)
             const scaleFactors = {
                 WMax_SF: this.extractValue(buffer, 22, 'int16'),
@@ -1737,15 +1910,15 @@ export class SunspecModbusClient {
     /**
      * Read inverter controls from Model 123 (Immediate Inverter Controls)
      */
-    async readInverterControls() {
-        const model = this.findModel(SunspecModelId.Controls);
+    async readInverterControls(unitId) {
+        const model = this.findModel(unitId, SunspecModelId.Controls);
         if (!model) {
-            console.log('Controls model 123 not found');
+            console.log(`Controls model 123 not found on unit ${unitId}`);
             return null;
         }
         try {
             // Read entire model block in a single Modbus call
-            const buffer = await this.readModelBlock(model);
+            const buffer = await this.readModelBlock(unitId, model);
             // Extract scale factors from buffer (offsets 21-23)
             const scaleFactors = {
                 WMaxLimPct_SF: this.extractValue(buffer, 21, 'int16'),
@@ -1832,27 +2005,28 @@ export class SunspecModbusClient {
     /**
      * Write Block 121 - Inverter Basic Settings
      */
-    async writeInverterSettings(settings) {
-        const model = this.findModel(SunspecModelId.Settings);
+    async writeInverterSettings(unitId, settings) {
+        const model = this.findModel(unitId, SunspecModelId.Settings);
         if (!model) {
-            console.error('Settings model 121 not found');
+            console.error(`Settings model 121 not found on unit ${unitId}`);
             return false;
         }
         const baseAddr = model.address;
         try {
+            const instance = this.getInstance(unitId);
             // For each setting, write the value if provided
             // Note: This is a simplified implementation. In production, you'd batch writes
-            if (settings.WMax !== undefined && this.modbusClient) {
+            if (settings.WMax !== undefined) {
                 // Need to read scale factor first if not provided
-                const sfBuffer = await this.modbusClient.readHoldingRegisters(baseAddr + 22, 1);
+                const sfBuffer = await instance.readHoldingRegisters(baseAddr + 22, 1);
                 const scaleFactor = sfBuffer.readInt16BE(0);
                 const scaledValue = Math.round(settings.WMax / Math.pow(10, scaleFactor));
                 // Writing registers needs to be implemented in EnergyAppModbusInstance
                 // For now, log the write operation
                 console.log(`Would write value ${scaledValue} to register ${baseAddr}`);
             }
-            if (settings.VRef !== undefined && this.modbusClient) {
-                const sfBuffer = await this.modbusClient.readHoldingRegisters(baseAddr + 23, 1);
+            if (settings.VRef !== undefined) {
+                const sfBuffer = await instance.readHoldingRegisters(baseAddr + 23, 1);
                 const scaleFactor = sfBuffer.readInt16BE(0);
                 const scaledValue = Math.round(settings.VRef / Math.pow(10, scaleFactor));
                 console.log(`Would write value ${scaledValue} to register ${baseAddr + 1}`);
@@ -1869,41 +2043,41 @@ export class SunspecModbusClient {
     /**
      * Write inverter controls to Model 123 (Immediate Inverter Controls)
      */
-    async writeInverterControls(controls) {
-        const model = this.findModel(SunspecModelId.Controls);
+    async writeInverterControls(unitId, controls) {
+        const model = this.findModel(unitId, SunspecModelId.Controls);
         if (!model) {
-            console.error('Controls model 123 not found');
+            console.error(`Controls model 123 not found on unit ${unitId}`);
             return false;
         }
         const baseAddr = model.address;
         try {
             // Connection control (Register 2)
             if (controls.Conn !== undefined) {
-                await this.writeRegisterValue(baseAddr + 2, controls.Conn, 'uint16');
+                await this.writeRegisterValue(unitId, baseAddr + 2, controls.Conn, 'uint16');
                 console.log(`Set connection control to ${controls.Conn}`);
             }
             // Power limit control (Register 3) - needs scale factor
             if (controls.WMaxLimPct !== undefined) {
-                const scaleFactor = await this.readRegisterValue(baseAddr + 21, 1, 'int16');
+                const scaleFactor = await this.readRegisterValue(unitId, baseAddr + 21, 1, 'int16');
                 const scaledValue = Math.round(controls.WMaxLimPct / Math.pow(10, scaleFactor));
-                await this.writeRegisterValue(baseAddr + 3, scaledValue, 'uint16');
+                await this.writeRegisterValue(unitId, baseAddr + 3, scaledValue, 'uint16');
                 console.log(`Set power limit to ${controls.WMaxLimPct}% (scaled: ${scaledValue})`);
             }
             // Throttle enable/disable (Register 7)
             if (controls.WMaxLim_Ena !== undefined) {
-                await this.writeRegisterValue(baseAddr + 7, controls.WMaxLim_Ena, 'uint16');
+                await this.writeRegisterValue(unitId, baseAddr + 7, controls.WMaxLim_Ena, 'uint16');
                 console.log(`Set throttle enable to ${controls.WMaxLim_Ena}`);
             }
             // Power factor control (Register 8) - needs scale factor
             if (controls.OutPFSet !== undefined) {
-                const scaleFactor = await this.readRegisterValue(baseAddr + 22, 1, 'int16');
+                const scaleFactor = await this.readRegisterValue(unitId, baseAddr + 22, 1, 'int16');
                 const scaledValue = Math.round(controls.OutPFSet / Math.pow(10, scaleFactor));
-                await this.writeRegisterValue(baseAddr + 8, scaledValue, 'int16');
+                await this.writeRegisterValue(unitId, baseAddr + 8, scaledValue, 'int16');
                 console.log(`Set power factor to ${controls.OutPFSet} (scaled: ${scaledValue})`);
             }
             // Power factor enable/disable (Register 12)
             if (controls.OutPFSet_Ena !== undefined) {
-                await this.writeRegisterValue(baseAddr + 12, controls.OutPFSet_Ena, 'uint16');
+                await this.writeRegisterValue(unitId, baseAddr + 12, controls.OutPFSet_Ena, 'uint16');
                 console.log(`Set PF enable to ${controls.OutPFSet_Ena}`);
             }
             console.log('Inverter controls written successfully');
@@ -1924,21 +2098,21 @@ export class SunspecModbusClient {
      * @param limitW - Power limit in Watts, or null to remove the limit
      * @returns true if successful, false otherwise
      */
-    async setFeedInLimit(limitW) {
+    async setFeedInLimit(unitId, limitW) {
         if (limitW === null) {
             // Remove limit: disable WMaxLim_Ena
-            console.log('Removing feed-in limit (disabling WMaxLim_Ena)');
-            return this.writeInverterControls({ WMaxLim_Ena: SunspecEnableControl.DISABLED });
+            console.log(`Removing feed-in limit (disabling WMaxLim_Ena) on unit ${unitId}`);
+            return this.writeInverterControls(unitId, { WMaxLim_Ena: SunspecEnableControl.DISABLED });
         }
         // Read WMax from Model 121 to compute percentage
-        const settings = await this.readInverterSettings();
+        const settings = await this.readInverterSettings(unitId);
         if (!settings || !settings.WMax) {
-            console.error('Cannot set feed-in limit: unable to read WMax from Model 121');
+            console.error(`Cannot set feed-in limit on unit ${unitId}: unable to read WMax from Model 121`);
             return false;
         }
         const pct = (limitW / settings.WMax) * 100;
-        console.log(`Setting feed-in limit to ${limitW}W (${pct.toFixed(2)}% of WMax ${settings.WMax}W)`);
-        return this.writeInverterControls({
+        console.log(`Setting feed-in limit to ${limitW}W (${pct.toFixed(2)}% of WMax ${settings.WMax}W) on unit ${unitId}`);
+        return this.writeInverterControls(unitId, {
             WMaxLimPct: pct,
             WMaxLim_Ena: SunspecEnableControl.ENABLED
         });