Citect SCADA 6[1].10 Modbus Driver Help

Modbus Driver The Modbus driver Help is designed to assist you in setting up and configuring communication with a Modbus system. This process involves the following steps:

1. Installing the Modbus Driver Pack

2. Preparing the Modbus System

3. Setting up Communications

4. Configuring Your CitectSCADA Project

You'll find additional information in the Advanced Configuration and Maintenance and Troubleshooting sections to help you resolve communication or configuration errors.

CitectSCADA Modbus Driver Help

Copyright © 2005 Citect Pty Ltd (www.citect.com). All rights reserved.

About Modbus

The Modbus protocol supports serial communication with many I/O devices (including the Modicon 484, 584, 884, and 984 programmable controllers).

The Modbus protocol differs from the Modbusa protocol only in the data framing technique used: the Modbus protocol is RTU-based while the Modbusa protocol is ASCII-based.

The Modbus protocol also supports the Siemens TI 405 PLC, and the Moore Industries IOExpress Data Collection Units. Other PLCs might also be supported; contact Citect Technical Support for details.

The maximum request length for the Modbus protocol is 2000 bits.

Notes

Some non-standard PLCs support the Modbus protocol. However, some of these I/O devices do not support the Modbus protocol correctly. When CitectSCADA tries to communicate with these I/O devices, you might get errors on startup or during communication.

To handle these non-standard I/O devices, the Modbus protocol has some special options to change its operation:

1. On startup, CitectSCADA tries to read some digital inputs to verify that the PLC does exist. If CitectSCADA cannot read these bits, it assumes the PLC is bad, and remains off line. Some non-standard I/O devices do not support digital bits, so this command fails. With the [MODBUS]InitType parameter, you can change the type of variable the Modbus protocol tries to read on startup, to allow communication to start.

2. The standard Modbus driver allows reading of 2000 bits in one request. Some non-standard I/O devices do not support such large reads. You can change the maximum read size with the [MODBUS]MaxBits parameter. (The default is 2000.)

You must also change the MAX_LENGTH field for the Modbus protocol (in the \CITECT\BIN\PROTDIR.DBF file) to the same value. You must re-compile your project after changing this option. Note that if you reinstall CitectSCADA, the PROTDIR.DBF file


is overwritten and you must repeat the change.

3. Some I/O devices that operate over radio modems also require the padding of protocol messages. The padding characters wake the radio modem to allow the rest of the message to be transmitted. Set the [MODBUS]Pad parameter to the number of characters to pad, and the [MODBUS]PadChar parameter to the ASCII code of the character to pad. For example, to pad 20 0xFF characters to the start of the message, set: [MODBUS] Padd=20 PadChar=255

4. In the Modbus protocol, LONG data types default to a simplified implementation, with a shortened range of 0 to 655,359,999. To increase the LONG data type to the full range, set the [MODBUS]LongDataType parameter to either 1 or 3.

As a LONG is composed from two registers, the register order used by CitectSCADA must match the order used by the PLC. Refer to the help accompanying the [MODBUS]LongDataType parameter to determine the appropriate value.


Installing the Modbus Driver Pack

You must install the Modbus driver pack on the computer that will connect to the Modbus system. This computer must be configured as a CitectSCADA I/O server. It should also be installed on any machines where the CitectSCADA project is compiled.

Any computer you install the driver pack on must have CitectSCADA installed.

No special setup is required required for this protocol: only the included CitectSCADA driver (modbus.dll) is used.

Before installing the driver pack, close your CitectSCADA runtime environment and Citect Explorer. You need administrator permissions for the I/O server PC.

To install the Modbus driver pack

1. Save the Modbus driver pack to an appropriate location on the I/O server PC.

2. Double-click the EXE file to launch the installation.

3. Follow the instructions provided by the installation Wizard. You are prompted to select the CitectSCADA installation folder. By default, this is C:\Program Files\Citect\CitectSCADA. If you installed CitectSCADA in a different folder, browse to that location. An error message will warn you if you select the wrong folder.

4. Click Finish to complete the installation.



Preparing the Modbus System


This section the hardware requirements for preparing your Modbus devices for communication with CitectSCADA and covers:

Ethernet hardware requirements

Serial hardware requirements


Ethernet hardware requirements

This section provides an overview of the Ethernet connection, as well as describing the hardware setup procedure.

Overview

The TCP/IP method of communication to devices supporting Modbus/TCP uses the Modnet protocol over Ethernet. Using this method you can connect to single or multiple PLCs as in the following diagram:

You can use the same Ethernet card that is being used for CitectSCADA communication for PLC communication, though this might degrade performance.

Setting up the Ethernet connection

Set up your specific Ethernet card as required and confirm basic network communications before configuring communications for the Modnet driver. Refer to the documentation accompanying your hardware for instruction.

You must also set up the TCP/IP protocol on your CitectSCADA computer. The Modnet protocol supports TCP/IP communication with the Modicon TSX Quantum PLC and most Modbus/TCP compatible devices.

