Troubleshooting Modbus Exception Errors in benthos-umh

When deploying protocol converters using the Modbus Protocol Converter within the Management Console on the UMH platform, you might encounter Modbus exception errors. These errors can be challenging to diagnose due to the complexity of Modbus communication. This tutorial aims to generalize the issue of Modbus exception errors and provide a step-by-step guide to troubleshoot and resolve them effectively.

Prerequisites

Before proceeding, ensure you have the following:

• Basic Understanding of Modbus Protocol: Familiarity with Modbus data models, function codes, and exception codes.
• Access to Device Documentation: Modbus register maps and device-specific configuration details.
• Network Access: Ability to communicate with Modbus devices over TCP/IP.

Understanding the Error Message

modbus:
  controller: tcp://10.20.10.10:502
  slaveIDs:
    - 10
    - 11
    - 13
    - 14
    - 20
    - 21
    - 50
  timeout: 1s
  timeBetweenReads: 1s
  addresses:
    - name: Voltage_L1_L2
      register: holding
      address: 3020
      type: FLOAT32
      output: FLOAT64
    - name: Voltage_L2_L3
      register: holding
      address: 3022
      type: FLOAT32
      output: FLOAT64
    - name: Serial_number
      register: holding
      address: 130
      type: UINT32
      output: FLOAT64

When deploying a protocol converter with above configuration, you might see an error message similar to the following:

level=info msg="Got 0 request(s) touching 0 discrete registers for 0 fields" @service=benthos label="" path=root.input
level=info msg="Got 0 request(s) touching 0 coil registers for 0 fields" @service=benthos label="" path=root.input
level=info msg="Listening for HTTP requests at: http://0.0.0.0:4195" @service=benthos
level=info msg="Successfully connected to Modbus device at tcp://10.20.10.10:502" @service=benthos label="" path=root.input
level=info msg="Input type modbus is now active" @service=benthos label="" path=root.input
level=info msg="Launching a Benthos instance, use CTRL+C to close" @service=benthos
level=info msg="Output type kafka is now active" @service=benthos label=kafka path=root.output_resources
level=error msg="slave 10 encountered an error: modbus: exception '3' (illegal data value), function '3'" @service=benthos label="" path=root.input
level=error msg="slave 10 encountered an error: modbus: exception '3' (illegal data value), function '3'" @service=benthos label="" path=root.input
level=error msg="Failed to read message: modbus: exception '3' (illegal data value), function '3'" @service=benthos label="" path=root.input

Breakdown of the Error

• slave 10 encountered an error: Indicates that the error occurred while communicating with the device assigned Slave ID 10.
• modbus: exception '3' (illegal data value): Modbus exception code 3 signifies an illegal data value error.
• function '3': Refers to Modbus function code 3, which is "Read Holding Registers".

Understanding this error is crucial for diagnosing the root cause.

Modbus Protocol Overview

Modbus Data Model

Modbus organizes data into four primary tables:

Modbus Function Codes

Function codes define operations requested by the client:

Common Function Codes

• 1: Read Coils
• 2: Read Discrete Inputs
• 3: Read Holding Registers
• 4: Read Input Registers
• 5: Write Single Coil
• 6: Write Single Holding Register
• 15: Write Multiple Coils
• 16: Write Multiple Holding Registers

Modbus Exception Codes

Exception codes indicate errors returned by the server:

Diagnosing Modbus Exception '3' (Illegal Data Value)

Possible Causes

1. Incorrect Register Addressing: Requesting a register address that does not exist or is out of range.
2. Invalid Data Type or Length: Specifying a data type or length that the device cannot process.
3. Incorrect Slave ID: Communicating with the wrong device or a device that does not support the requested operation.
4. Function Code Not Supported: Using a function code that the device does not support for the given register.

General Steps to Troubleshoot Modbus Errors in Benthos-UMH

Step 1: Verify Slave ID

• Action: Ensure the Slave ID in your configuration matches the device you intend to communicate with.
• Example: If you meant to communicate with Slave ID 11 but configured Slave ID 10, correct it in your configuration.

Step 2: Confirm Register Addresses

• Action: Check the device's documentation to verify that the register addresses you are querying exist and are correct.
• Note: Modbus register addresses can be zero-based or one-based. Adjust accordingly.

Step 3: Check Function Codes

• Action: Ensure you are using the correct function code for the registers you are accessing.
  • Function Code 3: Read Holding Registers
  • Function Code 4: Read Input Registers
• Tip: If you are trying to read input registers but using function code 3, switch to function code 4.

Step 4: Validate Data Types and Lengths

• Action: Verify that the data types (e.g., FLOAT32, UINT16) and lengths match the device's specifications.
• Example: Reading a FLOAT32 value requires reading two consecutive 16-bit registers.

Step 5: Adjust Byte Order (Endianness)

• Action: If the device uses a specific byte order, configure it accordingly in Benthos-UMH.

Example:

modbus:
  byteOrder: 'DCBA'  # Adjust based on device specification

Step 6: Test Communication with Minimal Configuration

• Action: Simplify your configuration to test basic communication.
• Procedure:
  • Comment out all but one register read.
  • Use a known valid register address and data type.
  • Check if the error persists.

Step 7: Review Network Settings

• Action: Ensure that network settings such as IP address, port, and timeouts are correctly configured.
• Tip: Increase the timeout and timeBetweenReads settings if network latency is suspected.

Step 8: Consult Device Manufacturer

• Action: If the issue persists, consult the device's documentation or contact the manufacturer for support.
• Information to Provide: Configuration details, error messages, and steps already taken.

Applying the Steps to the Error Message

Let's apply the troubleshooting steps to the provided error message.

Error Analysis

• Slave ID: 10
• Exception Code: 3 (Illegal Data Value)
• Function Code: 3 (Read Holding Registers)

Resolution Steps

1. Verify Slave ID:
   • The error occurred with Slave ID 10.
   • Action: Confirm if Slave ID 10 is the correct device.
   • Resolution: In this case, Slave ID 10 was incorrect. Updating to the correct Slave ID resolved the issue.
2. Check Register Addresses:
   • Registers being read: 3020, 3022, 130.
   • Action: Verify these addresses exist on the device assigned the correct Slave ID.
3. Validate Function Codes:
   • Function code 3 is used to read holding registers.
   • Action: Ensure that the registers are indeed holding registers.
4. Confirm Data Types and Lengths:
   • Reading FLOAT32 values.
   • Action: Ensure that the device supports FLOAT32 at these addresses.

Conclusion

Modbus exception errors, such as exception '3' (Illegal Data Value), can be resolved by systematically verifying your configuration and understanding the underlying Modbus protocol. By following the troubleshooting steps outlined in this tutorial, you can diagnose and fix issues when deploying protocol converters using the Modbus plugin in benthos-umh on the UMH platform.

Additional Resources

• Modbus Protocol Specification: Modbus Organization
• benthos-umh documentation