ModbusClient

The Commander4j Modbus Client (util_modbusClient) is a desktop tool that acts as a Modbus/TCP client — a Modbus master. It connects to a remote Modbus server (a device, PLC, or the Commander4j Modbus Server), continuously polls its four data tables across a chosen address window, and shows them in a single live grid. Coil and Holding Register values can be edited to drive the connected server. It is a test, troubleshooting and bench tool, and is the client-side companion to the Commander4j Modbus Server.

A Quick Modbus Primer

If you are new to Modbus, the following terms are used throughout this page. Modbus is a simple, widely used industrial protocol for moving numeric and on/off values between automation equipment.

Master / Client — the device that initiates requests (reads and writes). This tool is a client.
Slave / Server / Device — the device that holds the data and answers requests. The ModbusServer is a server.
Unit ID (also "slave address") — a number (0–247) identifying which device a request is for. A client must use the same unit ID the server is configured to answer as.
Modbus/TCP — Modbus carried over an ordinary TCP/IP network connection, as opposed to serial (RTU) wiring. These tools speak Modbus/TCP only.

Modbus organises all data into four tables, each addressed separately starting at zero:

Table	Holds	Size	Can a client write it?
Coils	On/off output bits	1 bit	Yes
Discrete Inputs	On/off input bits	1 bit	No — read-only
Input Registers	Numeric inputs (readings)	16 bits (0–65535)	No — read-only
Holding Registers	Numeric settings / values	16 bits (0–65535)	Yes

The two "input" tables represent values a device produces (sensor states, measurements), so a client can only read them. Coils and holding registers represent values a client is allowed to set. Each table also has a conventional reference number that operators quote instead of the raw zero-based address: coils start at 1, discrete inputs at 10001, input registers at 30001 and holding registers at 40001.

Purpose

The Modbus Client is useful when:

Reading the live coils and registers of a PLC or other Modbus device to confirm it is responding
Writing a coil or holding register to command a device during commissioning or fault-finding
Checking that a device is reachable on a given host, port and unit ID
Driving the ModbusServer during testing, or reading values the server is staging

Source Code and Releases

The Modbus Client is open source and hosted on GitHub:

Repository: https://github.com/C4J/ModbusClient
Releases (downloads): https://github.com/C4J/ModbusClient/releases

Running the Modbus Client

The recommended way to install the Modbus Client is to download a native installer for your platform from the GitHub releases page. Native installers are provided for Windows, macOS and Linux. Each installer bundles its own Java 25 runtime, so no separate Java installation is required.

Installing creates a native ModbusClient launcher that you run like any other desktop application — from the Start menu, Applications folder, or desktop — which opens the window described below.

Running from the jar

Alternatively the tool can be run directly from its distribution folder as an ordinary Java 25 (Swing) application:

java -jar modbusClient.jar

The supplied start_modbusClient.sh (macOS/Linux) and start_modbusClient.cmd (Windows) scripts launch it the same way. Run the jar from its own folder so the bundled lib/ dependencies are found alongside it.

The Main Window

The window has three parts: a connection bar across the top, the register table in the centre with a vertical button toolbar down the right-hand side, and an activity log along the bottom.

Connection Bar

Field	Meaning
Server host	The host name or IP address of the Modbus server to connect to. Defaults to `127.0.0.1` (this machine) for quick loopback testing against a local ModbusServer.
Port	The TCP port of the server. The Modbus standard is 502; match whatever the server is listening on.
Unit ID	The unit / slave address to address requests to (0–247, default 1). This must match the unit ID the server answers as, or every request will be rejected.
Status	Shows Disconnected, or Connected with the server address and unit ID in green.

The Connect / Disconnect button (the toggle at the top of the right-hand toolbar) opens and closes the connection. The host, port and unit ID can only be changed while disconnected. Once connected, the client polls the server roughly four times a second and the grid updates live.

Register Table

A single grid shows one row per address, with every Modbus data table side by side and colour-coded:

Column group	Contents	Editable here
Address	The zero-based Modbus protocol address (the same address for the whole row).	—
Coil	Modbus reference (1…) and an on/off checkbox.	Yes
Discrete	Discrete input reference (10001…) and an on/off checkbox.	No (read-only)
Input	Input register reference (30001…), a decimal value and a read-only Hex view.	No (read-only)
Holding	Holding register reference (40001…), a decimal value (0–65535) and a read-only Hex view.	Yes

Only the Coil and Holding Register value cells can be edited, and only while connected — because Modbus has no function code for a client to write the discrete-input and input-register tables. Editing a cell writes the new value straight through to the server; the displayed value updates immediately and is reverted if the server rejects the write.

Below the table, the Start address and Count fields choose which window of addresses the client polls; click the tick button (Apply range) to apply them. Up to 2000 rows can be shown at once.

The Zero registers button (eraser icon) on the toolbar opens a menu to clear the visible window of the writable tables — Zero Coils, Zero Holding Registers, or Zero All for both. Only the writable tables appear, because the read-only ones cannot be cleared by a client.

Activity Log

Connection events, writes, and any errors are written to the log at the bottom with a millisecond timestamp. The log keeps the most recent 400 lines. The two buttons beside it Save the log to a text file and Clear it. If the connection is lost (for example the server stops or the network drops), the client reports it in the log and returns to the disconnected state automatically.

Toolbar Buttons

The vertical toolbar to the right of the register table provides, from top to bottom: Connect / Disconnect, Open settings, Save settings, Zero registers, About, Licences, Help (opens this wiki page) and Close.

Configuration

The connection settings (server host, port and unit ID) are stored in a small XML file, by default xml/config/config.xml beneath the application folder:

<config>
  <ip>127.0.0.1</ip>
  <port>502</port>
  <id>1</id>
</config>

The default settings are loaded automatically at start-up. Use the Open settings and Save settings toolbar buttons to load or store a configuration from any location. If you change the settings and then close the application, you are prompted to save the changes first.

Using the Client and Server Together

The Modbus Client and the Modbus Server are designed to be used as a pair to exercise a Modbus link from both ends without any real hardware:

Start the ModbusServer on one machine (or the same machine), choose a port and unit ID, and press Start.
In the Modbus Client, set Server host to that machine (127.0.0.1 if both run on the same PC), set the matching port and unit ID, and press Connect.
Client → Server: edit a Coil or Holding Register in the client; the value is written to the server and appears in the server's grid and activity log.
Server → Client: edit any value in the server — including discrete inputs and input registers, which the client can only read; the client's grid reflects it on the next poll.

This makes the pair a complete bench setup: the server stands in for a device so you can develop or test a Modbus master, and the client stands in for a master so you can stage and inspect a device's data. Either tool can also be pointed at real third-party Modbus/TCP equipment.

Troubleshooting

"Connection refused" or a timeout on Connect — check the server host and port, that the server is running and listening, and that no firewall is blocking the connection.
Connected, but every read fails or the connection drops immediately — the Unit ID probably does not match the server. The client must address the exact unit ID the server answers as.
A startup warning about sun.misc.Unsafe — harmless, and does not affect operation. The supplied start scripts suppress it; launching the jar directly may still print it.