The maximum request length for the Modnet protocol is 1920.

Winsock TCP/IP Setup

This protocol requires only Winsock TCP/IP software to be installed in your computer. This protocol does not require any software from Modicon.


To use any CitectSCADA TCP/IP protocols, the Windows TCP/IP protocol driver must first be installed and set up by:

1. Allocating your computer an IP address.

2. Installing and setting up TCP/IP on your computer.

3. Testing that your setup has worked.


Serial hardware requirements

This section provides an overview of the serial connection, as well as describing the hardware setup procedure.

Overview

Many I/O devices use Modbus ASCII or Modbus RTU to communicate. The setup of these devices is identical with the exception of the I/O Device Protocol you specify in the I/O Devices dialog box:

Modbus ASCII devices use the Modbusa driver, so you must specify MODBUSA.

Modbus RTU devices use the Modbus driver, so you must specify MODBUS.

Communication is via the Modbus port on the PLC. Using this method you can connect to single or multiple PLCs as shown here:

Wiring Diagrams

Use the following serial wiring diagrams to help you wire your Modbus devices correctly.


Serial wiring diagram 1




Setting up the serial connection

You must set your PLC to the communication setting you want. The default hardware settings for the device are as follows:

These settings are recommendations only. If you use the Communications Express Wizard, these default settings are configured in your project automatically, though your hardware might support other values. If you set the baud rate, data bits, stop bits or parity to another value, you must manually set the new value(s) in your project.

Setting Value Baud Rate 19200

Data Bits 8

Stop Bits 1

Parity 2 (even)

You must also set the following configuration options on the Modbus port on the PLC:

Station number.

RTU mode (if this is not selected, you must use the Modbusa protocol).

Delay time to 1.

See Also

Installing the Modbus Driver Pack


Setting up Communications

Before configuring your CitectSCADA project, first you should establish and confirm communications between CitectSCADA and the devices in your Modbus system by creating a test project. This allows you to test the communication path in isolation, and ensures that CitectSCADA can bring your devices online.



Creating a test project

CitectSCADA will not communicate with an I/O device if there is no reason to read or write data. Therefore, you must define and implement some variable tags within your CitectSCADA project to initiate a read request and verify that the communication channel is functioning correctly. This requires you to create a test project.

When creating a test project, try to keep things as simple as possible, so that you can easily identify any communication errors. For example, you might design your test project to do nothing more than use an integer variable to display a number on a graphics page.

You should build your test project on the CitectSCADA I/O server that will connect to the Modbus system.

After confirming communications using your test project, it can be set aside for testing other communications later.

To create a communications test project:

1. In Citect Explorer, create a new project and give it an appropriate name.

2. Add the device you want to communicate with to the project. Typically, the information required about a device can be gathered by running the Express Communications Wizard, which implements a set of recommended settings for the type of device you select.

To launch the Wizard, go to the Citect Project Editor and select Express Wizard from the Communications menu.


3. Progress through the Wizard, accepting all defaults for an I/O server and an I/O device. This will create an I/O server named "I/OServer" and an I/O device named "I/ODev".

4. When you reach the I/O Device Selection page, locate the device you want to communicate with; for example, Modicon|484|Serial (Modbus ASCII protocol).

5. Continue through the Wizard to the last page. Click Finish to implement the Wizard settings.

6. Run the Computer Setup Wizard accepting the defaults to make the computer a standalone CitectSCADA system configured to run your test project.

7. Compile the project to confirm that there are no errors. If you receive an error message, go back over the procedure to confirm your settings. See the Troubleshooting section to help resolve a persistent error.


Configuring Your CitectSCADA Project

Once you have confirmed that communications between your CitectSCADA system and any connected devices are stable, you can start to build your project. This process includes:

Adding devices to your project.

Adding tags to your project.

Configuring data types.



Adding devices to your project

Adding a device to your CitectSCADA project provides the information required about the device's location, communication method, connection port, and so on. This information is stored in the CitectSCADA project database.

You can add a device in two ways, by:

Using the Express Communication Wizard.

Manually configuring a device connection.

Usually the Express Communications Wizard is sufficient to set up your communications; the settings it implements for each device have been pre-configured for preferred operation. If, however, your device connection needs are complex, you can configure communications manually by using the CitectSCADA communication forms.



Using the Express Communication Wizard

Using the Express Communications Wizard enables you to configure a device quickly and easily using preconfigured settings.

To use the Express Communication Wizard:

1. In the Citect Project Editor, choose Communications | Express Wizard. 2. Work through the Wizard, filling in the appropriate information for the I/O server and I/O

device.

3. On the I/O Device Selection page, locate the device you want to communicate with; for example, Modicon|484|Serial (Modbus ASCII protocol).

4. Continue through the Wizard to the last page. Click Finish to implement the Wizard settings.



Manually configuring a device connection

