nodejs-poolcontroller 8.4.0 → 8.4.1

package/controller/comms/messages/config/SecurityMessage.ts

@@ -20,20 +20,44 @@ import { sys, SecurityRole } from "../../../Equipment";
 
 export class SecurityMessage {
     public static process(msg: Inbound): void {
-        var role: SecurityRole;
-        switch (msg.extractPayloadByte(1)) {
-            case 0:
-                sys.security.enabled = (msg.extractPayloadByte(3) & 1) === 1;
-                sys.security.roles.clear();
-                break;
+        const item = msg.extractPayloadByte(1, 0);
+        if (item === 0) {
+            // Item 0 is always the admin role and marks a full role block refresh.
+            sys.security.roles.clear();
         }
-        if ((msg.extractPayloadByte(3) & 2) === 2) {
-            role = sys.security.roles.getItemById(msg.extractPayloadByte(1) + 1, true);
-            role.name = msg.extractPayloadString(4, 16);
-            role.timeout = msg.extractPayloadByte(20);
-            role.flag1 = msg.extractPayloadByte(2);
-            role.flag2 = msg.extractPayloadByte(3);
-            role.pin = msg.extractPayloadByte(21).toString() + msg.extractPayloadByte(22).toString() + msg.extractPayloadByte(23).toString() + msg.extractPayloadByte(24).toString();
+
+        const roleId = item + 1;
+        const roleName = msg.extractPayloadString(5, 16).trim();
+        const pinNumber = ((msg.extractPayloadByte(3, 0) & 0xFF) << 8) | (msg.extractPayloadByte(4, 0) & 0xFF);
+        const timeout = msg.extractPayloadByte(25, 0);
+        const permissionsBytes = [
+            msg.extractPayloadByte(21, 0),
+            msg.extractPayloadByte(22, 0),
+            msg.extractPayloadByte(23, 0),
+            msg.extractPayloadByte(24, 0)
+        ];
+        const permissionsMask =
+            ((permissionsBytes[0] & 0xFF) * 16777216) +
+            ((permissionsBytes[1] & 0xFF) * 65536) +
+            ((permissionsBytes[2] & 0xFF) * 256) +
+            (permissionsBytes[3] & 0xFF);
+        const hasRoleData = roleName.length > 0 || pinNumber > 0 || timeout > 0 || permissionsMask > 0;
+
+        if (hasRoleData) {
+            const role: SecurityRole = sys.security.roles.getItemById(roleId, true);
+            role.name = roleName;
+            role.timeout = timeout;
+            role.flag1 = msg.extractPayloadByte(2, 0);
+            role.flag2 = msg.extractPayloadByte(24, 0);
+            role.pin = pinNumber.toString().padStart(4, '0');
+            role.permissionsMask = permissionsMask;
+            role.permissionsBytes = permissionsBytes;
+            if (item === 0) {
+                sys.security.enabledByte = permissionsBytes[3];
+                sys.security.enabled = (permissionsBytes[3] & 0x80) === 0x80;
+            }
+        } else {
+            sys.security.roles.removeItemById(roleId);
         }
         msg.isProcessed = true;
     }

package/controller/comms/messages/status/EquipmentStateMessage.ts

@@ -27,61 +27,7 @@ import { BodyTempState, ScheduleState, State, state } from '../../../State';
 import { ExternalMessage } from '../config/ExternalMessage';
 import { Inbound, Message, Outbound } from '../Messages';
 
-// Cache for pending Wireless Action 184 commands to correlate with state changes
-// Key: targetId, Value: { state: 0|1, timestamp: number }
-const pendingAction184Commands: Map<number, { state: number, timestamp: number }> = new Map();
-const PENDING_COMMAND_TTL_MS = 10000; // 10 second TTL for pending commands
-
-function findActiveCircuitTargetIdOwner(targetId: number, excludeCircuitId?: number): Circuit | null {
-    if (typeof targetId !== 'number' || targetId <= 0) return null;
-    for (let i = 0; i < sys.circuits.length; i++) {
-        const circ = sys.circuits.getItemByIndex(i);
-        if (!circ || !circ.isActive) continue;
-        if (typeof excludeCircuitId === 'number' && circ.id === excludeCircuitId) continue;
-        // `targetId` may be undefined on circuits that haven't learned it yet.
-        if (typeof (circ as any).targetId === 'number' && (circ as any).targetId === targetId) return circ;
-    }
-    return null;
-}
-
 export class EquipmentStateMessage {
-    // Called when Action 2 status shows a circuit state change
-    // Checks if there's a pending Wireless command that matches
-    public static checkPendingAction184Learning(circuitId: number, isOn: boolean): void {
-        const now = Date.now();
-        const targetState = isOn ? 1 : 0;
-        
-        // Clean up expired entries
-        for (const [targetId, entry] of pendingAction184Commands.entries()) {
-            if (now - entry.timestamp > PENDING_COMMAND_TTL_MS) {
-                pendingAction184Commands.delete(targetId);
-            }
-        }
-        
-        // Look for pending commands that match this state
-        for (const [targetId, entry] of pendingAction184Commands.entries()) {
-            if (entry.state === targetState) {
-                // This pending command matches the state change
-                // Check if this circuit needs a targetId
-                const circ = sys.circuits.getItemById(circuitId, false);
-                if (circ && circ.isActive && (typeof circ.targetId === 'undefined' || circ.targetId === 0)) {
-                    const owner = findActiveCircuitTargetIdOwner(targetId, circuitId);
-                    if (owner) {
-                        logger.warn(
-                            `v3.004+ Action 184: Refusing to learn duplicate targetId ${targetId} for circuit ${circuitId} (${circ.name || 'unnamed'}); ` +
-                            `already owned by circuit ${owner.id} (${owner.name || 'unnamed'}).`
-                        );
-                        pendingAction184Commands.delete(targetId);
-                        return;
-                    }
-                    logger.debug(`v3.004+ Action 184: Learned Target ID ${targetId} for circuit ${circuitId} (${circ.name || 'unnamed'}) [Wireless command correlation]`);
-                    circ.targetId = targetId;
-                    pendingAction184Commands.delete(targetId);
-                    return;
-                }
-            }
-        }
-    }
     private static initIntelliCenter(msg: Inbound) {
         sys.controllerType = ControllerType.IntelliCenter;
         sys.equipment.maxSchedules = 100;
@@ -216,11 +162,6 @@ export class EquipmentStateMessage {
                     pc & 0x02 ? msg.extractPayloadByte(17) : 0x00, pc & 0x02 ? msg.extractPayloadByte(18) : 0x00,
                     pc & 0x04 ? msg.extractPayloadByte(19) : 0x00, pc & 0x04 ? msg.extractPayloadByte(20) : 0x00);
                 sys.equipment.setEquipmentIds();
-                // v3.004+: As soon as firmware>=3.0 is known, seed known targetIds so the UI has stable defaults
-                // before any user toggles occur. These are best-effort and will be overridden by learned values.
-                if (sys.equipment.isIntellicenterV3 && typeof (sys.board.circuits as any)?.seedKnownV3TargetIds === 'function') {
-                    (sys.board.circuits as any).seedKnownV3TargetIds();
-                }
             }
             else return;
         }
@@ -679,154 +620,6 @@ export class EquipmentStateMessage {
                 break;
             }
             case 184: {
-                // v3.004+ Action 184 - Circuit state broadcast / control
-                // OCP broadcasts this for circuit state changes AND periodically for status.
-                // Wireless remote sends this to control circuits.
-                // 
-                // Payload structure (10 bytes):
-                //   Bytes 0-1: Channel/context ID (104,143 = default, or circuit-specific like 108,225)
-                //   Byte 2: Sequence number
-                //   Byte 3: Format (255 = command, 0 = status)
-                //   Bytes 4-5: Target ID (unique circuit identifier, e.g., 168,237 = Spa, 108,225 = Pool)
-                //   Byte 6: State (0=OFF, 1=ON, 255=idle for body status)
-                //   Bytes 7-9: Additional data (usually 0)
-                //
-                // KEY PATTERN: When channel ID (bytes 0-1) equals Target ID (bytes 4-5), 
-                // this identifies a specific circuit (e.g., Pool uses 108,225 for both).
-                //
-                // Learning strategies:
-                // 1. Channel = Target pattern: strong identification
-                // 2. State correlation: match broadcast state with circuit states
-                // 3. Only ONE circuit matches: definitive mapping
-                if (sys.controllerType === ControllerType.IntelliCenter && 
-                    sys.equipment.isIntellicenterV3 && 
-                    msg.payload.length >= 10) {
-                    
-                    const channelIdHi = msg.extractPayloadByte(0);
-                    const channelIdLo = msg.extractPayloadByte(1);
-                    const channelId = channelIdHi * 256 + channelIdLo;
-                    const targetIdHi = msg.extractPayloadByte(4);
-                    const targetIdLo = msg.extractPayloadByte(5);
-                    const targetId = targetIdHi * 256 + targetIdLo;
-                    const circuitState = msg.extractPayloadByte(6);
-                    
-                    // Process from OCP broadcasts (source=16) AND Wireless commands (source=36)
-                    // Skip idle status (byte 6 = 255) and body status target (212,182 = 0xD4B6 = 54454)
-                    // Learning from Wireless: When Wireless sends targetId X to OCP with state Y,
-                    // and OCP ACKs, we know targetId X controls the circuit that changed to state Y.
-                    const isFromOCP = msg.source === 16;
-                    const isFromWireless = msg.source === 36 && msg.dest === 16; // Wireless→OCP command
-                    
-                    // Cache Wireless commands for later correlation with state changes
-                    // This helps learn targetId when OCP doesn't broadcast the state=1 message
-                    if (isFromWireless && circuitState !== 255 && targetId !== 54454) {
-                        pendingAction184Commands.set(targetId, { state: circuitState, timestamp: Date.now() });
-                        logger.debug(`v3.004+ Action 184: Cached pending Wireless command - Target ${targetId}, State=${circuitState === 1 ? 'ON' : 'OFF'}`);
-                    }
-                    
-                    if ((isFromOCP || isFromWireless) && circuitState !== 255 && targetId !== 54454) {
-                        const sourceDesc = isFromOCP ? 'OCP broadcast' : 'Wireless command';
-                        const isOn = circuitState === 1;
-                        
-                        // Strategy 1: Channel = Target pattern (e.g., Pool circuit 6 uses 108,225 for both)
-                        // This is a strong signal - the circuit "owns" this channel
-                        if (channelId === targetId) {
-                            // Find body circuit with this pattern
-                            for (let i = 0; i < sys.bodies.length; i++) {
-                                const body = sys.bodies.getItemByIndex(i);
-                                if (body.isActive && typeof body.circuit === 'number' && body.circuit > 0) {
-                                    const sbody = state.temps.bodies.getItemById(body.id);
-                                    // For channel=target, trust it even if states don't match perfectly
-                                    // (OCP might broadcast before state is updated)
-                                    const circ = sys.circuits.getItemById(body.circuit, false);
-                                    if (circ && circ.isActive && (typeof circ.targetId === 'undefined' || circ.targetId === 0)) {
-                                        // Only learn if we don't have one yet - channel=target is reliable
-                                        if (sbody && sbody.isOn === isOn) {
-                                            const owner = findActiveCircuitTargetIdOwner(targetId, body.circuit);
-                                            if (!owner) {
-                                            logger.silly(`v3.004+ Action 184: Learned Target ID ${targetId} (${targetIdHi},${targetIdLo}) for body ${body.id} circuit ${body.circuit} (${circ.name || 'unnamed'}) [channel=target pattern]`);
-                                            circ.targetId = targetId;
-                                            } else {
-                                                logger.warn(
-                                                    `v3.004+ Action 184: Refusing to learn duplicate targetId ${targetId} for body circuit ${body.circuit} (${circ.name || 'unnamed'}); ` +
-                                                    `already owned by circuit ${owner.id} (${owner.name || 'unnamed'}).`
-                                                );
-                                            }
-                                        }
-                                    }
-                                }
-                            }
-                        }
-                        
-                        // Strategy 2: State correlation - find circuits matching this state
-                        // Count how many circuits match to avoid ambiguity
-                        // PRIORITY: Circuits without targetId that match state
-                        let matchingCircuitsNoTargetId: { id: number, name: string }[] = [];
-                        let matchingCircuitsWithTargetId: { id: number, name: string }[] = [];
-                        
-                        // Check body circuits first (Spa=circuit 1, Pool=circuit 6 in shared systems)
-                        for (let i = 0; i < sys.bodies.length; i++) {
-                            const body = sys.bodies.getItemByIndex(i);
-                            if (body.isActive && typeof body.circuit === 'number' && body.circuit > 0) {
-                                const sbody = state.temps.bodies.getItemById(body.id);
-                                const circ = sys.circuits.getItemById(body.circuit, false);
-                                if (sbody && sbody.isOn === isOn && circ && circ.isActive) {
-                                    if (typeof circ.targetId === 'undefined' || circ.targetId === 0) {
-                                        matchingCircuitsNoTargetId.push({ id: body.circuit, name: circ.name || `Body ${body.id}` });
-                                    } else if (circ.targetId !== targetId) {
-                                        matchingCircuitsWithTargetId.push({ id: body.circuit, name: circ.name || `Body ${body.id}` });
-                                    }
-                                }
-                            }
-                        }
-                        
-                        // Also check regular circuits
-                        for (let i = 0; i < sys.circuits.length; i++) {
-                            const circ = sys.circuits.getItemByIndex(i);
-                            if (circ.isActive) {
-                                const cstate = state.circuits.getItemById(circ.id);
-                                if (cstate && cstate.isOn === isOn) {
-                                    // Avoid duplicate if already counted as body circuit
-                                    if (!matchingCircuitsNoTargetId.find(m => m.id === circ.id) &&
-                                        !matchingCircuitsWithTargetId.find(m => m.id === circ.id)) {
-                                        if (typeof circ.targetId === 'undefined' || circ.targetId === 0) {
-                                            matchingCircuitsNoTargetId.push({ id: circ.id, name: circ.name || `Circuit ${circ.id}` });
-                                        } else if (circ.targetId !== targetId) {
-                                            matchingCircuitsWithTargetId.push({ id: circ.id, name: circ.name || `Circuit ${circ.id}` });
-                                        }
-                                    }
-                                }
-                            }
-                        }
-                        
-                        // Strategy 3: Only ONE circuit without targetId matches - definitive mapping
-                        // This is the best case: we know exactly which circuit needs learning
-                        if (matchingCircuitsNoTargetId.length === 1) {
-                            const match = matchingCircuitsNoTargetId[0];
-                            const circ = sys.circuits.getItemById(match.id, false);
-                            if (circ) {
-                                const owner = findActiveCircuitTargetIdOwner(targetId, match.id);
-                                if (!owner) {
-                                    logger.silly(`v3.004+ Action 184: Learned Target ID ${targetId} (${targetIdHi},${targetIdLo}) for circuit ${match.id} (${match.name}) [unique unassigned match]`);
-                                    circ.targetId = targetId;
-                                } else {
-                                    logger.warn(
-                                        `v3.004+ Action 184: Refusing to learn duplicate targetId ${targetId} for circuit ${match.id} (${match.name}); ` +
-                                        `already owned by circuit ${owner.id} (${owner.name || 'unnamed'}).`
-                                    );
-                                }
-                            }
-                        } else if (matchingCircuitsNoTargetId.length > 1) {
-                            // Multiple unassigned circuits match - can't determine which
-                            logger.silly(`v3.004+ Action 184: Target ${targetId} (state=${isOn ? 'ON' : 'OFF'}) matches ${matchingCircuitsNoTargetId.length} unassigned circuits (${matchingCircuitsNoTargetId.map(m => m.name).join(', ')}) - waiting for unique match`);
-                        } else if (matchingCircuitsNoTargetId.length === 0 && matchingCircuitsWithTargetId.length === 0) {
-                            // No matching circuits - might be a feature or virtual circuit
-                            logger.debug(`v3.004+ Action 184: Target ${targetId} (state=${isOn ? 'ON' : 'OFF'}) has no matching circuits - possibly feature or group`);
-                        }
-                        
-                        logger.debug(`v3.004+ Action 184 (${sourceDesc}): Channel=${channelId}, Target=${targetId} (${targetIdHi},${targetIdLo}), State=${isOn ? 'ON' : 'OFF'}`);
-                    }
-                }
                 msg.isProcessed = true;
                 break;
             }
@@ -863,10 +656,6 @@ export class EquipmentStateMessage {
                 state.time.month = msg.extractPayloadByte(7);
                 state.time.date = msg.extractPayloadByte(6);
                 sys.equipment.controllerFirmware = (msg.extractPayloadByte(42) + (msg.extractPayloadByte(43) / 1000)).toString();
-                // v3.004+: Seed known targetIds immediately once firmware>=3.0 is confirmed (before UI interaction).
-                if (sys.equipment.isIntellicenterV3 && typeof (sys.board.circuits as any)?.seedKnownV3TargetIds === 'function') {
-                    (sys.board.circuits as any).seedKnownV3TargetIds();
-                }
                 // v3.004 adds 4 additional bytes (44-46) that are the time of day
                 // Byte 44: Hour (0-23)
                 // Byte 45: Minute (0-59)
@@ -947,13 +736,6 @@ export class EquipmentStateMessage {
                     let isOn = ((circuitId === 6 || circuitId === 1) && sys.equipment.dual === true) ? cstate.isOn : (byte & (1 << j)) > 0;
                     //let isOn = (byte & (1 << j)) > 0;
                     cstate.isOn = isOn;
-                    // v3.004+ learning: When circuit state changes, check for pending Wireless commands
-                    if (sys.controllerType === ControllerType.IntelliCenter && 
-                        sys.equipment.isIntellicenterV3 && 
-                        wasOn !== isOn && 
-                        (typeof circuit.targetId === 'undefined' || circuit.targetId === 0)) {
-                        EquipmentStateMessage.checkPendingAction184Learning(circuitId, isOn);
-                    }
                     cstate.name = circuit.name;
                     cstate.nameId = circuit.nameId;
                     cstate.showInFeatures = circuit.showInFeatures;

package/controller/comms/messages/status/HeaterStateMessage.ts

@@ -18,6 +18,7 @@ along with this program.  If not, see <http://www.gnu.org/licenses/>.
 import { Inbound, Protocol } from "../Messages";
 import { state, BodyTempState, HeaterState } from "../../../State";
 import { sys, ControllerType, Heater } from "../../../Equipment";
+import { logger } from '../../../../logger/Logger';
 
 export class HeaterStateMessage {
     public static process(msg: Inbound) {
@@ -85,33 +86,44 @@ export class HeaterStateMessage {
         msg.isProcessed = true;
     }
     public static processUltraTempStatus(msg: Inbound) {
-        // RKS: 07-03-21 - We only know byte 2 at this point for Ultratemp for the 115 message we are processing here.  The 
+        // RKS: 07-03-21 - UltraTemp RS-485 protocol reverse engineering notes.
+        // The heat pump communicates via Action 114 (command) / 115 (response) messages.
+        //
+        // Action 115 - inbound response (heat pump -> controller, heartbeat every ~1s)
+        // [165, 0, 16, 112, 115, 10][160, 1, 0, 3, 0, 0, 0, 0, 0, 0][2, 70]
         // byte  description
         // ------------------------------------------------
-        // 0    Unknown (always seems to be 160 for response)
-        // 1    Unknown (always 1)
-        // 2    Current heater status 0=off, 1=heat, 2=cool
-        // 3-9  Unknown
-        
-        // 114 message - outbound response
-        //[165, 0, 112, 16, 114, 10][144, 0, 0, 0, 0, 0, 0, 0, 0, 0][2, 49] // OCP to Heater
+        // 0    Always 160 for response
+        // 1    Always 1
+        // 2    Current heater status: 0=off, 1=heat, 2=cool
+        // 3    Believed to be offset temp
+        // 4-9  Unknown
+        //
+        // Action 114 - outbound command (controller -> heat pump)
+        // [165, 0, 112, 16, 114, 10][144, 0, 0, 0, 0, 0, 0, 0, 0, 0][2, 49]
         // byte  description
         // ------------------------------------------------
-        // 0    Unknown (always seems to be 144 for request)
-        // 1    Current heater status 0=off, 1=heat, 2=cool
-        // 3    Believed to be ofset temp
+        // 0    Always 144 for request
+        // 1    Sets heater mode: 0=off, 1=heat, 2=cool
+        // 3    Believed to be offset temp
         // 4-9  Unknown
-        
-        //   byto 0: always seems to be 144 for outbound
-        //   byte 1: Sets heater mode to 0 = Off 1 = Heat 2 = Cool
-        //[165, 0, 16, 112, 115, 10][160, 1, 0, 3, 0, 0, 0, 0, 0, 0][2, 70] // Heater Reply
         let heater: Heater = sys.heaters.getItemByAddress(msg.source);
+        if (typeof heater === 'undefined' || !heater.isActive) {
+            // Heat pump not configured for this address
+            msg.isProcessed = true;
+            return;
+        }
         let sheater = state.heaters.getItemById(heater.id);
         let byte = msg.extractPayloadByte(2);
+        let prevOn = sheater.isOn;
+        let prevCooling = sheater.isCooling;
         sheater.isOn = byte >= 1;
         sheater.isCooling = byte === 2;
         sheater.commStatus = 0;
         state.equipment.messages.removeItemByCode(`heater:${heater.id}:comms`);
+        if (prevOn !== sheater.isOn || prevCooling !== sheater.isCooling) {
+            logger.info(`UltraTemp heartbeat: src=${msg.source} status=${byte} (${byte === 0 ? 'OFF' : byte === 1 ? 'HEAT' : 'COOL'}) heater=${heater.name}`);
+        }
         msg.isProcessed = true;
     }
     public static processMasterTempStatus(msg: Inbound) {

package/controller/comms/messages/status/NeptuneModbusStateMessage.ts

@@ -0,0 +1,217 @@
+/*  nodejs-poolController.  An application to control pool equipment.
+Copyright (C) 2016, 2017, 2018, 2019, 2020, 2021, 2022.
+Russell Goldin, tagyoureit.  russ.goldin@gmail.com
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as
+published by the Free Software Foundation, either version 3 of the
+License, or (at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>.
+*/
+import { Inbound } from "../Messages";
+import { state, PumpState } from "../../../State";
+import { sys, Pump } from "../../../Equipment";
+import { logger } from "../../../../logger/Logger";
+
+type PendingRead = {
+    startAddr: number;
+    quantity: number;
+    requestedAt: number;
+};
+
+export class NeptuneModbusStateMessage {
+    private static pendingReads: Map<number, PendingRead[]> = new Map();
+
+    public static enqueueReadRequest(address: number, startAddr: number, quantity: number) {
+        const queue = this.pendingReads.get(address) || [];
+        queue.push({ startAddr, quantity, requestedAt: Date.now() });
+        this.pendingReads.set(address, queue);
+    }
+
+    public static clearReadRequests(address: number) {
+        this.pendingReads.delete(address);
+    }
+
+    private static dequeueReadRequest(address: number): PendingRead {
+        const queue = this.pendingReads.get(address);
+        if (!queue || queue.length === 0) return undefined;
+        const request = queue.shift();
+        if (queue.length === 0) this.pendingReads.delete(address);
+        else this.pendingReads.set(address, queue);
+        return request;
+    }
+
+    private static getNeptunePumpByAddress(address: number): Pump {
+        for (let i = 0; i < sys.pumps.length; i++) {
+            const pump = sys.pumps.getItemByIndex(i);
+            const typeName = sys.board.valueMaps.pumpTypes.getName(pump.type);
+            if (typeName === 'neptunemodbus' && pump.address === address) return pump;
+        }
+        return undefined;
+    }
+
+    private static toSigned16(value: number): number {
+        return value > 0x7FFF ? value - 0x10000 : value;
+    }
+
+    private static decodeModbusException(code: number): string {
+        const modbusExceptions = {
+            0x01: 'Illegal function',
+            0x02: 'Illegal data address',
+            0x03: 'Illegal data value',
+            0x04: 'Server device failure',
+            0x05: 'Acknowledge',
+            0x06: 'Server device busy',
+            0x08: 'Memory parity error',
+            0x0A: 'Gateway path unavailable',
+            0x0B: 'Gateway target failed to respond',
+        };
+        return modbusExceptions[code] || `Unknown Modbus exception ${code}`;
+    }
+
+    private static processReadInput(msg: Inbound, address: number, pumpState: PumpState) {
+        const request = this.dequeueReadRequest(address);
+        const byteCount = msg.extractPayloadByte(0, 0);
+        if (byteCount <= 0 || (byteCount % 2) !== 0) {
+            logger.debug(`NeptuneModbusStateMessage.processReadInput invalid byte count ${byteCount} (Address: ${address})`);
+            return;
+        }
+        if (msg.payload.length < byteCount + 1) {
+            logger.debug(`NeptuneModbusStateMessage.processReadInput short payload (Address: ${address})`);
+            return;
+        }
+
+        let motorFaultCode = 0;
+        let interfaceFaultCode = 0;
+        let stoppedState: number = undefined;
+
+        for (let i = 0; i < byteCount; i += 2) {
+            const value = (msg.payload[i + 1] << 8) | msg.payload[i + 2];
+            const offset = i / 2;
+            const registerAddr = request ? request.startAddr + offset : -1;
+            switch (registerAddr) {
+                case 0: // 30001 Current Speed
+                    pumpState.rpm = value;
+                    break;
+                case 3: // 30004 Motor Power
+                    pumpState.watts = value;
+                    break;
+                case 5: // 30006 Motor Fault Status
+                    logger.debug(`Neptune motor fault status ${value} (Address: ${address})`);
+                    break;
+                case 6: // 30007 Motor Fault Code
+                    motorFaultCode = value;
+                    break;
+                case 30: // 30031 Interface Fault State
+                    logger.debug(`Neptune interface fault state ${value} (Address: ${address})`);
+                    break;
+                case 31: // 30032 Interface Fault Code
+                    interfaceFaultCode = value;
+                    break;
+                case 113: // 30114 Stopped State bit image
+                    stoppedState = value;
+                    break;
+                case 119: // 30120 Target shaft speed (signed)
+                    pumpState.targetSpeed = Math.abs(this.toSigned16(value));
+                    break;
+                default:
+                    // Keep MVP mapping focused on existing pump state fields.
+                    break;
+            }
+        }
+
+        const hasFault = motorFaultCode > 0 || interfaceFaultCode > 0;
+        if (hasFault) {
+            logger.warn(`Neptune fault detected (Address: ${address}) motorFault=${motorFaultCode} interfaceFault=${interfaceFaultCode}`);
+            pumpState.status = 16;
+            pumpState.driveState = 4;
+            pumpState.command = 4;
+            return;
+        }
+
+        if (typeof stoppedState !== 'undefined') {
+            const isStopped = (stoppedState & 0x01) === 1;
+            pumpState.driveState = isStopped ? 0 : 2;
+            pumpState.command = isStopped ? 4 : 10;
+            pumpState.status = isStopped ? 0 : 1;
+        }
+        else if (pumpState.rpm > 0) {
+            pumpState.driveState = 2;
+            pumpState.command = 10;
+            pumpState.status = 1;
+        }
+        else {
+            pumpState.driveState = 0;
+            pumpState.command = 4;
+            pumpState.status = 0;
+        }
+    }
+
+    private static processWriteSingle(msg: Inbound, address: number, pumpState: PumpState) {
+        if (msg.payload.length < 4) return;
+        const registerAddr = (msg.payload[0] << 8) | msg.payload[1];
+        const registerValue = (msg.payload[2] << 8) | msg.payload[3];
+        switch (registerAddr) {
+            case 0: // 40001 Motor On/Off
+                if (registerValue === 0) {
+                    pumpState.driveState = 0;
+                    pumpState.command = 4;
+                    pumpState.status = 0;
+                }
+                else if (registerValue === 1) {
+                    pumpState.driveState = 2;
+                    pumpState.command = 10;
+                    pumpState.status = 1;
+                }
+                break;
+            case 1: // 40002 Manual speed RPM
+                pumpState.rpm = registerValue;
+                break;
+            default:
+                logger.debug(`Neptune write ack for unhandled register ${registerAddr}=${registerValue} (Address: ${address})`);
+                break;
+        }
+    }
+
+    public static process(msg: Inbound) {
+        const address = msg.dest;
+        const functionCode = msg.action;
+        const pumpCfg = this.getNeptunePumpByAddress(address);
+        if (typeof pumpCfg === 'undefined') {
+            logger.debug(`NeptuneModbusStateMessage.process ignored unconfigured address ${address}`);
+            return;
+        }
+        const pumpState = state.pumps.getItemById(pumpCfg.id, pumpCfg.isActive === true);
+
+        if ((functionCode & 0x80) === 0x80) {
+            const exceptionCode = msg.extractPayloadByte(0, 0);
+            logger.warn(`Neptune Modbus exception response fn=0x${functionCode.toString(16)} code=${exceptionCode} (${this.decodeModbusException(exceptionCode)}) address=${address}`);
+            pumpState.status = 16;
+            state.emitEquipmentChanges();
+            return;
+        }
+
+        switch (functionCode) {
+            case 0x04: // Read input registers
+                this.processReadInput(msg, address, pumpState);
+                break;
+            case 0x06: // Write single register
+                this.processWriteSingle(msg, address, pumpState);
+                break;
+            case 0x10: // Write multiple registers
+                logger.debug(`Neptune write-multiple response (Address: ${address})`);
+                break;
+            default:
+                logger.debug(`NeptuneModbusStateMessage.process unhandled function 0x${functionCode.toString(16)} (Address: ${address})`);
+                break;
+        }
+        state.emitEquipmentChanges();
+    }
+}