@enyo-energy/sunspec-sdk 0.0.88 → 0.0.90

package/dist/cjs/sunspec-devices.cjs

@@ -351,15 +351,15 @@ class SunspecInverter extends BaseSunspecDevice {
      * non-fault read).
      */
     static OPERATING_FAULT_THRESHOLD = 3;
-    storage;
     consecutiveOperatingFaults = 0;
+    // In-memory only — never persisted. See SunspecInverterErrorState.
     errorState = { activeCodes: [], lastStatus: 'healthy' };
     snapshotService;
     // Whether we've emitted a status update at least once since (re)connecting.
-    // The persisted errorState can diverge from what the core actually shows
-    // (e.g. a faulted that was never cleared while our local state reads
-    // healthy), so we force one re-assert of the current status on the first
-    // successful read of each session to converge the core.
+    // Our fresh in-memory errorState can diverge from what the core still shows
+    // across an SDK restart (e.g. a faulted the core persisted while our local
+    // state reads healthy), so we force one re-assert of the current status on
+    // the first successful read of each session to converge the core.
     statusReassertedThisSession = false;
     constructor(energyApp, name, networkDevice, sunspecClient, applianceManager, unitId = 1, port = 502, baseAddress = 40000, capabilities = [], retryConfig, appliance, useTls) {
         super(energyApp, name, networkDevice, sunspecClient, applianceManager, unitId, port, baseAddress, retryConfig, appliance, useTls);
@@ -438,23 +438,13 @@ class SunspecInverter extends BaseSunspecDevice {
         if (mpptModel) {
             console.log(`MPPT model found for inverter ${this.networkDevice.hostname}`);
         }
-        await this.loadErrorState();
         // Fresh session: force the next successful read to re-assert the true
         // status so a stale faulted in the core is cleared on (re)start.
         this.statusReassertedThisSession = false;
         this.startDataBusListening();
-        // Cold-start recovery: if the persisted state says we were stuck in
-        // connection_lost but connect() just succeeded (we read commonBlock,
-        // settings, controls and MPPT above), the Modbus path is provably
-        // healthy. Clear the stale fault and emit Healthy via the same hook
-        // the in-process reconnect path uses.
-        if (this.errorState.lastStatus === 'connection_lost') {
-            await this.onConnectionRestored();
-        }
     }
     async disconnect() {
         this.stopDataBusListening();
-        await this.removePersistedErrorState();
         if (this.applianceId) {
             try {
                 await this.applianceManager.updateApplianceState(this.applianceId, enyo_appliance_js_1.EnyoApplianceConnectionType.Connector, enyo_appliance_js_1.EnyoApplianceStateEnum.Offline);
@@ -621,41 +611,6 @@ class SunspecInverter extends BaseSunspecDevice {
             }
         };
     }
-    storageKey() {
-        return `sunspec-inverter-error-state-${this.applianceId}`;
-    }
-    async loadErrorState() {
-        try {
-            this.storage = this.energyApp.useStorage();
-            const loaded = await this.storage.load(this.storageKey());
-            if (loaded) {
-                this.errorState = loaded;
-                console.log(`Inverter ${this.applianceId}: loaded persisted error state (lastStatus=${loaded.lastStatus}, codes=[${loaded.activeCodes.join(', ')}])`);
-            }
-        }
-        catch (error) {
-            console.error(`Inverter ${this.applianceId}: failed to load persisted error state: ${error}`);
-        }
-    }
-    async persistErrorState() {
-        if (!this.storage)
-            return;
-        try {
-            await this.storage.save(this.storageKey(), this.errorState);
-        }
-        catch (error) {
-            console.error(`Inverter ${this.applianceId}: failed to persist error state: ${error}`);
-        }
-    }
-    async removePersistedErrorState() {
-        const storage = this.storage ?? this.energyApp.useStorage();
-        try {
-            await storage.remove(this.storageKey());
-        }
-        catch (error) {
-            console.error(`Inverter ${this.applianceId}: failed to remove persisted error state: ${error}`);
-        }
-    }
     async detectAndEmitStatusTransition(data, timestamp) {
         if (!this.applianceId || !this.dataBus)
             return;
@@ -702,7 +657,6 @@ class SunspecInverter extends BaseSunspecDevice {
             activeCodes: codeIds,
             lastStatus: newLastStatus,
         };
-        await this.persistErrorState();
     }
     async onConnectionFailure(consecutiveFailures) {
         if (!this.applianceId || !this.dataBus)
@@ -725,7 +679,6 @@ class SunspecInverter extends BaseSunspecDevice {
             activeCodes: [sunspec_interfaces_js_1.SUNSPEC_CONNECTION_LOST_CODE],
             lastStatus: 'connection_lost',
         };
-        await this.persistErrorState();
     }
     async onConnectionRestored() {
         if (!this.applianceId || !this.dataBus)
@@ -739,7 +692,6 @@ class SunspecInverter extends BaseSunspecDevice {
             activeCodes: [],
             lastStatus: 'healthy',
         };
-        await this.persistErrorState();
     }
     /**
      * Compute the currently active feed-in / production limit in Watts from the

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

@@ -137,7 +137,6 @@ export declare class SunspecInverter extends BaseSunspecDevice {
      * non-fault read).
      */
     private static readonly OPERATING_FAULT_THRESHOLD;
-    private storage?;
     private consecutiveOperatingFaults;
     private errorState;
     private snapshotService?;
@@ -179,10 +178,6 @@ export declare class SunspecInverter extends BaseSunspecDevice {
     protected mapVendorEventBit(_registerIndex: 1 | 2 | 3 | 4, _bit: number): EnyoApplianceErrorCode | undefined;
     private hasErrorSetChanged;
     private buildStatusMessage;
-    private storageKey;
-    private loadErrorState;
-    private persistErrorState;
-    private removePersistedErrorState;
     private detectAndEmitStatusTransition;
     protected onConnectionFailure(consecutiveFailures: number): Promise<void>;
     protected onConnectionRestored(): Promise<void>;

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

@@ -148,11 +148,14 @@ export declare enum SunspecInverterEvent1 {
  */
 export declare const SUNSPEC_CONNECTION_LOST_CODE = "modbus_connection_lost";
 /**
- * Persisted error state for a SunSpec inverter, written to storage so the
- * status reporter can detect transitions across process restarts and avoid
- * re-emitting `faulted` for the same already-known errors.
- */
-export interface SunspecInverterPersistedErrorState {
+ * In-memory error/status-tracking state for a SunSpec inverter. Held only for
+ * the lifetime of the process (never written to storage) so the status reporter
+ * can detect transitions and avoid re-emitting `faulted` for the same
+ * already-known errors on every poll. Because it is not persisted, a transient
+ * error clears the moment the next read no longer sees it, and a restart never
+ * resurrects a stale fault.
+ */
+export interface SunspecInverterErrorState {
     evt1?: number;
     evt2?: number;
     evtVnd1?: number;

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

@@ -103,6 +103,14 @@ class SunspecModbusClient {
     // Serializes connection-state transitions so concurrent callers cannot open duplicate
     // sockets for the same unit ID while one is still alive.
     operationChain = Promise.resolve();
+    // Serializes data transactions per unit so only one Modbus request is in flight on a
+    // unit's socket at a time. Reads go through the fault-tolerant reader and writes go
+    // straight to the instance — two paths to the same socket. Without this, a concurrent
+    // poll + control write cross their responses on the wire and the transport raises
+    // "OutOfSync: request fc and response fc does not match". Kept separate from
+    // operationChain (the connection lock) to avoid re-entrancy: a transaction never waits
+    // on a connect/disconnect, and vice versa.
+    txChains = new Map();
     constructor(energyApp) {
         this.energyApp = energyApp;
         this.connectionHealth = new EnergyAppModbusConnectionHealth_js_1.EnergyAppModbusConnectionHealth();
@@ -333,6 +341,22 @@ class SunspecModbusClient {
         this.operationChain = run.catch(() => undefined);
         return run;
     }
+    /**
+     * Run `fn` with exclusive access to a single unit's socket, so at most one Modbus
+     * transaction is in flight per unit at a time. Subsequent calls for the same unit queue
+     * behind any in-flight one; different units run in parallel (independent chains). A
+     * rejected `fn` does not poison the chain for later callers.
+     *
+     * IMPORTANT: only wrap leaf transactions (a single reader/instance read or write). Never
+     * call this around a method that itself calls a runExclusive-wrapped method for the same
+     * unit — that re-enters the unit's chain and deadlocks.
+     */
+    runExclusive(unitId, fn) {
+        const prev = this.txChains.get(unitId) ?? Promise.resolve();
+        const run = prev.then(fn, fn);
+        this.txChains.set(unitId, run.catch(() => undefined));
+        return run;
+    }
     recordOpen() {
         this.openCount++;
         const expected = this.modbusInstances.size;
@@ -433,7 +457,7 @@ class SunspecModbusClient {
             console.log(`Detect models for custom base address '${customBaseAddress}' ...`);
             // Try 0-based at custom address
             try {
-                const sunspecId = await instance.readRegisterStringValue(customBaseAddress, 2);
+                const sunspecId = await this.runExclusive(unitId, () => instance.readRegisterStringValue(customBaseAddress, 2));
                 if (sunspecId.includes('SunS')) {
                     console.log(`Detected 0-based addressing mode (base address: ${customBaseAddress})`);
                     return {
@@ -448,7 +472,7 @@ class SunspecModbusClient {
             }
             // Try 1-based at custom address (customBaseAddress + 1)
             try {
-                const sunspecId = await instance.readRegisterStringValue(customBaseAddress + 1, 2);
+                const sunspecId = await this.runExclusive(unitId, () => instance.readRegisterStringValue(customBaseAddress + 1, 2));
                 if (sunspecId.includes('SunS')) {
                     console.log(`Detected 1-based addressing mode (base address: ${customBaseAddress + 1})`);
                     return {
@@ -465,7 +489,7 @@ class SunspecModbusClient {
         else {
             // Try 1-based addressing first (most common)
             try {
-                const sunspecId = await instance.readRegisterStringValue(40001, 2);
+                const sunspecId = await this.runExclusive(unitId, () => instance.readRegisterStringValue(40001, 2));
                 if (sunspecId.includes('SunS')) {
                     console.log('Detected 1-based addressing mode (base address: 40001)');
                     return {
@@ -480,7 +504,7 @@ class SunspecModbusClient {
             }
             // Try 0-based addressing
             try {
-                const sunspecId = await instance.readRegisterStringValue(40000, 2);
+                const sunspecId = await this.runExclusive(unitId, () => instance.readRegisterStringValue(40000, 2));
                 if (sunspecId.includes('SunS')) {
                     console.log('Detected 0-based addressing mode (base address: 40000)');
                     return {
@@ -531,7 +555,7 @@ class SunspecModbusClient {
         currentAddress = addressInfo.nextAddress;
         try {
             while (currentAddress < maxAddress) {
-                const buffer = await instance.readHoldingRegisters(currentAddress, 2);
+                const buffer = await this.runExclusive(unitId, () => instance.readHoldingRegisters(currentAddress, 2));
                 const modelData = [buffer.readUInt16BE(0), buffer.readUInt16BE(2)];
                 if (!modelData || modelData.length < 2) {
                     console.debug(`No data at address ${currentAddress}, ending discovery`);
@@ -673,15 +697,20 @@ class SunspecModbusClient {
         // length 124, which combined with the 2-register header (126) exceeds the limit,
         // so chunk reads larger than 125 registers and concatenate the results.
         const MAX_REGISTERS_PER_READ = 125;
-        const chunks = [];
-        for (let offset = 0; offset < totalRegisters; offset += MAX_REGISTERS_PER_READ) {
-            const quantity = Math.min(MAX_REGISTERS_PER_READ, totalRegisters - offset);
-            const result = await reader.readHoldingRegisters(model.address + offset, quantity);
-            if (!result.success || !result.value) {
-                throw new Error(`Failed to read model block ${model.id} at address ${model.address + offset} (unit ${unitId}): ${result.error?.message || 'Unknown error'}`);
+        // Serialize the whole (possibly multi-chunk) block read on the unit's socket so a
+        // concurrent poll or control write can't interleave its frames between our chunks.
+        const chunks = await this.runExclusive(unitId, async () => {
+            const acc = [];
+            for (let offset = 0; offset < totalRegisters; offset += MAX_REGISTERS_PER_READ) {
+                const quantity = Math.min(MAX_REGISTERS_PER_READ, totalRegisters - offset);
+                const result = await reader.readHoldingRegisters(model.address + offset, quantity);
+                if (!result.success || !result.value) {
+                    throw new Error(`Failed to read model block ${model.id} at address ${model.address + offset} (unit ${unitId}): ${result.error?.message || 'Unknown error'}`);
+                }
+                acc.push(result.value);
             }
-            chunks.push(result.value);
-        }
+            return acc;
+        });
         this.connectionHealth.recordSuccess();
         return chunks.length === 1 ? chunks[0] : Buffer.concat(chunks);
     }
@@ -708,7 +737,7 @@ class SunspecModbusClient {
     async readRegisterValue(unitId, address, quantity = 1, dataType) {
         const reader = this.getReader(unitId);
         try {
-            const result = await reader.readHoldingRegisters(address, quantity);
+            const result = await this.runExclusive(unitId, () => 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'}`);
@@ -758,8 +787,9 @@ class SunspecModbusClient {
                         break;
                 }
             }
-            // Write to holding registers
-            await instance.writeMultipleRegisters(address, registerValues);
+            // Write to holding registers. Serialized on the unit's socket so the write can't
+            // collide with a concurrent poll's read (which would cross their response frames).
+            await this.runExclusive(unitId, () => instance.writeMultipleRegisters(address, registerValues));
             this.connectionHealth.recordSuccess();
             // Per-register write success — fires for every parameter inside higher-level
             // writers (writeBatteryControls / writeInverterControls). Demoted to debug.
@@ -2375,7 +2405,7 @@ class SunspecModbusClient {
             // Note: This is a simplified implementation. In production, you'd batch writes
             if (settings.WMax !== undefined) {
                 // Need to read scale factor first if not provided
-                const sfBuffer = await instance.readHoldingRegisters(baseAddr + 22, 1);
+                const sfBuffer = await this.runExclusive(unitId, () => 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
@@ -2383,7 +2413,7 @@ class SunspecModbusClient {
                 console.debug(`Would write value ${scaledValue} to register ${baseAddr}`);
             }
             if (settings.VRef !== undefined) {
-                const sfBuffer = await instance.readHoldingRegisters(baseAddr + 23, 1);
+                const sfBuffer = await this.runExclusive(unitId, () => instance.readHoldingRegisters(baseAddr + 23, 1));
                 const scaleFactor = sfBuffer.readInt16BE(0);
                 const scaledValue = Math.round(settings.VRef / Math.pow(10, scaleFactor));
                 console.debug(`Would write value ${scaledValue} to register ${baseAddr + 1}`);

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

@@ -47,6 +47,7 @@ export declare class SunspecModbusClient {
     private openCount;
     private closeCount;
     private operationChain;
+    private txChains;
     constructor(energyApp: EnergyApp);
     /**
      * Connect to a Modbus device unit. Multiple unit IDs on the same network device share this
@@ -107,6 +108,17 @@ export declare class SunspecModbusClient {
      * behind any in-flight one. A rejected `fn` does not poison the chain for later callers.
      */
     private withConnectionLock;
+    /**
+     * Run `fn` with exclusive access to a single unit's socket, so at most one Modbus
+     * transaction is in flight per unit at a time. Subsequent calls for the same unit queue
+     * behind any in-flight one; different units run in parallel (independent chains). A
+     * rejected `fn` does not poison the chain for later callers.
+     *
+     * IMPORTANT: only wrap leaf transactions (a single reader/instance read or write). Never
+     * call this around a method that itself calls a runExclusive-wrapped method for the same
+     * unit — that re-enters the unit's chain and deadlocks.
+     */
+    private runExclusive;
     private recordOpen;
     private recordClose;
     /**

package/dist/cjs/version.cjs

@@ -9,7 +9,7 @@ exports.getSdkVersion = getSdkVersion;
 /**
  * Current version of the enyo Energy App SDK.
  */
-exports.SDK_VERSION = '0.0.88';
+exports.SDK_VERSION = '0.0.90';
 /**
  * Gets the current SDK version.
  * @returns The semantic version string of the SDK

package/dist/cjs/version.d.cts

@@ -5,7 +5,7 @@
 /**
  * Current version of the enyo Energy App SDK.
  */
-export declare const SDK_VERSION = "0.0.88";
+export declare const SDK_VERSION = "0.0.90";
 /**
  * Gets the current SDK version.
  * @returns The semantic version string of the SDK

package/dist/sunspec-devices.d.ts

@@ -137,7 +137,6 @@ export declare class SunspecInverter extends BaseSunspecDevice {
      * non-fault read).
      */
     private static readonly OPERATING_FAULT_THRESHOLD;
-    private storage?;
     private consecutiveOperatingFaults;
     private errorState;
     private snapshotService?;
@@ -179,10 +178,6 @@ export declare class SunspecInverter extends BaseSunspecDevice {
     protected mapVendorEventBit(_registerIndex: 1 | 2 | 3 | 4, _bit: number): EnyoApplianceErrorCode | undefined;
     private hasErrorSetChanged;
     private buildStatusMessage;
-    private storageKey;
-    private loadErrorState;
-    private persistErrorState;
-    private removePersistedErrorState;
     private detectAndEmitStatusTransition;
     protected onConnectionFailure(consecutiveFailures: number): Promise<void>;
     protected onConnectionRestored(): Promise<void>;

package/dist/sunspec-devices.js

@@ -344,15 +344,15 @@ export class SunspecInverter extends BaseSunspecDevice {
      * non-fault read).
      */
     static OPERATING_FAULT_THRESHOLD = 3;
-    storage;
     consecutiveOperatingFaults = 0;
+    // In-memory only — never persisted. See SunspecInverterErrorState.
     errorState = { activeCodes: [], lastStatus: 'healthy' };
     snapshotService;
     // Whether we've emitted a status update at least once since (re)connecting.
-    // The persisted errorState can diverge from what the core actually shows
-    // (e.g. a faulted that was never cleared while our local state reads
-    // healthy), so we force one re-assert of the current status on the first
-    // successful read of each session to converge the core.
+    // Our fresh in-memory errorState can diverge from what the core still shows
+    // across an SDK restart (e.g. a faulted the core persisted while our local
+    // state reads healthy), so we force one re-assert of the current status on
+    // the first successful read of each session to converge the core.
     statusReassertedThisSession = false;
     constructor(energyApp, name, networkDevice, sunspecClient, applianceManager, unitId = 1, port = 502, baseAddress = 40000, capabilities = [], retryConfig, appliance, useTls) {
         super(energyApp, name, networkDevice, sunspecClient, applianceManager, unitId, port, baseAddress, retryConfig, appliance, useTls);
@@ -431,23 +431,13 @@ export class SunspecInverter extends BaseSunspecDevice {
         if (mpptModel) {
             console.log(`MPPT model found for inverter ${this.networkDevice.hostname}`);
         }
-        await this.loadErrorState();
         // Fresh session: force the next successful read to re-assert the true
         // status so a stale faulted in the core is cleared on (re)start.
         this.statusReassertedThisSession = false;
         this.startDataBusListening();
-        // Cold-start recovery: if the persisted state says we were stuck in
-        // connection_lost but connect() just succeeded (we read commonBlock,
-        // settings, controls and MPPT above), the Modbus path is provably
-        // healthy. Clear the stale fault and emit Healthy via the same hook
-        // the in-process reconnect path uses.
-        if (this.errorState.lastStatus === 'connection_lost') {
-            await this.onConnectionRestored();
-        }
     }
     async disconnect() {
         this.stopDataBusListening();
-        await this.removePersistedErrorState();
         if (this.applianceId) {
             try {
                 await this.applianceManager.updateApplianceState(this.applianceId, EnyoApplianceConnectionType.Connector, EnyoApplianceStateEnum.Offline);
@@ -614,41 +604,6 @@ export class SunspecInverter extends BaseSunspecDevice {
             }
         };
     }
-    storageKey() {
-        return `sunspec-inverter-error-state-${this.applianceId}`;
-    }
-    async loadErrorState() {
-        try {
-            this.storage = this.energyApp.useStorage();
-            const loaded = await this.storage.load(this.storageKey());
-            if (loaded) {
-                this.errorState = loaded;
-                console.log(`Inverter ${this.applianceId}: loaded persisted error state (lastStatus=${loaded.lastStatus}, codes=[${loaded.activeCodes.join(', ')}])`);
-            }
-        }
-        catch (error) {
-            console.error(`Inverter ${this.applianceId}: failed to load persisted error state: ${error}`);
-        }
-    }
-    async persistErrorState() {
-        if (!this.storage)
-            return;
-        try {
-            await this.storage.save(this.storageKey(), this.errorState);
-        }
-        catch (error) {
-            console.error(`Inverter ${this.applianceId}: failed to persist error state: ${error}`);
-        }
-    }
-    async removePersistedErrorState() {
-        const storage = this.storage ?? this.energyApp.useStorage();
-        try {
-            await storage.remove(this.storageKey());
-        }
-        catch (error) {
-            console.error(`Inverter ${this.applianceId}: failed to remove persisted error state: ${error}`);
-        }
-    }
     async detectAndEmitStatusTransition(data, timestamp) {
         if (!this.applianceId || !this.dataBus)
             return;
@@ -695,7 +650,6 @@ export class SunspecInverter extends BaseSunspecDevice {
             activeCodes: codeIds,
             lastStatus: newLastStatus,
         };
-        await this.persistErrorState();
     }
     async onConnectionFailure(consecutiveFailures) {
         if (!this.applianceId || !this.dataBus)
@@ -718,7 +672,6 @@ export class SunspecInverter extends BaseSunspecDevice {
             activeCodes: [SUNSPEC_CONNECTION_LOST_CODE],
             lastStatus: 'connection_lost',
         };
-        await this.persistErrorState();
     }
     async onConnectionRestored() {
         if (!this.applianceId || !this.dataBus)
@@ -732,7 +685,6 @@ export class SunspecInverter extends BaseSunspecDevice {
             activeCodes: [],
             lastStatus: 'healthy',
         };
-        await this.persistErrorState();
     }
     /**
      * Compute the currently active feed-in / production limit in Watts from the

package/dist/sunspec-interfaces.d.ts

@@ -148,11 +148,14 @@ export declare enum SunspecInverterEvent1 {
  */
 export declare const SUNSPEC_CONNECTION_LOST_CODE = "modbus_connection_lost";
 /**
- * Persisted error state for a SunSpec inverter, written to storage so the
- * status reporter can detect transitions across process restarts and avoid
- * re-emitting `faulted` for the same already-known errors.
- */
-export interface SunspecInverterPersistedErrorState {
+ * In-memory error/status-tracking state for a SunSpec inverter. Held only for
+ * the lifetime of the process (never written to storage) so the status reporter
+ * can detect transitions and avoid re-emitting `faulted` for the same
+ * already-known errors on every poll. Because it is not persisted, a transient
+ * error clears the moment the next read no longer sees it, and a restart never
+ * resurrects a stale fault.
+ */
+export interface SunspecInverterErrorState {
     evt1?: number;
     evt2?: number;
     evtVnd1?: number;

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

@@ -47,6 +47,7 @@ export declare class SunspecModbusClient {
     private openCount;
     private closeCount;
     private operationChain;
+    private txChains;
     constructor(energyApp: EnergyApp);
     /**
      * Connect to a Modbus device unit. Multiple unit IDs on the same network device share this
@@ -107,6 +108,17 @@ export declare class SunspecModbusClient {
      * behind any in-flight one. A rejected `fn` does not poison the chain for later callers.
      */
     private withConnectionLock;
+    /**
+     * Run `fn` with exclusive access to a single unit's socket, so at most one Modbus
+     * transaction is in flight per unit at a time. Subsequent calls for the same unit queue
+     * behind any in-flight one; different units run in parallel (independent chains). A
+     * rejected `fn` does not poison the chain for later callers.
+     *
+     * IMPORTANT: only wrap leaf transactions (a single reader/instance read or write). Never
+     * call this around a method that itself calls a runExclusive-wrapped method for the same
+     * unit — that re-enters the unit's chain and deadlocks.
+     */
+    private runExclusive;
     private recordOpen;
     private recordClose;
     /**

package/dist/sunspec-modbus-client.js

@@ -98,6 +98,14 @@ export class SunspecModbusClient {
     // Serializes connection-state transitions so concurrent callers cannot open duplicate
     // sockets for the same unit ID while one is still alive.
     operationChain = Promise.resolve();
+    // Serializes data transactions per unit so only one Modbus request is in flight on a
+    // unit's socket at a time. Reads go through the fault-tolerant reader and writes go
+    // straight to the instance — two paths to the same socket. Without this, a concurrent
+    // poll + control write cross their responses on the wire and the transport raises
+    // "OutOfSync: request fc and response fc does not match". Kept separate from
+    // operationChain (the connection lock) to avoid re-entrancy: a transaction never waits
+    // on a connect/disconnect, and vice versa.
+    txChains = new Map();
     constructor(energyApp) {
         this.energyApp = energyApp;
         this.connectionHealth = new EnergyAppModbusConnectionHealth();
@@ -328,6 +336,22 @@ export class SunspecModbusClient {
         this.operationChain = run.catch(() => undefined);
         return run;
     }
+    /**
+     * Run `fn` with exclusive access to a single unit's socket, so at most one Modbus
+     * transaction is in flight per unit at a time. Subsequent calls for the same unit queue
+     * behind any in-flight one; different units run in parallel (independent chains). A
+     * rejected `fn` does not poison the chain for later callers.
+     *
+     * IMPORTANT: only wrap leaf transactions (a single reader/instance read or write). Never
+     * call this around a method that itself calls a runExclusive-wrapped method for the same
+     * unit — that re-enters the unit's chain and deadlocks.
+     */
+    runExclusive(unitId, fn) {
+        const prev = this.txChains.get(unitId) ?? Promise.resolve();
+        const run = prev.then(fn, fn);
+        this.txChains.set(unitId, run.catch(() => undefined));
+        return run;
+    }
     recordOpen() {
         this.openCount++;
         const expected = this.modbusInstances.size;
@@ -428,7 +452,7 @@ export class SunspecModbusClient {
             console.log(`Detect models for custom base address '${customBaseAddress}' ...`);
             // Try 0-based at custom address
             try {
-                const sunspecId = await instance.readRegisterStringValue(customBaseAddress, 2);
+                const sunspecId = await this.runExclusive(unitId, () => instance.readRegisterStringValue(customBaseAddress, 2));
                 if (sunspecId.includes('SunS')) {
                     console.log(`Detected 0-based addressing mode (base address: ${customBaseAddress})`);
                     return {
@@ -443,7 +467,7 @@ export class SunspecModbusClient {
             }
             // Try 1-based at custom address (customBaseAddress + 1)
             try {
-                const sunspecId = await instance.readRegisterStringValue(customBaseAddress + 1, 2);
+                const sunspecId = await this.runExclusive(unitId, () => instance.readRegisterStringValue(customBaseAddress + 1, 2));
                 if (sunspecId.includes('SunS')) {
                     console.log(`Detected 1-based addressing mode (base address: ${customBaseAddress + 1})`);
                     return {
@@ -460,7 +484,7 @@ export class SunspecModbusClient {
         else {
             // Try 1-based addressing first (most common)
             try {
-                const sunspecId = await instance.readRegisterStringValue(40001, 2);
+                const sunspecId = await this.runExclusive(unitId, () => instance.readRegisterStringValue(40001, 2));
                 if (sunspecId.includes('SunS')) {
                     console.log('Detected 1-based addressing mode (base address: 40001)');
                     return {
@@ -475,7 +499,7 @@ export class SunspecModbusClient {
             }
             // Try 0-based addressing
             try {
-                const sunspecId = await instance.readRegisterStringValue(40000, 2);
+                const sunspecId = await this.runExclusive(unitId, () => instance.readRegisterStringValue(40000, 2));
                 if (sunspecId.includes('SunS')) {
                     console.log('Detected 0-based addressing mode (base address: 40000)');
                     return {
@@ -526,7 +550,7 @@ export class SunspecModbusClient {
         currentAddress = addressInfo.nextAddress;
         try {
             while (currentAddress < maxAddress) {
-                const buffer = await instance.readHoldingRegisters(currentAddress, 2);
+                const buffer = await this.runExclusive(unitId, () => instance.readHoldingRegisters(currentAddress, 2));
                 const modelData = [buffer.readUInt16BE(0), buffer.readUInt16BE(2)];
                 if (!modelData || modelData.length < 2) {
                     console.debug(`No data at address ${currentAddress}, ending discovery`);
@@ -668,15 +692,20 @@ export class SunspecModbusClient {
         // length 124, which combined with the 2-register header (126) exceeds the limit,
         // so chunk reads larger than 125 registers and concatenate the results.
         const MAX_REGISTERS_PER_READ = 125;
-        const chunks = [];
-        for (let offset = 0; offset < totalRegisters; offset += MAX_REGISTERS_PER_READ) {
-            const quantity = Math.min(MAX_REGISTERS_PER_READ, totalRegisters - offset);
-            const result = await reader.readHoldingRegisters(model.address + offset, quantity);
-            if (!result.success || !result.value) {
-                throw new Error(`Failed to read model block ${model.id} at address ${model.address + offset} (unit ${unitId}): ${result.error?.message || 'Unknown error'}`);
+        // Serialize the whole (possibly multi-chunk) block read on the unit's socket so a
+        // concurrent poll or control write can't interleave its frames between our chunks.
+        const chunks = await this.runExclusive(unitId, async () => {
+            const acc = [];
+            for (let offset = 0; offset < totalRegisters; offset += MAX_REGISTERS_PER_READ) {
+                const quantity = Math.min(MAX_REGISTERS_PER_READ, totalRegisters - offset);
+                const result = await reader.readHoldingRegisters(model.address + offset, quantity);
+                if (!result.success || !result.value) {
+                    throw new Error(`Failed to read model block ${model.id} at address ${model.address + offset} (unit ${unitId}): ${result.error?.message || 'Unknown error'}`);
+                }
+                acc.push(result.value);
             }
-            chunks.push(result.value);
-        }
+            return acc;
+        });
         this.connectionHealth.recordSuccess();
         return chunks.length === 1 ? chunks[0] : Buffer.concat(chunks);
     }
@@ -703,7 +732,7 @@ export class SunspecModbusClient {
     async readRegisterValue(unitId, address, quantity = 1, dataType) {
         const reader = this.getReader(unitId);
         try {
-            const result = await reader.readHoldingRegisters(address, quantity);
+            const result = await this.runExclusive(unitId, () => 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'}`);
@@ -753,8 +782,9 @@ export class SunspecModbusClient {
                         break;
                 }
             }
-            // Write to holding registers
-            await instance.writeMultipleRegisters(address, registerValues);
+            // Write to holding registers. Serialized on the unit's socket so the write can't
+            // collide with a concurrent poll's read (which would cross their response frames).
+            await this.runExclusive(unitId, () => instance.writeMultipleRegisters(address, registerValues));
             this.connectionHealth.recordSuccess();
             // Per-register write success — fires for every parameter inside higher-level
             // writers (writeBatteryControls / writeInverterControls). Demoted to debug.
@@ -2370,7 +2400,7 @@ export class SunspecModbusClient {
             // Note: This is a simplified implementation. In production, you'd batch writes
             if (settings.WMax !== undefined) {
                 // Need to read scale factor first if not provided
-                const sfBuffer = await instance.readHoldingRegisters(baseAddr + 22, 1);
+                const sfBuffer = await this.runExclusive(unitId, () => 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
@@ -2378,7 +2408,7 @@ export class SunspecModbusClient {
                 console.debug(`Would write value ${scaledValue} to register ${baseAddr}`);
             }
             if (settings.VRef !== undefined) {
-                const sfBuffer = await instance.readHoldingRegisters(baseAddr + 23, 1);
+                const sfBuffer = await this.runExclusive(unitId, () => instance.readHoldingRegisters(baseAddr + 23, 1));
                 const scaleFactor = sfBuffer.readInt16BE(0);
                 const scaledValue = Math.round(settings.VRef / Math.pow(10, scaleFactor));
                 console.debug(`Would write value ${scaledValue} to register ${baseAddr + 1}`);

package/dist/version.d.ts

@@ -5,7 +5,7 @@
 /**
  * Current version of the enyo Energy App SDK.
  */
-export declare const SDK_VERSION = "0.0.88";
+export declare const SDK_VERSION = "0.0.90";
 /**
  * Gets the current SDK version.
  * @returns The semantic version string of the SDK

package/dist/version.js

@@ -5,7 +5,7 @@
 /**
  * Current version of the enyo Energy App SDK.
  */
-export const SDK_VERSION = '0.0.88';
+export const SDK_VERSION = '0.0.90';
 /**
  * Gets the current SDK version.
  * @returns The semantic version string of the SDK

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enyo-energy/sunspec-sdk",
-  "version": "0.0.88",
+  "version": "0.0.90",
   "description": "enyo Energy Sunspec SDK",
   "type": "module",
   "main": "dist/index.js",