Modbus/TCP driver details

This chapter is intended for advanced WinCC OA users. It describes in detail the function codes, config entries and debug possibilities.

Function codes

The following table contains the possible function codes as well as a short description. If WinCC OA operates as a Slave the function code depends on the used PLC.

Function code	Code	Description
read coils	1	Reads the ON/OFF status of a discrete output.
read input discretes	2	Reads the ON/OFF status of a discrete input.
read multiple registers	3	Reads the binary content of Holding Register.
read input registers	4	Reads the binary content of input Register.
write coil	5	Sets a single coil to either ON or OFF
write single register	6	Writes a value in a holding register.
read exception status	7	Reads the content of eight exception status coils.
force multiple coils	15	Sets each coil in a sequence of coils to either ON or OFF.
write multiple registers	16	Writes values in multiple holding registers.
read FIFO queue	24	Reads the contents of FIFO queue registers

Config file entries

Entry	Type	Default	Range	Description
plc	string	""	-	Obsolete since WinCC OA version 3.9. The data point name of PLC the driver cares for. An entry must exist for each PLC (e.g. plc = "_Mod_Plc_2"). The data points are created automatically by defining the parameters in the configuration panel of the Modbus/TCP driver (see Configuration panel of the Modbus/TCP driver).
tcpServerPort	unsigned	502	1..65535	The port number of the TCP server. The Slave opens a server socket for clients using this port.
tcpConnectTimeout	unsigned	2000	>= 1000	Connection timeout. (in ms) When the connection is established, the driver waits until the connection is initialized and until an acknowledgement is received from the PLC. If the driver does not receive the acknowledgement within a timeout, the driver re-establishes the connection. The timeout is specified using the config entry tcpConnectTimeout in the Modbus section.
maxPendingRequests	unsigned	1	1..8	The maximum number of outstanding requests without response. The entry can be used for sending more requests in advance in order to speed up the communication. If you set the value of the entry to higher than 1, you have to verify that the PLCs controlled by the driver are able to handle several requests.
aliveTimeout	unsigned	0	>= 0	Specifies an alive timeout for the driver in seconds. Value 0 means that no messages are sent. A value > 0 means that the driver sends a request to all connected PLCs every aliveTimeout seconds. A dummy request is sent to test if the connection is OK.
aliveTimeoutMsg	unsigned unsigned	1 0	-	Specifies the function code and the reference number for the alive request.
simUnicosPlc	bool	0	0\|1	Determines if the master should send UNICOS frames for specific, normally unused function codes. If you specify the function code 120 in to a peripheral address, a data status frame containing arbitrary data is generated. If you specify the function code 121, an Event Report frame containing arbitrary data is generated. Used only for TEST PURPOSES. The function code is used to inform the driver to generate a UNICOS frame. The code is not sent outside.
simUnicosEvents	unsigned	24	1..24	The parameter specifies the number of items for a simulated Event Report.
unicosMarker	int	65535	-1..65535	The driver decides with this reference number whether a Modbus or a UNICOS frame should be used. The entry is deactivated with -1. In order to deactivate UNICOS completely, set the entry to -1 (nothing may be set for addUnicosMarker!).
addUnicosMarker	unsigned	-1	-1..65535	Defines the reference number that is used by the driver to decide whether it is a Modbus or a UNICOS frame. The entry is deactivated by default.
maxRetryNumber	unsigned	0	>= 0	Specifies the number of retries for a connection establishment before the connection is marked as "dead". Default: 0, i.e. after the first failure the driver is continuous endlessly retrying to establish the connection.
maxConnRetryNumber	unsigned	0	>= 0	Specifies how many times the driver retries to establish a connection when sending a telegram, if the connection request fails.
littleEndianRegister	bool	1	0\|1	Defines, whether 16 Bit register is organized little endian or big endian. By default the little endian register is transmitted first. Note Little Endian = The least significant bit is saved on the first position. Big Endian = The most significant bit is saved on the first position. For more information see: Wikipedia
maxQueueSize	int	256	-	Defines the size of the request queue for master mode. For example maxQueueSize = 1000
requestDelay	uint	0	>= 0	Time in milliseconds, which must be between two requests. The value should not be set to high, because it reduces data throughput. This entry is only relevant if gateways are involved.
idleCloseTimeout	unsigned	0	>= 0	The driver closes the connection to the PLC if the connection is idle for the specified time (in seconds). This is done only for connections in master mode.
statCheckInterval	uint	20	5..100	Time interval where request statistic data point elements are written by the driver.
maxGap	uint	16	0..100	If the difference of two consecutive address reference numbers is lower or equal the value in maxGap, than these addresses are grouped together in one poll block. If not, then a second poll block is created. This entry provides the poll query optimization.
pollOptForBlob	bool	1	0\|1	Defines whether a poll query optimization is used for blobs

