IMDHMIControls LibraryShop main store

How-to

Setting up a CODESYS Modbus TCP client to talk through a gateway

Industrial networks Published 7 min read

Short answer

In CODESYS, Modbus TCP is an application library, not a fieldbus add-on: reference the Modbus TCP Client SL library, point the client at the gateway's IP on port 502 with the gateway's unit ID, and split the map into contiguous blocks of at most 125 registers per request. Every value is a cached copy whose worst-case age is the gateway poll cycle plus your client's map refresh time, so budget both against the freshness the process needs.

On this page
  1. Why there is no Modbus entry in the fieldbus tree
  2. What the client needs before you write code
  3. The 125-register ceiling on every read
  4. Setting up and commissioning the link
  5. Worked example: sizing read blocks for a 300-register map at a 1000 ms gateway poll
  6. How many servers the client can reach
  7. Fast faults to check first
  8. Questions asked

Modbus TCP in a CODESYS project is an application library, not a fieldbus add-on, so searching the add-on list for a Modbus item finds nothing. Reference the Modbus TCP Client SL library in the application, point the client at the gateway's IP address on TCP port 502 with the unit ID the gateway's configuration assigns, and split the register map into contiguous blocks of at most 125 registers per Read Holding Registers request. Then treat every value you read as a cached copy whose worst-case age is the gateway's poll cycle plus your client's map refresh time. The steps below cover the settings, the block sizing, the commissioning checks, and the age budget that sets your cycle times.

Why there is no Modbus entry in the fieldbus tree #

CODESYS delivers Modbus TCP as a library you call from the application, not as a master object in the device tree. The client library creates Modbus clients over a standard Ethernet adapter, so nothing appears under the fieldbus communication add-ons, and nothing needs to: the connection, the request sizing and the error handling all live in your own code, where you can watch them work. Some controller vendors ship the same client under their own library name, and the tell is identical — you reference it as a library, you never add it as a device. Choosing the Ethernet fieldbus side of a controller is a different job entirely; that one is covered by selecting a CODESYS fieldbus master for industrial Ethernet.

What the client needs before you write code #

Setting Value to use Where it comes from
Server IP Gateway address, same subnet as the controller Gateway configuration
TCP port 502, the Modbus TCP default Protocol default; change it only if the gateway is set otherwise
Unit ID The value the gateway assigns its Modbus server table Gateway configuration
Timeouts Longer than the gateway's slowest response Gateway datasheet, confirmed by test
Register map Addressing basis and 32-bit word order The gateway's exported map

Confirm two things from the exported map before writing any code: whether addresses are zero-based or one-based, and which word of a 32-bit value comes first. An off-by-one start address does not fault — it returns plausible, wrong numbers.

The 125-register ceiling on every read #

Function code 03, Read Holding Registers, reads between 1 and 125 holding registers in a single request. The 125 is a protocol limit, not a CODESYS setting: the response leads with its function code and a one-byte count of the data bytes, and a maximum-size response is 252 bytes — two of those bytes are the function code and the count, the other 250 are register data, exactly 125 sixteen-bit registers.

Read a larger map as several requests, one contiguous block each, every block at or below 125 registers, and end a block where the map has a gap rather than spanning it. A request that reaches unmapped addresses comes back as exception 02, the failure walked through for Modbus exception 02 when a read crosses a register map gap. The ceiling is not CODESYS-specific either: resolving the Modbus TCP 125-register limit on an S7 CPU is the same split done in different software.

  1. Reference the Modbus TCP Client SL library in the application — or your controller vendor's equivalently named Modbus TCP client library — and instantiate its client function block. There is no fieldbus device node on this path.
  2. Configure the client with the gateway's IP address, TCP port 502, and the unit ID from the gateway's Modbus server configuration.
  3. Export the gateway's register map and mark the addressing basis and the 32-bit word order directly on it.
  4. Group the map into contiguous blocks of at most 125 registers each, placing block boundaries on the map's gaps.
  5. Write code around the client's error and connection-state outputs. A read that silently stops updating is worse than one that faults, so latch and alarm those states.
  6. Bench-test the program against a software Modbus TCP server before the gateway is on the network, the approach described for simulating a Modbus TCP link on one PC, then swap in the gateway's IP and map.
  7. On site, confirm reachability with a ping from the same segment, then capture traffic on port 502. Every request needs a matching response carrying the same transaction ID and a response function code without bit 7 set; that bit is what marks an exception.
  8. Prove the data age: change a value at a field device and time how long it takes to appear in the controller. That interval is the gateway's poll cycle plus your client's refresh time, and it is the number the process actually cares about.

Worked example: sizing read blocks for a 300-register map at a 1000 ms gateway poll #

Inputs — the 125-register limit is the documented protocol maximum; the other figures are illustrative values for a typical gateway job:

  • Register map: 300 holding registers in the gateway's Modbus table, read from the gateway's exported configuration.
  • Request limit: 125 registers per Read Holding Registers request, the function code 03 protocol maximum.
  • Client cycle: 500 ms, the task rate at which the program issues the next block — a setting you choose.
  • Gateway poll cycle: 1000 ms, how often the gateway refreshes its table from the field side, taken from the gateway configuration (on a BACnet/IP far side that polling runs over UDP, default port 47808).
  • Freshness requirement: 2000 ms, the process spec the data must meet.

