Commander4j - User contributions [en-gb]

Menu4j

2026-07-21T14:59:32Z

Dgarratt: /* The Menu Tree */

Menu4j (JMenuTree) is a desktop command launcher that organises shell commands, scripts, and applications into a hierarchical tree menu. It provides a configurable, script-aware alternative to Finder shortcuts and shell aliases, with support for real-time terminal output, multiple linked menu trees, and optional startup password protection.

== Purpose ==

Menu4j is used to organise the day-to-day development and operational commands for the Commander4j suite in a single, structured interface. Menu items can run shell scripts, open applications, pass parameters, capture output, and link to other menu tree files.

== Running Menu4j ==

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

Alternatively, Menu4j can be run directly from the distribution archive. It is a Java 25 desktop (Swing) application:

java -jar JMenu.jar

On first launch, if no configuration file is found, Menu4j copies a template configuration from <code>xml/config/init/config.xml</code> and a template menu tree from <code>xml/tree/init/tree.xml</code>.

If a startup password has been configured, you are prompted to enter it before the menu is shown. Three failed attempts close the application.

== The Menu Tree ==

The main window displays a JTree. There are two node types:

{| class="wikitable"
|-
! Type !! Purpose
|-
| Branch || A folder that contains other branches or leaves
|-
| Leaf || An executable item — a command, script, or application
|}

Double-click a leaf to execute it. Double-click a branch to expand or collapse it.

=== Adding and Editing Items ===

The right sidebar toolbar provides:

* '''Add''' — insert a new branch or leaf under the selected node
* '''Edit''' — open the editor for the selected node
* '''Delete''' — remove the selected node
* '''Duplicate''' — copy the selected node

[[File:JMenuTree1.png|400px]]

=== Leaf Properties ===

When editing a leaf node, the following properties are available:

{| class="wikitable"
|-
! Property !! Description
|-
| Description || The label shown in the menu tree
|-
| Directory || The working directory for the command
|-
| Command || The executable or system command to run
|-
| Parameters || A list of arguments to pass to the command
|-
| Shell Script Required || Whether to wrap the command in the configured shell wrapper script
|-
| Terminal Window Required || Whether to open a terminal output window to show command output
|-
| Confirm Execute || Whether to show a confirmation prompt before running
|-
| Link to Menu Tree || Whether this item opens a different tree file instead of running a command
|-
| Hint || A tooltip shown when hovering over the item
|-
| Icon || An image file to display next to the item label
|}

[[File:JMenuTree2.png|600px]]

== Executing Commands ==

When a leaf is executed:

# Menu4j validates that the directory and command exist
# If '''Shell Script Required''' is set, the command is wrapped using the script configured in Settings (typically a shell wrapper that sources the user's environment)
# If '''Terminal Window Required''' is set, a terminal output window opens and displays stdout and stderr in real time; otherwise the command runs silently in the background
# Environment variables configured in Settings are injected before execution

=== Terminal Output Window ===

The terminal window displays command output with configurable foreground and background colours and font (configured in Settings). A '''Respond''' button allows text to be sent to the command's standard input for interactive commands. When the command completes, the return code is displayed.

== Multiple Tree Files ==

A leaf node can be configured to switch to a different menu tree rather than execute a command. Set '''Link to Menu Tree''' and specify the filename. Double-clicking the leaf saves the current tree's expansion state and loads the linked tree. The application title bar updates to show the active tree filename.

== Configuration ==

=== config.xml ===

Located at <code>xml/config/config.xml</code>. This file stores global settings including the active tree filename, shell script settings, colours, fonts, environment variables, system command whitelist, and the encrypted startup password.

=== tree.xml ===

Located at <code>xml/tree/tree.xml</code> (or a different filename if you have switched trees). This is the menu structure file. It is written automatically when you save from the application.

=== tree.xml.state ===

Located alongside the tree file. Records which branches were expanded on the last exit and restores them on next launch.

== Settings ==

Open Settings from the toolbar to configure:

{| class="wikitable"
|-
! Setting !! Description
|-
| Password || Optional startup password (stored AES-encrypted)
|-
| Shell script || Enable/disable the shell wrapper and set the script filename
|-
| Terminal colours || Foreground and background colours for the terminal output window
|-
| Tree colours || Foreground colours for leaf and branch labels
|-
| Fonts || Font choice and size for the terminal window, leaf labels, and branch labels
|-
| Environment variables || Key/value pairs injected into every executed process
|-
| System commands || Whitelist of system commands (such as <code>open</code>) that do not require a file path to be validated
|}

[[File:JMenuTree3.png|600px]]

== Tree Navigation ==

The top toolbar provides four buttons for expanding and collapsing the tree:

* Expand All
* Expand Selected Branch
* Collapse Selected Branch
* Collapse All

== Saving ==

Changes to the tree structure are saved using the '''Save''' button in the sidebar toolbar. You are prompted to save if you close the application with unsaved changes.

See also: [[LaunchPad]], [[Downloads]]

[[Category:Commander4j]]

ModbusBridge

2026-07-15T20:10:43Z

Dgarratt: Updated by push_wiki.py

