Commander4j - User contributions [en-gb]

Pallet Issue

2026-08-20T15:36:29Z

Dgarratt:

[[file:Pallet_Issue.png|link=|800px]]

Use this screen to issue either a part or full pallet to a Process Order. The transaction is written to Pallet History and can optionally create an xml interface message.

The issue transaction will reference a number of tables within the application. It will check that the Material being issued is in the requirements for the Bill of Materials for the Process Order. It will check that the issue location (where the material is being sent) is correct. It will also check that the Pallet has an acceptable status and batch status for the location being issued to.

[[file:Issue_Relationships.png|link=|900px]]

Pallet Issue

2026-08-20T15:33:57Z

Dgarratt:

File:Issue Relationships.png

2026-08-20T15:33:28Z

Dgarratt:

Pallet Issue

2026-08-20T15:33:12Z

Dgarratt:

Pallet Issue

2026-08-20T15:10:26Z

Dgarratt:

Pallet Return

2026-08-20T15:06:20Z

Dgarratt:

[[file:Pallet_Return.png|link=|600px]]

Pallet Issue

2026-08-20T15:04:38Z

Dgarratt:

[[file:Pallet_Issue.png|link=|800px]]

File:Pallet Issue.png

2026-08-20T15:01:27Z

Dgarratt:

File:Pallet Return.png

2026-08-20T15:00:20Z

Dgarratt:

Pallet Return

2026-08-20T15:00:06Z

Dgarratt: Created page with " 500px"

[[file:Pallet_Return.png|link=|500px]]

Pallet Issue

2026-08-20T14:59:07Z

Dgarratt: Created page with " 500px"

[[file:Pallet_Issue.png|link=|500px]]

Template:Commander4j

2026-08-20T14:12:37Z

Dgarratt: /* Pallet Transactions */

=Getting Started=
*[[Introduction]]
*[[Overview]]
*[[Requirements]]
*[[Downloads]]
*[[Installation|Install]]
*[[Upgrading|Upgrade]]
*[[Setup4j|Database Configuration]]
*[[Default Username & Password]]
*[[Starting]]
*[[Logon]]
*[[Navigation]]
*[[Example Screens]]

[[Category:Commander4j]]

=User Guide=
[[Category:Commander4j]]
===Pallet Transactions===
*[[Pallet Label]]
*[[Production Declaration]]
*[[Production Confirmation]]
*[[Pallet Admin]]
*[[Pallet History]]
*[[Pallet Issue]]
*[[Pallet Return]]
*[[Split Pallet]]
*[[Assign Process Order to Auto Labeller]]
*[[Production Lines & Labellers]]
*[[Despatch]]
**[[Equipment Admin]]
**[[Journeys]]
*[[Material Batches|Batches]]
*[[Bill of Materials]]
**[[Enquiries]]
**[[View / Edit]]
**Configuration
***[[Structure]]
***[[Elements]]
***[[Defaults]]
***[[Lists]]

[[Category:Commander4j]]

===Case / Tray Labels===
*[[Case Label|Case & Tray Labels]]
**[[Production Lines & Labellers]]

[[Category:Commander4j]]

===Quality Control Transactions===
*[[Quality Control Sample|Sample Labels]]
**[[Inspections]]
***[[Selection Lists]]
***[[Dictionary]]
**[[Update Samples]]
**[[Results Analysis and Reporting]]
**[[Database Schema used by Panel Samples]]
*Pallet Sorting
**[[Pallet Samples & Faults|Samples & Faults]]
**[[Pallet Samples Enquiries & Reports|Enquiries & Reports]]
***[[Pallet Sample Reasons|Reasons]]
***[[Pallet Sample Defect Types|Defect Types]]
***[[Pallet Sample Defect IDs|Defect IDs]]
***[[Sample Point Admin|Sample Points]]
***[[Pallet Sample Shift Names|Shift Names]]
***[[Pallet Sample Packing Lines|Packing Lines]]
***[[Pallet Sample Supplier Admin|Suppliers]]
***[[Pallet Sample Operatives|Operatives]]
*[[Isolate]]
**[[Quality Control Decisions]]
**[[Quality Control Reasons]]

[[Category:Commander4j]]

===Waste Recording===

*[[Waste Recording | Overview]]
*[[Waste Log]]
**[[Waste Transactions]]
**[[Waste Containers]]
**[[Waste Locations]]
**[[Waste Materials]]
**[[Waste Types]]
**[[Waste Reasons]]
*[[Waste Reporting]]
**[[Waste Reports Examples]]
**[[Waste Reporting IDs]]
**[[Waste Reporting Groups]]
**[[Link Location to Reporting ID]]
**[[Link Reporting ID to Location]]

===Weight Checks===
*[[Weight Checks Data Capture]]
*[[Weight Check Reports]]
**[[Sample Point Admin]]
**[[Scale Admin]]
**[[Workstation Admin]]
**[[Tolerable Negative Errors]]
**[[Product Groups]]
**[[Container Codes]]

[[Category:Commander4j]]
===Customers===
*[[Customers|Customer Admin]]
*[[Customer Data]]

[[Category:Commander4j]]
[[Category:Commander4j]]
===Process Orders===
*[[Process Orders]]
**[[Process Order Barcode]]
**[[Required Resources]]

[[Category:Commander4j]]
===Materials===
*[[Materials|Material Admin]]
**[[Units of Measure]]
**[[Material Locations]]
**[[Material Types]]
**[[Material UOMs]]
**[[Material Data IDs]]
**[[Customer Data|Customer Specific Data]]

[[Category:Commander4j]]

===Locations===
*[[Locations]]

===Interfaces===
*[[Interface Admin]]
*[[Interface Log]]
*[[Request Queue]]
*[[Process Messages]]
*[[Interface Example Data Flow 1]]
*[[Interface Example Data Flow 2]]
*[[Interface Message Formats]]

===Security===
*[[Users]]
*[[Groups]]
**[[Permissions]]
*[[Audit Reports]]

{{Commander4j Configuration}}

File:Bom structure.png

2026-08-20T14:08:51Z

Dgarratt:

Bill of Materials

2026-08-20T14:08:30Z

Dgarratt: /* Viewing a BOM */

The Bill of Materials (BOM) module allows you to define and manage product recipes — the ingredients or components required to manufacture a finished product. BOMs can be entered manually or imported from an external system via the XML interface.

== Structure ==

A BOM in Commander4j is hierarchical. Each BOM has a unique '''BOM ID''' and a '''version number''', allowing multiple versions of the same recipe to coexist. The BOM is displayed as a tree, with the finished product at the root and its components, sub-components, and associated data as branches beneath it.

Each node in the tree has the following properties:

{| class="wikitable"
|-
! Field !! Description
|-
| '''Data ID''' || The identifier of this element (e.g. a material or ingredient code)
|-
| '''Data Type''' || The classification of this element (e.g. ingredient, component, instruction)
|-
| '''Data String''' || A text value associated with this element
|-
| '''Data Decimal''' || A numeric value such as a quantity or percentage
|-
| '''Data Date''' || A date value if applicable
|-
| '''Stage''' || The production stage at which this element is used, allowing filtering of the BOM by stage
|-
| '''Sequence''' || The order of this element within its parent level
|}

Each node has a unique UUID that maintains its position in the tree hierarchy.

== Viewing a BOM ==

Enter the BOM ID (and optionally a version) to load the structure into the tree view. The tree can be expanded and collapsed at any level using the toolbar buttons. Individual nodes can be selected to view their full properties. The Stage filter allows the tree to be restricted to elements relevant to a particular production stage.

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

== Versions ==

Multiple versions of a BOM can exist for the same BOM ID. This allows recipe changes to be tracked over time whilst retaining historical versions for reference or reactivation.

== Importing BOMs ==

BOMs can be imported from XML files via the [[Interface Message Formats|XML interface]]. The import process validates the structure and auto-generates UUIDs for all nodes. This is the recommended method when the BOM originates in an ERP or recipe management system.

Manual entry is also supported for sites that do not have an external recipe system.