Usually the Express Communication Wizard is sufficient to set up communication with a device. However, if the device configuration is unusual, you can manually enter information into the required dialog boxes in Project Editor.

The settings you specify using the Boards, Ports, and I/O Devices dialog boxes depend on the type of communication method used. Choose the appropriate section:

Configuring an Ethernet connection

Configuring a serial connection

Configuring an Ethernet connection

This section describes how to manually configure communications for an Ethernet connection by using the Boards, Ports, and I/O Devices dialog boxes.

Before configuring your Ethernet connection, make sure that you have installed and set up TCP/IP on your machine.

Complete the communications dialog boxes for the devices using Modbus within the network environment using the Modbus protocol with the information specified.

Boards dialog box

Use the table below to enter the correct information in the Boards dialog box.


Text Box Description Board Type You must enter TCPIP.

Address You must enter 0.

I/O Port Leave this field blank.

Interrupt Leave this field blank.

Ports dialog box

Use the table below to enter the correct information in the Ports dialog box.

I/O Devices dialog box

Use the table below to enter the correct information in the I/O Devices dialog box.

Configuring a serial connection

This section describes how to manually configure communications for a serial connection by using the Boards, Ports, and I/O Devices dialog boxes.

Boards dialog box

Use the table below to enter the correct information in the Boards dialog box.

Ports dialog box

Use the table below to enter the correct information in the Ports dialog box.

Special Options Leave this field blank.

Text Box Description Port Number Leave this field blank.

Baud Rate Leave this field blank.

Data Bits Leave this field blank.

Stop Bits Leave this field blank.

Parity Leave this field blank.

Special Options

You must enter the destination IP address of the PLC. Use the following format: -Ia -Pn -T where: a = IP address in standard Internet dot format (for example 192.9.2.60). n = destination Port number. Often one physical port has several virtual ports, used for different purposes. Use this option only to override the default of 502. -T = forces the driver to use TCP, rather than UDP (-U).

Text Box Description I/O Device Name

Enter a unique name (different to other I/O device names with the same port name). This value could be blank if only one IO device exists.

I/O Device Protocol

You must enter MODNET.

I/O Device Address

Leave this field blank.

Text Box Description Board Type If using a serial board or COM port, you should enter COMx.

Address If using a serial board or COM port, you should enter 0.

I/O Port Leave this field blank.

Interrupt Leave this field blank.

Special Options Leave this field blank.

Text Box Description Port Number This value should match the COM port number. This number is defined in the Ports section of the Control

Panel.

Baud Rate This value should match the setting of the PLC - 19200 is recommended.

Data Bits You must enter 8.

Stop Bits You must enter 1.

I/O Devices dialog box

Use the table below to enter the correct information in the I/O Devices dialog box.

Parity This value should match the setting of the PLC - EVEN_P is recommended.

Special Options

You might want to use the special options for the COMx driver if you are using a modem (or similar) and want the driver to perform differently.

Text Box Description I/O Device Name

Enter a unique name (different to other I/O device names with the same port name). This value could be blank if only one I/O device exists.

I/O Device Protocol

Enter MODBUS to use the Modbus RTU (binary) protocol. Enter MODBUSA to use the Modbus ASCII protocol.

I/O Device Address

The PLC station number configured on the PLC. Try 1 to 10. 1 specifies station number 1, and 9 specifies station number 9.


Adding tags to your project

You must add a separate variable tag to your CitectSCADA project for each data-point (memory register) on the I/O devices you want to communicate with. Define your CitectSCADA variable tags by using the Variable Tags dialog box:

For CitectSCADA to compile correctly, you must include appropriate values for the following fields:.

CitectSCADA does not display compile errors if an invalid address is entered in the Variable Tag dialog box. Variable tag values that have an invalid address display as "#COM" at runtime on the graphic pages where they are inserted.


Field Value Variable Tag Name

A unique name per project for the variable tag (up to 79 alphanumeric characters in Version 6, 32 characters for earlier versions). This can be used by CitectSCADA graphic pages and in Cicode where defined.

Data Type Type of variable. Select from the menu. It must be one of the predefined types used in CitectSCADA.

I/O Device Name

Name of an I/O device defined in the I/O Devices dialog box, which identifies the controller for the device using Modbus.

Address The name of a predefined Modbus system PLC tag.


Data types

This section describes the correct data types to use; the data types you use depend on the type of connection:

Ethernet connection data types

Serial connection data types

You must use the correct data types when defining your variables for your CitectSCADA project.



Ethernet connection data types

The table below show the data types for configuring an Ethernet connection.


Data Types Valid Address Range

Address Format CitectSCADA Data Type

Output Coils 00001 - 099999

Valid address (e.g. 01000) DIGITAL

Input Status 10001 - 19999

Valid address (e.g. 13000) DIGITAL

Input Registers 30001 - 399999

Valid address (e.g. 31350) INT/ REAL/ LONG/ BCD/ LONGBCD