The '''Commander4j Modbus Bridge''' (''util_modbusBridge'') is a '''headless service''' that lets applications without [https://en.wikipedia.org/wiki/Modbus Modbus/TCP] client capability set and query the values of a remote Modbus server over a simple REST API. It connects to one Modbus server, polls a fixed list of '''named points''' (configured in XML), keeps the latest values in memory, and serves them over HTTP. It also provides a live web UI to view and change values, and a second page to tail the log.

Unlike the interactive [[ModbusClient|Commander4j Modbus Client]], the Bridge runs unattended: it auto-reconnects when the link drops and is packaged to run as an operating-system service. It reuses the same Modbus engine as the [[ModbusClient]] and is a natural companion to the [[ModbusServer]].

If you are new to Modbus, the [[ModbusClient#A Quick Modbus Primer|Modbus primer on the Modbus Client page]] explains the terms (client/server, unit ID, and the four data tables) used throughout this page.

== Purpose ==

The Modbus Bridge is useful when:

* An application or script that cannot speak Modbus needs to read or write a PLC or other Modbus/TCP device over plain HTTP/JSON
* A remote Modbus server's values should be exposed on a network as named points rather than raw addresses
* An unattended, always-on bridge is needed that survives link drops and restarts as a managed service
* A browser-based view of live values, with inline editing and a live log, is wanted without installing a desktop tool
* A calling application must keep working, unchanged, while the physical Modbus device is out of service (see [[#Simulated points|Simulated points]])

The Bridge is a '''generic tool''' — any application that can issue HTTP requests can use it. Within the Commander4j suite, for example, the web Issue application (''c4j_web_Issue'') can use it to pulse a PLC relay when a pallet is scanned in the wrong lane, but nothing about the Bridge is specific to that (or any other) application.

== Source Code and Releases ==

The Modbus Bridge is open source and hosted on GitHub:

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

== Running the Modbus Bridge ==

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

=== As a service ===

The native installer registers and starts the Bridge as an operating-system service — '''launchd''' on macOS, a '''Windows service''', or a '''systemd / init''' unit on Linux. The service runs with its working directory set to the installation directory, so all the relative paths below resolve correctly. Stopping the service triggers an ordered shutdown so that teardown events still reach the log file.

=== Running from the jar ===

Alternatively the Bridge can be launched from its distribution folder:

* <code>./start_modbusBridge.sh</code> (macOS/Linux) or <code>start_modbusBridge.cmd</code> (Windows), or
* <code>ant run</code> to launch from compiled classes, or
* directly with Java:

java -Dlog4j2.shutdownHookEnabled=false -Dlog4j2.configurationFile=xml/config/log4j2.xml -jar modbusBridge.jar

<code>modbusBridge.jar</code> is a '''thin jar''' — it references the dependency jars in <code>lib/</code> via its manifest, so it must be run from the project root with <code>lib/</code>, <code>xml/</code>, <code>web/</code> and <code>logs/</code> alongside it. Any Java 25 runtime on the <code>PATH</code> will do; a bundled JRE is not required when run this way.

The two <code>-D</code> system properties matter, and the start scripts set them for you:

* <code>-Dlog4j2.shutdownHookEnabled=false</code> — lets the Bridge's own shutdown hook stop log4j2 '''last''', so teardown events still reach the log file the tail page reads.
* <code>-Dlog4j2.configurationFile=xml/config/log4j2.xml</code> — <code>log4j2.xml</code> lives under <code>xml/config/</code>, not on the classpath, so log4j2 must be pointed at it explicitly.

== Configuration ==

All configuration is in <code>xml/config/config.xml</code>:

<config>
<modbus>
<ip>127.0.0.1</ip>
<port>1502</port>
<id>1</id>
<pollIntervalMs>1000</pollIntervalMs>
<maxHoldMs>60000</maxHoldMs>
</modbus>
<webserver>
<ip>0.0.0.0</ip>
<port>8080</port>
</webserver>
<restapi>
<id name="LANEA" point="pump_run" caseSensitive="false"/>
<id name="LANEB" point="pump_run" caseSensitive="false"/>
</restapi>
<points>
<point name="pump_run" kind="COIL" address="0" initialise="false" value="false"
minHoldMs="500" maxHoldMs="10000" defaultHoldMs="3000"/>
<point name="tank_level" kind="HOLDING_REGISTER" address="100" initialise="false" value="0"/>
<point name="fault" kind="DISCRETE_INPUT" address="10"/>
<point name="flow_rate" kind="INPUT_REGISTER" address="30"/>
</points>
</config>

The <code><modbus></code> block points the Bridge at the remote Modbus server: its host <code><ip></code>, TCP <code><port></code> (the Modbus standard is '''502'''; the example uses '''1502''' because ports below 1024 need root on macOS/Linux), the unit / slave <code><id></code> to address, and the <code><pollIntervalMs></code> between reads. The optional <code><maxHoldMs></code> is the default hold cap for points that do not set their own <code>maxHoldMs</code> attribute (60 000 ms if absent) — see [[#Pulse (momentary output)|Pulse]] below. The <code><webserver></code> block sets the bind address for the HTTP server (<code>0.0.0.0</code> = all interfaces) and the port it listens on. The optional <code><restapi></code> block maps application-facing ids onto points — see [[#REST ids (application names for points)|REST ids]] below.

Each <code><point></code> gives a human-friendly '''name''' (how REST clients and the web UI refer to it), a Modbus data table '''kind''', and a zero-based protocol '''address'''. Valid kinds are <code>COIL</code>, <code>DISCRETE_INPUT</code>, <code>HOLDING_REGISTER</code> and <code>INPUT_REGISTER</code>. Only '''coils''' and '''holding registers''' are writable — discrete inputs and input registers are read-only in the Modbus data model (there is no client-write function code for them).

=== Startup initialisation (optional) ===

Add <code>initialise="true" value="..."</code> to a writable point to have the Bridge drive it to a known state at startup:

* On the '''first successful connect''' after the Bridge starts, it reads the point's current value and writes <code>value</code> '''only if it differs''' (an already-correct point is left untouched). This runs once — a later link drop and reconnect does '''not''' re-apply it, so runtime REST/operator changes survive an outage.
* If the Modbus server is unavailable at startup, initialisation simply waits and runs on the first connect once it becomes reachable.
* <code>value</code> is <code>true</code>/<code>false</code> (or <code>1</code>/<code>0</code>) for coils, and a <code>0..65535</code> integer for holding registers. <code>initialise</code> defaults to <code>false</code>.

Configuration is rejected at startup if <code>initialise="true"</code> is set on a read-only kind, or without a <code>value</code>, or with a value that does not match the kind.

=== Per-point pulse hold policy (optional, writable points only) ===

<code>minHoldMs</code>, <code>maxHoldMs</code> and <code>defaultHoldMs</code> control what a [[#Pulse (momentary output)|pulse]] request may ask this point to hold for:

* <code>minHoldMs</code> / <code>maxHoldMs</code> are the enforced bounds — a pulse whose <code>holdMs</code> falls outside them is rejected with '''400'''. Defaults: min <code>1</code>, max = the global <code><maxHoldMs></code> (60 000 if that is absent too). A tight per-point range (e.g. <code>500..10000</code> on a relay coil) means a typo like <code>30000</code> for <code>3000</code> can't hold the relay closed for half a minute.
* <code>defaultHoldMs</code> is the hold applied when a pulse request omits <code>holdMs</code> entirely, and is what the web UI pre-fills in the row's hold field (it is reported by the API for other clients to use the same way). Default: <code>3000</code> — sized for switching an electrical relay — clamped into the min/max range. Keeping callers' request bodies to just <code>{"value": 1}</code> leaves the relay timing centralised in the config file.
* Config-load validation enforces <code>1 ≤ minHoldMs ≤ defaultHoldMs ≤ maxHoldMs</code> and rejects the attributes on read-only kinds.

=== REST ids (application names for points) ===

The optional <code><restapi></code> section maps '''application-facing ids''' onto points, separating the caller's vocabulary from the physical wiring. Each <code><id></code> gives a <code>name</code> the REST API accepts and the <code>point</code> it resolves to; several ids may map to the same point:

<restapi>
<id name="LANEA" point="PLC_Link1"/>
<id name="LANEB" point="PLC_Link1"/>
<id name="LANEC" point="PLC_Link1"/>
<id name="LANED" point="PLC_Link1"/>
<id name="LANEE" point="PLC_Link2"/>
</restapi>

This lets a calling application address the Bridge in its own terms — lane names, machine names, whatever its domain uses — while the mapping to real Modbus points stays in the Bridge's configuration. As an example, the Commander4j web Issue application (''c4j_web_Issue'') signals a wrong-lane error by pulsing a relay, using the production '''lane id''' as the point name — but several lanes may share one physical relay. Mapping all of those ids onto the single point (<code>PLC_Link1</code> above) means the Bridge sees them as '''one entity''', so pulses fired for different lanes in quick succession '''queue on that point's single pulse queue''' — each set→hold→reset cycle completes before the next starts, instead of several independent "points" at the same address interfering with each other's hold and reset. The same mechanism serves any application whose naming does not map one-to-one onto the physical wiring. Note the consequence: a queued pulse's HTTP response is delayed until its turn comes (up to queue-depth × hold time), so callers should use a generous timeout or call asynchronously.

* '''Ids work everywhere a <code>{name}</code> is accepted''' — <code>GET</code>/<code>PUT /api/points/{name}</code> and <code>POST /api/points/{name}/pulse</code> — and single-point responses (and error messages) echo the name the caller used. The points list, SSE stream and web UI always show the point once, under its own name; the id→point map is reported in <code>/api/status</code> (<code>"restIds"</code>) and shown under the point's name in the web UI. Log lines record both, e.g. <code>Pulse accepted for PLC_Link1 (as LANEB)</code>, so the originating caller stays traceable even though the wire only sees the shared point.
* '''<code>caseSensitive</code>''' (optional, default <code>false</code>) controls matching: by default an id matches any capitalisation (<code>LANEA</code>, <code>LaneA</code>, <code>lanea</code>). Point names themselves remain case-sensitive and stay addressable alongside the ids.
* '''Validation at load:''' every id must reference an existing point; ids and point names share one namespace, so exact duplicates are rejected, and a case-insensitive id reserves its whole case class (nothing else may differ from it only by capitalisation). Bad configuration fails startup loudly, like every other config error.

=== Simulated points ===

Add <code>simulate="true"</code> to any point to detach it from the wire entirely — for keeping a calling application working, without error-handling changes, while the physical Modbus device is out of service:

<point name="pump_run" kind="COIL" address="0" simulate="true" value="false"/>

* '''REST callers cannot tell the difference.''' Reads return the in-memory value (always <code>"valid":true,"stale":false</code>); writes and pulses succeed with the normal responses and are visible to subsequent reads; read-only kinds still reject writes with 400. The points payload deliberately carries '''no''' simulation marker, so the client↔bridge conversation is unchanged.
* The poll thread never touches a simulated point, and a dead link (or <code><modbus enabled="false"></code>) does not mark it stale or fail its writes — that is the whole purpose.
* <code>value</code> seeds the simulated value at startup (<code>true</code>/<code>false</code>/<code>1</code>/<code>0</code> for bit kinds, <code>0..65535</code> for registers; default 0). Values are held in memory only: a restart resets to the seed.
* <code>simulate</code> cannot be combined with <code>initialise</code> (there is no wire to initialise), and any kind may be simulated — a simulated <code>DISCRETE_INPUT</code> simply reports its seed until changed at source.
* For the '''operator''' (not the REST caller): <code>/api/status</code> reports the simulated point names in <code>"simulatedPoints"</code>, and the web UI tags those rows ''simulated''.

=== Disabling the Modbus link ===

When the whole device is out of service, <code><modbus enabled="false"></code> (attribute on the <code><modbus></code> element; default <code>true</code>) stops the Bridge connecting at all — no reconnect attempts, no backoff noise in the log. Real points then behave exactly as during an outage (stale reads, 503 writes) while simulated points keep working. <code>/api/status</code> reports <code>"modbusEnabled":false</code> and the web UI banner says the link is disabled rather than disconnected.

Logging is configured in <code>xml/config/log4j2.xml</code> (rolling file at <code>logs/modbusBridge.log</code>, 10 MB cap, 5 generations). The Bridge's own classes log at <code>debug</code>; the Netty transport at <code>warn</code>.

== REST API ==

{| class="wikitable"
|-
! Method !! Path !! Behaviour
|-
| <code>GET</code> || <code>/api/points</code> || All points with current values + connection status.
|-
| <code>GET</code> || <code>/api/points/{name}</code> || One point's current value. 404 if unknown. <code>{name}</code> is a point name or a [[#REST ids (application names for points)|restapi id]] (everywhere below too); the response echoes the name the caller used.
|-
| <code>PUT</code> || <code>/api/points/{name}</code> <code>{"value": N}</code> || Write a coil (0/1, or <code>true</code>/<code>false</code>) or holding register (0–65535). 400 for read-only kinds or out-of-range; 503 if the server is unreachable.
|-
| <code>POST</code> || <code>/api/points/{name}/pulse</code> <code>{"value": N [, "holdMs": N, "restValue": N]}</code> || Momentary output: set the point active, hold <code>holdMs</code> (default: the point's <code>defaultHoldMs</code>), then guarantee a reset to <code>restValue</code> (default 0). See [[#Pulse (momentary output)|below]]. 200 once energised; 503 if it couldn't be; 409 if too many pulses are already queued for the point; 400 for read-only kinds, out-of-range values, or <code>holdMs</code> outside the point's <code>minHoldMs..maxHoldMs</code>.
|-
| <code>GET</code> || <code>/api/status</code> || Connection health: connected, target, unit id, poll interval, max hold, last-poll time, point count, <code>modbusEnabled</code>, <code>simulatedPoints</code> (names), <code>restIds</code> (point → its restapi ids).
|-
| <code>GET</code> || <code>/api/licence</code> || Third-party licence list (from <code>lib/license/LicenseInfo.xml</code>).
|-
| <code>GET</code> || <code>/api/log/tail</code> <code>?lines=N</code> || Recent log lines (default 200, max 5000).
|-
| <code>GET</code> || <code>/events</code> || Server-Sent Events stream of the full points payload, pushed on every change.
|-
| <code>GET</code> || <code>/events/log</code> || Server-Sent Events stream of newly-appended log lines.
|}

A write is '''self-correcting''', not optimistic: the Bridge writes the value, then immediately reads the point back from the server, so the response and cache reflect the server's actual state. When the link is down, reads return the last snapshot flagged <code>"valid":false,"stale":true</code> and writes return '''503'''. '''[[#Simulated points|Simulated points]]''' are exempt from all of this: their reads, writes and pulses always succeed against the in-memory value, link or no link, and their payloads are indistinguishable from a live point's.

Examples:

curl http://localhost:8080/api/points
curl -X PUT -H 'Content-Type: application/json' -d '{"value":1}' http://localhost:8080/api/points/pump_run
curl -X PUT -H 'Content-Type: application/json' -d '{"value":4242}' http://localhost:8080/api/points/tank_level

=== Pulse (momentary output) ===

<code>POST /api/points/{name}/pulse</code> sets a writable point active, holds it, then '''guarantees''' it returns to a rest value — with the timing owned by the Bridge, not the caller. It exists to drive a PLC relay safely: a dropped web session, a client crash, or a link blip during the hold can never leave the relay energised.

The following energises <code>pump_run</code> for 3 seconds, then resets it to 0:

curl -X POST -H 'Content-Type: application/json' -d '{"value":1,"holdMs":3000,"restValue":0}' http://localhost:8080/api/points/pump_run/pulse

* '''The response is a real confirmation.''' <code>200</code> means the relay was energised and its reset is scheduled; <code>503</code> means nothing was energised (link down) and nothing is owed. The set runs on the request thread; the hold and reset run in the background.
* '''The reset is guaranteed''' across a dropped caller session, a link drop during the hold (it retries as the Bridge reconnects), and a graceful service stop (the reset is flushed ''before'' the Modbus link closes). It is '''not''' guaranteed across a hard kill or power loss — for that, configure a PLC-side hardware watchdog that de-energises a coil that stops being refreshed.
* '''<code>holdMs</code> is optional''' — when omitted, the point's configured <code>defaultHoldMs</code> applies, so a caller can send just <code>{"value": 1}</code> and leave the relay timing to the Bridge's configuration. When supplied, it must be within the point's <code>minHoldMs..maxHoldMs</code> (see [[#Per-point pulse hold policy (optional, writable points only)|the config section]]; defaults <code>1..60000</code>) so a typo can't hold a relay for hours — set a tight per-point range on real relay coils. '''<code>restValue</code>''' is optional (default 0). The point's bounds and its <code>defaultHoldMs</code> are reported in every points payload for clients to discover.
* '''Concurrency:''' pulses on the same point run one complete set→hold→reset cycle at a time, so the relay returns to rest between them; a caller that outruns the queue gets <code>409</code>. Pulses on different points are independent. Note that a '''queued''' pulse's HTTP response is delayed until its turn to fire (up to <code>holdMs</code> × its position in the queue), so a client's request timeout must exceed the worst-case wait, or it may abandon a pulse that still fires server-side.

== Web UI ==

Open <code>http://<host>:8080/</code> in a browser:

* '''Points''' (<code>index.html</code>) — a live table of every configured point, updated by push (SSE) with no refresh needed. Writable points have an inline editor; type a value and click '''Set''' (or press Enter) to issue the PUT. Next to it, a '''Pulse''' button with a hold-time field (pre-filled from the point's <code>defaultHoldMs</code>, bounded by its <code>minHoldMs</code>/<code>maxHoldMs</code>) sets the value, holds it for that time, then auto-resets to 0 — the timing runs server-side (see [[#Pulse (momentary output)|Pulse]]), so closing the page mid-hold cannot leave the point energised. You can watch the value go active and drop back live in the table. Stale values (link down) are shown in red. A manual '''Refresh''' button is kept as a fallback.
* '''Log''' (<code>log.html</code>) — the recent log backlog followed live as new lines are written, with an auto-scroll toggle. <code>WARN</code> / <code>ERROR</code> lines are colour-coded.
* '''Licences''' (<code>licence.html</code>) — the third-party libraries and their licences rendered as a table (the underlying <code>/api/licence</code> endpoint returns the same data as raw JSON).

== Modbus Behaviour ==

* '''Transport:''' Modbus/TCP only (no serial / RTU, no TLS), reusing the [[ModbusClient]]'s Modbus engine.
* The poll thread reads every configured point once per <code>pollIntervalMs</code>. A read failure tears the connection down, flags all points stale, and the Bridge auto-reconnects with exponential backoff (1 → 2 → 4 → 8 … up to 30 s), resetting on a successful connect.

== Troubleshooting ==

* '''<code>Address already in use</code> on start''' — another process holds the web port (default 8080). Change <code><webserver><port></code> or free the port.
* '''All points show stale / <code>/api/status</code> says not connected''' — the Modbus server is unreachable. Check <code><modbus><ip>/<port></code>, that the server is running, and that both ends use the same '''unit id''' (the server answers only its configured unit). The log shows the backoff retries.
* '''Writes return 503''' — the link is down at that moment; the Bridge is between reconnect attempts. Reads still return the last-known (stale) values.
* '''All points stale but no reconnect attempts in the log''' — the Modbus link may be switched off in the configuration: check for <code><modbus enabled="false"></code> (<code>/api/status</code> reports <code>"modbusEnabled":false</code> and the web UI banner shows ''disabled'' rather than ''disconnected'').
* '''PUT returns 400 "read-only"''' — the named point is a <code>DISCRETE_INPUT</code> or <code>INPUT_REGISTER</code>; those cannot be written by a Modbus client.
* '''No log lines / empty log tail page''' — confirm <code>-Dlog4j2.configurationFile=xml/config/log4j2.xml</code> is set (the start scripts do this) and the process working directory is the project root, so <code>logs/</code> is created in the right place.

== See Also ==

* [[ModbusClient]] — the interactive desktop Modbus client; the Bridge reuses its Modbus engine
* [[ModbusServer]] — the server-side companion tool, useful as a bench target for the Bridge
* [[AutoLab4j]] — uses the same Modbus stack to monitor a coil and trigger a labeller on a change of state
* [[SocketTest]] — a raw TCP/IP testing utility

[[Category:Commander4j]]

ModbusBridge

2026-07-02T16:46:29Z

Dgarratt: Updated by push_wiki.py

Label Function Syntax

2026-06-24T12:37:56Z

Dgarratt: Updated by push_wiki.py

There are a number of functions which you can embed in your barcode label template to help format the data before sending to a labeller.

Referencing field names uses this syntax.

<*fieldname*>

for example

<*SSCC*> <*QUANTITY*> <*DESCRIPTION*>

Functions are resolved innermost-first, so they can be nested. The result of an inner function is passed as the input to the function which encloses it.

<PADLEFT(<SUBSTRING(<*BATCH*>,1,3)>,5,0)>

If a function is given the wrong number of parameters it returns the function name followed by '''[Incorrect number of parameters]''', and a function given an invalid date/time format returns the function name followed by '''[Incorrect date/time format]'''. This makes mistakes visible on the printed label rather than failing silently.

===DATE_CREATED===

This function returns the date & time when the pallet record was created in the database and allows you to specify the format that you want it formatted in the label.

Example usage

<DATE_CREATED(ddMMyy)>
<DATE_CREATED(dd/MM/yyyy)>

If the value of the DATE_CREATED field is null or blank it will return spaces instead of date.

===DATETIME===

The function allows you to format a datetime/timestamp field value from the database and display it in the label using the format specified.

<DATETIME(fieldname,dd/MM/yyyy HH:mm:ss)>

===EXPIRYDATE===

When a label is printed Commander4j will automatically calculate the expiry date of the product. It is important to realise however that the application has 2 modes for recording the expiry date. It can be associated with the individual pallet number (SSCC) or it can be associated with the batch number. The mode that the system is using is defined in [[System Keys]] using the setting called '''EXPIRY DATE MODE'''

This function will retrieve the value from the appropriate table based on the setting above.

<EXPIRYDATE(MM yyyy)>
<EXPIRYDATE(MM)>
<EXPIRYDATE(yy)>
<EXPIRYDATE(dd)> <EXPIRYDATE(MM)> <EXPIRYDATE(yyyy)>

===IIF===

<IIF(param1,param2,param3,param4)>

IF param1 = param2 then
return param3
else
return param4

===JULIAN_YJJJ===

This function returns the production / manufacturing data in the format {last digit of year}{Julian day number}

<JULIAN_YJJJ()>

===LEFT===

<LEFT(fieldname,5)>

===LOWERCASE===

<LOWERCASE(fieldname)>

===LTRIM===

<LTRIM(fieldname)>

===PADLEFT===

<PADLEFT(fieldname,14,0)>

This function pads out the size of a string to the length specified using the character specified.

It adds any additional characters to the left size of the string.

===PADRIGHT===

<PADRIGHT(fieldname,14,0)>

This function pads out the size of a string to the length specified using the character specified.

It adds any additional characters to the right size of the string.

===PALLET_WEIGHT_BARCODE===

<PALLET_WEIGHT_BARCODE(KG,3)>

This function returns the total weight of the pallet (looked up from the pallet's SSCC) formatted to the number of decimal places specified, but with the decimal point '''removed''' so that the value can be embedded directly in a barcode.

The first parameter is the unit of measure for the weight; if it is left blank it defaults to '''KG'''. The second parameter is the number of decimal places.

For example a weight of 123.456 KG would produce '''123456'''

<PALLET_WEIGHT_BARCODE(KG,3)>

See also [[#PALLET_WEIGHT_TEXT|PALLET_WEIGHT_TEXT]], which is identical but keeps the decimal point for human-readable display.

===PALLET_WEIGHT_TEXT===

<PALLET_WEIGHT_TEXT(KG,3)>

This function returns the total weight of the pallet (looked up from the pallet's SSCC) formatted to the number of decimal places specified, for display as human-readable text on the label.

The first parameter is the unit of measure for the weight; if it is left blank it defaults to '''KG'''. The second parameter is the number of decimal places.

For example a weight of 123.456 KG would produce '''123.456'''

<PALLET_WEIGHT_TEXT(KG,3)>

This is the same as [[#PALLET_WEIGHT_BARCODE|PALLET_WEIGHT_BARCODE]] except that the decimal point is retained.

===PRODDATE===

This function returns the production / date of manufacture of the pallet and allows you to specify the format that you want it displayed in on the label.

<PRODDATE(dd/MM/yyyy)>
<PRODDATE(ddMMyy)>

If the format is left blank it defaults to '''dd/MM/yyyy'''. If the date of manufacture is null it returns spaces of the same length as the format specified instead of a date.

===RIGHT===

<RIGHT(fieldname,5)>

===RTRIM===

<RTRIM(fieldname)>

===SUBSTRING===

<SUBSTRING(fieldname,start,length)>

This function returns part of a string. '''start''' is the position of the first character to extract (the first character is position 1) and '''length''' is the number of characters to return.

<SUBSTRING(fieldname,1,3)>

would return the first 3 characters of the field. The function is bounds-safe; if the input is shorter than requested it returns as many characters as are available rather than producing an error.

===SUBTR_LPAD===

<SUBTR_LPAD(fieldname,start,length,size,padchar)>

This function first left-pads the input value out to '''size''' characters using '''padchar''', and then returns a substring of the padded value starting at position '''start''' (the first character is position 1) for '''length''' characters.

For example, if a field contains '''12''':

<SUBTR_LPAD(fieldname,1,4,4,0)>

would first pad the value to '''0012''' and then return the first 4 characters '''0012'''.

===TIMESTAMP===

This function returns the current system date & time at the moment the label is printed, formatted using the format specified.

<TIMESTAMP(dd/MM/yyyy HH:mm:ss)>
<TIMESTAMP(ddMMyy)>

If the format is left blank it defaults to '''dd/MM/yyyy HH:mm:ss'''.

===TRIM===

<TRIM(fieldname)>

===UPPERCASE===

<UPPERCASE(fieldname)>

===USERNAME===

This function returns the name of the user currently logged on to Commander4j, in upper case.

<USERNAME()>

===VERSION===

This function returns the version number of the Commander4j application.

<VERSION()>

ModbusServer

2026-06-22T14:23:09Z

Dgarratt: Updated by push_wiki.py

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

== 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 ==

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):

{| 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 as an ordinary Java 25 (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, 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 ==

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 monitor a coil and trigger a labeller on a change of state
* [[SocketTest]] — a raw TCP/IP testing utility

[[Category:Commander4j]]

ModbusClient

2026-06-22T14:23:08Z

Dgarratt: Updated by push_wiki.py

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

== 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 ==

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.

=== 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 <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 monitor a coil and trigger a labeller on a change of state
* [[SocketTest]] — a raw TCP/IP testing utility

[[Category:Commander4j]]

ModbusBridge

2026-06-22T14:23:07Z

Dgarratt: Updated by push_wiki.py

ModbusServer

2026-06-22T14:22:36Z

Dgarratt: Updated by push_wiki.py

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

== 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 ==

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):

{| 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 as an ordinary Java 25 (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, 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 ==

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]] — an automatic labeller that uses the same Modbus stack to watch production-line signals
* [[SocketTest]] — a raw TCP/IP testing utility

[[Category:Commander4j]]

ModbusClient

2026-06-22T14:22:35Z

Dgarratt: Updated by push_wiki.py

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

== 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 ==

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.

=== 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 <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]] — an automatic labeller that uses the same Modbus stack to watch production-line signals
* [[SocketTest]] — a raw TCP/IP testing utility

[[Category:Commander4j]]

ModbusBridge

2026-06-22T14:22:34Z

Dgarratt: Updated by push_wiki.py

Template:Menu Applications

2026-06-22T14:18:50Z

Dgarratt: /* Applications */

=Applications=
{| cellpadding="8" style="text-align:center"
||[[file:AutoLab4j_256x256.png|link=[[AutoLab4j]]|100px]]
====[[AutoLab4j]]====
|
||[[File:Commander4j_256x256.png|link=[[Commander4j]]|100px]]
====[[Commander4j]]====
|
||[[file:LabelServer4j_256x256.png|link=[[LabelServer4j]]|100px]]
====[[LabelServer4j]]====
|
||[[file:LaunchPad_256x256.png|link=[[LaunchPad]]|100px]]
====[[LaunchPad]]====
|-
||[[file:LogoClient_256x256.png|link=[[LogoClient]]|100px]]
====[[LogoClient]]====
|
||[[file:LogoRenderer_256x256.png|link=[[LogoRenderer]]|100px]]
====[[LogoRenderer]]====
|
||[[file:Menu4j_256x256.png|link=[[Menu4j]]|100px]]
====[[Menu4j]]====
|
||[[file:Middleware4j_256x256.png|link=[[Middleware4j]]|100px]]
====[[Middleware4j]]====
|-
||[[file:Modbus_256x256.png|link=[[ModbusBridge]]|100px]]
====[[ModbusBridge]]====
|
||[[file:Modbus_256x256.png|link=[[ModbusClient]]|100px]]
====[[ModbusClient]]====
|
||[[file:Modbus_256x256.png|link=[[ModbusServer]]|100px]]
====[[ModbusServer]]====
|
||[[file:SFTGet4j_256x256.png|link=[[SFTPGet]]|100px]]
====[[SFTPGet]]====
|-
||[[file:SFTPSend4j_256x256.png|link=[[SFTPSend]]|100px]]
====[[SFTPSend]]====
|
||[[file:sftpTransfer_256x256.png|link=[[SFTPTransfer]]|100px]]
====[[SFTPTransfer]]====
|
||[[file:SocketTest_256x256.png|link=[[SocketTest]]|100px]]
====[[SocketTest]]====
|
||[[file:TreeDoc_256x256.png|link=[[TreeDoc]]|100px]]
====[[TreeDoc]]====
|-
||[[file:XMLViewer_256x256.png|link=[[XMLViewer]]|100px]]
====[[XMLViewer]]====
|
||[[file:ZPLRenderer_256x256.png|link=[[ZPLRenderer]]|100px]]
====[[ZPLRenderer]]====
|}

ModbusBridge

2026-06-22T14:00:59Z

Dgarratt: Updated by push_wiki.py

ModbusBridge

2026-06-22T13:44:23Z

Dgarratt: Created blank page

Template:Menu Applications

2026-06-22T13:43:47Z

Dgarratt: /* Applications */

=Applications=
{| cellpadding="8" style="text-align:center"
||[[file:AutoLab4j_256x256.png|link=[[AutoLab4j]]|100px]]
====[[AutoLab4j]]====
|
||[[File:Commander4j_256x256.png|link=[[Commander4j]]|100px]]
====[[Commander4j]]====
|
||[[file:LabelServer4j_256x256.png|link=[[LabelServer4j]]|100px]]
====[[LabelServer4j]]====
|
||[[file:LaunchPad_256x256.png|link=[[LaunchPad]]|100px]]
====[[LaunchPad]]====
|-
||[[file:LogoClient_256x256.png|link=[[LogoClient]]|100px]]
====[[LogoClient]]====
|
||[[file:LogoRenderer_256x256.png|link=[[LogoRenderer]]|100px]]
====[[LogoRenderer]]====
|
||[[file:Menu4j_256x256.png|link=[[Menu4j]]|100px]]
====[[Menu4j]]====
|
||[[file:Middleware4j_256x256.png|link=[[Middleware4j]]|100px]]
====[[Middleware4j]]====
|-
||[[file:Modbus_256x256.png|link=[[ModbusClient]]|100px]]
====[[ModbusClient]]====
|
||[[file:Modbus_256x256.png|link=[[ModbusServer]]|100px]]
====[[ModbusServer]]====
|
||[[file:SFTGet4j_256x256.png|link=[[SFTPGet]]|100px]]
====[[SFTPGet]]====
|
||[[file:SFTPSend4j_256x256.png|link=[[SFTPSend]]|100px]]
====[[SFTPSend]]====
|-
||[[file:sftpTransfer_256x256.png|link=[[SFTPTransfer]]|100px]]
====[[SFTPTransfer]]====
|
||[[file:SocketTest_256x256.png|link=[[SocketTest]]|100px]]
====[[SocketTest]]====
|
||[[file:TreeDoc_256x256.png|link=[[TreeDoc]]|100px]]
====[[TreeDoc]]====
|
||[[file:XMLViewer_256x256.png|link=[[XMLViewer]]|100px]]
====[[XMLViewer]]====
|-
||[[file:ZPLRenderer_256x256.png|link=[[ZPLRenderer]]|100px]]
====[[ZPLRenderer]]====
|
||[[file:Modbus_256x256.png|link=[[ModbusBridge]]|100px]]
====[[ModbusBridge]]====
|}

File:ModbusServer1.png

2026-06-20T16:04:08Z

Dgarratt:

ModbusServer

2026-06-20T16:03:52Z

Dgarratt: /* Connection Bar */

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

== 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 ==

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):

{| 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 as an ordinary Java 25 (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.

[[File:ModbusServer1.png|600px]]

=== 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, 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 ==

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]]

ModbusClient

2026-06-20T16:03:12Z

Dgarratt: /* Connection Bar */

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

== 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 ==

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.

=== 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 <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.

[[File:ModbusClient1.png|600px]]

=== 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 Modbus printing triggers
* [[SocketTest]] — a raw TCP/IP testing utility

[[Category:Commander4j]]

ModbusClient

2026-06-20T16:02:55Z

Dgarratt: /* The Main Window */

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

== 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 ==

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.

=== 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 <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.

[[File:ModbusClient1.png|600px]]

=== 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 Modbus printing triggers
* [[SocketTest]] — a raw TCP/IP testing utility

[[Category:Commander4j]]

File:ModbusClient1.png

2026-06-20T16:00:19Z

Dgarratt:

ModbusClient

2026-06-20T15:59:45Z

Dgarratt: /* The Main Window */

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

== 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 ==

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.

=== 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 <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.

[[File:ModbusClient1.png|600px]]

=== 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 Modbus printing triggers
* [[SocketTest]] — a raw TCP/IP testing utility

[[Category:Commander4j]]

File:JMenuTree3.png

2026-06-20T15:53:43Z

Dgarratt:

Menu4j

2026-06-20T15:53:22Z

Dgarratt: /* Settings */

Menu4j (JMenuTree) is a desktop command launcher that organises shell commands, scripts, and applications into a hierarchical tree menu. It provides a configurable, script-aware alternative to Finder shortcuts and shell aliases, with support for real-time terminal output, multiple linked menu trees, and optional startup password protection.

== Purpose ==

Menu4j is used to organise the day-to-day development and operational commands for the Commander4j suite in a single, structured interface. Menu items can run shell scripts, open applications, pass parameters, capture output, and link to other menu tree files.

== Running Menu4j ==

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

Alternatively, Menu4j can be run directly from the distribution archive. It is a Java 25 desktop (Swing) application:

java -jar JMenu.jar

On first launch, if no configuration file is found, Menu4j copies a template configuration from <code>xml/config/init/config.xml</code> and a template menu tree from <code>xml/tree/init/tree.xml</code>.

If a startup password has been configured, you are prompted to enter it before the menu is shown. Three failed attempts close the application.

== The Menu Tree ==

The main window displays a JTree. There are two node types:

{| class="wikitable"
|-
! Type !! Purpose
|-
| Branch || A folder that contains other branches or leaves
|-
| Leaf || An executable item — a command, script, or application
|}

Double-click a leaf to execute it. Double-click a branch to expand or collapse it.

=== Adding and Editing Items ===

The right sidebar toolbar provides:

* '''Add''' — insert a new branch or leaf under the selected node
* '''Edit''' — open the editor for the selected node
* '''Delete''' — remove the selected node
* '''Duplicate''' — copy the selected node

[[File:JMenuTree1.png|600px]]

=== Leaf Properties ===

When editing a leaf node, the following properties are available:

{| class="wikitable"
|-
! Property !! Description
|-
| Description || The label shown in the menu tree
|-
| Directory || The working directory for the command
|-
| Command || The executable or system command to run
|-
| Parameters || A list of arguments to pass to the command
|-
| Shell Script Required || Whether to wrap the command in the configured shell wrapper script
|-
| Terminal Window Required || Whether to open a terminal output window to show command output
|-
| Confirm Execute || Whether to show a confirmation prompt before running
|-
| Link to Menu Tree || Whether this item opens a different tree file instead of running a command
|-
| Hint || A tooltip shown when hovering over the item
|-
| Icon || An image file to display next to the item label
|}

[[File:JMenuTree2.png|600px]]

== Executing Commands ==

When a leaf is executed:

# Menu4j validates that the directory and command exist
# If '''Shell Script Required''' is set, the command is wrapped using the script configured in Settings (typically a shell wrapper that sources the user's environment)
# If '''Terminal Window Required''' is set, a terminal output window opens and displays stdout and stderr in real time; otherwise the command runs silently in the background
# Environment variables configured in Settings are injected before execution

=== Terminal Output Window ===

The terminal window displays command output with configurable foreground and background colours and font (configured in Settings). A '''Respond''' button allows text to be sent to the command's standard input for interactive commands. When the command completes, the return code is displayed.

== Multiple Tree Files ==

A leaf node can be configured to switch to a different menu tree rather than execute a command. Set '''Link to Menu Tree''' and specify the filename. Double-clicking the leaf saves the current tree's expansion state and loads the linked tree. The application title bar updates to show the active tree filename.

== Configuration ==

=== config.xml ===

Located at <code>xml/config/config.xml</code>. This file stores global settings including the active tree filename, shell script settings, colours, fonts, environment variables, system command whitelist, and the encrypted startup password.

=== tree.xml ===

Located at <code>xml/tree/tree.xml</code> (or a different filename if you have switched trees). This is the menu structure file. It is written automatically when you save from the application.

=== tree.xml.state ===

Located alongside the tree file. Records which branches were expanded on the last exit and restores them on next launch.

== Settings ==

Open Settings from the toolbar to configure:

{| class="wikitable"
|-
! Setting !! Description
|-
| Password || Optional startup password (stored AES-encrypted)
|-
| Shell script || Enable/disable the shell wrapper and set the script filename
|-
| Terminal colours || Foreground and background colours for the terminal output window
|-
| Tree colours || Foreground colours for leaf and branch labels
|-
| Fonts || Font choice and size for the terminal window, leaf labels, and branch labels
|-
| Environment variables || Key/value pairs injected into every executed process
|-
| System commands || Whitelist of system commands (such as <code>open</code>) that do not require a file path to be validated
|}

[[File:JMenuTree3.png|600px]]

== Tree Navigation ==

The top toolbar provides four buttons for expanding and collapsing the tree:

* Expand All
* Expand Selected Branch
* Collapse Selected Branch
* Collapse All

== Saving ==

Changes to the tree structure are saved using the '''Save''' button in the sidebar toolbar. You are prompted to save if you close the application with unsaved changes.

See also: [[LaunchPad]], [[Downloads]]

[[Category:Commander4j]]

Menu4j

2026-06-20T15:51:52Z

Dgarratt: /* Adding and Editing Items */

Menu4j (JMenuTree) is a desktop command launcher that organises shell commands, scripts, and applications into a hierarchical tree menu. It provides a configurable, script-aware alternative to Finder shortcuts and shell aliases, with support for real-time terminal output, multiple linked menu trees, and optional startup password protection.

== Purpose ==

Menu4j is used to organise the day-to-day development and operational commands for the Commander4j suite in a single, structured interface. Menu items can run shell scripts, open applications, pass parameters, capture output, and link to other menu tree files.

== Running Menu4j ==

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

Alternatively, Menu4j can be run directly from the distribution archive. It is a Java 25 desktop (Swing) application:

java -jar JMenu.jar

On first launch, if no configuration file is found, Menu4j copies a template configuration from <code>xml/config/init/config.xml</code> and a template menu tree from <code>xml/tree/init/tree.xml</code>.

If a startup password has been configured, you are prompted to enter it before the menu is shown. Three failed attempts close the application.

== The Menu Tree ==

The main window displays a JTree. There are two node types:

{| class="wikitable"
|-
! Type !! Purpose
|-
| Branch || A folder that contains other branches or leaves
|-
| Leaf || An executable item — a command, script, or application
|}

Double-click a leaf to execute it. Double-click a branch to expand or collapse it.

=== Adding and Editing Items ===

The right sidebar toolbar provides:

* '''Add''' — insert a new branch or leaf under the selected node
* '''Edit''' — open the editor for the selected node
* '''Delete''' — remove the selected node
* '''Duplicate''' — copy the selected node

[[File:JMenuTree1.png|600px]]

=== Leaf Properties ===

When editing a leaf node, the following properties are available:

{| class="wikitable"
|-
! Property !! Description
|-
| Description || The label shown in the menu tree
|-
| Directory || The working directory for the command
|-
| Command || The executable or system command to run
|-
| Parameters || A list of arguments to pass to the command
|-
| Shell Script Required || Whether to wrap the command in the configured shell wrapper script
|-
| Terminal Window Required || Whether to open a terminal output window to show command output
|-
| Confirm Execute || Whether to show a confirmation prompt before running
|-
| Link to Menu Tree || Whether this item opens a different tree file instead of running a command
|-
| Hint || A tooltip shown when hovering over the item
|-
| Icon || An image file to display next to the item label
|}

[[File:JMenuTree2.png|600px]]

== Executing Commands ==

When a leaf is executed:

# Menu4j validates that the directory and command exist
# If '''Shell Script Required''' is set, the command is wrapped using the script configured in Settings (typically a shell wrapper that sources the user's environment)
# If '''Terminal Window Required''' is set, a terminal output window opens and displays stdout and stderr in real time; otherwise the command runs silently in the background
# Environment variables configured in Settings are injected before execution

=== Terminal Output Window ===

The terminal window displays command output with configurable foreground and background colours and font (configured in Settings). A '''Respond''' button allows text to be sent to the command's standard input for interactive commands. When the command completes, the return code is displayed.

== Multiple Tree Files ==

A leaf node can be configured to switch to a different menu tree rather than execute a command. Set '''Link to Menu Tree''' and specify the filename. Double-clicking the leaf saves the current tree's expansion state and loads the linked tree. The application title bar updates to show the active tree filename.

== Configuration ==

=== config.xml ===

Located at <code>xml/config/config.xml</code>. This file stores global settings including the active tree filename, shell script settings, colours, fonts, environment variables, system command whitelist, and the encrypted startup password.

=== tree.xml ===

Located at <code>xml/tree/tree.xml</code> (or a different filename if you have switched trees). This is the menu structure file. It is written automatically when you save from the application.

=== tree.xml.state ===

Located alongside the tree file. Records which branches were expanded on the last exit and restores them on next launch.

== Settings ==

Open Settings from the toolbar to configure:

{| class="wikitable"
|-
! Setting !! Description
|-
| Password || Optional startup password (stored AES-encrypted)
|-
| Shell script || Enable/disable the shell wrapper and set the script filename
|-
| Terminal colours || Foreground and background colours for the terminal output window
|-
| Tree colours || Foreground colours for leaf and branch labels
|-
| Fonts || Font choice and size for the terminal window, leaf labels, and branch labels
|-
| Environment variables || Key/value pairs injected into every executed process
|-
| System commands || Whitelist of system commands (such as <code>open</code>) that do not require a file path to be validated
|}

== Tree Navigation ==

The top toolbar provides four buttons for expanding and collapsing the tree:

* Expand All
* Expand Selected Branch
* Collapse Selected Branch
* Collapse All

== Saving ==

Changes to the tree structure are saved using the '''Save''' button in the sidebar toolbar. You are prompted to save if you close the application with unsaved changes.

See also: [[LaunchPad]], [[Downloads]]

[[Category:Commander4j]]

Menu4j

2026-06-20T15:50:56Z

Dgarratt: /* Leaf Properties */

Menu4j (JMenuTree) is a desktop command launcher that organises shell commands, scripts, and applications into a hierarchical tree menu. It provides a configurable, script-aware alternative to Finder shortcuts and shell aliases, with support for real-time terminal output, multiple linked menu trees, and optional startup password protection.

== Purpose ==

Menu4j is used to organise the day-to-day development and operational commands for the Commander4j suite in a single, structured interface. Menu items can run shell scripts, open applications, pass parameters, capture output, and link to other menu tree files.

== Running Menu4j ==

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

Alternatively, Menu4j can be run directly from the distribution archive. It is a Java 25 desktop (Swing) application:

java -jar JMenu.jar

On first launch, if no configuration file is found, Menu4j copies a template configuration from <code>xml/config/init/config.xml</code> and a template menu tree from <code>xml/tree/init/tree.xml</code>.

If a startup password has been configured, you are prompted to enter it before the menu is shown. Three failed attempts close the application.

== The Menu Tree ==

The main window displays a JTree. There are two node types:

{| class="wikitable"
|-
! Type !! Purpose
|-
| Branch || A folder that contains other branches or leaves
|-
| Leaf || An executable item — a command, script, or application
|}

Double-click a leaf to execute it. Double-click a branch to expand or collapse it.

=== Adding and Editing Items ===

The right sidebar toolbar provides:

* '''Add''' — insert a new branch or leaf under the selected node
* '''Edit''' — open the editor for the selected node
* '''Delete''' — remove the selected node
* '''Duplicate''' — copy the selected node

[[File:JMenuTree1.png|400px]]

=== Leaf Properties ===

When editing a leaf node, the following properties are available:

{| class="wikitable"
|-
! Property !! Description
|-
| Description || The label shown in the menu tree
|-
| Directory || The working directory for the command
|-
| Command || The executable or system command to run
|-
| Parameters || A list of arguments to pass to the command
|-
| Shell Script Required || Whether to wrap the command in the configured shell wrapper script
|-
| Terminal Window Required || Whether to open a terminal output window to show command output
|-
| Confirm Execute || Whether to show a confirmation prompt before running
|-
| Link to Menu Tree || Whether this item opens a different tree file instead of running a command
|-
| Hint || A tooltip shown when hovering over the item
|-
| Icon || An image file to display next to the item label
|}

[[File:JMenuTree2.png|600px]]

== Executing Commands ==

When a leaf is executed:

# Menu4j validates that the directory and command exist
# If '''Shell Script Required''' is set, the command is wrapped using the script configured in Settings (typically a shell wrapper that sources the user's environment)
# If '''Terminal Window Required''' is set, a terminal output window opens and displays stdout and stderr in real time; otherwise the command runs silently in the background
# Environment variables configured in Settings are injected before execution

=== Terminal Output Window ===

The terminal window displays command output with configurable foreground and background colours and font (configured in Settings). A '''Respond''' button allows text to be sent to the command's standard input for interactive commands. When the command completes, the return code is displayed.

== Multiple Tree Files ==

A leaf node can be configured to switch to a different menu tree rather than execute a command. Set '''Link to Menu Tree''' and specify the filename. Double-clicking the leaf saves the current tree's expansion state and loads the linked tree. The application title bar updates to show the active tree filename.

== Configuration ==

=== config.xml ===

Located at <code>xml/config/config.xml</code>. This file stores global settings including the active tree filename, shell script settings, colours, fonts, environment variables, system command whitelist, and the encrypted startup password.

=== tree.xml ===

Located at <code>xml/tree/tree.xml</code> (or a different filename if you have switched trees). This is the menu structure file. It is written automatically when you save from the application.

=== tree.xml.state ===

Located alongside the tree file. Records which branches were expanded on the last exit and restores them on next launch.

== Settings ==

Open Settings from the toolbar to configure:

{| class="wikitable"
|-
! Setting !! Description
|-
| Password || Optional startup password (stored AES-encrypted)
|-
| Shell script || Enable/disable the shell wrapper and set the script filename
|-
| Terminal colours || Foreground and background colours for the terminal output window
|-
| Tree colours || Foreground colours for leaf and branch labels
|-
| Fonts || Font choice and size for the terminal window, leaf labels, and branch labels
|-
| Environment variables || Key/value pairs injected into every executed process
|-
| System commands || Whitelist of system commands (such as <code>open</code>) that do not require a file path to be validated
|}

== Tree Navigation ==

The top toolbar provides four buttons for expanding and collapsing the tree:

* Expand All
* Expand Selected Branch
* Collapse Selected Branch
* Collapse All

== Saving ==

Changes to the tree structure are saved using the '''Save''' button in the sidebar toolbar. You are prompted to save if you close the application with unsaved changes.

See also: [[LaunchPad]], [[Downloads]]

[[Category:Commander4j]]

File:JMenuTree2.png

2026-06-20T15:50:36Z

Dgarratt:

Menu4j

2026-06-20T15:50:10Z

Dgarratt: /* Leaf Properties */

Menu4j (JMenuTree) is a desktop command launcher that organises shell commands, scripts, and applications into a hierarchical tree menu. It provides a configurable, script-aware alternative to Finder shortcuts and shell aliases, with support for real-time terminal output, multiple linked menu trees, and optional startup password protection.

== Purpose ==

Menu4j is used to organise the day-to-day development and operational commands for the Commander4j suite in a single, structured interface. Menu items can run shell scripts, open applications, pass parameters, capture output, and link to other menu tree files.

== Running Menu4j ==

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

Alternatively, Menu4j can be run directly from the distribution archive. It is a Java 25 desktop (Swing) application:

java -jar JMenu.jar

On first launch, if no configuration file is found, Menu4j copies a template configuration from <code>xml/config/init/config.xml</code> and a template menu tree from <code>xml/tree/init/tree.xml</code>.

If a startup password has been configured, you are prompted to enter it before the menu is shown. Three failed attempts close the application.

== The Menu Tree ==

The main window displays a JTree. There are two node types:

{| class="wikitable"
|-
! Type !! Purpose
|-
| Branch || A folder that contains other branches or leaves
|-
| Leaf || An executable item — a command, script, or application
|}

Double-click a leaf to execute it. Double-click a branch to expand or collapse it.

=== Adding and Editing Items ===

The right sidebar toolbar provides:

* '''Add''' — insert a new branch or leaf under the selected node
* '''Edit''' — open the editor for the selected node
* '''Delete''' — remove the selected node
* '''Duplicate''' — copy the selected node

[[File:JMenuTree1.png|400px]]

=== Leaf Properties ===

When editing a leaf node, the following properties are available:

{| class="wikitable"
|-
! Property !! Description
|-
| Description || The label shown in the menu tree
|-
| Directory || The working directory for the command
|-
| Command || The executable or system command to run
|-
| Parameters || A list of arguments to pass to the command
|-
| Shell Script Required || Whether to wrap the command in the configured shell wrapper script
|-
| Terminal Window Required || Whether to open a terminal output window to show command output
|-
| Confirm Execute || Whether to show a confirmation prompt before running
|-
| Link to Menu Tree || Whether this item opens a different tree file instead of running a command
|-
| Hint || A tooltip shown when hovering over the item
|-
| Icon || An image file to display next to the item label
|}

[[File:JMenuTree2.png|400px]]

== Executing Commands ==

When a leaf is executed:

# Menu4j validates that the directory and command exist
# If '''Shell Script Required''' is set, the command is wrapped using the script configured in Settings (typically a shell wrapper that sources the user's environment)
# If '''Terminal Window Required''' is set, a terminal output window opens and displays stdout and stderr in real time; otherwise the command runs silently in the background
# Environment variables configured in Settings are injected before execution

=== Terminal Output Window ===

The terminal window displays command output with configurable foreground and background colours and font (configured in Settings). A '''Respond''' button allows text to be sent to the command's standard input for interactive commands. When the command completes, the return code is displayed.

== Multiple Tree Files ==

A leaf node can be configured to switch to a different menu tree rather than execute a command. Set '''Link to Menu Tree''' and specify the filename. Double-clicking the leaf saves the current tree's expansion state and loads the linked tree. The application title bar updates to show the active tree filename.

== Configuration ==

=== config.xml ===

Located at <code>xml/config/config.xml</code>. This file stores global settings including the active tree filename, shell script settings, colours, fonts, environment variables, system command whitelist, and the encrypted startup password.

=== tree.xml ===

Located at <code>xml/tree/tree.xml</code> (or a different filename if you have switched trees). This is the menu structure file. It is written automatically when you save from the application.

=== tree.xml.state ===

Located alongside the tree file. Records which branches were expanded on the last exit and restores them on next launch.

== Settings ==

Open Settings from the toolbar to configure:

{| class="wikitable"
|-
! Setting !! Description
|-
| Password || Optional startup password (stored AES-encrypted)
|-
| Shell script || Enable/disable the shell wrapper and set the script filename
|-
| Terminal colours || Foreground and background colours for the terminal output window
|-
| Tree colours || Foreground colours for leaf and branch labels
|-
| Fonts || Font choice and size for the terminal window, leaf labels, and branch labels
|-
| Environment variables || Key/value pairs injected into every executed process
|-
| System commands || Whitelist of system commands (such as <code>open</code>) that do not require a file path to be validated
|}

== Tree Navigation ==

The top toolbar provides four buttons for expanding and collapsing the tree:

* Expand All
* Expand Selected Branch
* Collapse Selected Branch
* Collapse All

== Saving ==

Changes to the tree structure are saved using the '''Save''' button in the sidebar toolbar. You are prompted to save if you close the application with unsaved changes.

See also: [[LaunchPad]], [[Downloads]]

[[Category:Commander4j]]

Menu4j

2026-06-20T15:49:10Z

Dgarratt: /* Adding and Editing Items */

Menu4j (JMenuTree) is a desktop command launcher that organises shell commands, scripts, and applications into a hierarchical tree menu. It provides a configurable, script-aware alternative to Finder shortcuts and shell aliases, with support for real-time terminal output, multiple linked menu trees, and optional startup password protection.

== Purpose ==

Menu4j is used to organise the day-to-day development and operational commands for the Commander4j suite in a single, structured interface. Menu items can run shell scripts, open applications, pass parameters, capture output, and link to other menu tree files.

== Running Menu4j ==

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

Alternatively, Menu4j can be run directly from the distribution archive. It is a Java 25 desktop (Swing) application:

java -jar JMenu.jar

On first launch, if no configuration file is found, Menu4j copies a template configuration from <code>xml/config/init/config.xml</code> and a template menu tree from <code>xml/tree/init/tree.xml</code>.

If a startup password has been configured, you are prompted to enter it before the menu is shown. Three failed attempts close the application.

== The Menu Tree ==

The main window displays a JTree. There are two node types:

{| class="wikitable"
|-
! Type !! Purpose
|-
| Branch || A folder that contains other branches or leaves
|-
| Leaf || An executable item — a command, script, or application
|}

Double-click a leaf to execute it. Double-click a branch to expand or collapse it.

=== Adding and Editing Items ===

The right sidebar toolbar provides:

* '''Add''' — insert a new branch or leaf under the selected node
* '''Edit''' — open the editor for the selected node
* '''Delete''' — remove the selected node
* '''Duplicate''' — copy the selected node

[[File:JMenuTree1.png|400px]]

=== Leaf Properties ===

When editing a leaf node, the following properties are available:

{| class="wikitable"
|-
! Property !! Description
|-
| Description || The label shown in the menu tree
|-
| Directory || The working directory for the command
|-
| Command || The executable or system command to run
|-
| Parameters || A list of arguments to pass to the command
|-
| Shell Script Required || Whether to wrap the command in the configured shell wrapper script
|-
| Terminal Window Required || Whether to open a terminal output window to show command output
|-
| Confirm Execute || Whether to show a confirmation prompt before running
|-
| Link to Menu Tree || Whether this item opens a different tree file instead of running a command
|-
| Hint || A tooltip shown when hovering over the item
|-
| Icon || An image file to display next to the item label
|}

== Executing Commands ==

When a leaf is executed:

# Menu4j validates that the directory and command exist
# If '''Shell Script Required''' is set, the command is wrapped using the script configured in Settings (typically a shell wrapper that sources the user's environment)
# If '''Terminal Window Required''' is set, a terminal output window opens and displays stdout and stderr in real time; otherwise the command runs silently in the background
# Environment variables configured in Settings are injected before execution

=== Terminal Output Window ===

The terminal window displays command output with configurable foreground and background colours and font (configured in Settings). A '''Respond''' button allows text to be sent to the command's standard input for interactive commands. When the command completes, the return code is displayed.

== Multiple Tree Files ==

A leaf node can be configured to switch to a different menu tree rather than execute a command. Set '''Link to Menu Tree''' and specify the filename. Double-clicking the leaf saves the current tree's expansion state and loads the linked tree. The application title bar updates to show the active tree filename.

== Configuration ==

=== config.xml ===

Located at <code>xml/config/config.xml</code>. This file stores global settings including the active tree filename, shell script settings, colours, fonts, environment variables, system command whitelist, and the encrypted startup password.

=== tree.xml ===

Located at <code>xml/tree/tree.xml</code> (or a different filename if you have switched trees). This is the menu structure file. It is written automatically when you save from the application.

=== tree.xml.state ===

Located alongside the tree file. Records which branches were expanded on the last exit and restores them on next launch.

== Settings ==

Open Settings from the toolbar to configure:

{| class="wikitable"
|-
! Setting !! Description
|-
| Password || Optional startup password (stored AES-encrypted)
|-
| Shell script || Enable/disable the shell wrapper and set the script filename
|-
| Terminal colours || Foreground and background colours for the terminal output window
|-
| Tree colours || Foreground colours for leaf and branch labels
|-
| Fonts || Font choice and size for the terminal window, leaf labels, and branch labels
|-
| Environment variables || Key/value pairs injected into every executed process
|-
| System commands || Whitelist of system commands (such as <code>open</code>) that do not require a file path to be validated
|}

== Tree Navigation ==

The top toolbar provides four buttons for expanding and collapsing the tree:

* Expand All
* Expand Selected Branch
* Collapse Selected Branch
* Collapse All

== Saving ==

Changes to the tree structure are saved using the '''Save''' button in the sidebar toolbar. You are prompted to save if you close the application with unsaved changes.

See also: [[LaunchPad]], [[Downloads]]

[[Category:Commander4j]]

2026-06-13T12:36:10Z

Dgarratt:

2026-06-10T16:48:56Z

Dgarratt:

XML Viewer is a desktop application for exploring XML documents as an interactive, expandable tree. It supports configurable display modes, multi-language element name translation, and adjustable tree expansion depth. It is designed for viewing structured XML files such as SAP IDoc messages, Commander4j configuration files, and production schedule exports.

== Purpose ==

XML Viewer makes it practical to inspect complex XML files that are difficult to read as raw text. Element names can be translated into plain-language descriptions (for example, the SAP field code <code>ABWKZ</code> becomes "Deviation indicator" in the English translation), and the tree can be expanded to a specific depth to give a high-level overview without showing every leaf value.

== Running XML Viewer ==

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

Alternatively, XML Viewer can be run directly from the distribution archive. It is a Java 25 desktop (Swing) application:

java -jar xmlviewer.jar [optional path to XML file]

If a file path is provided on the command line, that file is opened immediately on launch. Otherwise, the last-opened file from the configuration is loaded.

== Loading a Document ==

Click the '''Open XML Document''' button in the right sidebar, or pass a file path on the command line. Only well-formed XML files are supported. Click '''Reload XML Document''' to re-read the current file after it has been changed externally.

== Display Modes ==

=== Standard Mode ===

The XML hierarchy is displayed exactly as it appears in the file — elements nest within their parent elements, forming a tree that mirrors the XML structure.

=== Flat Mode ===

Leaf elements (those containing only text, no child elements) are collapsed into their parent's row rather than appearing as separate tree nodes. Only elements that contain child elements appear as tree nodes. This produces a more compact view of documents with many small leaf values.

Toggle between modes using the '''View Mode''' button in the right sidebar.

== Tree Expansion Control ==

The top toolbar provides four buttons:

* '''Expand All''' — expand every node in the tree
* '''Expand Selected''' — expand only the selected subtree
* '''Collapse Selected''' — collapse the selected subtree
* '''Collapse All''' — collapse everything to root level

The '''−''' and '''+''' buttons in the toolbar adjust the current expansion level (shown as a number between the buttons). Clicking '''Refresh''' after changing the level re-expands the tree to that depth.

The expansion level is saved in the configuration and restored on next launch.

== Translation ==

XML Viewer can replace technical XML element names and values with plain-language descriptions from a translation file.

=== Enabling Translation ===

Toggle translations using the '''View Translations''' button. The '''Translation''' dropdown at the bottom of the window selects which translation file to use. The '''Language''' dropdown selects the language within that file.

=== Built-in Translation Files ===

{| class="wikitable"
|-
! File !! Contents
|-
| matmas05.xml || SAP MATMAS05 IDoc field translations
|-
| zmatmas03.xml || SAP ZMATMAS03 IDoc field translations
|-
| productionschedule.xml || Production schedule export field translations
|-
| config.xml || Commander4j configuration element translations
|-
| default.xml || Generic fallback translations
|}

=== Languages ===

The default installation includes English, French, German, and Italian. The active language can be changed at any time from the Language dropdown.

=== Adding Translations ===

Translation files are XML documents located in <code>xml/translations/</code>. Each file maps element names, attribute names, element values, and attribute values to their translated equivalents for each language. Elements without a translation entry are shown using their original name from the XML file.

== Other Display Options ==

{| class="wikitable"
|-
! Button !! Effect
|-
| View Icons || Show or hide the icon column next to each tree node
|-
| View Brackets || Wrap element values in <code>[ ]</code> brackets to distinguish them from element names
|}

== Configuration ==

=== config.xml ===

Located at <code>xml/config/config.xml</code>. Stores the last-opened file path, selected translation file, selected language, current expansion level, and the state of all four display toggles (mode, translations, brackets, icons). Updated automatically on exit.

=== log4j2.xml ===

Located at <code>xml/log/log4j2.xml</code>. Controls logging to <code>logs/XML_View.log</code>. Log files rotate at 10 MB and are retained for 14 days.

=== fonts.xml / icons ===

Icons are loaded from <code>images/xmlIcons/</code>. If an icon file referenced by a translation is not found, the icon column is left blank for that element without an error.

See also: [[TreeDoc]], [[Middleware4j]], [[Label Template Syntax]]

[[Category:Commander4j]]