Simulate a device

modsim runs simulated Modbus devices for development and integration testing. It reads profile 0.2 TM/TD input and simulation data, and runs independent devices on one Modbus TCP listener. Models, simulation data, the simulator and the client stay separate. Simulation is not evidence of physical device behavior.

One device

modsim --config device.tm.json --port 5020 --data device.data.json

Without --port, modsim listens on 5020, so the first command needs no administrator rights; read it with modpoll --tcp 127.0.0.1 --tcp-port 5020. Linux, and macOS when binding to 127.0.0.1, reserve ports below 1024 for administrators: to listen on the standard port 502, run the command with sudo (with uvx, sudo "$(command -v uvx)" modsim --port 502 ...). modsim prints the same hint when a port is refused. Windows does not reserve these ports.

A modpoll --export snapshot is simulation data too, so a device read once can be replayed locally. Snapshots hold readings of a real device; keep them on your computer:

modpoll --config device.tm.json --tcp 192.168.1.10 --once --export snapshot.json
modsim --config device.tm.json --port 5020 --data snapshot.json

See model-driven simulation for the supported profile, codecs, constraints and behavior scripts.

Modbus RTU

--serial pty simulates a Modbus RTU device without hardware (Linux and macOS). modsim creates a virtual serial cable, prints the port for the client and the matching modpoll command, and removes it on exit:

modsim --config device.tm.json --serial pty
# Virtual serial port for the client: /dev/pts/7
# Read it with: modpoll --config device.tm.json --serial /dev/pts/7 --serial-baud 9600

Virtual ports ignore baud rate and parity, so --serial-baud and --serial-parity only shape the printed command. --serial-link PATH adds a fixed symbolic link to the client port. Pass a port name instead of pty to listen on an existing serial port with those settings. Windows has no pseudo-terminals: create a virtual serial pair with a driver such as com0com, listen on one port with --serial COM5 and connect the client to the other. --serial and --port are mutually exclusive.

The single-device model runtime supports TCP and Modbus RTU.

Several devices

A managed deployment runs several devices on one listener from a YAML file and updates them while running. examples/deployment.yaml in the modsim source starts two virtual ADAM devices: Unit 1 exposes ADAM-5017UH raw inputs; Unit 2 exposes ADAM-6024 raw I/O with synthetic AO→AI and DO→DI loopback.

modsim up -f examples/deployment.yaml -d
modsim ps -f examples/deployment.yaml
modsim down -f examples/deployment.yaml

Managed commands require POSIX (Linux, macOS or WSL). See managed deployments for the file format, updates, logging, TD export and Docker Compose.

Models in your ModioHub Workspace

After modsim login (see signing in), --config modiohub:<id>@<version> simulates one of your custom Thing Models, or a shared one without signing in; the download is checked against the SHA-256 the server states. Deployment files do not take modiohub: models, so a hosted deployment never carries your login.

modsim --config modiohub:k3x9f2m7q4a8n5bd@latest --port 5020

Unconfigured demo

modsim --comm tcp --port 5020 starts the legacy demonstration datastore; all Unit IDs share its four Modbus tables. TCP and UDP use socket framing; UDP listens on loopback. TLS loads certificates/pymodbus.crt and certificates/pymodbus.key from the working directory and does not authenticate clients. Serial supports RTU and ASCII; physical serial hardware has not been validated by the local regression suite. The CLI rejects a non-default --store and the unsupported --slaves and --context options.