Debug levels

There are several command line debug options for the Modbus/TCP driver. These options are used to find errors during the driver operation. Information on further options can be queried with -helpdbg (see also manager options).

Debug level	Description
-dbg 2	Informs about the driver operation in detail. It is recommended to set this option only when the driver load is low in order to not affect the time performance of the driver.
-dbg 25	If you suspect that a polling request has lost its message, this option can be used. The option activates the corresponding error messages and displays these messages in the Log Viewer. These error messages are normally deactivated because they are not critical for a polling request. In addition to the lost polling tasks this debug level can be used for displaying warnings when data that does not belong to any configured address arrives. The warnings are filtered via debug level since the logging would be overfilled with logging messages which in most cases are not necessary for the user.
-dbg 26	Displays the amount of frames in the Modbus queue.
-dbg 27	Displays the transaction IDs of running Modbus frames. The option can be used to check the amount of unconfirmed requests.
-dbg 9	Can be used to obtain information of the driver cycle time.
-dbg 10	With this debug level the time stamp of the UNICOS Event frames is shown in the Log Viewer in order to find errors related to time stamps in UNICOS Event frame generation.
-report ALL	Activate this debug level at runtime to display the poll groups and poll blocks.

Transformations

A transformation converts hardware data into a WinCC OA format. The following table contains information of transformations and compatibility with the function codes. The driver controls if a data type and code are compatible. If they are incompatible an error message is displayed.

Required data type	Trafo	Subindex (Array) Support	Item size [byte]	Elements in an item	WinCC OA element type	FC for Write Request	FC for Read Request
bit	boolean	yes	1	8	bool	15, 6, 16	1, 2, 3, 4, 7, 24
bit	boolean as byte	no	1	1	bool	5	none
byte	byte	yes	2	2	char	6, 16	3, 4, 7, 24
word	int 16	yes	2	1	int	6, 16	3, 4, 24
unsigned word	uint 16	yes	2	1	unsigned	6, 16	3, 4, 24
dword	int 32	yes	4	1	int	16	3, 4, 24
unsigned dword	uint 32	yes	4	1	unsigned	16	3, 4, 24
qword	int 64	yes	8		float	16	3,4,24
float	float	yes	4	1	float	16	3, 4, 24
string	string	no	max. 240	1	string	16	3, 4, 24
blob	blob	no	max. 240	1	blob	16	3, 4, 24

Error codes

The table in this chapter describes the error codes of the PLC configuration panel (see Configuration panel of the Modbus/TCP driver).

Error number	Description
Error, output of the driver
0	no error
1	Master connection to PLC disconnected, no attempt of reconnection
2	Master connection to PLC disconnected, attempt of reconnection
3	Error in the slave connection
4	Peer closed the slave connection
5	Overflow of the Modbus queue.
6	Error in frame decoding
Exception codes, output of the PLC Note that the value 100 is added to the value received from the PLC (for example, 100 + 11 = 111) so that the errors can be distinguished from the errors of the driver. Note also that the error descriptions are recommendations from the general Modbus/TCP specification. The exact meaning is mostly contained in the description of the specific device.
101	Illegal function
102	Illegal data address
103	Illegal data value
104	Illegal response length
105	Acknowledge
106	Slave device busy
107	Negative acknowledgement
108	Memory parity error
110	Gateway path unavailable
111	Response from Gateway target device failed

Error Messages

The following table describes the error messages of the Modbus/TCP driver.

