Modbus TCP/IP Simulator
A virtual device lab to simulate realistic Modbus device behavior — register maps, scaling, and edge cases — so you can test integrations without physical hardware.
-
Register map & realistic device behavior
-
Scenario-driven testing (timeouts, faults, bad values)
-
Automation-ready (Python wrapper + CI/CD, Docker)
SPX enables realistic Modbus device simulation that matches how clients behave in the field:
• Register map modeling — coils, discrete inputs, input registers, and holding registers.
• Addressing correctness — validate offset handling and common addressing pitfalls.
• Endianness & data types — emulate real device encoding patterns for multi-register values.
• Scaling & engineering units — test client-side conversions and rounding behavior.
• Device-like behavior — stable identity, repeatable data, and realistic update patterns.Use this to validate gateways, SCADA/HMI, and custom clients against the same register behavior every time.
communication:
- modbus_slave:
unit_id: 1
endian: big
mapping:
# Coils (0xxxx)
pump_enable:
address: 1
table: coil
type: bool
write_attribute: "#attr(cmd__pump_enable)"# Discrete Inputs (1xxxx)
pump_running:
address: 10001
table: discrete_input
type: bool
read_attribute: "#attr(pump_running)"# Input Registers (3xxxx)
temperature_c:
address: 30001
table: input_register
type: float
endian: little
scale: 0.1
read_attribute: "#attr(temperature_c)"# Holding Registers (4xxxx)
setpoint_c:
address: 40001
table: holding_register
type: float
endian: little
scale: 0.1
read_attribute: "#attr(k__setpoint_c)"
write_attribute: "#attr(k__setpoint_c)"
When Modbus integrations break, you need precise visibility into what was requested and returned:
• Per-register visibility — track which addresses were read/written and when.
• Function code traces — understand read/write patterns and client behavior.
• Timing-aware debugging — validate polling intervals, delays, and timeouts.
• Regression comparisons — compare runs to detect subtle behavior changes.This makes it practical to reproduce issues like timeouts, wrong scaling, and swapped endianness.
SPX is not only protocol traffic — it can model realistic device behavior that drives register values over time:
• Environment-driven dynamics (e.g., temperature trends, pressure changes, occupancy effects).
• Noise & drift — emulate sensor imperfections and real signal behavior.
• State machines — startup, normal operation, degraded modes, and faults.
• Engineering realism — validate thresholds, alarms, filtering, and UI logic.This capability is shared across SPX protocols and packs, so your simulation remains realistic beyond Modbus.
actions:
# Environment-driven dynamics: warm-up ramp
- function: $out(temperature_c)
name: Warmup Ramp
params:
start_c: 20.0
end_c: 45.0
t0: 0.0
t1: 120.0
call: |
(lambda t:
start_c + (end_c - start_c) * min(1.0, max(0.0, (t - t0) / max(0.1, t1 - t0)))
)($attr(timer.time))# Noise & drift: realistic sensor imperfections
- noise: $out(temperature_c)
name: Temperature Noise
std: 0.02
mode: proportional
- function: $out(pressure_bar)
name: Pressure Drift
params: {drift_per_s: 0.0002}
call: $out(pressure_bar) + drift_per_s * $in(cycle_time_s)# State machine: startup → normal → degraded
- function: $out(device_state)
name: Device State Machine
params:
t_startup: 30.0
t_degraded: 180.0
call: |
(lambda t:
"startup" if t < t_startup else
"normal" if t < t_degraded else
"degraded"
)($attr(timer.time))# Engineering realism: alarms based on thresholds
- function: $out(alarm_overtemp)
name: Overtemp Alarm
call: 1 if $out(temperature_c) > 50.0 else 0
Scenario-driven simulation lets you test what usually breaks Modbus systems:
• Predefined scenarios to reproduce complex conditions consistently.
• Sequenced events — normal → degraded → offline → recovery.
• Fault injection — timeouts, stale values, stuck registers, or abnormal spikes.
• Deterministic outcomes — replay the same scenario across machines and teams.Use scenarios to validate resiliency: polling recovery, fallback logic, alerting, and gateway stability.
scenarios:
modbus_fault_cycle:
display_name: "Modbus fault cycle"
duration: 60.0
conditions:
- if: $attr(timer.time) < 20.0
actions:
- function: $out(device_state)
call: "normal"
- if: ($attr(timer.time) >= 20.0) and ($attr(timer.time) < 40.0)
actions:
- function: $out(device_state)
call: "offline"
- if: $attr(timer.time) >= 40.0
actions:
- function: $out(device_state)
call: "normal"SPX projects can be structured to work efficiently with LLM-assisted development — so you can scale simulation content while keeping it consistent:
• LLM-ready specs describing models, nodes/bindings, scenarios, and expected behavior.
• Consistent conventions for packs, simulators, and integration tests.
• Spec-first iteration — refine behavior in the spec, then generate/update implementations.
• Reviewable outputs — LLM-generated changes are easier to validate when behavior is testable.
• Automation alignment — specs + tests support a tight loop: generate → run scenarios → verify → iterate.This makes it practical to add new device models and scenarios faster without sacrificing quality or reproducibility.
SPX fits modern pipelines where integrations are tested continuously:
• Python client wrapper to control simulations programmatically from tests.
• CI/CD integration — start simulators, run scenarios, assert outcomes, collect logs automatically.
• Docker-based distribution for consistent environments across dev machines and build agents.
• Repeatable baselines — the same simulator behavior locally and in CI.This enables practical integration testing: bring up the Modbus simulator, connect your gateway/client, run a scenario, and verify outcomes automatically.
Technical capabilities
These capabilities focus on repeatability, protocol realism, and automation—so you can ship embedded integrations with confidence.
Related resources
Protocol simulation for embedded software testing
Protocol simulators (including Modbus) are often the missing link in embedded software testing. They let you validate firmware behavior, integration flows, and edge cases without physical hardware, while keeping test environments deterministic and CI-ready. If you want the full workflow—how we combine simulation models, runtime smoke checks, and automation with spx-python—see our overview here: Embedded Software Testing with SPX.
SPX platform overview
SPX is the engineering environment behind this Modbus simulator — a portable, Docker-based virtual device lab for building and testing realistic device behavior. It supports multiple industrial protocols, code-defined simulations, physics-driven dynamics, and scenario-based validation, enabling model-in-the-loop style workflows without a physical lab. The project structure is LLM-friendly by design, helping teams extend models, scenarios, and tests faster — from engineers, for engineers.
