modbus-sim

Simulated Modbus devices that behave: an energy meter whose counters count, a temperature controller that heats towards its setpoint, a frequency converter that ramps up when you set the run bit and trips when you tell it to. Three profiles follow the published register maps of real devices: an Eastron SDM630 energy meter, an Omron E5CC temperature controller and a SunSpec PV inverter. Try them in your browser, no install needed. They speak Modbus TCP, RTU over TCP and RTU on a serial line or a virtual serial port, so you can develop and test SCADA links, data loggers, gateways, Node-RED flows or your own Modbus code without the hardware, also in CI.

$ modbus-sim serve --bench examples/plant.yaml &
modbus-sim: 3 devices (units 1, 2, 3) on modbus tcp 127.0.0.1:5020, control on :5021
  unit   1  meter  (energy-meter)
  unit   2  oven  (temperature-controller)
  unit   3  pump  (vfd)
$ modbus-sim read input 0 -c 3 -t float32 -o CDAB          # meter: L1-L3 voltage
input 0: 230.201  [336c 4366]
input 2: 229.924  [ec8c 4365]
input 4: 229.215  [3714 4365]
$ modbus-sim write holding 1 30 --scale 0.01 -u 3          # pump: 30 Hz reference
$ modbus-sim write holding 0 1 -u 3                        # control word: run
$ modbus-sim read holding 101 --scale 0.01 -u 3            # two seconds later
holding 101: 21.09  [083d]
$ modbus-sim inject pump trip code=4
$ modbus-sim read holding 105 -u 3                         # fault code
holding 105: 4  [0004]
$ modbus-sim inject oven no_response
$ modbus-sim read input 0 -u 2 --timeout 1
modbus-sim: no (complete) answer

Why

Free Modbus simulators give you a table of registers. Real integrations break on other things:

• behaviour: a drive needs a control word and a ramp before it reports a speed, a meter's energy must rise, a controller's process value must follow its setpoint. Code that only ever saw static registers has never been tested.
• the classic pitfalls: 32-bit values in word order ABCD, CDAB, BADC or DCBA; integers scaled by 0.1 or 0.01; gaps in the register map that answer exception 02; request size limits that answer exception 03; 0-based protocol addresses against 1-based "40001" references in the manual.
• failures: devices that do not answer, answer late, answer busy or with an exception, send a bad CRC, a wrong transaction or unit ID, a truncated frame, or drop the connection. And device faults: a drive trip, a broken temperature sensor, a lost phase.

modbus-sim gives you all of that from a YAML profile, switchable at runtime.

Install

Requires Python 3.10 or newer; the only dependency is PyYAML.

pip install modbus-sim
pip install 'modbus-sim[serial]'    # also for real serial ports (pyserial)

From source, with the test dependencies:

git clone https://github.com/steitec/modbus-sim
cd modbus-sim
pip install -e '.[dev,serial]'
pytest

Quick start

modbus-sim profiles                     # the bundled profiles
modbus-sim map vfd                      # register map of one of them
modbus-sim serve vfd                    # one drive, unit 1, Modbus TCP on 127.0.0.1:5020
modbus-sim serve vfd --host 0.0.0.0     # reachable from the network
modbus-sim serve vfd --rtu-over-tcp     # RTU frames over TCP (as many gateways do)
modbus-sim serve vfd --pty              # RTU on a new virtual serial port (Linux/macOS)
modbus-sim serve vfd --serial /dev/ttyUSB0 --baud 9600 --parity N
modbus-sim serve --bench examples/plant.yaml

Port 502 needs root on Linux, so the default is 5020. With --pty, the server prints the device to open, for example /dev/pts/7; point your Modbus RTU master at it. On Windows, use --serial COM5 with a virtual null-modem pair such as com0com.

Profiles

Profiles after real devices

eastron-sdm630, omron-e5cc and sunspec-inverter are built from public documentation, so code written against them should work against the real device's register map:

Each was checked against a third-party client: sdm_modbus reads the simulated SDM630, and the SunSpec Alliance's pysunspec2 scans and decodes the inverter. steitec is not affiliated with Eastron, Omron or the SunSpec Alliance; product names identify the documented register maps only. Firmware versions of real devices differ, so check your device's documentation.

$ modbus-sim serve omron-e5cc &
$ modbus-sim write holding 0x2103 100 --scale 0.1     # refused: exception 04
$ modbus-sim write holding 0 0x0001                   # communications writing on
$ modbus-sim write holding 0x2103 100 --scale 0.1     # set point 100.0 degC
$ modbus-sim serve sunspec-inverter --port 5030 \
    --control-port 5031 &
$ modbus-sim read holding 40000 -c 2 -t string --port 5030

modbus-sim map PROFILE prints the complete register map, with the 0-based protocol address and the conventional reference (400001 = holding register 0):

$ modbus-sim map vfd
table     address  ref     point             type          scale  unit  access  limits  notes
discrete  0        100001  ready             bool                       ro
...
holding   0        400001  control_word      uint16                     rw              0: run, 1: reverse, 2: fault reset (rising edge)
holding   1        400002  speed_reference   uint16        0.01   Hz    rw      0..50
holding   100      400101  status_word       uint16                     ro              0: ready, 1: running, 2: at reference, 3: fault, 4: reverse
holding   101      400102  output_frequency  uint16        0.01   Hz    ro
...

--markdown gives the same as a Markdown table for your documentation.

Your own profiles

A profile is a YAML file with points. Each point sits in one table at a 0-based address and gets its value from a model variable, a signal source, or a stored value:

