Empty cart
Title Page
Login
Search 
 Control Web 8
 Drivers for Control Web
 DataLab
 DataCam
 DataLight
 For schools
 Other software
 Control Web - previous versions
 Services

MODBUS TCP/IP
 

MODBUS TCP/IP


Code:CW-MBTCP
Price for system integrators (excl. VAT): 208 EUR
List price (excl. VAT): 231 EUR
Manufacturer:Moravian Instruments
 
TOTAL
Dealer Price (excl. VAT):
Total Price (excl. VAT):
*) Estimated availability varies depending on product options. Estimated availability does not include time of shipping and it is not obligatory.

These drivers provide interface among Control Web process control software system and one or more devices (e.g. PLCs) using MODBUS serial protocol or MODBUS TCP protocol.

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.

Remark:

Both section and parameter names are case-sensitive.

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>
driver

text string

device

text string

n

numeric value.

Individual parameters description:

ComDriver

name of the driver library of the series interface (link layers) and name of the communication port (COMx) which is installed in the Windows environment. The name of the standard driver is 'CWCOMM.DLL'.

Mode

Defines mode of communication. It is possible to choose between binary RTU mode or character ASCII mode.

Timeout

time of waiting for a response in milliseconds. If during this time there is no device response, the communication error will be returned into the application.

Remark:

In the TCP/IP driver the parameter NumRepeat is ignored.

EnableMonitor

This parameter enables/disables output of debug messages in the driver window.

DisablePresetSingleRegister

This parameter enables/disables function No. 6 -- setting of individual registers. Some devices (e.g. Simatic CP-521) do not support this function. Then it is necessary to use function No. 16 -- setting multiple registers with number = 1.

SwapBytes

flag which states whether swap byte order is altered in the word. This flag is global for all blocks. If it is set to false or is not stated, it is possible to set swap byte order individually within the channels blocks.

SwapRegisters

This parameters enables/disables swapping of registers in the case one value is contained in multiple registers.

OffsetFromOne

This parameter determines if data area begins from 0 or from 1. Default value OffsetFromOne = true means data area begins from 1 (e.g. register number 40001 has offset 1). OffsetFromOne = false means beginning from 0 (register number 40001 has offset 0).

MaxRegistersInBlock

This parameter defines maximum number of registers in one communicated block. Default value is 100 which means maximum block size is 200 byte. Correct value can be determined from the device documentation.

NumRepeat

number of repeated requests for communication after communication error occurred.

Remark:

In the TCP/IP driver the parameter NumRepeat is ignored.

FinalizeAfterEachBlock

using this parameter it is stated whether data will be transferred to the application after each communication (the value of the parameter = true) or after completion of the transfer of all blocks which are resolved within the respective time step. The default value is false.

WritePriority

This parameter affects the way the PLC driver communicates. If set to false, all requests for channel read- ings and then all channel listing requirements are alternated. If the parameter is set to true, write requests to PLCs take precedence. The default setting is true.

TraceOutput

switching of communication trace outputs. If it is necessary to monitor the communication of the driver with the device, it is possible to select by this parameter the target of trace outputs.

Possible values of the parameter are:

none

no trace outputs

log

outputs are directed into Log window of the tab Debug of the Control Web system

xtrace

outputs are directed into the file '\XTRACE.TXT'

windows

outputs are directed into the debug window of the Windows system

Warning:

Trace outputs slow down the activity of the application or they may lead to decreasing the space in the memory or on the disk. Therefore, it is not recommended to use trace outputs in the final application.

ConnectOnStartup

If this parameter is set to true, the driver attempts to connect to all devices on application startup. If some device is not available, application execution continues after network timeout expires. The first access to channel of unavailable device the driver exception is generated and bit 3 (exception kind) of channel no. 1 is set.

CheckTimeout

This parameter defined the period for attempts to restore broken TCP connection. It is defined in milliseconds. Default value is 120000 (2 minutes).

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 = ...
  ...
Station

slave device address for serial line driver (a number within the range from 0 to 255).

 

IP address/port identifier for Modbus/TCP driver:

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

is "Unit Identifier", which is used for communication over IP bridge or gateway.

IPAdr

