Modbus driver troubleshooting

The features and functions available in a node are controlled by the licenses that are installed in the node.

To verify that the Modbus driver license is installed:

1. From the Workbench left pane, expand the node whose license you want to check, and then select the Administration icon.
2. From the Administration window, select the Licenses tab.
3. Select the appropriate license. Details of the license appear on the tab.
4. View the Features column to identify the device driver.

If you do not see the correct license, or if the license is expired, you must request a license from your license key provider.

For information on how to install a license, refer to System Administration > Licenses.

The Modbus driver is not part of this node's installation. The Modbus driver is installed as a package separate from the base product installation.

You may be working with different levels of nodes, each with different levels of support for devices. Ensure that this node is the one with support for Modbus devices.

For information on how to add the Modbus driver package, refer to System Administration > Packages.

The Modbus device needs to be configured using the device’s configuration software. The complete description of this configuration is beyond the scope of this documentation. Ensure that the IP Address, Port and Slave Address settings are correctly configured for your network setup and that they match the definitions in the device that represents the Modbus device.

If the MODBUS server is connected to a MODBUS+ or MODBUS Serial Line sub-network and addressed through a bridge or a gateway the Slave Address value is necessary to identify the device connected on the sub-network behind the bridge or the gateway. This value allows the gateway to route a message to a specific Modbus device attached to the bridge or gateway. The Slave Address parameter should be set to the default value of 0 when communicating directly to a Modbus device. Protocol errors will occur when read or write attempts are made to devices with an invalid Slave Address value, whether the device is connected directly to a Modbus device or to a Modbus device attached to a bridge or gateway.

Ensure that the serial port assigned to the device is active. If the node is running on a Microsoft Windows platform, the Device Manager component, which is accessible from the Control Panel, can be checked to determine if the specific COM port is active. If the node is running on a Linux platform, the following command can be run to determine if the COM port is active.

dmesg | grep tty

A node may have a serial connection to a Modbus RTU device, that is daisy-chained to additional Modbus RTU devices. A device can be defined for each Modbus RTU device in the chain based on the address of the Modbus device in the chain. The address of the Modbus RTU device can be determined using that device's configuration software. Protocol errors will occur when read or write attempts are made to a device with an invalid Device Address Identification value.

A common method to serial connect a RS-485 device to a node is through the use of a USB to Serial converter cable. This cable connects the Modbus RTU device to the node using a USB port. The supplier of the converter cable must provide a device driver to enable this capability if the node is running on a Microsoft Windows platform.

On Linux platforms you can determine if the USB port recognizes the cable by issuing the lsusb command from a terminal window. Vendor and product codes will be displayed if the cable is plugged into the USB port. This information can then be added to the Linux ftdi_sio table to enable the USB converter cable. This is done by issuing the following command from a terminal window.

sudo modprobe ftdi_sio vendor=0xnnnn product=0xnnnn

Where nnnn is the hexadecimal values of the vendor and product codes returned from the lsusb command.

Successful definition of a Modbus device that utilizes a serial connection to a physical Modbus device relies on the proper setting of the connection parameters. The connection parameters in the device definition: Baud Rate, Parity, Stop Bits, and Data Bits, must match exactly the settings defined on the physical device. Testing has shown that the timeout parameter in the device definition should be set to 10000 milliseconds for devices that require a Baud Rate setting of less than 9600, to prevent the device from disabling. Data triggers that are monitoring Modbus registers for serial devices connected at slower Baud Rate settings (less than 9600) should also be set to a minimum of 5000 milliseconds, to avoid timeout conditions that will lead to the device disabling.

XML files can be created to map symbolic names to specific Modbus data regions. The XML file is also used to map data types to specific Holding Register and Input Register regions. One of the data types that can be mapped to these data regions is a String. An individual Holding Register or Input Register contains two bytes, which means that two ASCII characters can be written into one register. Consequently all String lengths defined in the XML file must have an even number length. A string size that is an odd number will be reduced by one to obtain a String with an even length.

This section describes the error codes that you might encounter when using the Modbus driver.

These error codes are available from the Devices window in the Extended Status column. The error codes are also referenced in the Exceptions Log.

When the system experiences an abnormal condition (such as a device failure, disconnect from a controller, or software error), an error code and extended error code are recorded in the Exceptions Log.

In the Devices window, the Status column will always be a generic error code that can tell you if the error is a communication error, a data error, or some other internal device error. The Extended Status column provides the error code from the driver. These error codes can be basic runtime error codes or specific to the Modbus driver.

Error Code	Reason
1	Illegal function was attempted
2	Illegal data address
3	Illegal data value
4	Slave device failure
5	Acknowledgment pending, timeout
6	Slave device busy
7	Negative acknowledgment received
8	Memory parity error
9	Invalid CRC response
10	Gateway path unavailable
11	Gateway target device failed to respond
12	Illegal data size
13	Incorrect device address
137	Calculated CRC did not match the CRC that was received