== Relationship to Material Issue ==

The [[Web_Applications_Overview|c4j_web_Issue]] application uses BOM data to validate that operators are issuing the correct raw materials to a production line — checking the scanned material SSCC against the BOM for the active process order.

== Database Table ==

BOM records are stored in <code>APP_BOM</code>, with a composite primary key of BOM ID, version, and node UUID.

See also: [[Materials]], [[Process Orders]], [[Interface Message Formats]]

[[Category:Commander4j]]

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

File:JMenuTree1.png

2026-06-20T15:48:44Z

Dgarratt:

Menu4j

2026-06-20T15:48:29Z

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

LogoClient

2026-06-13T19:43:05Z

Dgarratt: Updated by push_wiki.py

'''LogoClient''' (''c4j_logoclient'') is a standalone desktop application — and underlying client library — for communicating with [[Logopak]] PowerLeap label printers over the network. It connects to a labeller, transfers layout and data files to and from it, sends commands and field data, browses the printer's on-board storage and retrieves its logs. It exists so that the software-to-labeller conversation can be developed, exercised and diagnosed '''on an ordinary PC, in environments where no physical Logopak labeller is available''' to test against.

It is the client half of a pair: where a real labeller is not to hand, [[LogoRenderer]] can emulate one, and LogoClient talks to that emulator exactly as it would talk to real hardware. Together they let you exercise the whole label-printing workflow with no hardware at all.

''Disclaimer: LogoClient is an independent open-source tool and is '''not''' a Logopak product. It is not affiliated with, endorsed by, or supported by Logopak. Logopak, PowerLeap and related names are trademarks of their respective owners and are used solely to describe interoperability. The software is intended for local test and development use only — it must not be relied upon for production label printing.''

== Purpose ==

Software from Logopak DE drives labellers in production. When developing or supporting that software it is useful to be able to perform the same low-level operations by hand, and to see exactly what goes across the wire. LogoClient is that tool. It is useful when:

* You need to '''send a layout or data file to a labeller''' and confirm it loads correctly.
* You want to '''browse, upload, download or delete files''' on the printer's on-board drives.
* You are '''debugging the protocol''' and want a live, byte-level trace of everything sent and received.
* You need to '''send raw commands or field data''' to a labeller and read its replies.
* You want to '''poll a labeller's pallet log''' and capture one file per SSCC as labels are applied.
* You want to '''develop without a physical Logopak''' by pointing LogoClient at the [[LogoRenderer]] printer emulator instead of real hardware.

== Supported Printers and Protocols ==

LogoClient supports both current Logopak controller generations:

{| class="wikitable"
|-
! Mode !! Hardware !! Transport
|-
| '''PL3 (TCP)''' || PowerLeap III || Direct TCP socket on the data ports (8000 / 8100 / 8200 / 8300). Carries the full LEAP, LAMA/LACE and LSP command set — layout activation, field data, firmware queries, file management, I/O monitoring and asynchronous reporting.
|-
| '''PL6 (SFTP)''' || PowerLeap 6 || File transfer over SFTP (port 22). PL6 is driven by exchanging files rather than TCP commands, so this mode is focused on uploading, downloading and listing files and reading the pallet log.
|}

== Source Code and Releases ==

LogoClient is part of the open-source Commander4j suite and is distributed under the GNU General Public License. The source code and release downloads are hosted on GitHub, and native install packages for every platform are listed on the Commander4j [[Downloads]] page.

