Modbus TCP/IP Protocol: MBAP, Registers, Timing & Diagnostics

Separate the protocol from Ethernet, TCP and the PLC program

A useful troubleshooting model has five contracts. Ethernet proves local media and switching; IP proves addressing and routing; TCP proves a byte-stream connection; Modbus TCP proves MBAP and PDU behavior; the application contract proves that decoded data represents the intended process variable and is safe to use. A green port LED proves only part of the first contract. A successful ping reaches IP. A completed TCP handshake reaches a listening transport endpoint. Only a valid, correlated response to a known request proves the selected Modbus path.

Decode the seven-byte MBAP header before touching a register

TCP is a byte stream. One receive operation may contain part of an ADU, exactly one ADU or several ADUs. A robust parser buffers bytes, waits for the complete fixed header, validates the Protocol Identifier and Length, then waits until the number of bytes declared by Length is present. It must not assume one Ethernet frame, one TCP segment or one socket read equals one Modbus message.

Byte-complete FC03 example

The following controlled request asks Unit Identifier 17 (`0x11`) to read three holding registers starting at protocol address 107 (`0x006B`). Transaction Identifier is 42 (`0x002A`). The request Length is six because it counts Unit Identifier plus a five-byte request PDU.

Request:  00 2A 00 00 00 06 11 03 00 6B 00 03
          | TID | PID | Len |UI|FC| Start | Qty |

Response: 00 2A 00 00 00 09 11 03 06 02 2B 00 00 00 64
          | TID | PID | Len |UI|FC|BC|  three register words  |

The response Length is nine: one Unit Identifier, one function byte, one byte-count byte and six data bytes. The response returns raw words `0x022B`, `0x0000` and `0x0064`. Their engineering meaning is not defined by the frame. Only the controlled register map can say whether they are three independent unsigned integers, part of a 32-bit value, flags, a scaled measurement or something else. Download the transaction-vector CSV to check parser behavior.

Build a register contract that survives address and data-format ambiguity

The application specification describes coils, discrete inputs, input registers and holding registers. The request carries a zero-based address field inside a selected function. Manuals and client tools may instead show labels such as `40001`, offsets, tag names or one-based entries. Do not settle the difference through intuition. Store the manual label, Modbus table, wire address, client entry and proof value in separate columns.

A 16-bit register is just two data bytes at the protocol boundary. Multi-register types are application conventions. For every value define quantity, register order, byte order inside each word, signedness or IEEE format, scale, offset, unit, valid range, unavailable sentinel, write authority and freshness rule. Use deliberately asymmetric test patterns such as `0x1234` and `0x5678`; symmetrical or zero values can hide swaps.

Design transactions, scheduling and freshness as one state machine

A reliable PLC client does not fire a request every scan. It owns a transaction state: idle, issue, waiting, complete, failed, backoff and reconnect. The request trigger is usually an edge or controlled state transition. A result is consumed once. On timeout, the application classifies the failure, resolves that request, increments evidence counters and waits according to a bounded retry policy. Writes require stricter duplicate protection than reads because a reconnect must not silently repeat an action whose first outcome is unknown.

Connection handling and request handling are related but not identical. A socket may remain established while a server application stops responding. Conversely, a server may close idle connections and still be healthy. Track at least connection state, last request time, last good response time, consecutive failures, last exception, reconnect count and age of every published value group.

CASE TxState OF
  Idle:
    IF Due AND ConnectionReady THEN
      TxId := NextTransactionId();
      StartRequest := TRUE;       // one controlled issue event
      TxState := Waiting;
    END_IF;

  Waiting:
    IF ResponseDone AND ResponseTxId = TxId THEN
      ValidateMbapPdu();
      DecodeOnlyIfValid();
      LastGoodTime := Now;
      TxState := Idle;
    ELSIF ExceptionDone OR TransportError OR TimeoutExpired THEN
      RecordFirstFailedBoundary();
      InvalidateAffectedQuality();
      TxState := Backoff;
    END_IF;

  Backoff:
    IF BackoffExpired THEN TxState := Idle; END_IF;
END_CASE;

DataGood := LastDecodeValid AND (Now - LastGoodTime <= MaxAge);

This is a behavior pattern, not a drop-in vendor block. Adapt it to the exact instruction's `BUSY`, `DONE`, `ERROR`, status and connection semantics. For a value consumed by the PLC or HMI, a conservative age budget includes client schedule wait, connection or recovery delay, network delay, server and controller-task processing, device update, decode and publication. Test the complete chain under representative load rather than quoting an Ethernet link rate as application performance.

Troubleshoot by the first boundary that disagrees

“Modbus is down” hides several mutually exclusive outcomes. No route, connection refused, TCP timeout, complete response with an exception, malformed MBAP, correct response with wrong value, and fresh-looking but stale application data require different corrections. Save the first disagreement before changing IP settings, register offsets and timeouts together.

For every failure, capture UTC/local timestamp context, client and server IP/port, connection event, Transaction Identifier, Protocol Identifier, Length, Unit Identifier, function, starting address, quantity, raw response or exception, client status, server/gateway counter, last-good age and the change made. The acceptance matrix provides a reusable starting record.

Commission a Modbus TCP client/server path in nine controlled gates

1. 1. Freeze the scope

   Record exact controller, firmware, communication module, engineering-tool version, client/server roles, endpoint and approved network zone.

2. 2. Control the register map

   Archive the device-map revision and create a machine-readable contract for every value used by logic, HMI, historian or maintenance tools.

3. 3. Prove the endpoint

   Verify switch/VLAN and IP path, the designed TCP service and endpoint diagnostics without exposing the service beyond the approved conduit.

4. 4. Prove one read

   Use one stable, documented value and save the byte-complete request and response before adding a large poll list.

5. 5. Prove representation

   Inject or observe asymmetric patterns, boundaries, negative values, invalid sentinels and engineering scaling.

6. 6. Prove exceptions

   Create controlled illegal-function/address/value cases and confirm the client distinguishes them from transport failure.

7. 7. Prove age and recovery

   Interrupt responses and connections; verify quality aging, backoff, reconnect and clean resumption without duplicate writes.

8. 8. Prove representative load

   Run every client, poll class and expected background load while measuring application age, server capacity and PLC task impact.

9. 9. Freeze acceptance evidence

   Save projects, maps, captures, results, deviations, security rules, owners and a restoration procedure under change control.

Modbus TCP acceptance test matrix

Run positive, negative, boundary, timing and recovery cases. Record raw evidence and the first failed boundary, not just a green/red result.

Frequently asked questions