MB_CLIENT in TIA Portal: Modbus TCP setup and STATUS codes

MB_CLIENT turns an S7-1200 or S7-1500 CPU into a Modbus TCP client. It opens the connection, sends the request, waits for the reply and reports through DONE, BUSY, ERROR and a 16-bit STATUS word. Most commissioning time goes on that word, so most of this article is about reading it.

Everything here follows Siemens' TIA Portal V21 documentation for the Modbus TCP library from V4.0, which the S7-1500 and current S7-1200 CPUs use; Siemens notes that an S7-1200 with firmware V4.0 is limited to library V3.1. If Modbus itself is new, Modbus explained covers the register areas and the 40001 numbering used below.

Before you start

Collect the server's IP address and port (502 unless its manual says otherwise), a connection ID from 1 to 4095 that nothing else in the CPU uses, and, for a device behind a TCP to serial gateway, its serial address. Above all, get the register map: addresses, whether they count from 0 or 1, data types and the word order of 32-bit values. Write it into an I/O list with the numbering convention stated.

The parameters

Editable Static tags in the instance DB that matter on site:

The connection: TCON_IP_v4

Create one TCON_IP_v4 structure per MB_CLIENT instance, normally in a global DB:

Siemens forbids the local TCP ports 20, 21, 25, 80, 102, 123, 5001, 34962, 34963 and 34964. Migrating from library V2.1, CONNECT_ID becomes ID, IP_PORT becomes RemotePort and the IP_OCTET parameters become RemoteAddress; moving from any version before V4.0 also means replacing the Open User Communication library.

MB_MODE and the address

Modes 0, 1 and 2 use the traditional numbering, from which MB_CLIENT works out the function code and the zero-based remote address. Modes 101 to 116 name the function and send the address as given.

A worked example. A meter's manual lists a value at holding register 40101, two registers long. MB_MODE 0, MB_DATA_ADDR 40101, MB_DATA_LEN 2 sends function 03 for remote address 100, because 40001 maps to remote address 0. The same request in direct mode is MB_MODE 103, MB_DATA_ADDR 100. If the manual already numbers from zero, use the direct modes so nobody subtracts one twice.

MB_MODE 2 always sends the multiple-write functions. A server that only implements 06 answers that with exception 01, reported as 8381; use mode 1 or 106 for single registers on such devices.

The data buffer

In a global DB with optimised access, MB_DATA_PTR can point to one elementary tag or an array of elementary types such as Word, Int, DInt or Real. In bit memory or a standard-access DB it can also point to a PLC data type, using an ANY pointer such as P#M1000.0 WORD 500 for memory. A 32-bit value arrives as two registers; if a REAL reads as nonsense, suspect the word order (Modbus explained covers it, and PLC data types the types).

A working call

One read of ten holding registers in SCL. Siemens' rules for parameter lists allow any order, and expressions as actual parameters.

// "Meter" is a global DB holding Conn : TCON_IP_v4 and Regs : Array[0..9] of Word
"Meter_Client_DB"(REQ := "Meter".Poll,
                  DISCONNECT := FALSE,
                  MB_MODE := 103,          // read holding registers, direct address
                  MB_DATA_ADDR := 100,
                  MB_DATA_LEN := 10,
                  DONE => "Meter".Done,
                  BUSY => "Meter".Busy,
                  ERROR => "Meter".Error,
                  STATUS => "Meter".Status,
                  MB_DATA_PTR := "Meter".Regs,
                  CONNECT := "Meter".Conn);

IF "Meter".Error THEN
  "Meter".LastError := "Meter".Status;   // keep it for the HMI
END_IF;

Copy STATUS into your own tag, as Siemens' examples do; it changes with the next call.

Polling several register blocks

One instance can serve several requests on one connection. Siemens' rules: the same instance DB, connection ID and port; one request at a time, in an order your program sets; and no input changes while a request runs. Another instance with the same connection parameters sending while the first is busy gets 8200. Separate servers each need their own instance DB, connection ID and IP address.

A step pattern, each call with its own result tags:

// Step 0: read 10 registers from 100. Step 1: write 2 registers at 200.
"Meter_Client_DB"(REQ := #Step = 0, DISCONNECT := FALSE,
                  MB_MODE := 103, MB_DATA_ADDR := 100, MB_DATA_LEN := 10,
                  DONE => #Done0, ERROR => #Error0, STATUS => #Status0,
                  MB_DATA_PTR := "Meter".ReadRegs, CONNECT := "Meter".Conn);
IF #Step = 0 AND (#Done0 OR #Error0) THEN
  IF #Error0 THEN
    "Meter".ReadStatus := #Status0;
  END_IF;
  #Step := 1;
END_IF;

"Meter_Client_DB"(REQ := #Step = 1, DISCONNECT := FALSE,
                  MB_MODE := 116, MB_DATA_ADDR := 200, MB_DATA_LEN := 2,
                  DONE => #Done1, ERROR => #Error1, STATUS => #Status1,
                  MB_DATA_PTR := "Meter".WriteRegs, CONNECT := "Meter".Conn);
IF #Step = 1 AND (#Done1 OR #Error1) THEN
  IF #Error1 THEN
    "Meter".WriteStatus := #Status1;
  END_IF;
  #Step := 0;
END_IF;

STATUS: progress codes

These come with ERROR = 0. They are not faults; they say how far the current request got.

STATUS: protocol errors

These come with ERROR = 1. Several are the server's exception reply, translated: the second column gives the Modbus exception for the remote case, and Modbus exception codes explains each.

STATUS: parameter errors

Also ERROR = 1, and all are fixed in the call, not on the network.

STATUS: connection codes from TCON and TDISCON

MB_CLIENT uses TCON, TDISCON, TSEND, TRCV, T_DIAG and TRESET internally, and Siemens says their error codes can appear too; each one's own STATUS sits in the Static section of the instance DB. After 80C4, 80C5 or 80A1 while sending or receiving, the connection is ended, so 7003 shows first and the cause once it has closed. Meanings from Siemens' TCON and TDISCON references:

One overlap: TCON's own table uses 80C8 for an ID already used by a connection with different settings. At MB_CLIENT's STATUS output, 80C8 means no reply; inside the TCON status in the instance DB, it means the ID clash.

A commissioning order that saves time

1. Prove the server from a PC first with any Modbus TCP test client, using the same IP address, port, unit ID and register. If that fails, the PLC will too.
2. Start with one register: MB_MODE 103, MB_DATA_LEN 1. Set REQ and watch STATUS run 7001, 7002, 7005, 7006 and 0000 with DONE.
3. Stuck at 7002 is a connection problem: read the TCON code. Stuck at 7006 and ending in 80C8 is a server that is not answering the Modbus request: unit ID, timeout or transaction ID.
4. 8381 to 8385 means the server answered and refused. Fix the request, not the network.
5. Then scale up, log STATUS on error for the HMI, and add the Modbus test to the commissioning checklist. For intermittent faults, follow a troubleshooting method rather than swapping parameters.