Dgarratt: Updated by push_wiki.py

2026-06-04T10:39:54Z

Updated by push_wiki.py

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

	The recommended way to install the Modbus Server is to download a native installer for your platform from the [https://github.com/C4J/ModbusServer/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 Server is to download a native installer for your platform, either from the [[Downloads]] page or from the [https://github.com/C4J/ModbusServer/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 native '''launchers''' you can run like any other desktop application (from the Start menu, Applications folder, or desktop):		Installing creates native '''launchers''' you can run like any other desktop application (from the Start menu, Applications folder, or desktop):

Dgarratt: Updated by push_wiki.py

2026-06-04T10:39:07Z

Updated by push_wiki.py

← Older revision		Revision as of 12:39, 4 June 2026
Line 36:		Line 36:
	* Toggling discrete inputs and input registers — values a real device produces but a client cannot write — to simulate sensor or status changes		* Toggling discrete inputs and input registers — values a real device produces but a client cannot write — to simulate sensor or status changes
	* Confirming a client is configured for the correct host, port and unit ID		* Confirming a client is configured for the correct host, port and unit ID

			== Source Code and Releases ==

			The Modbus Server is open source and hosted on GitHub:

			* '''Repository:''' [https://github.com/C4J/ModbusServer https://github.com/C4J/ModbusServer]
			* '''Releases (downloads):''' [https://github.com/C4J/ModbusServer/releases https://github.com/C4J/ModbusServer/releases]

	== Running the Modbus Server ==		== Running the Modbus Server ==

	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 Server is to download a native installer for your platform from the [https://github.com/C4J/ModbusServer/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 native '''launchers''' you can run like any other desktop application (from the Start menu, Applications folder, or desktop):

			{\| class="wikitable"
			\|-
			! Launcher !! What it does
			\|-
			\| '''ModbusServer''' \|\| Starts the interactive window described below.
			\|-
			\| '''ModbusServer Service''' \|\| Starts the server [[#Headless (Service) Mode\|headless]], with no window, using the saved configuration file. Intended for running as a background service.
			\|}

			=== 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 modbusServer.jar		java -jar modbusServer.jar
Line 117:		Line 137:
	== Headless (Service) Mode ==		== Headless (Service) Mode ==

	In addition to the interactive window, the Modbus Server can run headless as a background service. In this mode it loads the saved <code>xml/config/config.xml</code>, binds the server with no user interface, and runs until the operating system asks it to stop (for example a service stop, console Ctrl-C, or system shutdown). ~~The~~ native ~~install packages provide both a GUI launcher~~ and a Service ~~launcher~~ for ~~this purpose~~.		In addition to the interactive window, the Modbus Server can run headless as a background service, started by the '''ModbusServer Service''' launcher. In this mode it loads the saved <code>xml/config/config.xml</code>, binds the server with no user interface, and runs until the operating system asks it to stop (for example a service stop, console Ctrl-C, or system shutdown). This is why the native installer provides two launchers — '''ModbusServer''' for the window and '''ModbusServer Service''' for the headless service.

	== Using the Server and Client Together ==		== Using the Server and Client Together ==

Dgarratt: Updated by push_wiki.py

2026-06-04T10:31:45Z

Updated by push_wiki.py

New page

The '''Commander4j Modbus Server''' (''util_modbusServer'') is a desktop tool that turns your PC into a [https://en.wikipedia.org/wiki/Modbus Modbus/TCP] server — a Modbus slave, or "device". It shows the live state of all four Modbus data tables in a single editable grid, so you can both '''observe''' what a connected Modbus client writes and '''drive''' that client by staging values for it to read. It is a test, simulation and bench tool, and is the server-side companion to the [[ModbusClient|Commander4j Modbus Client]].

== 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). The [[ModbusClient]] is a client.
* '''Slave / Server / Device''' — the device that holds the data and answers requests. This tool 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''. Because this server stands in for the device, it lets you edit '''all four''' tables directly — including the two a client cannot write. 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 Server is useful when:

* Testing a Modbus master (PLC, SCADA package, or the [[ModbusClient]]) without needing the real device it normally talks to
* Watching exactly which coils and registers a client reads and writes, with a timestamped log of every change
* Staging register values in advance so a client polling the server sees a known scenario
* Toggling discrete inputs and input registers — values a real device produces but a client cannot write — to simulate sensor or status changes
* Confirming a client is configured for the correct host, port and unit ID

== Running the Modbus Server ==

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 modbusServer.jar

The supplied <code>start_modbusServer.sh</code> (macOS/Linux) and <code>start_modbusServer.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
|-
| '''Bind address''' || The network interface to listen on. <code>0.0.0.0</code> listens on all interfaces; enter a specific IP to restrict the server to one.
|-
| '''Port''' || The TCP port to listen on. The Modbus standard is '''502''', but ports below 1024 require elevated privileges on macOS and Linux — use a high port such as '''1502''' for unprivileged testing.
|-
| '''Unit ID''' || The single slave / unit address this server answers as (0–247, default '''1'''). Requests addressed to any other unit ID are rejected, so this is a deliberate one-device simulator.
|-
| '''Status''' || Shows '''Stopped''', or '''Running''' with the active address, port and unit ID in green.
|}

The '''Start / Stop''' button (the toggle at the top of the right-hand toolbar) binds and unbinds the server. The bind address, port and unit ID can only be changed while the server is stopped. The server can be stopped and started again without restarting the application, and '''all register values are kept across a stop/start''' — they are only lost when you exit the application.

=== 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. || Yes
|-
| '''Input''' || Input register reference (30001…), a decimal value (0–65535) and a read-only '''Hex''' view. || Yes
|-
| '''Holding''' || Holding register reference (40001…), a decimal value (0–65535) and a read-only '''Hex''' view. || Yes
|}

The '''Address''' is the zero-based protocol address; the '''Modbus Ref''' column in each group is the conventional reference number an operator would quote (for example coil 0 is reference 1, holding register 0 is reference 40001).

All four tables are editable directly in this window — including discrete inputs and input registers, which a Modbus client is not allowed to write. This lets the server stand in for a real device whose inputs change. Values can be edited whether or not the server is running and whether or not a client is connected, which is useful for staging a test scenario in advance.

Below the table, the '''Start address''' and '''Count''' fields choose which window of addresses is listed; 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 for an individual table — Coils, Discrete Inputs, Input Registers or Holding Registers — or '''Zero All''' to clear every table at once.

=== Activity Log ===

Every change to a coil or register is written to the log at the bottom with a millisecond timestamp, whether it came from a connected client or from an operator edit in the window. The log keeps the most recent 400 lines. The two buttons beside it '''Save''' the log to a text file and '''Clear''' it.

== Toolbar Buttons ==

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

== Configuration ==

The connection settings (bind address, 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>0.0.0.0</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.

== Headless (Service) Mode ==

In addition to the interactive window, the Modbus Server can run headless as a background service. In this mode it loads the saved <code>xml/config/config.xml</code>, binds the server with no user interface, and runs until the operating system asks it to stop (for example a service stop, console Ctrl-C, or system shutdown). The native install packages provide both a GUI launcher and a Service launcher for this purpose.

== Using the Server and Client Together ==

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

# Start this server, choose a '''port''' and '''unit ID''', and press '''Start'''.
# In the [[ModbusClient]], set '''Server host''' to this 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:''' when the client edits a Coil or Holding Register, the value is written here and appears in this server's grid and activity log.
# '''Server → Client:''' edit any value here — including discrete inputs and input registers, which the client can only read — and the client's grid reflects it on its 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, while the client stands in for a master so you can stage and inspect a device's data. This server can equally answer a real third-party Modbus/TCP master.

== Troubleshooting ==

* '''"Permission denied" when starting''' — the chosen port is below 1024 (the default is 502) and the operating system requires elevated privileges to bind it. Use a port of 1024 or higher, such as 1502, or run with elevated privileges.
* '''A client's requests are rejected''' — the server answers only the configured '''Unit ID'''. Check the client is using the same unit ID shown in the connection bar.
* '''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 ==

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

[[Category:Commander4j]]

ModbusServer - Revision history

Dgarratt: Updated by push_wiki.py

Dgarratt: Updated by push_wiki.py

Dgarratt: Updated by push_wiki.py