Skip to main content

Modbus Troubleshooting

Modbus is one of the most widely used industrial communication protocols in Mango deployments. Its simplicity can be deceptive -- subtle configuration issues around device IDs, register addressing, data types, and byte ordering cause the majority of problems. This page covers systematic diagnosis and resolution of common Modbus issues.

Symptoms​

  • The data source shows "Connection refused" or "Connection timed out" errors.
  • Data points display no values or show null / NaN.
  • Numeric values appear incorrect -- wildly large, negative, or shifted by a factor.
  • Binary points appear inverted (showing "On" when the device is "Off" and vice versa).
  • The data source alternates between online and offline status.
  • The Mango log shows ModbusTransportException, TimeoutException, or IOException related to the Modbus data source.
  • Only some points in a data source return values while others are stuck or show errors.

Common Causes​

1. Network Connectivity Issues (Modbus TCP)​

The Mango server cannot reach the Modbus device on the configured host and port. Firewalls, incorrect IP addresses, wrong port numbers, or the device being offline are the most common reasons.

2. Incorrect Device ID (Slave ID)​

The Modbus device ID (also called slave ID or unit ID) configured in the data point does not match the actual device. Valid IDs range from 1 to 247 (though Mango supports 1-240 by default). A mismatched ID causes the device to ignore the request entirely, resulting in a timeout.

3. Wrong Register Range or Offset​

Modbus vendors vary in how they document register addresses. Some use 1-based addressing while Mango uses 0-based offsets. A documentation address of 40001 (holding register 1) corresponds to offset 0 in Mango.

4. Incorrect Data Type or Byte Order​

Modbus does not specify a byte order (endianness). Different manufacturers use big-endian, little-endian, or word-swapped byte orders. Selecting the wrong data type in Mango results in garbled numeric values.

5. Timeout and Retry Configuration​

The timeout may be too short for devices on slow or congested networks, or the retry count may be too low for devices that occasionally miss a response.

6. Serial Communication Errors (Modbus RTU/ASCII)​

For serial connections: wrong baud rate, parity, stop bits, or data bits; incorrect COM port; or physical wiring issues (RS-485 termination, biasing, cable length).

7. Multiple Masters or Polling Conflicts​

If another system is also polling the same Modbus device, the two masters may interfere with each other, causing intermittent timeouts and communication errors.

Diagnosis​

Step 1: Verify Network Connectivity​

For Modbus TCP:

# Test basic connectivity to the device
ping <device-ip>

# Test that the Modbus TCP port is open (default 502)
nc -zv <device-ip> 502
# or
telnet <device-ip> 502

If the connection is refused or times out, the problem is at the network or device level, not in Mango.

Step 2: Enable IO Logging​

Mango's Modbus data source has a Log IO option that records all Modbus communication as hex data to a special log file:

  1. Open the Modbus data source editor.
  2. Check the Log IO checkbox.
  3. Save the data source.
  4. The IO log file will be created at MA_HOME/logs/modbusIO-<dataSourceId>.log.

The IO log shows the raw hex bytes of every request sent and response received. This is invaluable for diagnosing register addressing, data type, and byte order issues.

Step 3: Analyze the IO Log​

A typical IO log entry looks like:

TX: 00 01 00 00 00 06 01 03 00 00 00 01
RX: 00 01 00 00 00 05 01 03 02 00 64

Breaking down the request (TX):

  • 00 01 -- Transaction ID
  • 00 00 -- Protocol identifier
  • 00 06 -- Length
  • 01 -- Device ID (Unit ID = 1)
  • 03 -- Function code (03 = Read Holding Registers)
  • 00 00 -- Starting register offset (0)
  • 00 01 -- Number of registers to read (1)

Breaking down the response (RX):

  • 01 -- Device ID
  • 03 -- Function code
  • 02 -- Byte count
  • 00 64 -- Data (hex 0064 = decimal 100)

If the response contains an exception code instead of data:

  • 01 -- Illegal Function: The function code is not supported by the device
  • 02 -- Illegal Data Address: The register address does not exist on the device
  • 03 -- Illegal Data Value: The data value is not acceptable
  • 04 -- Slave Device Failure: An unrecoverable error occurred on the device

Step 4: Use the Node Scan Feature​

The Modbus data source provides a node scan utility that iterates from device ID 1 to 240, sending a ReadExceptionStatus request (function code 7) to each. Devices that respond are displayed as available nodes.

note

Not all Modbus devices support function code 7 (ReadExceptionStatus). A device that does not respond to the scan may still be functional -- this is a false negative. Try connecting with the known device ID directly.

Step 5: Verify with an External Modbus Tool​