Rule in words: the map needs the register count divided by 125, rounded up to a whole number of blocks, each read as its own request; the worst-case age of any value is the gateway poll cycle plus the block count times the client cycle.

Arithmetic: 300 ÷ 125 = 2.4, rounded up to 3 blocks, sized 125 + 125 + 50 registers. At one block per 500 ms cycle, the whole map refreshes in 3 × 500 = 1500 ms, so the worst-case age is 1000 + 1500 = 2500 ms.

Decision: 2500 ms misses the 2000 ms requirement, so the 500 ms client cycle fails. Set the client cycle to 250 ms: the map then refreshes in 3 × 250 = 750 ms and the worst-case age is 1000 + 750 = 1750 ms — inside the requirement with 250 ms of margin, so accept that setting. Rebalancing the blocks to 100 + 100 + 100 changes nothing, because the refresh time follows the block count, not the block sizes. If this data drives control actions, act on its age as well as its value: a cached copy can be 1.75 s old with everything working, and a protocol-translating gateway is not a safety path.

How many servers the client can reach #

The client library's product page publishes no maximum server count and no per-client register capacity, so there is no documented figure to design to from that side. Two real bounds remain. Scan time is one: with requests issued sequentially, every added server contributes its round trips to the total, the same arithmetic as polling several PLC sites from one Modbus master. Connections are the other: the gateway or server device limits concurrent TCP connections, and that number lives in its datasheet — a link that works until a second client connects has hit it. Decide by measurement: run the full server list at the target cycle for an hour, and if the measured scan crowds the freshness budget, split the polling across parallel connections or a second client, but only after reading the gateway's connection limit.

Fast faults to check first #

Symptom Likely cause Fix
No response at all Wrong IP, subnet or VLAN; unit ID the gateway does not recognize Ping the gateway from the same segment, then verify the unit ID against its configuration
Exception 02 on a read Block spans a map gap or runs past the map end Re-split the blocks along the gaps, as covered in fixing CODESYS Modbus TCP server exception 0x0002
Plausible values that are slightly wrong Zero-based map read as one-based, or the reverse Shift the start address by one register and retest
Floats that read as wild numbers 32-bit word order swapped Swap the words in code against a value visible at the source
Link drops when a second client connects Gateway's TCP connection limit reached Consolidate clients or raise the limit per the gateway datasheet

Questions asked

Do input registers share the same 125-register limit as holding registers?

Yes. The cap applies to Read Holding Registers, function code 03, and to Read Input Registers, function code 04, because both responses carry their data behind the same one-byte count field in the same fixed frame. A 200-register input map splits exactly like a holding map: two requests of 125 and 75.

Does the unit ID still matter over Modbus TCP?

On a gateway it is never optional. The gateway uses the unit ID to pick the register table or the far-side device a request belongs to, and a value it does not recognize typically produces no response at all rather than an exception you can read. Set it to exactly the value the gateway's configuration assigns to its Modbus server side.

How fast should the client cycle run?

Set it from the age budget: gateway poll cycle plus block count times client cycle must stay inside the freshness requirement. Past a certain point extra speed buys nothing, because the worst-case age never drops below the gateway's own poll cycle — that cache refresh is the floor no client rate beats. If the floor itself misses the requirement, raise the gateway's poll rate rather than the client's.

How do I read 32-bit floats correctly through the gateway?

Read both 16-bit words that make up the value, then test against a number you can watch at the source device. If the far side sends the low word first and the code assumes the reverse, swap the words in the program rather than re-mapping the gateway; one swap fixes every value of that type in the block. A setpoint you can set to a known value is the quickest reference.

Keep reading

  • Troubleshooting

    Reading Modbus TCP from a ControlLogix PLC without a gateway

    Yes — ControlLogix reads Modbus TCP without a gateway card through Rockwell's sample Modbus TCP driver, but only on controller firmware version 20 or later with socket-capable Ethernet hardware such as a 1756-EN2xx module at firmware 5.007 or later. If either side misses the gate, use a standalone EtherNet/IP to Modbus TCP converter. When the driver runs, prove one request against a known-good PC client and match unit ID, start address and count field by field.

    Industrial networks

  • How-to

    Linking Modbus RTU BMS SCADA to a redundant S7-1500R

    Use one Modbus RTU-to-TCP gateway as the Modbus TCP client, and run the Modbus TCP server on the S7-1500R system IP address that switched communication moves to the surviving CPU. The BMS keeps polling its RS-485 link unchanged; on a switchover the TCP session drops and the gateway reconnects. Set the comm-fail timeout to the measured gap plus one poll interval: 3 s at a 1 s rate in the example.

    Industrial networks

  • How-to

    How to build a virtual PLC test bench for protocol practice

    One laptop runs the whole bench: a Modbus TCP server simulator, a master test client, a Node-RED OPC UA server and a SCADA trial connect over loopback, so you can practice addressing, sessions, scaling, alarms and fault diagnosis without a PLC. Work through three bounded projects and finish with seven pass criteria you can defend.

    Industrial networks