Driver features

The driver is available in two versions:

Version for standard RS-232C serial interface (including RS-485, RS-422).

Version for TCP/IP networks (a.k.a. Modbus/TCP)

Both versions have similar features, there are only differences caused by different data transport layer. The driver enables one or more devices to communicate with Control Web through MODBUS protocol using RTU or ASCII mode. One driver instance works with one serial interface (COM port). If more devices have to be connected to more serial interfaces, it is necessary to declare multiple instances of this driver in application. Modbus/TCP driver version can communicate with more devices within TCP network.

List of sections:

Driver features

Driver functionality

Driver parameters

Driver channels

Driver procedures

Driver map file

Driver exceptions and exceptions handling

Error codes

Example of driver usage

Driver functionality

Data transfer and types

The driver is capable to read/write data from/to

• Coils (binary outputs) — area 0X.

• Inputs (binary inputs) — area 1X.

• Input Registers — area 3X.

• Holding Registers — area 4X.

All areas can be assigned to individual registers according to the driver parameter file. There is also a set of channels dedicated to driver control so it is recommended to start numbering of data channel from 100.

Holding registers (4X) or Input Registers (3X) can be interpreted differently depending on the station.

• One word (16-bit) register can hold signed or unsigned value corresponding to one channel.

• One word (16-bit) register can be split to two signed or unsigned byte values interpreted as two separate channels.

• One word (16-bit) register can be split to 16 logical values interpreted as 16 separate boolean channels.

• One word (16-bit) register can be interpreted as one boolean channel (0 means false, any other value means true).

• Two words (16-bit) registers can be interpreted as one channel. Resulting 32-bit value can hold:

  • 4 byte floating point number (single precision)

  • 4 byte signed integer

  • 4 byte unsigned integer

• Four words (16-bit) registers can be interpreted as one channel. Resulting 64-bit value can hold:

  • 8 byte floating point number (double precision)

  • 8 byte signed integer

There is a rule that all numeric values are converted to real (floating point) channels. All conversions between device number formats and Control Web real numbers are performed by driver.

Communication through serial interface

The driver opens the serial interface during applications startup and keeps it open while the application is running. It is not necessary to close and reopen the serial interface in the case of communication errors. If the communication fails, the driver reports an error and tries to communicate with the device again when the next communication request occurs. The application performance can be negatively affected by errors in communication (the amount of performance decrease depends on the timeout parameter of individual channels). If this parameters is set to some small value, the performance decrease is not significant. If the error condition terminates, communication resumes automatically. There is also a possibility to suspend the communication while the error condition persists and only periodically check for the error state using the Control Web application logic.

TCP/IP communication

Communication within TCP/IP networks requires somewhat different approach than communication through serial line. It is necessary to create TCP connection first and then it is possible to exchange data over the established connection. If the connection fails due to arbitrary reason, the TCP connection closes. That is why the driver must try to establish the TCP connection again before the next communication attempt. If the connection could not be created for a long time, the performance decreases significantly, because the attempt to create TCP connection a s long procedure with timeouts controlled by the underlying TCP/IP software stack. The driver does not attempt to establish broken TCP connection for every communication request to reduce performance decrease. It periodically checks for the possibility to create the connection and notifies the application by means of driver exception in the case of successful connection establishment. The period used for attempts to create the connection can be defined as driver parameter.

Driver parameters

Driver behavior can be modified by settings of its parameters. These parameters are defined in the '.PAR' file, which is specified together with the driver in the Control Web application. PAR file is a text (ASCII) file, which can be edited by a number of text editors (e.g. Notepad). Individual parameters are grouped into several sections. Every section begins with a section name, specified within square brackets. The parameter definition follows, one parameter per line. Every line begins with parameter name, followed by delimiter (character "=") and parameter value.

Driver parameter definition — section [Modbus]

This section contains parameters, which configures the driver. Individual parameters and their possible values are:

[Modbus]
ComDriver = <driver>, <device>
Mode = RTU | ASCII
Timeout = <n>
EnableMonitor = true | false
DisablePresetSingleRegister = true | false
SwapBytes = true | false
SwapRegisters = true | false
OffsetFromOne = true | false
MaxRegistersInBlock = <n>
NumRepeat = <n>
WritePriority = true | false
FinalizeAfterEachBlock = true | false
TraceOutput = none | log | windows | xtrace
MaxExceptions = <n>
ConnectOnStartup = true | false
CheckTimeout = <n>

