MODBUS TCP/IP

Exception Codes

Read/write registers (FC 23)

There is a defined set of exception codes to be returned by slaves in the event of problems. Note that masters may send out commands ‘speculatively’, and use the success or exception codes received to determine which MODBUS commands the device is willing to respond to and to determine the size of the various data regions available on the slave.All exceptions are signaled by adding 0x80 to the function code of the request, and following this byte by a single reason byte for example as follows:03 12 34 00 01 => 83 02request read 1 register at index 0x1234 response exception type 2 – ‘illegal data address’The list of exceptions follows:

ILLEGAL FUNCTlON

The function code received in the query is not an allowable action for the slave. This may be because the function code is only applicable to newer controllers, and was not implemented in the unit selected. It could also indicate that the slave is in the wrong state to process a request of this type, for example because it is unconfigured and is being asked to return register values.

ILLEGAL DATA ADDRESS

The data address received in the query is not an allowable address for the slave. More specifically, the combination of reference number and transfer length is invalid. For a controller with 100 registers, a request with offset 96 and length 4 would succeed, a request with offset 96 and length 5 will generate exception 02.

ILLEGAL DATA VALUE

A value contained in the query data field is not an allowable value for the slave. This indicates a fault in the structure of the remainder of a complex request, such as that the implied length is incorrect. It specifically does NOT mean that a data item submitted for storage in a register has a value outside the expectation of the application program, since the MODBUS protocol is unaware of the significance of any particular value of any particular register.

ILLEGAL RESPONSE LENGTH

Indicates that the request as framed would generate a response whose size exceeds the available MODBUS data size. Used only by functions generating a multi-part response, such as functions 20 and 21.

ACKNOWLEDGE

Specialized use in conjunction with programming commands

SLAVE DEVlCE BUSY

Specialized use in conjunction with programming commands

NEGATlVE ACKNOWLEDGE

Specialized use in conjunction with programming commands

MEMORY PARlTY ERROR

Specialized use in conjunction with function codes 20 and 21, to indicate that the extended file area failed to pass a consistency check.

GATEWAY PATH UNAVAILABLE

Specialized use in conjunction with MODBUS Plus gateways, indicates that the gateway was unable to allocate a MODBUS Plus PATH to use to process the request. Usually means that the gateway is misconfigured.

GATEWAY TARGET DEVICE FAILED TO RESPOND

Specialized use in conjunction with MODBUS Plus gateways, indicates that no response was obtained from the target device. Usually means that the device is not present on the network.

Appendices

Client and Server Implementation Guidance

The comments in this section should not be regarded as binding upon any particular implementation of a client or server. However, if followed, these policies will minimize integration ‘surprises’ when implementing multi-vendor systems and gateways to installed MODBUS equipment. The software structure below assumes familiarity with the BSD Sockets service interface, as used on for example UNIX and Windows NT.

Client design

MODBUS/TCP/IP is designed to allow the design of a client to be as simple as possible. Examples of software are given elsewhere, but the basic process of handling a transaction is as follows:

• Establish a TCP/IP connection to port 502 at the desired server using connect()
• Prepare a MODBUS request, encoded as described before
• Submit the MODBUS request, including its 6-byte MODBUS TCP/IP prefix, as a single buffer to be transmitted using send()
• Wait for a response to appear on the same TCP/IP connection. Optionally, run a timeout on this step, using select(), if you wish to be advised of communication problems faster than TCP/IP would normally report.
• Read, using recv(), the first 6 bytes of the response, which will indicate the actual length of the response message
• Use recv() to read the remaining bytes of the response.
• If no further communication is expected to this particular target in the immediate future, close down the TCP/IP connection so that the resources at the server can be used in the interim to serve other clients. A time of 1 second is suggested as the maximum period to leave a connection open at the client.
• In the event of a timeout waiting for a response, issue a unilateral close of the connection, open up a new one, and resubmit the request. This technique allows the client control of retry timing which is superior to that provided by default by TCP/IP. It also allows for alternate fallback strategies, such as submitting the request to an alternate IP address, using a totally independent communication network, in case of failure of a network infrastructure component.

Server design