is IP address or network name (hostname) of the station. IP address is defined in "dotted quad" notation (four numbers 0..255 delimited by dots, e.g. 10.0.0.5).

IPPort

is optional parameter specifying IP port. The default value 502 (Modbus/TCP defined default) is used if not specified.

Example of fully specified address: 00@10.0.0.5:502

ChFrom

first channels of the block (number).

ChTo

last channels of the block (number).

Area

area in station (0X,1X,3X,4X respective O,I,R,H).

Ofs

address of the first element in station corresponding to the first channel. See OffsetFromOne parameter of the [Modbus] section.

SubType

data type of register area 4X and 3X (see data types list).

Bidirect

defines if this block is duplicated for reading and writing.

Id

connection identifier. It is specified in the form ID:<Number>, where <Number> is positive integer.

Comment

comment prepended with semicolon. Any text up to the end of line is considered to be a comment.

Data types used in the driver

Area SubType Channel type Description
0X   boolean 1-bit value used for writing to binary outputs or for reading binary output status
1X   boolean 1-bit binary input
3X, 4X int64 real 64-bit signed integer (four registers)
float64 real 64-bit floating point value (four registers)
uint32 real 32-bit unsigned integer (two registers)
int32 real 32-bit signed integer (two registers)
float32 real 32-bit floating point value (two registers)
uint16 real 16-bit unsigned integer
int16 real 16-bit signed integer
uint8 real two 8-bit unsigned values
int8 real two 8-bit signed values
bool16 boolean one boolean value in one register
bits16 boolean 16 boolean values in one register

Table of driver data types

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:

file

file name at the parameter file

comdevice

section name at the parameter device

N

numeric value

Description of individual parameters:

file

parameter file. It is advisable to use this parameter where more drivers use a single link layer. Line parameters can then be maintained in a single file.

device

name, e.g.COM1. If this parameter is specified, the device of this name will be used. If at the same time there is a section with the same name, the following parameters will be achieved from this section. If there is no section with this name, parameters are read from the actual section.[comm].

priority

priority of the communication thread. The default value is normal.

mode

communication mode full duplex (bi-directional) or half duplex (unidirectional). The default value is fullduplex.

pre_key

delay in milliseconds before the starting of data transmission. The status of DTR/RTS signals, if they work in toggle mode, is changed during the delay to active.

hold_key

delay in milliseconds after data transmission termination. DTR/RTS signals , if they work in toggle mode, remain active during the delay period.

rx_frame_buffer

size of the secondary buffer for input. Permitted range <96;65535>, the parameter does not have a default value.

tx_frame_buffer

size of the secondary buffer for output. Permitted range <96;65535>, the parameter does not have a default value.

rx_buffer

size of the buffer for input; range <96;65535>, the default value is 4096.

tx_buffer

size of the buffer for output; range <96;65535>, the default value is 4096.

baudrate

communicating speed.

databits

number of data bits.

stopbits

number of stop bits.

parity

parity of the transfer.

cts_flow

enables CTS control (handshake)

dsr_flow

enables DSR control (handshake)

dtr_control
rts_control

behavior of DTS and RTS, meaning of values:

disable

control is off, permanently at low level

low

works the same as disable

enable

control is off, permanently at high level

high

works the same as enable

handshake

positive handshake

toggle

the status of the signal is changed during data transmission to high (positive key), otherwise permanently in low

toggle_neg

the status of the signal is changed during data transmission to low (negative key), otherwise permanently in high

Behavior of DTR/RTS in the modes toggle/toggle_neg

Behavior of DTR/RTS in the modes toggle/toggle_neg

dsr_sense

parameter determines if DSR is active at the high or low level (high = positive handshake, low = negative handshake).

tx_continue_xon_xoff

enables stopping of transmission if the input buffer is full and the character XOFF was sent (xoff_char). If true is set, the transmission continues up to the moment when in the input buffer contains at least xoff_tresh free characters and the driver sent the XOFF character (xoff_char) for pause receiving. If false is set, the transmission does not continue up to the moment when in the input buffer contains at least xon_tresh free characters and the driver sent the XON character (xon_char) for restoration of receipt. The default value is false.

tx_xon_xoff

enables XON/XOFF (software) control for output. The default value is false.