name: tank
description: level sensor and two pumps
identification: {vendor: ACME, product: TANK-1, revision: "2.1"}
word_order: CDAB        # default for 32/64-bit points
gaps: error             # unmapped addresses: exception 02 ("zero" reads 0 instead)
points:
  - {name: level, table: input, address: 0, type: float32, unit: m,
     source: [{type: sine, offset: 2.0, amplitude: 0.5, period: 120},
              {type: noise, sigma: 0.01}]}
  - {name: temperature, table: input, address: 2, type: int16, scale: 0.1, unit: degC,
     source: {type: ramp, start: 15, stop: 25, period: 600}}
  - {name: pump1, table: coil, address: 0}
  - {name: pump2, table: coil, address: 1, value: true}
  - {name: max_level, table: holding, address: 0, type: uint16, scale: 0.01, unit: m,
     value: 3.5, min: 0.5, max: 4.0}
  - {name: site, table: holding, address: 10, type: string, length: 8, value: "PLANT A"}

• types: bool (coils, discrete inputs), uint16, int16, uint32, int32, float32, uint64, int64, float64, string (with length in registers)
• word_order per profile or per point: ABCD (big endian), CDAB, BADC, DCBA
• scale: register value × scale = engineering value; integers saturate at their range like real devices do
• access: rw (default for coils and holding registers) or ro; writing a read-only point is exception 02
• min/max: written values outside are exception 03
• sources: constant (value), ramp (start, stop, period), sine (offset, amplitude, period), noise (sigma); a list is added up
• model: the bundled profiles bind points to a model (energy_meter, temperature_controller, vfd, pv_inverter) with model: <variable>; model_params tune it (time_scale speeds any model up)
• bits: names for the bits of a uint16 register (shown by map)

A point named exception_status provides the byte returned by function 07.

Bench files

Several devices behind one server, each with its own unit ID, like a gateway:

devices:
  - {profile: energy-meter, unit: 1, name: meter}
  - {profile: temperature-controller, unit: 2, name: oven,
     model_params: {setpoint: 180.0, time_constant: 60.0}}
  - {profile: vfd, unit: 3, name: pump, model_params: {accel_time: 5, decel_time: 5}}
  - {profile: profiles/tank.yaml, unit: 10, word_order: ABCD, values: {site: "PLANT B"}}

An entry can override word_order, gaps, model_params, identification and values (initial values of stored points). Profile paths are relative to the bench file.

Protocol

Anything else answers exception 01. Exceptions follow the specification: 02 for unmapped or read-only addresses and for writes that would change only part of a 32/64-bit value, 03 for bad quantities, byte counts and values outside min/max, 04 where a device refuses a write in its present state (omron-e5cc with communications writing off).

Unit IDs. On Modbus TCP an unknown unit answers exception 0x0B (gateway target failed to respond); a single device also answers unit 0 and 255. On RTU an unknown unit gets no answer, a frame with a bad CRC is ignored, and unit 0 is a broadcast: write requests reach every device and nobody answers.

Fault injection

Inject faults into a running bench with modbus-sim inject DEVICE FAULT [name=value ...] (device by name or unit ID), clear them with modbus-sim clear DEVICE [FAULT]:

Control channel

modbus-sim serve also listens on a control port (default 5021, loopback only, no authentication). It takes one JSON object per line:

{"device": "pump", "inject": "trip", "params": {"code": 7}}
{"device": "pump", "clear": true}
{"device": 2, "set": {"pv": 99.5}}
{"device": "oven", "get": ["pv", "output"]}
{"list": true}

set overrides a point's value (a model or source point keeps it until you set null); the CLI has the same as modbus-sim set, get and list. --no-control turns the channel off.

Python client

A minimal master is included, mainly for trying things out and for tests:

from modbus_sim.client import ModbusClient

with ModbusClient("127.0.0.1", 5020) as c:
    c.write_register(1, 2500, unit=3)                # 25.00 Hz
    c.write_register(0, 1, unit=3)                   # run
    status, frequency = c.read_holding_registers(100, 2, unit=3)

with ModbusClient.serial("/dev/pts/7") as c:         # RTU on a serial port or pty
    print(c.read_device_identification(unit=1))

Errors raise ModbusError (with .code), TimeoutError or ProtocolError. For production code use pymodbus or similar; the test suite cross-checks the simulator against pymodbus.

pytest plugin

Installing modbus-sim registers two fixtures:

def test_my_poller(modbus_bench):                  # one vfd at unit 1, free port
    modbus_bench.inject(1, "busy")
    result = my_poller("127.0.0.1", modbus_bench.port)
    assert result == "device busy"

def test_plant(modbus_bench_factory):
    bench = modbus_bench_factory("examples/plant.yaml")      # or a dict or a profile
    rtu = modbus_bench_factory("energy-meter", framing="rtu")  # RTU over TCP
    with bench.client() as c:
        ...

--modbus-bench FILE or the ini key modbus_bench sets what modbus_bench starts. See examples/test_example.py.

Limitations

• For development and testing; not a certified or conformance-tested Modbus implementation.
• energy-meter, temperature-controller and vfd are invented devices with plausible register maps. The profiles after real devices follow the published register maps but not every behaviour of the device (see Profiles after real devices). Models are plausible, not physically accurate.
• No Modbus ASCII, no Modbus/TCP Security (TLS), no function codes 11, 12, 17, 20, 21, 24; diagnostics only sub-function 00.
• RTU framing finds the end of a request from its function code, and the 3.5-character silence only for unknown function codes; inter-character timeouts (t1.5) are not enforced.
• Over a pty, baud rate and parity are not simulated.

Licence

MIT, see LICENSE.