A MODBUS TCP/IP server should always be designed to support multiple concurrent clients, even if in its intended use only a single client appears to make sense. This allows a client to close and reopen the connection in rapid sequence in order to respond quickly to non-delivery of a response.If a conventional TCP/IP protocol stack is used, significant memory resources can be saved by reducing the receive and transmit buffer sizes. A normal TCP/IP service on UNIX or NT would usually allocate 8K bytes or more as a per-connection receive buffer in order to encourage ‘streamed’ transfer of data from for example file servers. Such buffer space has no value in MODBUS TCP/IP, since the maximum size of a request or response is less than 300 bytes. It is often possible to trade the storage space for additional connection resources.Either a multithreaded or single-threaded model can be used to handle the multiple connections. Descriptions follow in the next sections.

Multithreaded server

Operating systems or languages which encourage the use of multiple threads, such as JAVA, can use the multithreaded strategy, described here:

• Use listen() to wait for incoming connections on TCP/IP port 502
• When a new connection request is received, use accept() to accept it and spawn a new thread to handle the connection
• Within the new thread, do the following in an infinite loop:ssue a recv(6) request for the 6 byte MODBUS TCP/IP header. Do not place a timeout here, but instead be willing to wait until either a request comes through or the connection is closed. Both situations will wake up the thread automatically.
• Analyze the header. If it appears corrupt, for example the protocol field is non-zero or the length of message is larger than 256, then UNILATERALLY CLOSE THE CONNECTION. This is the correct response as a server to a situation implying the TCP/IP encoding is incorrect.
• Issue a recv() for the remaining bytes of the message, whose length is now known. Note in particular that issuing a recv() with a limit like this on the length will tolerate clients who insist on ‘pipelining’ requests. Any such pipelined requests would remain in the TCP/IP buffers at either server or client, and be picked up later, when the current request has completed service.
• Now process the incoming MODBUS message, if necessary suspending the current thread until the correct response can be calculated. Eventually you will have either a valid MODBUS message or an EXCEPTION message to use as a response
• Generate the MODBUS TCP/IP prefix for the response, copying the ‘transaction identifier’ field from bytes 0 and 1 of the request, and recalculating the length field.
• Submit the response, including the MODBUS TCP/IP prefix, as a single buffer for transmission on the connection, using send()
• Go back and wait for the next 6 byte prefix record.
• Eventually, when the client elects to close the connection, the recv() of the 6 – byte prefix will fail. An orderly close will usually result in a recv() with a zero return byte count. A force close may generate an error return from the recv(). In either case, close the connection and cancel the current thread.

Single-threaded server

Some embedded systems and older operating systems such as UNIX and MS-DOS encourage the handling of multiple connections using the ‘select’ call from the sockets interface. In such a system, instead of handling the processing of individual concurrent requests in their own thread, you can handle the requests as multiple state machines within a common handler. Languages such as C++ make the structure of software like this convenient.The structure now would be as follows:

• Initialize multiple state machines by setting their state to ‘idle’ listen() for incoming connections on TCP/IP port 502
• Now start an infinite loop checking the ‘listen’ port and the state machines as follows:
  • If state is ‘new request’:
  • Use select() to see whether a request has arrived. Normally set the timeout to zero, since you don’t wish to suspend the process because of inactivity on this particular connection.
  • If select() indicates there is a packet, use recv(6) to read the header as in the multithreaded case. If the header is corrupt, CLOSE THE CONNECTION and set the state machine to idle.
  • If the read succeeded and select() indicates that more input is available, read the rest of the request.
  • If the request is complete, change the state of the session to ‘await response’.
  • If the recv() returns indicating that the connection is no longer in use, close the connection and reset the state machine to ‘idle’.
  • If state is ‘await response’
  • See if the application response information is available, if it is, build up the response packet, and send it using send(), exactly as for the multithreaded case. Set the state to ‘new request’
  • It is possible to optimize performance by combining the multiple select() calls into a single call on a per-cycle basis, without affecting the functional structure of the application.

Required and expected performance

There is deliberately NO specification of required response time for a transaction over MODBUS or MODBUS TCP/IP. This is because MODBUS TCP/IP is expected to be used in the widest possible variety of communication situations, from I/O scanners expecting sub-millisecond timing to long distance radio links with delays of several seconds. In addition, the MODBUS family is designed to encourage automatic conversion between networks by means of ‘blind’ conversion gateways. Such devices include the Schneider ‘Ethernet to Modbus Plus Bridge’, and various devices which convert from MODBUS TCP/IP to MODBUS serial links. Use of such devices implies that the performance of existing MODBUS devices is consistent with use of MODBUS TCP/IP. In general, devices such as PLC’s which exhibit a ‘scan’ behavior will respond to incoming requests in one scan time, which typically varies between 20 msec and 200 msec.