Input Registers (DIGITAL)

30001 - 399999

Valid address.b where b is the bit number between 1 and 16 inclusive(e.g. 32300.2)

DIGITAL

Input Registers (STRING) (For use with Modnet version 3.00B and later)

30001 - 399999

SValid address where S denotes the STRING data type (e.g. S300206)

STRING

Output Registers 40001 - 499999

Valid address (e.g. 41190) INT/ REAL/ LONG/ BCD/ LONGBCD

Output Registers (DIGITAL)

40001 - 499999

Valid address.b where b is the bit number between 1 and 16 inclusive (e.g. 40001.4)

DIGITAL

Output Registers (STRING) (For use with Modnet version 3.00B and later)

40001 - 49999

SValid address where S denotes the STRING data type (e.g. S40020)

STRING

Input Registers Odd address (for use with Modnet version 3.00B and later)

300001 - 399999

OValid address (e.g. O326750) LONG/ LONGBCD/ REAL

Input Registers Even address (for use with Modnet version 3.00B and later)

300001 - 399999

EValid address (e.g. E345999) LONG/ LONGBCD/ REAL

Output Registers Odd address (for use with Modnet version 3.00B and later)

400001 - 499999

OValid address (e.g. O450601) LONG/ LONGBCD/ REAL

Output Registers Even address (for use with Modnet version 3.00B and later)

400001 - 499999

EValid address (e.g. E435001) LONG/ LONGBCD/ REAL

Extended registers EF:R where E denotes the extended register. F is INT/ REAL/ LONG/

Examples:

the file number between 1 and 16 inclusive and R is the register between 0 and 9999 inclusive

BCD/ LONGBCD/ STRING

Note: When writing DIGITAL variables to Output registers, individual bits in a register (1..16) can be written to with the format n.BitPosition (e.g. 40001.1). Writing to sequential bits requires individual write commands. You can specify the bit order direction in the INI parameter [MODBUS]RegisterBitReverse.

Data Type Address Comment

DIGITAL 00036 Output Coil


LONGBCD 30019 Input Register


Serial connection data types

The table below show the data types for configuring a serial connection:

Examples

Note: In the Modbus protocol, LONG data types default to a simplified implementation, with a shortened range of 0 to 655,359,999. To increase the LONG data type to the full range, set [MODBUS]LongDataType to either 1 or 3.


Data Types Address Format CitectSCADA Data Type DIGITAL

Output Coils 00001 to 09999 DIGITAL (Note: Leading zero is required.)

Input Status 10001 to 19999 DIGITAL (Read Only)

INTEGER

Input Registers 30001 to 39999 INT / LONG / STRING / REAL (Read Only)

Output Registers 40001 to 49999 INT / LONG / STRING / REAL

EXTENDED REGISTERS

(6xxxxx range) Ef:r.b where: f = file no. (1 - 999) r = register no. (0 - 9999) b = bit no. (1 - 16)

DIGITAL / INT / LONG / STRING / REAL


DIGITAL 00001 Output Coil 00001


INT 40001 Output Register 40001


INT E1:00001 Modbus Address 600001


Advanced Configuration and Maintenance

This section contains advanced configuration information for your devices using Modbus.

See Also

Customizing a project using Citect.ini parameters



Customizing a project using Citect.ini parameters

Citect.ini parameters are used to tune the performance of the CitectSCADA Modbus driver and to perform runtime maintenance diagnostics.

You can customize the way CitectSCADA communicates with the Modbus system (and even individual PLCs) by creating or editing the [MODBUS] section of the citect.ini file for your project.

There are some common CitectSCADA driver settings as well as custom CitectSCADA Modbus driver settings.

When CitectSCADA starts at runtime, it reads configuration values from the citect.ini file that is stored locally. Therefore, any Modbus configuration settings must be included in the citect.ini file located on the computer acting as the I/O server to the Modbus system.

By default, CitectSCADA looks for the citect.ini file in the CitectSCADA project \bin directory. If it can't find the file there, it searches the default Windows directory.

See Also

Common Citect.ini driver parameters Modbus device/group-specific parameters



Common Citect.ini driver parameters

Warning! Citect has determined the default values for these parameters to be the optimal value for the CitectSCADA Modbus driver. All these parameters default to a value tested to work in most cases. We do not recommend adjusting these default values except on the direct advice of Citect Customer Support.

With certain parameters, the Modbus driver can apply different initialization parameter values to specific I/O devices or groups of I/O devices. For details see Modbus device/group-specific parameters.


[MODBUS]Block

A value (bytes) used by the I/O server to determine if two or more packets can be blocked into one data request before being sent to the I/O device. For example, if you set the value to 10 and the I/O server receives two simultaneous data requests (one for byte 3 and another for byte 8) the two requests are blocked into a single physical data request packet. This single request packet is then sent to the I/O device, saving on bandwidth and processing.

Allowable Values: 5 to 256 Default Value: 50