* '''Repository:''' [https://github.com/C4J/LogoClient https://github.com/C4J/LogoClient]
* '''Releases (download media):''' [https://github.com/C4J/LogoClient/releases https://github.com/C4J/LogoClient/releases]
* '''All Commander4j downloads:''' [[Downloads]]

== Installation ==

Native install packages for '''Windows, macOS and Linux''' are available from the [[Downloads]] page and are the preferred installation method. Each installer bundles its own Java runtime, so '''no separate Java installation is required'''. Installing creates a native '''LogoClient''' launcher that can be started like any other desktop application.

=== Running from the jar ===

Alternatively the tool can be run directly as an ordinary Java (Swing) application:

java -jar c4j_logoclient.jar

Running the jar requires a recent Java runtime (Java 21 or later). The bundled JSch library is required only for PL6 (SFTP); PL3 (TCP) has no external dependencies.

== The Main Window ==

The window has a '''connection bar''' across the top, a central '''file-transfer and directory area''', a '''message pane''' for composing raw commands, and a pair of log panes along the bottom — an '''activity log''' and a '''wire trace'''. All transfer and command actions are disabled until a connection is open.

=== Connecting ===

In the connection bar you choose the connection '''Type''' (PL3 TCP or PL6 SFTP), enter the labeller's '''host / IP address''' and '''port''', and — for PL6 — a '''username and password'''. Pressing the connect button opens the link; a status indicator shows the connected host and port. For example, the [[LogoRenderer]] emulator running on the same PC is reached at <code>127.0.0.1</code>.

Options in the connection area let you list the remote directory automatically on connect, send a periodic '''heartbeat''' to detect a dropped link, and set the socket read timeout.

=== Transferring and Managing Files ===

The central area lists the files on the printer for a chosen remote path and file mask, showing each file's name, size, modified time and type. From here you can:

* '''Upload''' a local file to the printer.
* '''Download''' one or more selected files to a chosen local folder.
* '''Delete''' selected files from the printer (with confirmation).
* '''Refresh''' the listing, and on PL6 navigate into sub-folders.

PL3 exposes the printer's storage areas (<code>/c0/</code>, <code>/c9/</code>, <code>/f0/</code>, <code>/r0/</code>) with file masks such as <code>*.llf</code> or <code>*.pcx</code>; PL6 exposes its SFTP folders.

=== Sending Commands and Field Data ===

In PL3 mode the message pane composes and transmits raw text to the labeller. Control characters can be entered as readable tokens such as <code><STX></code>, <code><ETX></code> and <code><CR></code>, and the end-of-line terminator appended on send is selectable. This is how layouts are activated, field data is sent, and LAMA/LSP queries are issued by hand. Replies appear in the activity log and the raw bytes in the wire trace.

=== Pallet Log Polling ===

LogoClient can poll the labeller's pallet log at a chosen interval and write the results to disk — one timestamped file per unique SSCC — into a chosen log folder. This reproduces, by hand, the "what was printed" feedback that production software collects, and works against both PL3 and PL6.

=== Activity Log and Wire Trace ===

Two panes record what happens. The '''activity log''' is a readable, timestamped narrative of connects, transfers, commands and errors. The '''wire trace''' shows the raw bytes in both directions — transmitted and received — with control characters rendered as tokens, which is invaluable when diagnosing exactly what a labeller sent or expected. Both panes can be saved to a text file or cleared.

== Configuration ==

The connection details and interface preferences are saved when you quit and restored on the next start, so the tool reopens ready to reconnect to the labeller you last used.

== Using LogoClient and LogoRenderer Together ==

The two tools form a complete bench setup for label development with no Logopak hardware:

# In '''[[LogoRenderer]]''', start the '''printer emulator''' on a port (default 8000).
# In '''LogoClient''', choose '''PL3 (TCP)''', set the host to <code>127.0.0.1</code> and the matching port, and connect.
# '''Upload a layout''', '''send field data''', '''browse the emulated drives''' or '''poll the pallet log''' — and watch LogoRenderer render the result and log the traffic.

In this arrangement LogoClient stands in for the driving software so you can develop and test against the renderer, while LogoRenderer stands in for the printer so you have something to talk to.

== See Also ==

* [[LogoRenderer]] — the companion tool that renders labels and emulates a Logopak printer
* [[Middleware4j]], [[LabelServer4j]], [[AutoLab4j]] — other Commander4j components in the labelling workflow
* [[SocketTest]] — a raw TCP/IP testing utility

[[Category:Commander4j]]

LogoRenderer

2026-06-13T19:43:03Z

Dgarratt: Updated by push_wiki.py

'''LogoRenderer''' (''c4j_logorenderer'') is a standalone desktop application that renders [[Logopak]] PowerLeap label layout files to a visual on-screen preview '''and''' can stand in for a physical label printer by emulating its TCP communication protocol. It exists so that label layouts and the software that drives them can be developed and tested '''on an ordinary PC, in environments where no physical Logopak labeller is available''' to test against.

It is the rendering and printer-emulation half of a pair: [[LogoClient]] is the client that sends layouts and data to a printer, and LogoRenderer can play the part of that printer. Together they let you exercise the whole label-printing workflow with no hardware at all.

''Disclaimer: LogoRenderer is an independent open-source tool and is '''not''' a Logopak product. It is not affiliated with, endorsed by, or supported by Logopak. Logopak, PowerLeap and related names are trademarks of their respective owners and are used solely to describe interoperability. The software is intended for local test and development use only — it must not be relied upon for production label printing.''

== Purpose ==

A Logopak PowerLeap labeller normally lives on the factory floor and is driven over the network by software provided by Logopak DE. When developing or supporting that software — or designing the label layouts themselves — it is often impractical to have a real labeller on the bench. LogoRenderer removes that dependency. It is useful when:

* You need to '''see what a label layout will look like''' without printing it, by opening a <code>.llf</code>, <code>.lqf</code> or <code>.ldf</code> file and viewing a faithful preview.
* You are '''writing or debugging software that talks to a labeller''' and need something on the network that answers the same protocol — without owning the hardware.
* You want to '''develop without a physical Logopak''' altogether: render layouts, emulate the printer, and feed it from [[LogoClient]] or your own client code.
* You need to '''check field data and operator prompts''' (LQF query fields) by typing values and watching the rendered label update.
* You are '''tuning fonts''' so the on-screen rendering matches a real printed label.

== Label and Data File Types ==

LogoRenderer understands the PowerLeap LEAP layout family:

{| class="wikitable"
|-
! Extension !! Description
|-
| <code>.llf</code> || Layout File — a complete label layout with all field data embedded. Opening one renders the label immediately.
|-
| <code>.lqf</code> || Query Layout File — a base layout containing <code>QUE</code> operator prompts for fields that are filled in at print time. Opening one also populates the '''QUE Input''' tab so values can be typed in.
|-
| <code>.ldf</code> || Data File — a data-only file that references a master layout. Opening one runs its <code>LOAD</code> and <code>FD</code> commands to load the referenced layout and populate its fields.
|}

Layouts may reference <code>.pcx</code> and <code>.bmp</code> images (logotypes) and a range of barcode types. A reference list of the wider Logopak file-type ecosystem is maintained alongside the project.

== Source Code and Releases ==

LogoRenderer is part of the open-source Commander4j suite and is distributed under the GNU General Public License. The source code and release downloads are hosted on GitHub, and native install packages for every platform are listed on the Commander4j [[Downloads]] page.

* '''Repository:''' [https://github.com/C4J/LogoRenderer https://github.com/C4J/LogoRenderer]
* '''Releases (download media):''' [https://github.com/C4J/LogoRenderer/releases https://github.com/C4J/LogoRenderer/releases]
* '''All Commander4j downloads:''' [[Downloads]]

== Installation ==

Native install packages for '''Windows, macOS and Linux''' are available from the [[Downloads]] page and are the preferred installation method. Each installer bundles its own Java runtime, so '''no separate Java installation is required'''. Installing creates a native '''LogoRenderer''' launcher that can be started like any other desktop application.

=== Running from the jar ===

Alternatively the tool can be run directly as an ordinary Java (Swing) application. It is built with Maven:

mvn package
java -jar c4j_logorenderer.jar [file.llf]

Running the jar requires a recent Java runtime (Java 25 or later). If a layout file is supplied on the command line it is opened on start-up; otherwise the application starts with an empty canvas. Demo layouts and data files are provided in the <code>virtual_disk/c0/</code> folder.

== The Main Window ==

The window is divided into a '''label preview canvas''' on the left and a '''tabbed working area''' on the right, with a menu bar and toolbars around them and a status bar along the bottom. The title bar shows the program name, version and the name of the open file.

The status bar reports the current file, the layout dimensions in printer dots and millimetres, the zoom level, and the number of fields in the layout.

=== Preview Canvas ===

The canvas shows the rendered label exactly as the layout describes it — text, scalable text, barcodes, graphic lines and boxes, and embedded logotype images. The rendering engine replicates the coordinate system and geometry of a PowerLeap III print head, including the upside-down (180°) print orientation. Clicking a rendered element highlights the source lines that produce it.

=== Source / QUE Input / Log Tabs ===

{| class="wikitable"
|-
! Tab !! Purpose
|-
| '''Source''' || Lists the raw layout commands, one per line, each with a checkbox and a plain-language description. Un-checking a line excludes it from the render, so individual elements can be toggled on and off. Selecting a line shows its properties for editing.
|-
| '''QUE Input''' || For LQF layouts, presents one input box per operator prompt. Type values and apply them to see the populated label. This mirrors what an operator would be asked for at the machine.
|-
| '''Log''' || A colour-coded activity log showing file loads, parser messages, and all traffic to and from the printer emulator.
|}

=== Viewing Controls ===

The '''File''' menu opens and reloads layout files and exports the rendered label as a PNG image. The '''View''' menu provides zoom (preset levels, zoom in/out, and fit-to-window) and a '''Rotate 180°''' toggle that flips the preview to match the printer's print orientation.

== Font Mapping ==

Because Logopak fonts are not present on a development PC, LogoRenderer maps each Logopak font name to a Java font for rendering. The '''Settings → Font Mappings''' dialog lists every mapping and lets you set the Java font family (or a bundled TrueType file), style, reference cell size and calibration factors so that the on-screen text closely matches a real printed label. The mappings are stored in <code>xml/config/fonts.xml</code>; fonts found in a layout but not yet mapped are added automatically with sensible defaults, ready to be fine-tuned.

== The Printer Emulator ==

This is the feature that makes hardware-free development possible. LogoRenderer can open a TCP server that emulates a Logopak PowerLeap III labeller, answering the same '''LEAP / LAMA''' protocol commands a real machine would.

=== Starting the emulator ===

The connection bar at the top of the window selects the '''IP address''' (default <code>127.0.0.1</code> for the local machine) and '''port''' (default '''8000''', the PowerLeap III primary data port; <code>8100</code>, <code>8200</code> and <code>8300</code> are also offered). Pressing '''Start Server''' begins listening; the Log tab shows when a client connects. Pressing the button again stops the server.

=== What it emulates ===

A connected client can do, against the emulator, the things it would do against a real labeller:

* '''Browse and transfer files''' on an emulated drive — the <code>virtual_disk/</code> folder provides the labeller's storage areas (<code>c0/</code>, <code>c9/</code>, <code>d0/</code>, <code>f0/</code>, <code>r0/</code>), so directory listings, downloads, uploads and deletes all behave realistically.
* '''Load a layout and send field data''' — when the client issues a <code>LOAD</code> command the emulator loads that layout into the preview, and as <code>FD</code> field-data commands arrive the on-screen label updates. The PC screen therefore shows what the real printer would be putting on a label.
* '''Retrieve logs''' — the emulator can serve pallet/label log files back to the client, so software that polls a labeller for "what was printed" can be tested end to end.

=== Pallet print simulation ===

When a loaded layout contains the pallet SSCC field, a '''Print Label''' control appears. Each press simulates a pallet print — two labels per pallet sharing one [https://en.wikipedia.org/wiki/Serial_Shipping_Container_Code SSCC] — increments the SSCC counter (persisted in <code>sscc.dat</code>), and queues a log entry that a client can later retrieve. This lets log-polling and pallet-tracking logic be exercised without a real production run.

== Using LogoRenderer and LogoClient Together ==

The two tools form a complete bench setup for label development with no Logopak hardware:

# In '''LogoRenderer''', start the '''printer emulator''' on a port (default 8000).
# In '''[[LogoClient]]''', connect in '''PL3 (TCP)''' mode to <code>127.0.0.1</code> on the same port.
# From LogoClient, '''upload a layout''', '''send field data''', '''browse the emulated drives''' or '''poll the pallet log''' — and watch LogoRenderer render the result and log the traffic.

In this arrangement LogoRenderer stands in for the printer so you can develop and test a client, while LogoClient stands in for the driving software so you can drive the renderer.

== See Also ==

* [[LogoClient]] — the client-side companion tool that sends layouts and data to a labeller (real or emulated)
* [[Middleware4j]], [[LabelServer4j]], [[AutoLab4j]] — other Commander4j components in the labelling workflow
* [[ZPLRenderer]] — the equivalent preview tool for Zebra ZPL labels

[[Category:Commander4j]]

LogoClient

2026-06-13T19:41:08Z

Dgarratt: Updated by push_wiki.py

'''LogoClient''' (''c4j_logoclient'') is a standalone desktop application — and underlying client library — for communicating with [[Logopak]] PowerLeap label printers over the network. It connects to a labeller, transfers layout and data files to and from it, sends commands and field data, browses the printer's on-board storage and retrieves its logs. It exists so that the software-to-labeller conversation can be developed, exercised and diagnosed '''on an ordinary PC, in environments where no physical Logopak labeller is available''' to test against.

It is the client half of a pair: where a real labeller is not to hand, [[LogoRenderer]] can emulate one, and LogoClient talks to that emulator exactly as it would talk to real hardware. Together they let you exercise the whole label-printing workflow with no hardware at all.

''Disclaimer: LogoClient is an independent open-source tool and is '''not''' a Logopak product. It is not affiliated with, endorsed by, or supported by Logopak. Logopak, PowerLeap and related names are trademarks of their respective owners and are used solely to describe interoperability. The software is intended for local test and development use only — it must not be relied upon for production label printing.''

== Purpose ==

Software from Logopak DE drives labellers in production. When developing or supporting that software it is useful to be able to perform the same low-level operations by hand, and to see exactly what goes across the wire. LogoClient is that tool. It is useful when:

* You need to '''send a layout or data file to a labeller''' and confirm it loads correctly.
* You want to '''browse, upload, download or delete files''' on the printer's on-board drives.
* You are '''debugging the protocol''' and want a live, byte-level trace of everything sent and received.
* You need to '''send raw commands or field data''' to a labeller and read its replies.
* You want to '''poll a labeller's pallet log''' and capture one file per SSCC as labels are applied.
* You want to '''develop without a physical Logopak''' by pointing LogoClient at the [[LogoRenderer]] printer emulator instead of real hardware.

== Supported Printers and Protocols ==

LogoClient supports both current Logopak controller generations:

{| class="wikitable"
|-
! Mode !! Hardware !! Transport
|-
| '''PL3 (TCP)''' || PowerLeap III || Direct TCP socket on the data ports (8000 / 8100 / 8200 / 8300). Carries the full LEAP, LAMA/LACE and LSP command set — layout activation, field data, firmware queries, file management, I/O monitoring and asynchronous reporting.
|-
| '''PL6 (SFTP)''' || PowerLeap 6 || File transfer over SFTP (port 22). PL6 is driven by exchanging files rather than TCP commands, so this mode is focused on uploading, downloading and listing files and reading the pallet log.
|}

== Source Code and Releases ==

LogoClient is part of the open-source Commander4j suite and is distributed under the GNU General Public License. The source code and release downloads are hosted on GitHub, and native install packages for every platform are listed on the Commander4j [[Downloads]] page.

* '''Repository:''' [https://github.com/C4J/LogoClient https://github.com/C4J/LogoClient]
* '''Releases (download media):''' [https://github.com/C4J/LogoClient/releases https://github.com/C4J/LogoClient/releases]
* '''All Commander4j downloads:''' [[Downloads]]

== Installation ==

Native install packages for '''Windows, macOS and Linux''' are available from the [[Downloads]] page and are the preferred installation method. Each installer bundles its own Java runtime, so '''no separate Java installation is required'''. Installing creates a native '''LogoClient''' launcher that can be started like any other desktop application.

=== Running from the jar ===

Alternatively the tool can be run directly as an ordinary Java (Swing) application:

java -jar c4j_logoclient.jar

Running the jar requires a recent Java runtime (Java 21 or later). The bundled JSch library is required only for PL6 (SFTP); PL3 (TCP) has no external dependencies.

== The Main Window ==

The window has a '''connection bar''' across the top, a central '''file-transfer and directory area''', a '''message pane''' for composing raw commands, and a pair of log panes along the bottom — an '''activity log''' and a '''wire trace'''. All transfer and command actions are disabled until a connection is open.

=== Connecting ===

In the connection bar you choose the connection '''Type''' (PL3 TCP or PL6 SFTP), enter the labeller's '''host / IP address''' and '''port''', and — for PL6 — a '''username and password'''. Pressing the connect button opens the link; a status indicator shows the connected host and port. A real labeller is typically reached at its own network address (for example <code>192.168.1.100</code>); the [[LogoRenderer]] emulator is reached at <code>127.0.0.1</code>.

Options in the connection area let you list the remote directory automatically on connect, send a periodic '''heartbeat''' to detect a dropped link, and set the socket read timeout.

=== Transferring and Managing Files ===

The central area lists the files on the printer for a chosen remote path and file mask, showing each file's name, size, modified time and type. From here you can:

* '''Upload''' a local file to the printer.
* '''Download''' one or more selected files to a chosen local folder.
* '''Delete''' selected files from the printer (with confirmation).
* '''Refresh''' the listing, and on PL6 navigate into sub-folders.

PL3 exposes the printer's storage areas (<code>/c0/</code>, <code>/c9/</code>, <code>/f0/</code>, <code>/r0/</code>) with file masks such as <code>*.llf</code> or <code>*.pcx</code>; PL6 exposes its SFTP folders.

=== Sending Commands and Field Data ===

In PL3 mode the message pane composes and transmits raw text to the labeller. Control characters can be entered as readable tokens such as <code><STX></code>, <code><ETX></code> and <code><CR></code>, and the end-of-line terminator appended on send is selectable. This is how layouts are activated, field data is sent, and LAMA/LSP queries are issued by hand. Replies appear in the activity log and the raw bytes in the wire trace.

=== Pallet Log Polling ===

LogoClient can poll the labeller's pallet log at a chosen interval and write the results to disk — one timestamped file per unique SSCC — into a chosen log folder. This reproduces, by hand, the "what was printed" feedback that production software collects, and works against both PL3 and PL6.

=== Activity Log and Wire Trace ===

Two panes record what happens. The '''activity log''' is a readable, timestamped narrative of connects, transfers, commands and errors. The '''wire trace''' shows the raw bytes in both directions — transmitted and received — with control characters rendered as tokens, which is invaluable when diagnosing exactly what a labeller sent or expected. Both panes can be saved to a text file or cleared.

== Configuration ==

The connection details and interface preferences are saved when you quit and restored on the next start, so the tool reopens ready to reconnect to the labeller you last used.

== Using LogoClient and LogoRenderer Together ==

The two tools form a complete bench setup for label development with no Logopak hardware:

# In '''[[LogoRenderer]]''', start the '''printer emulator''' on a port (default 8000).
# In '''LogoClient''', choose '''PL3 (TCP)''', set the host to <code>127.0.0.1</code> and the matching port, and connect.
# '''Upload a layout''', '''send field data''', '''browse the emulated drives''' or '''poll the pallet log''' — and watch LogoRenderer render the result and log the traffic.

In this arrangement LogoClient stands in for the driving software so you can develop and test against the renderer, while LogoRenderer stands in for the printer so you have something to talk to. LogoClient can equally be pointed at a real Logopak labeller when one is available.

== See Also ==

* [[LogoRenderer]] — the companion tool that renders labels and emulates a Logopak printer
* [[Middleware4j]], [[LabelServer4j]], [[AutoLab4j]] — other Commander4j components in the labelling workflow
* [[SocketTest]] — a raw TCP/IP testing utility

[[Category:Commander4j]]

LogoRenderer

2026-06-13T19:41:07Z

Dgarratt: Updated by push_wiki.py

'''LogoRenderer''' (''c4j_logorenderer'') is a standalone desktop application that renders [[Logopak]] PowerLeap label layout files to a visual on-screen preview '''and''' can stand in for a physical label printer by emulating its TCP communication protocol. It exists so that label layouts and the software that drives them can be developed and tested '''on an ordinary PC, in environments where no physical Logopak labeller is available''' to test against.

It is the rendering and printer-emulation half of a pair: [[LogoClient]] is the client that sends layouts and data to a printer, and LogoRenderer can play the part of that printer. Together they let you exercise the whole label-printing workflow with no hardware at all.

''Disclaimer: LogoRenderer is an independent open-source tool and is '''not''' a Logopak product. It is not affiliated with, endorsed by, or supported by Logopak. Logopak, PowerLeap and related names are trademarks of their respective owners and are used solely to describe interoperability. The software is intended for local test and development use only — it must not be relied upon for production label printing.''

== Purpose ==

A Logopak PowerLeap labeller normally lives on the factory floor and is driven over the network by software provided by Logopak DE. When developing or supporting that software — or designing the label layouts themselves — it is often impractical to have a real labeller on the bench. LogoRenderer removes that dependency. It is useful when:

* You need to '''see what a label layout will look like''' without printing it, by opening a <code>.llf</code>, <code>.lqf</code> or <code>.ldf</code> file and viewing a faithful preview.
* You are '''writing or debugging software that talks to a labeller''' and need something on the network that answers the same protocol — without owning the hardware.
* You want to '''develop without a physical Logopak''' altogether: render layouts, emulate the printer, and feed it from [[LogoClient]] or your own client code.
* You need to '''check field data and operator prompts''' (LQF query fields) by typing values and watching the rendered label update.
* You are '''tuning fonts''' so the on-screen rendering matches a real printed label.

== Label and Data File Types ==

LogoRenderer understands the PowerLeap LEAP layout family:

{| class="wikitable"
|-
! Extension !! Description
|-
| <code>.llf</code> || Layout File — a complete label layout with all field data embedded. Opening one renders the label immediately.
|-
| <code>.lqf</code> || Query Layout File — a base layout containing <code>QUE</code> operator prompts for fields that are filled in at print time. Opening one also populates the '''QUE Input''' tab so values can be typed in.
|-
| <code>.ldf</code> || Data File — a data-only file that references a master layout. Opening one runs its <code>LOAD</code> and <code>FD</code> commands to load the referenced layout and populate its fields.
|}

Layouts may reference <code>.pcx</code> and <code>.bmp</code> images (logotypes) and a range of barcode types. A reference list of the wider Logopak file-type ecosystem is maintained alongside the project.

== Source Code and Releases ==

LogoRenderer is part of the open-source Commander4j suite and is distributed under the GNU General Public License. The source code and release downloads are hosted on GitHub, and native install packages for every platform are listed on the Commander4j [[Downloads]] page.

* '''Repository:''' [https://github.com/C4J/LogoRenderer https://github.com/C4J/LogoRenderer]
* '''Releases (download media):''' [https://github.com/C4J/LogoRenderer/releases https://github.com/C4J/LogoRenderer/releases]
* '''All Commander4j downloads:''' [[Downloads]]

== Installation ==

Native install packages for '''Windows, macOS and Linux''' are available from the [[Downloads]] page and are the preferred installation method. Each installer bundles its own Java runtime, so '''no separate Java installation is required'''. Installing creates a native '''LogoRenderer''' launcher that can be started like any other desktop application.

=== Running from the jar ===

Alternatively the tool can be run directly as an ordinary Java (Swing) application. It is built with Maven:

mvn package
java -jar c4j_logorenderer.jar [file.llf]

Running the jar requires a recent Java runtime (Java 25 or later). If a layout file is supplied on the command line it is opened on start-up; otherwise the application starts with an empty canvas. Demo layouts and data files are provided in the <code>virtual_disk/c0/</code> folder.

== The Main Window ==

The window is divided into a '''label preview canvas''' on the left and a '''tabbed working area''' on the right, with a menu bar and toolbars around them and a status bar along the bottom. The title bar shows the program name, version and the name of the open file.

The status bar reports the current file, the layout dimensions in printer dots and millimetres, the zoom level, and the number of fields in the layout.

=== Preview Canvas ===

The canvas shows the rendered label exactly as the layout describes it — text, scalable text, barcodes, graphic lines and boxes, and embedded logotype images. The rendering engine replicates the coordinate system and geometry of a PowerLeap III print head, including the upside-down (180°) print orientation. Clicking a rendered element highlights the source lines that produce it.

=== Source / QUE Input / Log Tabs ===

{| class="wikitable"
|-
! Tab !! Purpose
|-
| '''Source''' || Lists the raw layout commands, one per line, each with a checkbox and a plain-language description. Un-checking a line excludes it from the render, so individual elements can be toggled on and off. Selecting a line shows its properties for editing.
|-
| '''QUE Input''' || For LQF layouts, presents one input box per operator prompt. Type values and apply them to see the populated label. This mirrors what an operator would be asked for at the machine.
|-
| '''Log''' || A colour-coded activity log showing file loads, parser messages, and all traffic to and from the printer emulator.
|}

=== Viewing Controls ===

The '''File''' menu opens and reloads layout files and exports the rendered label as a PNG image. The '''View''' menu provides zoom (preset levels, zoom in/out, and fit-to-window) and a '''Rotate 180°''' toggle that flips the preview to match the printer's print orientation.

== Font Mapping ==

Because Logopak fonts are not present on a development PC, LogoRenderer maps each Logopak font name to a Java font for rendering. The '''Settings → Font Mappings''' dialog lists every mapping and lets you set the Java font family (or a bundled TrueType file), style, reference cell size and calibration factors so that the on-screen text closely matches a real printed label. The mappings are stored in <code>xml/config/fonts.xml</code>; fonts found in a layout but not yet mapped are added automatically with sensible defaults, ready to be fine-tuned.

== The Printer Emulator ==

This is the feature that makes hardware-free development possible. LogoRenderer can open a TCP server that emulates a Logopak PowerLeap III labeller, answering the same '''LEAP / LAMA''' protocol commands a real machine would.

=== Starting the emulator ===

The connection bar at the top of the window selects the '''IP address''' (default <code>127.0.0.1</code> for the local machine) and '''port''' (default '''8000''', the PowerLeap III primary data port; <code>8100</code>, <code>8200</code> and <code>8300</code> are also offered). Pressing '''Start Server''' begins listening; the Log tab shows when a client connects. Pressing the button again stops the server.

=== What it emulates ===

A connected client can do, against the emulator, the things it would do against a real labeller:

* '''Browse and transfer files''' on an emulated drive — the <code>virtual_disk/</code> folder provides the labeller's storage areas (<code>c0/</code>, <code>c9/</code>, <code>d0/</code>, <code>f0/</code>, <code>r0/</code>), so directory listings, downloads, uploads and deletes all behave realistically.
* '''Load a layout and send field data''' — when the client issues a <code>LOAD</code> command the emulator loads that layout into the preview, and as <code>FD</code> field-data commands arrive the on-screen label updates. The PC screen therefore shows what the real printer would be putting on a label.
* '''Retrieve logs''' — the emulator can serve pallet/label log files back to the client, so software that polls a labeller for "what was printed" can be tested end to end.

=== Pallet print simulation ===

When a loaded layout contains the pallet SSCC field, a '''Print Label''' control appears. Each press simulates a pallet print — two labels per pallet sharing one [https://en.wikipedia.org/wiki/Serial_Shipping_Container_Code SSCC] — increments the SSCC counter (persisted in <code>sscc.dat</code>), and queues a log entry that a client can later retrieve. This lets log-polling and pallet-tracking logic be exercised without a real production run.

== Using LogoRenderer and LogoClient Together ==

The two tools form a complete bench setup for label development with no Logopak hardware:

# In '''LogoRenderer''', start the '''printer emulator''' on a port (default 8000).
# In '''[[LogoClient]]''', connect in '''PL3 (TCP)''' mode to <code>127.0.0.1</code> on the same port.
# From LogoClient, '''upload a layout''', '''send field data''', '''browse the emulated drives''' or '''poll the pallet log''' — and watch LogoRenderer render the result and log the traffic.

In this arrangement LogoRenderer stands in for the printer so you can develop and test a client, while LogoClient stands in for the driving software so you can drive the renderer. Either tool can equally be pointed at a real Logopak labeller when one is available.

== See Also ==

* [[LogoClient]] — the client-side companion tool that sends layouts and data to a labeller (real or emulated)
* [[Middleware4j]], [[LabelServer4j]], [[AutoLab4j]] — other Commander4j components in the labelling workflow
* [[ZPLRenderer]] — the equivalent preview tool for Zebra ZPL labels

[[Category:Commander4j]]

LogoClient

2026-06-13T19:40:36Z

Dgarratt: Updated by push_wiki.py

'''LogoClient''' (''c4j_logoclient'') is a standalone desktop application — and underlying client library — for communicating with [[Logopak]] PowerLeap label printers over the network. It connects to a labeller, transfers layout and data files to and from it, sends commands and field data, browses the printer's on-board storage and retrieves its logs. It exists so that the software-to-labeller conversation can be developed, exercised and diagnosed '''on an ordinary PC, in environments where no physical Logopak labeller is available''' to test against.

It is the client half of a pair: where a real labeller is not to hand, [[LogoRenderer]] can emulate one, and LogoClient talks to that emulator exactly as it would talk to real hardware. Together they let you exercise the whole label-printing workflow with no hardware at all.

''Disclaimer: LogoClient is an independent open-source tool and is '''not''' a Logopak product. It is not affiliated with, endorsed by, or supported by Logopak. Logopak, PowerLeap and related names are trademarks of their respective owners and are used solely to describe interoperability. The software is intended for local test and development use only — it must not be relied upon for production label printing.''

== Purpose ==

Software from Logopak DE drives labellers in production. When developing or supporting that software it is useful to be able to perform the same low-level operations by hand, and to see exactly what goes across the wire. LogoClient is that tool. It is useful when:

* You need to '''send a layout or data file to a labeller''' and confirm it loads correctly.
* You want to '''browse, upload, download or delete files''' on the printer's on-board drives.
* You are '''debugging the protocol''' and want a live, byte-level trace of everything sent and received.
* You need to '''send raw commands or field data''' to a labeller and read its replies.
* You want to '''poll a labeller's pallet log''' and capture one file per SSCC as labels are applied.
* You want to '''develop without a physical Logopak''' by pointing LogoClient at the [[LogoRenderer]] printer emulator instead of real hardware.

== Supported Printers and Protocols ==

LogoClient supports both current Logopak controller generations:

{| class="wikitable"
|-
! Mode !! Hardware !! Transport
|-
| '''PL3 (TCP)''' || PowerLeap III || Direct TCP socket on the data ports (8000 / 8100 / 8200 / 8300). Carries the full LEAP, LAMA/LACE and LSP command set — layout activation, field data, firmware queries, file management, I/O monitoring and asynchronous reporting.
|-
| '''PL6 (SFTP)''' || PowerLeap 6 || File transfer over SFTP (port 22). PL6 is driven by exchanging files rather than TCP commands, so this mode is focused on uploading, downloading and listing files and reading the pallet log.
|}

== Source Code and Releases ==

LogoClient is part of the open-source Commander4j suite and is distributed under the GNU General Public License. The source code and release downloads are hosted on GitHub, and native install packages for every platform are listed on the Commander4j [[Downloads]] page.

* '''Repository:''' [https://github.com/C4J/LogoClient https://github.com/C4J/LogoClient]
* '''Releases (download media):''' [https://github.com/C4J/LogoClient/releases https://github.com/C4J/LogoClient/releases]
* '''All Commander4j downloads:''' [[Downloads]]

== Installation ==

Native install packages for '''Windows, macOS and Linux''' are available from the [[Downloads]] page and are the preferred installation method. Each installer bundles its own Java runtime, so '''no separate Java installation is required'''. Installing creates a native '''LogoClient''' launcher that can be started like any other desktop application.

=== Running from the jar ===

Alternatively the tool can be run directly as an ordinary Java (Swing) application:

java -jar c4j_logoclient.jar

Running the jar requires a recent Java runtime (Java 21 or later). The bundled JSch library is required only for PL6 (SFTP); PL3 (TCP) has no external dependencies.

== The Main Window ==

The window has a '''connection bar''' across the top, a central '''file-transfer and directory area''', a '''message pane''' for composing raw commands, and a pair of log panes along the bottom — an '''activity log''' and a '''wire trace'''. All transfer and command actions are disabled until a connection is open.

=== Connecting ===

In the connection bar you choose the connection '''Type''' (PL3 TCP or PL6 SFTP), enter the labeller's '''host / IP address''' and '''port''', and — for PL6 — a '''username and password'''. Pressing the connect button opens the link; a status indicator shows the connected host and port. A real labeller is typically reached at its own network address (for example <code>192.168.1.100</code>); the [[LogoRenderer]] emulator is reached at <code>127.0.0.1</code>.

Options in the connection area let you list the remote directory automatically on connect, send a periodic '''heartbeat''' to detect a dropped link, and set the socket read timeout.

=== Transferring and Managing Files ===

The central area lists the files on the printer for a chosen remote path and file mask, showing each file's name, size, modified time and type. From here you can:

* '''Upload''' a local file to the printer.
* '''Download''' one or more selected files to a chosen local folder.
* '''Delete''' selected files from the printer (with confirmation).
* '''Refresh''' the listing, and on PL6 navigate into sub-folders.

PL3 exposes the printer's storage areas (<code>/c0/</code>, <code>/c9/</code>, <code>/f0/</code>, <code>/r0/</code>) with file masks such as <code>*.llf</code> or <code>*.pcx</code>; PL6 exposes its SFTP folders.

=== Sending Commands and Field Data ===

In PL3 mode the message pane composes and transmits raw text to the labeller. Control characters can be entered as readable tokens such as <code><STX></code>, <code><ETX></code> and <code><CR></code>, and the end-of-line terminator appended on send is selectable. This is how layouts are activated, field data is sent, and LAMA/LSP queries are issued by hand. Replies appear in the activity log and the raw bytes in the wire trace.

=== Pallet Log Polling ===

LogoClient can poll the labeller's pallet log at a chosen interval and write the results to disk — one timestamped file per unique SSCC — into a chosen log folder. This reproduces, by hand, the "what was printed" feedback that production software collects, and works against both PL3 and PL6.

=== Activity Log and Wire Trace ===

Two panes record what happens. The '''activity log''' is a readable, timestamped narrative of connects, transfers, commands and errors. The '''wire trace''' shows the raw bytes in both directions — transmitted and received — with control characters rendered as tokens, which is invaluable when diagnosing exactly what a labeller sent or expected. Both panes can be saved to a text file or cleared.

== Configuration ==

The connection details and interface preferences are saved when you quit and restored on the next start, so the tool reopens ready to reconnect to the labeller you last used.

== Using LogoClient and LogoRenderer Together ==

The two tools form a complete bench setup for label development with no Logopak hardware:

# In '''[[LogoRenderer]]''', start the '''printer emulator''' on a port (default 8000).
# In '''LogoClient''', choose '''PL3 (TCP)''', set the host to <code>127.0.0.1</code> and the matching port, and connect.
# '''Upload a layout''', '''send field data''', '''browse the emulated drives''' or '''poll the pallet log''' — and watch LogoRenderer render the result and log the traffic.

In this arrangement LogoClient stands in for the driving software so you can develop and test against the renderer, while LogoRenderer stands in for the printer so you have something to talk to. LogoClient can equally be pointed at a real Logopak labeller when one is available.

== See Also ==

* [[LogoRenderer]] — the companion tool that renders labels and emulates a Logopak printer
* [[Middleware4j]], [[LabelServer4j]], [[AutoLab4j]] — production software that drives Logopak labellers
* [[SocketTest]] — a raw TCP/IP testing utility

[[Category:Commander4j]]

LogoRenderer

2026-06-13T19:40:34Z

Dgarratt: Updated by push_wiki.py

'''LogoRenderer''' (''c4j_logorenderer'') is a standalone desktop application that renders [[Logopak]] PowerLeap label layout files to a visual on-screen preview '''and''' can stand in for a physical label printer by emulating its TCP communication protocol. It exists so that label layouts and the software that drives them can be developed and tested '''on an ordinary PC, in environments where no physical Logopak labeller is available''' to test against.

It is the rendering and printer-emulation half of a pair: [[LogoClient]] is the client that sends layouts and data to a printer, and LogoRenderer can play the part of that printer. Together they let you exercise the whole label-printing workflow with no hardware at all.

''Disclaimer: LogoRenderer is an independent open-source tool and is '''not''' a Logopak product. It is not affiliated with, endorsed by, or supported by Logopak. Logopak, PowerLeap and related names are trademarks of their respective owners and are used solely to describe interoperability. The software is intended for local test and development use only — it must not be relied upon for production label printing.''

== Purpose ==

A Logopak PowerLeap labeller normally lives on the factory floor and is driven over the network by software provided by Logopak DE. When developing or supporting that software — or designing the label layouts themselves — it is often impractical to have a real labeller on the bench. LogoRenderer removes that dependency. It is useful when:

* You need to '''see what a label layout will look like''' without printing it, by opening a <code>.llf</code>, <code>.lqf</code> or <code>.ldf</code> file and viewing a faithful preview.
* You are '''writing or debugging software that talks to a labeller''' and need something on the network that answers the same protocol — without owning the hardware.
* You want to '''develop without a physical Logopak''' altogether: render layouts, emulate the printer, and feed it from [[LogoClient]] or your own client code.
* You need to '''check field data and operator prompts''' (LQF query fields) by typing values and watching the rendered label update.
* You are '''tuning fonts''' so the on-screen rendering matches a real printed label.

== Label and Data File Types ==

LogoRenderer understands the PowerLeap LEAP layout family:

{| class="wikitable"
|-
! Extension !! Description
|-
| <code>.llf</code> || Layout File — a complete label layout with all field data embedded. Opening one renders the label immediately.
|-
| <code>.lqf</code> || Query Layout File — a base layout containing <code>QUE</code> operator prompts for fields that are filled in at print time. Opening one also populates the '''QUE Input''' tab so values can be typed in.
|-
| <code>.ldf</code> || Data File — a data-only file that references a master layout. Opening one runs its <code>LOAD</code> and <code>FD</code> commands to load the referenced layout and populate its fields.
|}

Layouts may reference <code>.pcx</code> and <code>.bmp</code> images (logotypes) and a range of barcode types. A reference list of the wider Logopak file-type ecosystem is maintained alongside the project.

== Source Code and Releases ==

LogoRenderer is part of the open-source Commander4j suite and is distributed under the GNU General Public License. The source code and release downloads are hosted on GitHub, and native install packages for every platform are listed on the Commander4j [[Downloads]] page.

* '''Repository:''' [https://github.com/C4J/LogoRenderer https://github.com/C4J/LogoRenderer]
* '''Releases (download media):''' [https://github.com/C4J/LogoRenderer/releases https://github.com/C4J/LogoRenderer/releases]
* '''All Commander4j downloads:''' [[Downloads]]

== Installation ==

Native install packages for '''Windows, macOS and Linux''' are available from the [[Downloads]] page and are the preferred installation method. Each installer bundles its own Java runtime, so '''no separate Java installation is required'''. Installing creates a native '''LogoRenderer''' launcher that can be started like any other desktop application.

=== Running from the jar ===

Alternatively the tool can be run directly as an ordinary Java (Swing) application. It is built with Maven:

mvn package
java -jar c4j_logorenderer.jar [file.llf]

Running the jar requires a recent Java runtime (Java 25 or later). If a layout file is supplied on the command line it is opened on start-up; otherwise the application starts with an empty canvas. Demo layouts and data files are provided in the <code>virtual_disk/c0/</code> folder.

== The Main Window ==

The window is divided into a '''label preview canvas''' on the left and a '''tabbed working area''' on the right, with a menu bar and toolbars around them and a status bar along the bottom. The title bar shows the program name, version and the name of the open file.

The status bar reports the current file, the layout dimensions in printer dots and millimetres, the zoom level, and the number of fields in the layout.

=== Preview Canvas ===

The canvas shows the rendered label exactly as the layout describes it — text, scalable text, barcodes, graphic lines and boxes, and embedded logotype images. The rendering engine replicates the coordinate system and geometry of a PowerLeap III print head, including the upside-down (180°) print orientation. Clicking a rendered element highlights the source lines that produce it.

=== Source / QUE Input / Log Tabs ===

{| class="wikitable"
|-
! Tab !! Purpose
|-
| '''Source''' || Lists the raw layout commands, one per line, each with a checkbox and a plain-language description. Un-checking a line excludes it from the render, so individual elements can be toggled on and off. Selecting a line shows its properties for editing.
|-
| '''QUE Input''' || For LQF layouts, presents one input box per operator prompt. Type values and apply them to see the populated label. This mirrors what an operator would be asked for at the machine.
|-
| '''Log''' || A colour-coded activity log showing file loads, parser messages, and all traffic to and from the printer emulator.
|}

=== Viewing Controls ===

The '''File''' menu opens and reloads layout files and exports the rendered label as a PNG image. The '''View''' menu provides zoom (preset levels, zoom in/out, and fit-to-window) and a '''Rotate 180°''' toggle that flips the preview to match the printer's print orientation.

== Font Mapping ==

Because Logopak fonts are not present on a development PC, LogoRenderer maps each Logopak font name to a Java font for rendering. The '''Settings → Font Mappings''' dialog lists every mapping and lets you set the Java font family (or a bundled TrueType file), style, reference cell size and calibration factors so that the on-screen text closely matches a real printed label. The mappings are stored in <code>xml/config/fonts.xml</code>; fonts found in a layout but not yet mapped are added automatically with sensible defaults, ready to be fine-tuned.

== The Printer Emulator ==

This is the feature that makes hardware-free development possible. LogoRenderer can open a TCP server that emulates a Logopak PowerLeap III labeller, answering the same '''LEAP / LAMA''' protocol commands a real machine would.

=== Starting the emulator ===

The connection bar at the top of the window selects the '''IP address''' (default <code>127.0.0.1</code> for the local machine) and '''port''' (default '''8000''', the PowerLeap III primary data port; <code>8100</code>, <code>8200</code> and <code>8300</code> are also offered). Pressing '''Start Server''' begins listening; the Log tab shows when a client connects. Pressing the button again stops the server.

=== What it emulates ===

A connected client can do, against the emulator, the things it would do against a real labeller:

* '''Browse and transfer files''' on an emulated drive — the <code>virtual_disk/</code> folder provides the labeller's storage areas (<code>c0/</code>, <code>c9/</code>, <code>d0/</code>, <code>f0/</code>, <code>r0/</code>), so directory listings, downloads, uploads and deletes all behave realistically.
* '''Load a layout and send field data''' — when the client issues a <code>LOAD</code> command the emulator loads that layout into the preview, and as <code>FD</code> field-data commands arrive the on-screen label updates. The PC screen therefore shows what the real printer would be putting on a label.
* '''Retrieve logs''' — the emulator can serve pallet/label log files back to the client, so software that polls a labeller for "what was printed" can be tested end to end.

=== Pallet print simulation ===

When a loaded layout contains the pallet SSCC field, a '''Print Label''' control appears. Each press simulates a pallet print — two labels per pallet sharing one [https://en.wikipedia.org/wiki/Serial_Shipping_Container_Code SSCC] — increments the SSCC counter (persisted in <code>sscc.dat</code>), and queues a log entry that a client can later retrieve. This lets log-polling and pallet-tracking logic be exercised without a real production run.

== Using LogoRenderer and LogoClient Together ==

The two tools form a complete bench setup for label development with no Logopak hardware:

# In '''LogoRenderer''', start the '''printer emulator''' on a port (default 8000).
# In '''[[LogoClient]]''', connect in '''PL3 (TCP)''' mode to <code>127.0.0.1</code> on the same port.
# From LogoClient, '''upload a layout''', '''send field data''', '''browse the emulated drives''' or '''poll the pallet log''' — and watch LogoRenderer render the result and log the traffic.

In this arrangement LogoRenderer stands in for the printer so you can develop and test a client, while LogoClient stands in for the driving software so you can drive the renderer. Either tool can equally be pointed at a real Logopak labeller when one is available.

== See Also ==

* [[LogoClient]] — the client-side companion tool that sends layouts and data to a labeller (real or emulated)
* [[Middleware4j]], [[LabelServer4j]], [[AutoLab4j]] — production software that drives Logopak labellers
* [[ZPLRenderer]] — the equivalent preview tool for Zebra ZPL labels

[[Category:Commander4j]]

LogoClient

2026-06-13T19:35:33Z

Dgarratt:

'''LogoClient''' (''c4j_logoclient'') is a standalone desktop application — and underlying client library — for communicating with [[Logopak]] PowerLeap label printers over the network. It connects to a labeller, transfers layout and data files to and from it, sends commands and field data, browses the printer's on-board storage and retrieves its logs. It exists so that the software-to-labeller conversation can be developed, exercised and diagnosed '''on an ordinary PC, in environments where no physical Logopak labeller is available''' to test against.

It is the client half of a pair: where a real labeller is not to hand, [[LogoRenderer]] can emulate one, and LogoClient talks to that emulator exactly as it would talk to real hardware. Together they let you exercise the whole label-printing workflow with no hardware at all.

''Disclaimer: LogoClient is an independent open-source tool and is '''not''' a Logopak product. It is not affiliated with, endorsed by, or supported by Logopak. Logopak, PowerLeap and related names are trademarks of their respective owners and are used solely to describe interoperability. The software is intended for local test and development use only — it must not be relied upon for production label printing.''

== Purpose ==

Software from Logopak DE drives labellers in production. When developing or supporting that software it is useful to be able to perform the same low-level operations by hand, and to see exactly what goes across the wire. LogoClient is that tool. It is useful when:

* You need to '''send a layout or data file to a labeller''' and confirm it loads correctly.
* You want to '''browse, upload, download or delete files''' on the printer's on-board drives.
* You are '''debugging the protocol''' and want a live, byte-level trace of everything sent and received.
* You need to '''send raw commands or field data''' to a labeller and read its replies.
* You want to '''poll a labeller's pallet log''' and capture one file per SSCC as labels are applied.
* You want to '''develop without a physical Logopak''' by pointing LogoClient at the [[LogoRenderer]] printer emulator instead of real hardware.

== Supported Printers and Protocols ==

LogoClient supports both current Logopak controller generations:

{| class="wikitable"
|-
! Mode !! Hardware !! Transport
|-
| '''PL3 (TCP)''' || PowerLeap III || Direct TCP socket on the data ports (8000 / 8100 / 8200 / 8300). Carries the full LEAP, LAMA/LACE and LSP command set — layout activation, field data, firmware queries, file management, I/O monitoring and asynchronous reporting.
|-
| '''PL6 (SFTP)''' || PowerLeap 6 || File transfer over SFTP (port 22). PL6 is driven by exchanging files rather than TCP commands, so this mode is focused on uploading, downloading and listing files and reading the pallet log.
|}

== Source Code and Releases ==

LogoClient is part of the open-source Commander4j suite and is distributed under the GNU General Public License.

== Installation ==

Native install packages for '''Windows, macOS and Linux''' are available from the [[Downloads]] page and are the preferred installation method. Each installer bundles its own Java runtime, so '''no separate Java installation is required'''. Installing creates a native '''LogoClient''' launcher that can be started like any other desktop application.

=== Running from the jar ===

Alternatively the tool can be run directly as an ordinary Java (Swing) application:

java -jar c4j_logoclient.jar

Running the jar requires a recent Java runtime (Java 21 or later). The bundled JSch library is required only for PL6 (SFTP); PL3 (TCP) has no external dependencies.

== The Main Window ==

The window has a '''connection bar''' across the top, a central '''file-transfer and directory area''', a '''message pane''' for composing raw commands, and a pair of log panes along the bottom — an '''activity log''' and a '''wire trace'''. All transfer and command actions are disabled until a connection is open.

=== Connecting ===

In the connection bar you choose the connection '''Type''' (PL3 TCP or PL6 SFTP), enter the labeller's '''host / IP address''' and '''port''', and — for PL6 — a '''username and password'''. Pressing the connect button opens the link; a status indicator shows the connected host and port. A real labeller is typically reached at its own network address (for example <code>192.168.1.100</code>); the [[LogoRenderer]] emulator is reached at <code>127.0.0.1</code>.

Options in the connection area let you list the remote directory automatically on connect, send a periodic '''heartbeat''' to detect a dropped link, and set the socket read timeout.

=== Transferring and Managing Files ===

The central area lists the files on the printer for a chosen remote path and file mask, showing each file's name, size, modified time and type. From here you can:

* '''Upload''' a local file to the printer.
* '''Download''' one or more selected files to a chosen local folder.
* '''Delete''' selected files from the printer (with confirmation).
* '''Refresh''' the listing, and on PL6 navigate into sub-folders.

PL3 exposes the printer's storage areas (<code>/c0/</code>, <code>/c9/</code>, <code>/f0/</code>, <code>/r0/</code>) with file masks such as <code>*.llf</code> or <code>*.pcx</code>; PL6 exposes its SFTP folders.

=== Sending Commands and Field Data ===

In PL3 mode the message pane composes and transmits raw text to the labeller. Control characters can be entered as readable tokens such as <code><STX></code>, <code><ETX></code> and <code><CR></code>, and the end-of-line terminator appended on send is selectable. This is how layouts are activated, field data is sent, and LAMA/LSP queries are issued by hand. Replies appear in the activity log and the raw bytes in the wire trace.

=== Pallet Log Polling ===

LogoClient can poll the labeller's pallet log at a chosen interval and write the results to disk — one timestamped file per unique SSCC — into a chosen log folder. This reproduces, by hand, the "what was printed" feedback that production software collects, and works against both PL3 and PL6.

=== Activity Log and Wire Trace ===

Two panes record what happens. The '''activity log''' is a readable, timestamped narrative of connects, transfers, commands and errors. The '''wire trace''' shows the raw bytes in both directions — transmitted and received — with control characters rendered as tokens, which is invaluable when diagnosing exactly what a labeller sent or expected. Both panes can be saved to a text file or cleared.

== Configuration ==

The connection details and interface preferences are saved when you quit and restored on the next start, so the tool reopens ready to reconnect to the labeller you last used.

== Using LogoClient and LogoRenderer Together ==

The two tools form a complete bench setup for label development with no Logopak hardware:

# In '''[[LogoRenderer]]''', start the '''printer emulator''' on a port (default 8000).
# In '''LogoClient''', choose '''PL3 (TCP)''', set the host to <code>127.0.0.1</code> and the matching port, and connect.
# '''Upload a layout''', '''send field data''', '''browse the emulated drives''' or '''poll the pallet log''' — and watch LogoRenderer render the result and log the traffic.

In this arrangement LogoClient stands in for the driving software so you can develop and test against the renderer, while LogoRenderer stands in for the printer so you have something to talk to. LogoClient can equally be pointed at a real Logopak labeller when one is available.

== See Also ==

* [[LogoRenderer]] — the companion tool that renders labels and emulates a Logopak printer
* [[Middleware4j]], [[LabelServer4j]], [[AutoLab4j]] — production software that drives Logopak labellers
* [[SocketTest]] — a raw TCP/IP testing utility

[[Category:Commander4j]]