Individual parameters description:

Example of the [Modbus] section:

[Modbus]
ComDriver = cwcomm, com2
Mode = RTU
Timeout = 350
EnableMonitor = true
DisablePresetSingleRegister = true
OffsetFromOne = true
SwapBytes = true
SwapRegisters = true
MaxRegistersInBlock = 100
NumRepeat = 1
WritePriority = true
FinalizeAfterEachBlock = false
TraceOutput = none

Channels definition — section [Channels]

This section defines individual channels or group of channels and their representation in the PLC's memory. Groups are defined in individual blocks. One block is defined by the range of channel numbers, connection identifier, PLC data area, data type and start and end addresses in the PLC data area. It is possible to define parameter bidirect, which eliminates collisions of bi-directional channels during overlapping read and write operations — there are two independent channel blocks for read and write created in the driver. Another optional parameter defines byte swapping for types longer than 1 byte. It is also possible to add a comment. Comments must be on separate lines and must begin with semicolon.

One block represent maximal continuous data area transferred during one communication transaction from the communication point of view. However, the maximal size transferred also depends on the used protocol and on the lower layers. They can split the block to even smaller packets.

Every channel group (block) is described on one line. Syntax for one block description is as follows. Optional parameters are in square brackets.

[Channels]
  Block = <Station>, <ChFrom>, <ChlTo>, <Area>, <Ofs> [, <SubType>] [, <Bidirect>] [, <Id>] [<;Comment>]
  Block = ...
  ...

<UnitId>@<IPAdr>[:<IPPort>]

Data types used in the driver

Example of the serial driver parameter file [Channels]section:

[Channels]
  Block = 01,  100,  199, H, 1, int16,  bidirect ; registers as numbers
  Block = 01,  200,  299, H, 1, bits16, bidirect ; registers as bits
  Block = 01,  300,  399, R, 1                   ; input registers
  Block = 01, 1000, 1015, O, 1,         bidirect ; digital outputs
  Block = 01, 1100, 1115, I, 1                   ; digital inputs

Example of the TCP/IP driver parameter file [Channels] section:

[Channels]
  Block = 00@10.0.0.5,  100,  199, H, 1, int16,  bidirect, ID:01 ; registers as numbers
  Block = 00@10.0.0.5,  200,  299, H, 1, bits16, bidirect, ID:02 ; registers as bits
  Block = 00@10.0.0.5,  300,  399, R, 1,                   ID:03 ; input registers
  Block = 00@10.0.0.5, 1000, 1015, O, 1,         bidirect, ID:04 ; digital outputs
  Block = 00@10.0.0.5, 1100, 1115, I, 1,                   ID:05 ; digital inputs

Communication link layer parameters — section [comm]

The communication link layer represents a tool for access to the standard serial interface of the computer. This layer makes it possible, among other things, for one serial interface to be shared by more drivers. In the Control Web system the communication link layer is represented by two DLL libraries ('CWXLINK.DLL' and 'CWCOMM.DLL'). For its configuration in the parameter files of the driver there is the section [comm]. Here you can either define serial communication parameters directly or assign the reference (redirection) to the independent configuration file with the serial communication parameters. In the case of redirection, the section [comm] contains only one parameter — file:

[comm]
  file=c:\cw\par\comm.par

Structure of parameters of the link layer:

[comm]
  file = <file>
  device = <comdevice>

If the parameter device is defined and the section with the name comdevice exists configuration parameters will be achieved with priority from this section, otherwise parameters will be used directly from the section [comm].

Mandatory parameters:

[comm]
  rx_frame_buffer = <N>
  tx_frame_buffer = <N>
  baudrate = <N>
  databits = <N>
  stopbits = one | 1 | oneandhalf | 1.5 | two | 2
  parity = none | no | even | mark | odd | space
  cts_flow = true | false 
  dsr_flow = true | false
  dtr_control = disable | low | enable | high | handshake | toggle | toggle_neg
  rts_control = disable | low | enable | high | handshake | toggle | toggle_neg
  dsr_sense = low | high
  rx_interchar_timeout = <N>
  rx_char_timeout = <N>
  rx_timeout = <N>
  tx_char_timeout = <N>
  tx_timeout = <N>