[MODBUS]Broadcast

Issues a write request to all controllers on a Modbus network. To use this feature, you must:

1. Define a Modbus or Modbusa I/O device with Address 0 (zero) for the Channel of interest.

2. Define the value for the BroadcastDelay parameter in the citect.ini file (default is 50ms). This parameter defines the amount of time the driver will delay after submitting a Broadcast request before it will send another request to the PLCs.

3. Define tags (Coils and Registers) associated with this I/ O device.

4. Implement a CitectSCADA Application that requests writes to the tags (via Cicode, application display, and so on).

Allowable Values: 0 = Broadcast disabled 1 = write request will be issued

Default Value: 0

Notes

Requests for Variable Tag READs to the I/O device with the address zero (0) will return a Driver Error of Unknown Command (driver error 15 decimal).

Requests for Variable Tag WRITEs to the I/O device with the address zero (0) will be issued to ALL controllers on the SAME Channel (port) as the I/O device with the assigned address of zero. The Modbus protocol does not provide a response to broadcast requests so you should inspect the appropriate coils or registers in each controller to observe completion of the request.

[MODBUS]BroadcastDelay

Defines the amount of time the driver will delay after submitting a broadcast request before sending another request to the PLCs.

Default Value: 50

[MODBUS]Delay

The period (in milliseconds) to wait between receiving a response and sending the next command.

Allowable Values: 0 to 300 (milliseconds) Default Value: 0

[MODBUS]DoCRC

Enables or disables the Modbus Cyclic Redundancy Check (CRC), a communications error check. The Modbus driver does a CRC on incoming data and provides a CRC remainder in

outgoing data blocks. In some limited cases, such as the testing of "slave" drivers, it may be necessary to disable the CRC.

Allowable Values: 1 or 0, where: 1 = enable CRC 0 = disable CRC

Default Value: 1

The CRC should remain "enabled" under normal circumstances. If the CRC is disabled, no checks are performed on incoming data and the CRC field in the data transmitted by the driver remains 0. This will mean the driver cannot detect communication errors between itself and the I/O device.

[MODBUS]FloatMode

Control byte order for floating point values (the Modbus driver supports floating point values). Some systems expect to use a different byte order for their floating point data.

Allowable Values: 0 to 3, where: 0 - Byte order = 1 0 3 2 1 - Byte order = 3 2 1 0 2 - Byte order = 0 1 2 3 3 - Byte order = 2 3 0 1

Default Value: 0

With this parameter, you can set different values for specific I/O devices or groups of I/O devices. See Modbus device/group-specific parameters.

[MODBUS]ForceMultiCoilsOnly

Forces the use of only function code 15 (multiple coils) for coil writes.

Allowable Values: 0 or 1: 0 - (function code 5 and 15) 1 - (function code 15 only)

Default Value: 0

[MODBUS]InitType

The type of variable the Modbus protocol tries to read on startup, to allow communication to start.

Allowable Values: 1 to 4, where:

Default Value: 2


[MODBUS]InitUnitAddress

InitType Address Variable

1 00001 - 00017 Output status

2 10001 - 10017 Input status

3 40001 Output registers

4 30001 Input registers

The Modbus driver reads the citect.ini file to determine the correct unit address for initialization of a PLC. InitUnitAddress is the parameter used to set the unit address.



[MODBUS]LongDataType

In the Modbus protocol, LONG data types default to a simplified implementation, with a shortened range of 0 to 655,359,999 - mode 0. Mode 2 has the same range as mode 0, but with the register order swapped. Mode 1 supports the full LONG range of -2,147,483,648 to +2,147,483,647. Mode 3 has the same range as mode 1, but with the register order swapped.

Allowable Values: 0 to 3, where: 0 = 10000 x low register + high register 1 = 65536 x low register + high register 2 = 10000 x high register + low register 3 = 65536 x high register + low register

Default Value: 0


[MODBUS]MaxBits

The maximum read size in one request. Decrease the value for non-standard I/O devices that do not support large reads.

Allowable Values: 1 to 2000 (bits) Default Value: 2000

[MODBUS]MaxPending

The maximum number of pending commands that the driver holds ready for immediate execution.


[MODBUS]Pad

The number of characters with which to pad protocol messages. The padding characters wake the radio modem to allow the rest of the message to be transmitted. A value of 20 is recommended for non-standard I/O devices that operate over radio modems.

Default Value: 0

[MODBUS]PadChar

The ASCII code of the padding character with which to pad protocol messages. The padding characters wake the radio modem to allow the rest of the message to be transmitted.

Default Value: 255

[MODBUS]PollTime

The interrupt or polling service time (in milliseconds). Setting the polling time to 0 puts the driver in interrupt mode.


[MODBUS]PresetMultiRegisterOnly

Forces the use of only function code 16 (multiple registers) for register writes.

Allowable Values: 0 or 1: 0 - (function code 6 and 16) 1 - (function code 16 only)

