Dgarratt at 10:42, 4 June 2026

2026-06-04T10:42:39Z

← Older revision		Revision as of 12:42, 4 June 2026
Line 143:		Line 143:

	* [[ModbusServer]] — the server-side companion tool		* [[ModbusServer]] — the server-side companion tool
	* [[AutoLab4j]] — uses the same Modbus stack to read ~~laboratory instruments~~		* [[AutoLab4j]] — uses the same Modbus stack to read Modbus printing triggers
	* [[SocketTest]] — a raw TCP/IP testing utility		* [[SocketTest]] — a raw TCP/IP testing utility

	[[Category:Commander4j]]		[[Category:Commander4j]]

Dgarratt: Updated by push_wiki.py

2026-06-04T10:39:55Z

Updated by push_wiki.py

← Older revision		Revision as of 12:39, 4 June 2026
Line 45:		Line 45:
	== Running the Modbus Client ==		== Running the Modbus Client ==

	The recommended way to install the Modbus Client is to download a native installer for your platform from the [https://github.com/C4J/ModbusClient/releases 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'''.		The recommended way to install the Modbus Client is to download a native installer for your platform, either from the [[Downloads]] page or from the [https://github.com/C4J/ModbusClient/releases 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.		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.

Dgarratt: Updated by push_wiki.py

2026-06-04T10:39:08Z

Updated by push_wiki.py

← Older revision		Revision as of 12:39, 4 June 2026
Line 35:		Line 35:
	* Checking that a device is reachable on a given host, port and unit ID		* 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		* 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 https://github.com/C4J/ModbusClient]
			* '''Releases (downloads):''' [https://github.com/C4J/ModbusClient/releases https://github.com/C4J/ModbusClient/releases]

	== Running the Modbus Client ==		== Running the Modbus Client ==

	Native ~~install packages~~ for Windows, macOS, and Linux ~~are available~~ from the ~~[[Downloads]] page and are~~ the ~~preferred installation method~~.		The recommended way to install the Modbus Client is to download a native installer for your platform from the [https://github.com/C4J/ModbusClient/releases 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~~. It is a~~ Java 25 ~~desktop~~ (Swing) application:		Alternatively the tool can be run directly from its distribution folder as an ordinary Java 25 (Swing) application:

	java -jar modbusClient.jar		java -jar modbusClient.jar

Dgarratt: Updated by push_wiki.py

2026-06-04T10:31:46Z

Updated by push_wiki.py

New page

The '''Commander4j Modbus Client''' (''util_modbusClient'') is a desktop tool that acts as a [https://en.wikipedia.org/wiki/Modbus Modbus/TCP] client — a Modbus master. It connects to a remote Modbus server (a device, PLC, or the [[ModbusServer|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 [[ModbusServer|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:

{| class="wikitable"
|-
! 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

== Running the Modbus Client ==

Native install packages for Windows, macOS, and Linux are available from the [[Downloads]] page and are the preferred installation method.

Alternatively the tool can be run directly from its distribution folder. It is a Java 25 desktop (Swing) application:

java -jar modbusClient.jar

The supplied <code>start_modbusClient.sh</code> (macOS/Linux) and <code>start_modbusClient.cmd</code> (Windows) scripts launch it the same way. Run the jar from its own folder so the bundled <code>lib/</code> 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 ===

{| class="wikitable"
|-
! Field !! Meaning
|-
| '''Server host''' || The host name or IP address of the Modbus server to connect to. Defaults to <code>127.0.0.1</code> (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:

{| class="wikitable"
|-
! 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 <code>xml/config/config.xml</code> 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 [[ModbusServer|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 (<code>127.0.0.1</code> 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 <code>sun.misc.Unsafe</code>''' — harmless, and does not affect operation. The supplied start scripts suppress it; launching the jar directly may still print it.

== See Also ==

* [[ModbusServer]] — the server-side companion tool
* [[AutoLab4j]] — uses the same Modbus stack to read laboratory instruments
* [[SocketTest]] — a raw TCP/IP testing utility

[[Category:Commander4j]]

ModbusClient - Revision history

Dgarratt at 10:42, 4 June 2026

Dgarratt: Updated by push_wiki.py

Dgarratt: Updated by push_wiki.py

Dgarratt: Updated by push_wiki.py