rx_xon_xoff

enables XON/XOFF (software) control for input. The default value is false.

xon_tresh

the minimum free capacity of the input buffer for sending of XON. The default value is 50 per cent.

xoff_tresh

influences the maximum number of characters in the input buffer for sending of XOFF. The maximum number of permitted characters can be calculated by subtracting the shown value from the input buffer size (rx_buffer) The default value is 80 per cent.

error_xlat

enables replacement of the characters received with parity error by the character err_char. If true is set and the checking of parity is enabled, there is replacement. The default value is false.

discard_null

enables removal of empty (NULL) characters. If true is set, each NULL character is removed from the input buffer immediately after receipt. The default value is false.

xon_char

decimal code of the character XON.

xoff_char

decimal code of the character XOFF.

err_char

decimal code of the character specified for replacement of the characters received with parity error.

eof_char

decimal code of the character EOF.

evt_char

decimal code of the character EVT.

rx_interchar_timeout

delay between individual characters for receipt in milliseconds

rx_char_timeout

timeout per one received character in milliseconds

rx_timeout

constant timeout for receipt in milliseconds

tx_char_timeout

timeout for sending of one character in milliseconds.

tx_timeout

constant timeout for sending in milliseconds

Warning:

The parameters rx_interchar_timeout, rx_char_timeout and rx_timeout influence the input throughput. By increasing the value rx_timeout it is possible to achieve increase in efficiency for wide data transfers (it is important to pay attention to the input buffer capacity), but will also result in increased timeout between reception of separate blocks of data. Setting the parameters to 0 instructs the system to use optimal values based on the selected communication parameters.

The parameters tx_char_timeout and tx_timeout influence the output throughput. Higher efficiency for large data transfers, particularly with enabled handshake, can be obtained by increasing the values. Too low values can cause transmission problems, including relatively high number of failed transmission trials. Zero parameter values cause setting of the optimum values according to the communication 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.

Channel number Description Type Note
Common
1 exception reason real input  
2 IP address string input IP address of successfully connected device
Read error
10 station address real input  
11 error code real input  
12 error description string input  
13 number of errors real input  
14 block first channel real input  
15 block last channel real input  
16 read area real input  
17 clear error description boolean output  
18 clear number of errors boolean output  
Write error
20 station address real input  
21 error code real input  
22 error description string input  
23 number of errors real input  
24 block first channel real input  
25 block last channel real input  
26 written area real input  
27 clear error description boolean output  
28 clear number of errors boolean output  

Reserved channels

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:

ParameterMeaning
DriverName

symbolic name of the driver defined in the application,

Param1

serves for typing of the command (name of the driver procedure).

Param2

is used as a parameter of the procedure or the return value of the procedure.

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)

GetVersion

Returns in Param2 the string describing the driver name and its version.

GetMajorVersion

Returns version higher word of the product Control Web.

GetMinorVersion

Returns version lower word of the product Control Web.

GetAPIMajorVersion

Returns version higher word of the API product Control Web.

GetAPIMinorVersion

Returns version lower word of the API product Control Web.

SetTraceOutput

Sets the target of trace outputs of the communication. The parameter states the output target.

ValueMeaning
0

no trace outputs

1

outputs are directed into the debug window of the Windows system

2

listings are directed into Log Windows of the tab Debug outputs of the Control Web system

3

outputs are directed into the file '\XTRACE.TXT'

OpenCom

Opens serial line port. Param2 is of type string and contains the name of serial port (e.g. COM1). If the Param2 parameter is passed by reference (is prepended by & character), the operation result is copied into the string. Return value 'ok' means open was successful. Error description is returned in the case of failure. The serial port is opened during startup and initialized with parameters specified in the driver parameter file.

CloseCom

Closes serial line port. Param2 is ignored.

GetStatus

Returns the state of TCP connection. The Param2 must contain valid connection identifier (identifier is defined as Id of channel block). The connection state is returned in Param2:

ValueMeaning
0

invalid connection identifier

1

connection closed

2

connection open (active)

3

connection error

4

device not yet connected

Param2 is of numeric type.

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.

Remark:

Codes 101 to 108 correspond to original codes 1 to 8 as defined in the MODBUS documentation.

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.