Optional parameters:

  priority = idle | low | below_normal | normal | above_normal | high | realtime
  mode = fullduplex | halfduplex
  pre_key = <N>
  hold_key = <N>
  rx_buffer = <N>
  tx_buffer = <N>
  tx_continue_xon_xoff = true | false
  tx_xon_xoff = true | false
  rx_xon_xoff = true | false
  xon_tresh = <N>
  xoff_tresh = <N>
  error_xlat = true | false
  discard_null = true | false
  xon_char = <N>
  xoff_char = <N>
  err_char = <N>
  eof_char = <N>
  evt_char = <N>

Syntax categories:

Description of individual parameters:

Example of [comm] section parameters:

[comm]
baudrate = 9600
parity = even
databits = 8
stopbits = 1
rx_buffer = 1152
tx_buffer = 1152
rx_frame_buffer = 1152
tx_frame_buffer = 1152
cts_flow = false
dsr_flow = false
dtr_control = disable
rts_control = disable
dsr_sense = low
rx_interchar_timeout = 0
rx_char_timeout = 0
rx_timeout = 0
tx_char_timeout = 0
tx_timeout = 0

Driver channels

The driver provides access to various data area elements by means of numeric and logical (bit) channels. Mapping of data area elements to channels is defined by [Channel] section of driver parameter file.

Reserved driver channels

The driver can pass information about its state in a set of special channels, mapped as channels number 1 to 99. Driver exception is generated in the case of communication error and individual channels hold information specifying the error or event. Channel No. 1 determines if the error occurred during read or write or if the TCP/IP connection was established. Channels 10 to 18 contain specification of read error, channels 20 to 28 contain specification of write error.

Driver procedures

The application may call for the driver certain procedures using which it is possible to control the behavior of the driver or to gain important information. This is done by means of the system procedure:

system.DriverQueryProc( DriverName : string; Param1 : any; &Param2 : any )

Parameters of the procedure have the following meaning:

DriverName and Param1 are typed as text strings. Param2 is of various type according to the meaning of the procedure. Some procedures serving for setting of parameters may finish in error.

Overview and meaning of driver procedures (Param1 parameter)

Driver map file

This file contains types of channels defined for this driver. Because the driver defines fixed set of reserved channels and variable set of channels providing access to data area elements, DMF file should contain always the same definition of reserved channels and variable definition of channels corresponding to channels defined in the [Channels] section of the driver parameter file.

Example of driver map file.

begin
     1 real input
    10 real input
    11 real input
    12 string input
    13 real input
    14 real input
    15 real input
    16 real input
    17 boolean output
    18 boolean output
    20 real input
    21 real input
    22 string input
    23 real input
    24 real input
    25 real input
    26 real input
    27 boolean output
    28 boolean output
   100 - 199 real bidirectional
   200 - 299 boolean bidirectional
   300 - 399 real input
  1000 - 1099 boolean bidirectional
  1100 - 1199 boolean input
end.

Driver exceptions and exceptions handling

Driver exception is raised in the case of communication error. There should be virtual instrument with the specified parameter driver_exception = driver_identifier in the running application. This instrument is activated by the exception and it can read the exception state by reading of channel no. 1. Individual bits of returned number defines the state (bits can be obtained e.g. by bitget function):

• bit 0 set — read error

• bit 1 set — write error

• bit 2 set — TCP connection with device identified by channel no. 2 established

• bit 3 set — connection error during application startup

Error codes

If some error occurs, the following error codes are generated by the driver. These codes are available at channels number 11 and 21. If the error condition occurs then an error message is also written to Log Window of the Control Web.

• 0 — success.

• 1 — timeout error.

• 2 — invalid value.

• 3 — non-existing channel.

• 101 — illegal function.

• 102 — illegal data address.

• 103 — illegal data value.

• 104 — slave device failure.

• 105 — acknowledge.

• 106 — slave device busy.

• 107 — negative acknowledge.

• 108 — memory parity error.

• 110 — gateway path unavailable.

• 111 — gateway target device failed to respond.

• 200 — CRC error.

• 201 — input communication buffer full.

• 202 — device address error.

• 203 — function error.

• 204 — data length error.

• 205 — TCP/IP connection error.

• 206 — device is disconnected.

• 207 — established connection was aborted by the host machine.

• 300 — undefined error.

Example of driver usage

There are several examples of the driver usage in the package installation. These examples can be found in the 'EXAMPLES\MODBUS' or 'EXAMPLES\MBUSTCP' directory. Examples also contain '*.DMF' and '*.PAR' files. It is necessary to modify these files according to actual device configuration.