Class	Error message	Description
ModConnection	Too many PLCs on one gateway	Too many PLCs with the same IP address. The maximum at the moment is 8.
ModHWMapper	Illegal transformation type for ...	An invalid transformation type was defined for a peripheral address config.
ModHWMapper	Subindex + transformation type exceeds max. data length ...	The subindex transformation and function code exceed max. data length.
ModHWMapper	Wrong Output function code for: ...	The function code is not allowed for an output DPE:
ModHWMapper	Wrong input spontaneous function code for: ...	The function code is not allowed for a spontaneous input DPE
ModHWMapper	Ref. number not modulo 16 for spontaneous mode and FC15 for: ...	The reference number for this combination has to be modulo 16.
ModHWMapper	Wrong input polling/squery function code for: ...	The function code is not allowed for polling or Single Query output DPE.
ModHWMapper	Wrong mode for: ...	Wrong input type for peripheral address config.
ModHWMapper	Transformation/FC incompatibility for: ...	Illegal combination of function code and transformation type.
ModHWMapper	UNICOS SFC != 0 and FC != 16 for: ...	UNICOS uses only the function code 16.
ModMasterConnection	Socket error during send	Error in socket during the data transmission.
ModMasterConnection	Cannot establish connection to server	The master cannot establish a connection to PLC either because of wrong host name/port number or because of a network problem.
ModMasterConnection	Peer has closed connection	The PLC closed the connection.
ModMasterConnection	Connection to ... marked as dead	The connection was assigned as "dead". No connection retries.
ModModbus	Error during reception of ASCII frame	No valid ASCII frame received.
ModModbus	No PLC for unit address: ...	No PLC with the received Unit address for this connection defined.
ModModbus	Invalid Request Size field	A Modbus frame without a valid Request size was received. The frame identification is not synchronized in this case. The connection will be closed and opened again in order to debug the error.
ModModbus	Error too many invalid frames	Too many wrong frames were received. This is a sequence error and occurs as a result of earlier errors. This causes a reopening of the connection.
ModModbusMaster	No host/unit address defined for PLC number: ...	There is no Host/Unit address defined for the PLC number. This error is caused if no internal DP (_Mod_Plc) was created for this PLC number.
ModModbusMaster	Unknown function code specified in Peripheral Address	Invalid function code contained in the PA.
ModModbusMaster	Missing some responses to outstanding requests	Some answers to outstanding requests are missing.
ModModbusMaster	Receiving Modbus frame without request	Receipt of an answer without sending a request. If too many errors of such kind occur, the connection is closed and reopened.
ModModbusMaster	Wrong unit address received: UA= ...	Receipt of a wrong Unit address for an outstanding request. If too many errors of such kind occur, the connection is closed and reopened.
ModModbusMaster	Exception code received: EC= ...	An error from PLC. PLC could not handle the request. The meaning of the exception code can be taken from the error codes table.
ModModbusMaster	Wrong response to output FC	Wrong response to a particular request. If too many errors of such kind occur, the connection is closed and reopened.
ModModbusMaster	Wrong response to read registers request	Wrong response to a particular request. If too many errors of such kind occur, the connection is closed and reopened.
ModModbusMaster	Wrong response to read discretes request	Wrong response to a particular request. If too many errors of such kind occur, the connection is closed and reopened.
ModModbusMaster	Wrong response to read exception status request	Wrong response to a particular request. If too many errors of such kind occur, the connection is closed and reopened.
ModModbusMaster	Wrong response to read FIFO request	Wrong response to a particular request. If too many errors of such kind occur, the connection is closed and reopened.
ModModbusSlave	Slave received unknown function code	The slave received an unsupported or invalid Modbus function code.
ModModbusSlave	Invalid number of events in UNICOS Event Report	An invalid number of Event field in UNICOS Event Report Frame.
ModModbusSlave	UNICOS Slave received unknown subfunction code	The slave received an unsupported or invalid function code.
ModOutputQueue	Maximum requests in queue, request discarded	Overflow of Modbus queue occurs.
ModOutputQueue	Discarding polling requests (Msg. every 100)	The same polling request is already in the queue, the current is discarded. This warning appears only when the driver starts with -dbg 25.
ModOutputQueue	Timeout appears for last sent request	A Modbus transaction timeout for a request occurred.
ModPlc	Error during setting of PLC data	An error occurred during setting the PLC data of an internal data point. Use -dbg 2 for further information (DP Identifier) on this error.
ModPrLayer	Cannot start Server	The driver can not create a server socket. The port number is probably already in use.
ModRsrce	Unknown keyword in config file	The config file contains an unknown entry.
ModSlaveConnection	Socket error during send	An error occurred during the data transmission via the socket.

V 3.11 SP1