ModbusServer

The Commander4j Modbus Server (util_modbusServer) is a desktop tool that turns your PC into a 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 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:

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

Source Code and Releases

The Modbus Server is open source and hosted on GitHub:

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

Running the Modbus Server

The recommended way to install the Modbus Server 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 native launchers you can run like any other desktop application (from the Start menu, Applications folder, or desktop):

Launcher	What it does
ModbusServer	Starts the interactive window described below.
ModbusServer Service	Starts the server 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 as an ordinary Java 25 (Swing) application:

java -jar modbusServer.jar

The supplied start_modbusServer.sh (macOS/Linux) and start_modbusServer.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
Bind address	The network interface to listen on. `0.0.0.0` 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:

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 xml/config/config.xml 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, started by the ModbusServer Service launcher. In this mode it loads the saved xml/config/config.xml, 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

The Modbus Server and the 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 (127.0.0.1 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 sun.misc.Unsafe — harmless, and does not affect operation. The supplied start scripts suppress it; launching the jar directly may still print it.