Default Value: 0

[MODBUS]RegisterBitReverse

Allows reverse interpretation of MSB and LSB in words. The Modbus specification defines bit 1 of a word as the MSB, and bit16 of the word as the LSB. Some devices use a different order, causing bit 1 of a word to be the LSB and bit 16 to be the MSB.

Allowable Values: 0 or 1, where: 1 - Bit 1= LSB, Bit 16 = MSB 0 - Bit 1 = MSB, Bit 16 = LSB

Default Value: 0


[MODBUS]Retry

The number of times to retry a command after a timeout.


[MODBUS]SendBCDSwap

Reverses the byte order for BCDs on writes (the Modbus driver supports BCDs). Some systems expect to use a different byte order for their data; in the case of BCDs, this causes "1234" to be written to the device as "3412".

Allowable Values: 0 or 1, where: 1 = 1 2 3 4 0 = 3 4 1 2

Default Value: 1


[MODBUS]Status

Sometimes you can read data from a device even though the processor module is not running. In view of this, it can be useful to detect this situation by monitoring a continuously changing register or a digital. If the register fails to change in a given period or the digital becomes zero, the processor can be assumed to have stopped running.

If enabled, the Modbus driver will check on startup and approximately every watchtime the status of a user specified variable in the PLC is changing. If a digital is specified, the value must always be on otherwise the unit is put offline. If an analog is specified, on startup two consecutive reads with an interval of 1000ms (specified by [MODBUS]Timeout) must return different values before the unit can be put online. At every watchtime, if the digital is off or the analog data does not change from the last value read, the driver returns an error and the unit is put offline.

The Status parameter takes the form:

status = RawType,BitWidth,UnitType,UnitAddress,UnitAddress

where:

Examples

To specify Modbus address 40001 as the analog tag variable which must change to indicate the device is online, use:

[MODBUS] status=1,16,3,0,1

To use Modbus address 00001 as the digital tag variable which must remain set to 1 to indicate the device is online, then use:

[MODBUS] status=0,1,1,0,16

[MODBUS]StringReverse

Reverse byte order for strings. The Modbus protocol driver supports strings. Some systems expect to use a different byte order for their data, which in the case of string variables, causes "ABCD" to appear as "BADC".

Allowable Values: 0 or 1 Default Value: 0 (do not reverse byte order)


[MODBUS]Timeout

Specifies how many milliseconds to wait for a response before displaying an error message.


[MODBUS]WatchTime

The frequency (in seconds) that the driver uses to check the communications link to the I/O device.

RawType BitWidth UnitType UnitAddress UnitCount 0 = Digital 1 = Digital See variable specification .dbf files The item number orbit number 1 = analog16 = digital

1 = Int 16 = Int 4 = Long 32 = Long 8 = Byte 8 = Byte

Allowable Values: 0 to 128 (seconds) Default Value: 30


Modbus device/group-specific parameters

The Modbus driver can apply different initialization parameter values to specific I/O devices or groups of I/O devices. This means the user can specify:

Global parameters that apply to all devices.

Channel- (port-) level parameters that apply to all devices on the specified port.

Group-level parameters that apply to all devices in a specified group.

Device-level parameters that apply only to the specified device.

This feature can be implemented in the citect.ini file for the following Modbus parameters:

[MODBUS]InitType

[MODBUS]LongDataType

[MODBUS]StringReverse

[MODBUS]InitUnitAddress

[MODBUS]FloatMode

[MODBUS]SendBCDSwap

[MODBUS]RegisterBitReverse

To set parameters for a particular port, group, or device, you must create a new section in the citect.ini file. Label it with the driver name followed by a period (.) character and the name of the particular port, group, or device you want to specify the parameter setting for.

For example:

[MODBUS.<Port_Name>]: applies the parameter settings to the specified port.

[MODBUS.<Group_Name>]: applies the parameter settings to the specified group.

[MODBUS.<Port_Name>.<IODevice_Name>]: applies to the specified device.

Any parameters you then define in the following section of the citect.ini file relate only to the specified device or device group.

Example

The following Citect INI file format is an example of how the InitType parameter could be specified differently for different I/O devices communicating using the Modbus protocol.

Assume that two ports are used: PORT1 and PORT2. PORT1 has three I/O devices attached:

DEV1A DEV1B EV1C


PORT2 also has three devices:

DEV2A DEV2B DEV2C

Assume that the user has specified that DEV1C and DEV2C belong to GROUPZ. The citect.ini file contains the following entries:

[MODBUS] InitType=1 [MODBUS.PORT1] InitType=2 [MODBUS.PORT2] InitType=2 [MODBUS.GROUPZ] InitType=3 [MODBUS.PORT1.DEV1A] InitType=1 [MODBUS.PORT2.DEV2B] InitType=4

The resultant InitType for the I/O devices will be as follows:

As the above example shows, there is a hierarchy that determines the outcome of such settings. In simple terms, specific parameter settings overwrite general level settings. Therefore, parameters written in the scope of I/O devices will overwrite those set for groups; parameters set for groups will overwrite global settings, and so on.

See Also

Common Citect.ini driver parameters

DEV1A: 1 as a result of [MODBUS.PORT1.DEV1A]

DEV1B: 2 as a result of [MODBUS.PORT1]

DEV1C: 3 as a result of [MODBUS.GROUPZ]

DEV2A: 2 as a result of [MODBUS.PORT2]

DEV2B: 4 as a result of [MODBUS.PORT2.DEV2B]

DEV2C: 3 as a result of [MODBUS.GROUPZ]


Troubleshooting

Most large projects will suffer bugs in the runtime system. These problems usually have simple solutions and require only perseverance to solve them.

The following topics describe the CitectSCADA tools provided to help resolve problems with communication and configuration.

Hardware alarms

syslog.dat file

Driver errors


Citect Kernel diagnostics

Maintaining the project database


Hardware alarms

When a system error occurs that is a malfunction in CitectSCADA operation, CitectSCADA generates a hardware alarm. Hardware alarms are usually displayed on a dedicated Hardware Alarm page, which is available as a standard template.

The hardware alarm page is your primary indicator of what is happening in your CitectSCADA system. If a communication fault occurs, if Cicode can't execute, if a graphics page is not updating correctly, or if a server fails, this page will alert you to it. Hardware alarms consist of a unique description and error code.

The hardware alarms do not have detailed information, but point you in the direction of a problem. For example, if you have a Conflicting Animation alarm, CitectSCADA will not tell you the cause. You must observe which page causes the hardware alarm, and locate the animations yourself.

Your system should have no recurring hardware alarms. If, after reviewing all documentation, you cannot rectify an alarm, contact Citect Technical Support.



syslog.dat file

The syslog.dat file is maintained by runtime CitectSCADA and contains a log of CitectSCADA system information. The types of information that can be logged to the syslog.dat is extensive: from low-level driver traffic and Kernel messages, to user-defined messages.

The Log Read and Log Write fields in the I/O Devices Properties dialog box control whether logs are made for each I/O device.

CitectSCADA locks the syslog.dat file while running. However, you can still view it by using the SysLog command in the Kernel. See Citect Kernel diagnostics, and the CitectSCADA User Guide for details.



Driver errors

CitectSCADA Modbus driver errors can occur when a device using Modbus fails to respond, or


is disconnected or offline, or returns an error itself. Error codes are listed below.

The Modbus driver can log combinations of trace levels across different categories. For more information, see Citect Kernel diagnostics.


Common protocol errors

CitectSCADA has two kinds of protocol driver errors:

Generic errors, which are hardware errors 0-31 and common to all protocols. Some generic errors are common to all protocols. Sometimes only the generic error is available, though often both the generic error and a specific error are given.

Specific errors, which can be unique and therefore cannot be recognized by the hardware alarm system. The drivers convert their specific errors into generic errors that can be identified by the I/O server. For example, when a driver has a fault, there is often both a protocol-specific error and a corresponding generic error.

When a hardware error occurs, CitectSCADA generates an alarm and displays the alarm on the Hardware Alarm page (in the alarm description of the hardware alarm). To see the error number, make sure you have Alarm Category 255 defined with a display format that includes {ErrDesc,15} {ErrPage,10}.



Modbus protocol-specific errors

The following errors, listed in (hexadecimal) sequence, are specific to this protocol. CitectSCADA displays the error number and description for common protocol-specific errors. Uncommon errors are not contained in the CitectSCADA error database, in which case CitectSCADA only displays the error number.

You might need additional information to rectify an error. This information should be detailed in the documentation that accompanied the I/O device (or network). If, after reviewing all documentation, you cannot rectify an error, contact Citect Technical Support.


Error (in hex) Description 0x0101 Illegal function The message function received is not allowed for the addressed slave.

0x0102 Illegal data address The address referenced is out of range.

0x0103 Illegal data value Invalid data is being written to the PLC.

0x0108 Memory parity error An error has been encountered in the computer's memory.



Citect Kernel diagnostics

The Citect Kernel window diagnostics framework (commonly referred to as the Kernel), is the primary gateway into the internal workings of CitectSCADA at runtime, and is provided for diagnostics and debugging purposes only.

The Kernel can display several different diagnostic windows each displaying an active view into the workings of the CitectSCADA runtime system. Each window is displayed when selected from the Citect Kernel View menu.

For details about the Citect Kernel, refer to the CitectSCADA User Guide.

Warning! Use the Kernel window with care: once in the Kernel, you can execute any Cicode function with no privilege restrictions. A person using the Kernel has total control of CitectSCADA (and subsequently your plant and equipment).


Setting up the Kernel

You need to configure your CitectSCADA project to provide run-time access to the Kernel diagnostics window. You can do one or both of the following:

