feat(emulator): add verbose logging for Modbus operations (#316)

Implements verbose logging functionality for the Modbus emulator, enabling detailed output of register read/write operations when the --verbose CLI flag is enabled.

Features:
- VerboseLogger class with zero overhead when disabled
- CLI integration with --verbose flag
- 100% statement coverage with 22 new tests
- Comprehensive documentation with usage examples

Changes:
- Add VerboseLogger class with buffer parsing and formatting
- Integrate logger into ModbusEmulator and function code handlers
- Wire --verbose flag from CLI to emulator config
- Eliminate array allocation overhead when verbose disabled
- Remove unused --log-requests flag
- Extract duplicate formatting logic (DRY refactoring)
- Add verbose logging guide to README

Fixes #309, #311, #312, #313
Addresses #310, #314

Author: groupsky

packages/emulator/README.md

@@ -155,11 +155,56 @@ Options:
   -s, --slave-id <id>      Slave ID (required if no config file)
   -v, --verbose            Enable verbose logging
   -q, --quiet              Suppress all output except errors
-  --log-requests           Log all Modbus requests/responses
   -V, --version            output the version number
   -h, --help               display help for command
 ```
 
+### Verbose Logging
+
+Enable verbose logging to see detailed Modbus operations for debugging and testing:
+
+**CLI:**
+
+```bash
+# With config file
+ya-modbus-emulator --config config.yaml --verbose
+
+# Or directly
+ya-modbus-emulator --transport rtu --port /dev/ttyUSB0 --slave-id 1 --verbose
+```
+
+**Programmatic:**
+
+```typescript
+const emulator = new ModbusEmulator({
+  transport: 'memory',
+  verbose: true,
+})
+```
+
+**Output Format:**
+
+```
+[VERBOSE] READ slave=1 func=0x03 addr=0x0000 count=2 values=[0x1234, 0x5678]
+[VERBOSE] WRITE slave=1 func=0x06 addr=0x0005 count=1 values=[0x9ABC]
+[VERBOSE] WRITE slave=2 func=0x10 addr=0x0010 count=3 values=[0xAABB, 0xCCDD, 0xEEFF]
+```
+
+Each log entry includes:
+
+- **Operation type**: READ or WRITE
+- **Slave ID**: Which device handled the request
+- **Function code**: Modbus function (0x03=Read Holding, 0x04=Read Input, 0x06=Write Single, 0x10=Write Multiple)
+- **Starting address**: Register address in hexadecimal
+- **Register count**: Number of registers accessed
+- **Values**: Register values in hexadecimal
+
+Verbose logging is useful for:
+
+- **E2E testing**: Verify exact data flow in integration tests
+- **Driver development**: Debug communication with emulated devices
+- **Protocol validation**: Ensure correct Modbus message formatting
+
 ### Configuration Files
 
 Create a YAML or JSON configuration file to define devices and behaviors:

packages/emulator/src/behaviors/function-codes.ts

@@ -3,6 +3,7 @@
  */
 
 import type { EmulatedDevice } from '../device.js'
+import type { VerboseLogger } from '../verbose-logger.js'
 
 // Modbus exception codes
 export const ILLEGAL_FUNCTION = 0x01
@@ -12,7 +13,11 @@ export const ILLEGAL_DATA_VALUE = 0x03
 /**
  * Handle a Modbus request and return the response
  */
-export function handleModbusRequest(device: EmulatedDevice, request: Buffer): Buffer {
+export function handleModbusRequest(
+  device: EmulatedDevice,
+  request: Buffer,
+  verboseLogger?: VerboseLogger
+): Buffer {
   if (request.length < 2) {
     return createExceptionResponse(request[0] ?? 0, 0x00, ILLEGAL_DATA_VALUE)
   }
@@ -26,13 +31,13 @@ export function handleModbusRequest(device: EmulatedDevice, request: Buffer): Bu
   try {
     switch (functionCode) {
       case 0x03:
-        return handleReadHoldingRegisters(device, request)
+        return handleReadHoldingRegisters(device, request, verboseLogger)
       case 0x04:
-        return handleReadInputRegisters(device, request)
+        return handleReadInputRegisters(device, request, verboseLogger)
       case 0x06:
-        return handleWriteSingleRegister(device, request)
+        return handleWriteSingleRegister(device, request, verboseLogger)
       case 0x10:
-        return handleWriteMultipleRegisters(device, request)
+        return handleWriteMultipleRegisters(device, request, verboseLogger)
       default:
         return createExceptionResponse(slaveId, functionCode, ILLEGAL_FUNCTION)
     }
@@ -45,7 +50,11 @@ export function handleModbusRequest(device: EmulatedDevice, request: Buffer): Bu
 /**
  * 0x03 - Read Holding Registers
  */
-function handleReadHoldingRegisters(device: EmulatedDevice, request: Buffer): Buffer {
+function handleReadHoldingRegisters(
+  device: EmulatedDevice,
+  request: Buffer,
+  verboseLogger?: VerboseLogger
+): Buffer {
   if (request.length < 6) {
     // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
     return createExceptionResponse(request[0]!, 0x03, ILLEGAL_DATA_VALUE)
@@ -68,13 +77,19 @@ function handleReadHoldingRegisters(device: EmulatedDevice, request: Buffer): Bu
     response.writeUInt16BE(value, 3 + i * 2)
   }
 
+  verboseLogger?.logRead(slaveId, 0x03, startAddress, quantity, response)
+
   return response
 }
 
 /**
  * 0x04 - Read Input Registers
  */
-function handleReadInputRegisters(device: EmulatedDevice, request: Buffer): Buffer {
+function handleReadInputRegisters(
+  device: EmulatedDevice,
+  request: Buffer,
+  verboseLogger?: VerboseLogger
+): Buffer {
   if (request.length < 6) {
     // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
     return createExceptionResponse(request[0]!, 0x04, ILLEGAL_DATA_VALUE)
@@ -97,31 +112,47 @@ function handleReadInputRegisters(device: EmulatedDevice, request: Buffer): Buff
     response.writeUInt16BE(value, 3 + i * 2)
   }
 
+  verboseLogger?.logRead(slaveId, 0x04, startAddress, quantity, response)
+
   return response
 }
 
 /**
  * 0x06 - Write Single Register
  */
-function handleWriteSingleRegister(device: EmulatedDevice, request: Buffer): Buffer {
+function handleWriteSingleRegister(
+  device: EmulatedDevice,
+  request: Buffer,
+  verboseLogger?: VerboseLogger
+): Buffer {
   if (request.length < 6) {
     // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
     return createExceptionResponse(request[0]!, 0x06, ILLEGAL_DATA_VALUE)
   }
 
+  // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+  const slaveId = request[0]!
   const address = request.readUInt16BE(2)
   const value = request.readUInt16BE(4)
 
   device.setHoldingRegister(address, value)
 
+  if (verboseLogger) {
+    verboseLogger.logWrite(slaveId, 0x06, address, 1, [value])
+  }
+
   // Echo the request as response
   return request
 }
 
 /**
  * 0x10 - Write Multiple Registers
  */
-function handleWriteMultipleRegisters(device: EmulatedDevice, request: Buffer): Buffer {
+function handleWriteMultipleRegisters(
+  device: EmulatedDevice,
+  request: Buffer,
+  verboseLogger?: VerboseLogger
+): Buffer {
   if (request.length < 7) {
     // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
     return createExceptionResponse(request[0]!, 0x10, ILLEGAL_DATA_VALUE)
@@ -139,9 +170,19 @@ function handleWriteMultipleRegisters(device: EmulatedDevice, request: Buffer):
   }
 
   // Write registers
-  for (let i = 0; i < quantity; i++) {
-    const value = request.readUInt16BE(7 + i * 2)
-    device.setHoldingRegister(startAddress + i, value)
+  if (verboseLogger) {
+    const values: number[] = []
+    for (let i = 0; i < quantity; i++) {
+      const value = request.readUInt16BE(7 + i * 2)
+      device.setHoldingRegister(startAddress + i, value)
+      values.push(value)
+    }
+    verboseLogger.logWrite(slaveId, 0x10, startAddress, quantity, values)
+  } else {
+    for (let i = 0; i < quantity; i++) {
+      const value = request.readUInt16BE(7 + i * 2)
+      device.setHoldingRegister(startAddress + i, value)
+    }
   }
 
   // Response: slave_id + function_code + start_address + quantity

packages/emulator/src/cli.ts

@@ -20,7 +20,6 @@ interface CliOptions {
   slaveId?: number
   verbose?: boolean
   quiet?: boolean
-  logRequests?: boolean
 }
 
 const program = new Command()
@@ -41,7 +40,6 @@ program
   .option('-s, --slave-id <id>', 'Slave ID (required if no config file)', parseInt)
   .option('-v, --verbose', 'Enable verbose logging')
   .option('-q, --quiet', 'Suppress all output except errors')
-  .option('--log-requests', 'Log all Modbus requests/responses')
 
 program.parse()
 
@@ -78,6 +76,7 @@ async function main(): Promise<void> {
           stopBits: fileConfig.transport.stopBits,
         }),
         ...(fileConfig.transport.lock !== undefined && { lock: fileConfig.transport.lock }),
+        ...(options.verbose === true && { verbose: true }),
       }
 
       devices = fileConfig.devices as Array<{ slaveId: number }>
@@ -102,6 +101,7 @@ async function main(): Promise<void> {
           parity: options.parity as 'none' | 'even' | 'odd',
         }),
         ...(typeof options.lock === 'boolean' && { lock: options.lock }),
+        ...(options.verbose === true && { verbose: true }),
       }
 
       devices = [{ slaveId: options.slaveId }]