Modbus Process Simulator v1.9.0

Java MODBUS slave and process simulator for industrial labs, training and integration testing.

Portuguese (pt-BR): README.pt-BR.md · CODE_OF_CONDUCT.md · Wiki

Author: André Henrique (@mrhenrike) | União Geek | https://uniaogeek.com.br/

Latest standalone release in this repository:

• releases/ModbusProcessSimulator-v1.9.0-standalone.jar

Earlier builds (ModbusSlaveSimulator-v1.7.x, ModbusProcessPlantSimulator-v1.8.x) remain under releases/ for reference.

Overview

Modbus Process Simulator reproduces complex and realistic MODBUS environments with an easy to use interface. The core is written in Java. TCP/IP is supported natively; serial RTU and ASCII links are supported through the bundled RxTx runtime.

Current capabilities:

• FlatLaf light and dark industrial themes, vector icons and a localized Help menu (pt-BR, en-US, es-ES).
• Slaves with holding registers, input registers, coils and discrete inputs, plus process point metadata (engineering unit, scale, offset, range, quality and write permission).
• Automations with linear, random and sine generators, bindings, real-time automation charts and multi-series process trends with CSV/PNG export.
• Jython 2.7 scripting with an embedded script library, startup and on-demand scripts.
• Console with bounded memory and configurable verbosity.
• Learn mode, master tasks, session recording and replay.
• Industrial example projects (IED, RTU, PLC, gateway, integrated plant) and a Python 3 loopback orchestrator.

Project format

Projects are stored as UTF-8 XML validated by the bundled schema mpsx-1.xsd:

Extension	Content	Root element
.mpsx	complete project	mpsx-project
.mpss	exported slave	mpsx-slave
.mpsa	exported automation	mpsx-automation
.mpsr	recorded session	text records

Scripts and replay recordings are referenced with paths relative to the project directory and must stay inside it. When a project is saved, external scripts are copied into scripts/ next to the project file.

Projects declaring scripts ask for confirmation before running them at load time. Headless sessions never run project scripts unless started with -trustScripts.

Historical .xmpp, .xmps, .xmpa and .xmpr files are converted by the separate importer in tools/legacy-import, which is not part of the standalone JAR.

How to run

java -jar releases/ModbusProcessSimulator-v1.9.0-standalone.jar
java -jar releases/ModbusProcessSimulator-v1.9.0-standalone.jar -loadFile=/absolute/path/project.mpsx

Command line options:

-loadFile=<path>       Load a project at startup (absolute path).
-portNumber=<port>     TCP port for the headless link (overrides the port stored in the project).
-hide                  Run without UI (headless); starts automations and the TCP link.
-consoleLevel=<level>  OFF | MINIMAL | NORMAL | VERBOSE | TRACE.
-trustScripts          Run project scripts automatically without confirmation.
-help                  Show this help.

Headless example:

java -jar ModbusProcessSimulator-v1.9.0-standalone.jar -loadFile=/absolute/path/project.mpsx -hide -portNumber=15020

Ctrl+C stops the link and the automations cleanly. Configure TCP slaves on 127.0.0.1 when the client runs on the same host.

Modbus ASCII is available for serial links and persists in .mpsx as ascii="true"; it uses hexadecimal text framing and LRC instead of RTU CRC.

Serial links on Windows

Serial communication uses RxTx. The bundled native libraries live in src/rxtx/[win-arch]/:

src/rxtx/[win-arch]/rxtxSerial.dll
src/rxtx/[win-arch]/rxtxParallel.dll
src/rxtx/[win-arch]/RXTXcomm.jar

The application extracts the matching library at startup. If you prefer a system-wide installation, copy RXTXcomm.jar to <JAVA_HOME>\jre\lib\ext and the DLLs to <JAVA_HOME>\jre\bin. Builds for other architectures are available at https://bitbucket.org/jlauer/mfz-cdn/downloads/ (thanks to Joe Lauer).

Quick start

1. Open the simulator and check the TCP port (default 502).
2. Add a slave: choose Add in the Slaves panel, pick an address and a name.
3. Open the slave editor (eye button) and add holding registers 1 to 10.
4. Double click a value cell and set it (for example address 1: 533).
5. Choose Run and open the Console to follow requests.

Addressing, Master, Learn and replay

• A display such as IED-Protection (127.0.0.1(1)) contains an editable device label plus the protocol address (host and Unit ID). The slave editor also provides a persisted visual type/icon: Device, IED, RTU, PLC, Gateway, Sensor or Motor.
• Master is optional. Use Tools > Master only when this application must initiate Modbus requests. Configure Task > Target > Request, enable Master, then Run. Leave Master off when an external PLC/SCADA/client initiates traffic.
• Learn does not generate traffic. While a link is running, enable Learn and send a request from an external Master to an unknown Unit ID or address. The requested slave/points are created; disable Learn after discovery.
• Serial opens an existing physical or virtual COM port; it does not emulate one. RTU uses binary frames and CRC. ASCII uses :, hexadecimal bytes, CRLF and LRC.
• Record creates a UTF-8 text .mpsr session, not PCAP. Stop recording, select Replay, choose the .mpsr file and Run. Replay processes incoming requests at their original intervals inside the current project.
• Process Trends only offers configured addresses. Drag or use the mouse wheel to zoom and choose Reset zoom to restore automatic bounds.

The built-in Help > Documentation > Complete operations manual contains the full procedures in pt-BR, en-US and es-ES.

Python 3 controllers and scripts

• scripts/modbus_simulator_ctl.py: dependency-free Modbus/TCP controller for headless sessions.
• scripts/industrial_lab.py: multi-instance loopback orchestrator for the industrial projects.
• Jython examples: import 16 curated scripts from Tools > Scripts > Example library, including inventory, safe shutdown, quality states, fault injection, setpoint steps and command-coil pulses. External copies live in Examples/ScriptLibrary and Examples/Automations.
• Device projects: Examples/Projects/Industrial.

Inside Jython scripts the current project is exposed as Simulator, together with mps_script_path, mps_script_directory and mps_script_file.

Build

Prerequisites: JDK 17 or newer, Apache Ant 1.10.x (Apache Ivy optional for NetBeans).

ant clean functional-test jar
ant legacy-import-tool

The standalone JAR is written to dist/ and copied to releases/. The legacy importer is written to dist/tools/legacy-import.jar.

Docker build image (produces the JAR under /usr/src/app/dist):

docker build -t simulator-builder .
docker run --name simulator-builder simulator-builder
docker cp simulator-builder:/usr/src/app/dist/ModbusProcessSimulator-v1.9.0-standalone.jar .

NetBeans users can open the project directly; the entry point is br.com.uniaogeek.modbus.simulator.app.SimulatorApplication.

Known limitations

• Tuning features are documented only in the built-in help.
• Javadoc coverage is partial.

---

Legal notice / aviso legal

This project is licensed under the Apache License 2.0; see LICENSE and NOTICE. No warranty beyond what the license states; no liability for misuse of industrial protocols or unauthorized testing. Use only in authorized lab or customer engagements. Upstream attribution is preserved in NOTICE.

Este projeto usa Apache License 2.0; ver LICENSE e NOTICE. Sem garantias adicionais; sem responsabilidade por uso indevido. Use apenas em ambientes autorizados.