Use an independent Modbus client tool to verify that the device responds correctly outside of Mango:

  • mbpoll (Linux command-line tool)
  • ModbusPoll or Modbus Doctor (Windows GUI tools)
  • PyModbus (Python library for scripting tests)

If the external tool reads values correctly but Mango does not, the issue is in the Mango data source or point configuration.

Solutions​

Solution 1: Fix Register Addressing (Off-by-One)​

Modbus documentation frequently uses 1-based register numbering. Mango uses 0-based offsets. Apply this conversion:

Documentation AddressMango OffsetRegister Range
000010Coil Status
100010Input Status
300010Input Register
400010Holding Register

Rule of thumb: If the vendor documentation shows a register like 40001, subtract 1 to get the Mango offset (0). If they show 40100, the offset is 99.

Some vendors document "Modbus addresses" rather than "register numbers." Check whether their first register starts at 0 or 1 to determine the convention.

Solution 2: Fix Data Type and Byte Order​

If numeric values look wrong (garbled, very large, or shifted), the byte order is likely incorrect. Mango provides many data type options to handle different endianness:

If values look like...Try this data type
Correct magnitude, wrong signSwitch between signed and unsigned
Completely wrong valueTry the _SWAPPED variant of the current type
Close to correct but slightly offCheck if the device uses BCD encoding
Very large or very smallTry a different width (2-byte vs. 4-byte)

Systematic approach: If you know the expected value (e.g., the device display shows 25.5):

  1. Read the raw register bytes from the IO log.
  2. Try each data type variant until the decoded value matches.
  3. Use the byte order reference table in the Modbus data point help to understand which byte arrangement each type expects.

Solution 3: Fix Timeout and Retry Settings​

For devices on slow networks or with high latency:

Timeout: 3000-5000 ms (increase from default)
Retries: 2-3 (increase from default)

For TCP connections over the internet or through VPN tunnels, timeouts of 5000-10000 ms may be necessary.

Solution 4: Choose the Correct Transport Type​

Transport TypeWhen to Use
TCPInfrequent polling; new socket per poll. Simple but less efficient.
TCP with keep-aliveRecommended for most use cases. Maintains the connection for reuse.
UDPMaximum network efficiency, but requires both Mango and device to be directly visible on the network.
EncapsulatedModbus RTU over IP, for serial-to-Ethernet converters that do not support Modbus TCP-to-RTU translation.

If you experience intermittent disconnections with "TCP with keep-alive," the device may have an idle timeout that closes connections. Try plain "TCP" mode or adjust the polling interval to keep the connection active.

Solution 5: Adjust Batch Request Settings​

Some devices have stricter limits on batch request sizes than the Modbus specification defaults:

  • Contiguous batches only: Check this if the device cannot handle optimized non-contiguous reads. Mango normally combines nearby registers into a single request for efficiency, but some devices reject requests that span non-existent registers.
  • Max read bit count / Max read register count / Max write register count: Reduce these if the device firmware has lower limits than the specification allows.
  • Use multiple write commands only: Check this if the device does not implement single-register write (function code 6), only multiple-register write (function code 16).

Solution 6: Configure the Back-Off Strategy​

When a device goes offline, Mango's Modbus data source can use a back-off strategy to avoid hammering the network with repeated failed connection attempts:

  • Scale Factor: How fast the retry interval increases after each failure (e.g., 2.0 doubles the wait each time).
  • Max back-off period: The maximum wait time between retries (e.g., 5 minutes). Once reached, retries continue at this fixed interval.

Solution 7: Fix Serial Communication Settings​

For Modbus RTU or ASCII over serial ports:

  1. Verify the baud rate, parity, stop bits, and data bits match the device configuration exactly.
  2. Ensure the correct COM port is selected and accessible by the Mango process.
  3. For RS-485: verify proper termination resistors (120 ohm) at both ends of the bus and correct biasing.
  4. Check cable length does not exceed RS-485 limits (up to 1200m / 4000ft depending on baud rate).

Prevention​

  • Always enable IO logging during initial data source configuration. Disable it once communication is confirmed and stable to avoid log file growth.
  • Start with a single point and verify it reads correctly before adding the full point list.
  • Document the device's register map with the exact Mango offset, data type, and byte order for each point. This is your most valuable reference for future troubleshooting.
  • Use the device's front panel or a known-good tool to confirm expected values before comparing with Mango readings.
  • Keep polling intervals reasonable. Polling a device every 100ms when values change every 10 seconds wastes bandwidth and increases the chance of timeouts under load.
  • Monitor the Modbus data source for communication errors using event detectors on data source error events.