Enable the Kernel on CitectSCADA startup.

Add the Kernel menu item to the runtime CitectSCADA Control menu.

To enable the Kernel diagnostics window on CitectSCADA start-up:

1. In the Citect Explorer menu, select View | Configuration File. This launches Windows Notepad and loads and displays the citect.ini file for manual editing. (The citect.ini file is located in the Windows folder, typically in C:\WINDOWS or C:\WINNT.)

2. Scroll down to the [Debug] category, and edit the section to include the following parameter: [DEBUG] Kernel=1

3. Save and Close Notepad.

This parameter causes the automatic display of the Citect Kernel window diagnostics framework upon startup of CitectSCADA. Swap to it to view what's happening inside CitectSCADA at runtime.

To add the Kernel menu item to the CitectSCADA runtime Control menu:

1. In Citect Explorer or Project Editor, launch the Computer Setup Wizard and select Custom mode:


2. Click Next until you reach the Security Setup - Control Menu page:

3. Check the Kernel on menu option and click Next until finished.

At runtime, you can display the Kernel window by selecting Kernel from the Control menu (top-left corner) of CitectSCADA. If you do not have a Title Bar displayed in your runtime project, you can access the Control menu by pressing Alt + Spacebar (if the Alt-Space enabled option is selected on the Security Setup - Keyboard page).

Warning! You should clear these options before handover to prevent accidental or unauthorized use of the Kernel in the delivered system.



Diagnostic windows

The key diagnostic windows included with the Kernel for testing I/O device communications are the Main window, the I/O Devices window, and the Driver Statistics window:

The Citect Kernel Main window displays the diagnostic messages a line at a time indicating the current CitectSCADA startup operation and status. When running, the Main diagnostics window continues to report changes in the status of the I/O devices.

The Citect Kernel Unit window displays the current status of all devices defined in the I/O device database.

The Citect Kernel driver window displays information about each driver in the CitectSCADA system. This window is only displayed if the computer is configured as an I/O server with physical I/O devices attached.


Citect Kernel Main window

After your I/O devices are properly configured, the Main window is particularly useful to check that all of your I/O devices come online correctly when CitectSCADA is started.


First the ports are initialized, then the I/O device is brought online. If there is a problem, CitectSCADA display the message "PLC not responding", "I/O Device Offline" or similar.

Some I/O devices might take two attempts to come online. If so, CitectSCADA waits (usually 30 seconds) and tries again. If your I/O device does not come online after the second attempt, check your configuration (at both ends) and the network in between.

Common problems that can cause startup errors include:

Incorrect computer setup - usually solved by the Computer Setup Wizard.

Networking faults or bad hardware - cables wrongly wired or unplugged, or equipment not powered up, or faulty equipment.

Communication faults - most often a configuration mistake like wrong protocol settings, wrong port, and so on.

The Kernel Main diagnostic window contains legacy behavior from early versions of Microsoft Windows. It has no scroll bar, so as new messages are added a line at a time to the end of the displayed list of messages, and the window is filled, the oldest message (at the top of the window list) scrolls out of view and is lost. However, you can view this information using the syslog.dat file.


Citect Kernel Unit window

The Unit diagnostics window, launched via the Page Unit Kernel command, displays the current status of all devices defined in the I/O device database. In this window, use the Page Up or Page Down keys to browse available devices.

The important values to check to confirm that communications with the I/O device are enabled and running are the Server Status and Client Status fields. When the I/O device is online, these both display "RUNNING".

For details about the fields displayed for each I/O device in the Unit diagnostics window, refer to the Citect SCADA User Guide.



Citect Kernel driver window

The Citect Kernel Driver window, launched via the Page Driver Kernel command, displays information about each driver in the CitectSCADA system. The statistics it presents include read requests, physical reads, digital reads per second, register reads, cache reads, error count, timeouts, and so on. Refer to the CitectSCADA User Guide for details.



Maintaining the project database

Over time with editing, the project database underlying a project can become fragmented and problematic. During project development you should periodically clear out all duplicated records and any orphaned ones.

Improperly maintained databases can result in communication problems at runtime. Most communications problems come from having duplicated or orphaned records in the communications database.

Sometimes orphaned records from a previous I/O server are left behind in the database files. As all the forms are indexed on the I/O server name, you can use the scroll bar to quickly navigate to the end of the current range of records for a particular I/O server and examine the last few and next few records to validate that they should be there. If you find extra (unwanted) records, delete them.

You should also make sure that there are no duplicated records. Use the record search facility to search for duplicate entries of devices that are causing unexplained communication errors. If you find extra (unwanted) records, delete them.

Once you have deleted orphaned and duplicated records, pack the project. Packing the database removes deleted records, and re-indexes the database. To pack the project databases, from the File menu in Citect Project Editor, choose Pack.



Citect SCADA 6[1].10 Modbus Driver Help

Documents

Transcript of Citect SCADA 6[1].10 Modbus Driver Help