From a client perspective, that time must be extended by the expected transport delays across the network, to determine a ‘reasonable’ response time. Such transport delays might be milliseconds for a switched Ethernet, or hundreds of milliseconds for a wide area network connection. In turn, any ‘timeout’ time used at a client to initiate an application retry should be larger than the expected maximum ‘reasonable’ response time. If this is not followed, there is a potential for excessive congestion at the target device or on the network, which may in turn cause further errors. This is a characteristic which should always be avoided. So in practice, the client timeouts used in high performance applications are always likely to be somewhat dependent on network topology and expected client performance. A timeout of say 30 msec might be reasonable when scanning 10 I/O devices across a local Ethernet and each device would normally respond in 1 msec. On the other hand, a timeout value of 1 second might be more appropriate when supervising slow PLC’s through a gateway across a serial link, where the normal scan sequence completed in 300 msec.

Applications which are not time critical can often leave timeout values to the normal TCP/IP defaults, which will report communication failure after several seconds on most platforms. Clients are encouraged to close and re-establish MODBUS TCP/IP connections which are used for data access only (not PLC programming) and where the expected time before next use is significant, for example longer than one second. If clients follow this principle, it allows a server with limited connection resources to service a larger number of potential clients, as well as facilitating error recovery strategies such as selection of alternative target IP addresses. It should be remembered that the extra communication and CPU load caused by closing and reopening a connection is comparable to that caused by a SINGLE MODBUS transaction.

Data Encoding for non-word data

The most efficient method of transporting bulk information of any type over MODBUS us to use function codes 3 (read registers), 16 (write registers), or possibly 23 (read/write registers). Although these functions are defined in terms of their operation on 16-bit registers, they can be used to move any type of information from one machine to another, so long as that information can be represented as a contiguous block of 16-bit words. The original MODBUS-capable PLC’s were specialized computers using a ‘big-endian’ architecture. Most modern PLC’s are based on commodity microprocessors using a ‘little-endian’ architecture. The fact that MODBUS is used to exchange data potentially between these two architectures introduces some subtleties which can trap the unwary. Almost all data types other than the primitive ‘discrete bit’ and ’16 bit register’ were introduced after the adoption of little-endian microprocessors. Therefore the representation on MODBUS of these data types follows the little-endian model, meaning:
First register bits 15 – 0 = bits 15 – 0 of data item
Second register bits 15 – 0 = bits 31 – 16 of data item
Third register bits 15 – 0 = bits 47 – 32 of data item etc. etc.

Bit numbers within a word

Modicon PLC’s have predefined functions in the 984 Ladder Language which will convert a series of contiguous registers into an equivalent length block of 1-bit ‘discretes’. The most common such function is BLKM (Block Move). For consistency with the original big-endian architecture, such discretes were numbered from most significant bit to least significant bit, and to add more confusion, all number sequences started at one, not zero. (Bit numbers within this document are always referenced from zero as the least significant bit, to be consistent with modern software documentation) So within a word (register):
Discrete 1 would be bit 15 (value 0x8000)
Discrete 2 would be bit 14 (value 0x4000)
Discrete 3 would be bit 13 (value 0x2000)
Discrete 4 would be bit 12 (value 0x1000)
Discrete 5 would be bit 11 (value 0x0800)
Discrete 6 would be bit 10 (value 0x0400)
Discrete 7 would be bit 9 (value 0x0200)
Discrete 8 would be bit 8 (value 0x0100)
Discrete 9 would be bit 7 (value 0x0080)
Discrete 10 would be bit 6 (value 0x0040)
Discrete 11 would be bit 5 (value 0x0020)
Discrete 12 would be bit 4 (value 0x0010)
Discrete 13 would be bit 3 (value 0x0008)
Discrete 14 would be bit 2 (value 0x0004)
Discrete 15 would be bit 1 (value 0x0002)
Discrete 16 would be bit 0 (value 0x0001)

When there are more than 16 bits, for example a 32 point discrete input module, discretes 1 to 16 would be in the first register, discretes 17 to 32 would be in the second register. This numbering convention is particularly important to understand when dealing with discrete input or output devices over MODBUS TCP/IP, where the numbering of the discrete points has been arranged to be consistent with Modicon PLC’s. In particular, note that the IEC-1131 numbering convention for bits within a word is from 0 (least significant) to 15 (most significant), which is the opposite of the discrete numbering.

Multi-word quantities

In principle, any data structure which can be ‘cast’ to an array of 16-bit words can be transported, and will arrive unchanged on a machine with the same data representation.The following PLC data types should be noted: