Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Modbus/TCP Simulator

The Modbus/TCP simulator is a standalone Python server that emulates a realistic PLC with pre-populated data across all four Modbus data types. It runs entirely in software — no physical hardware required. So every iottack modbus plugin can be exercised locally.

Source: test-targets/iottack-modbus/simulator.py

Requirements

pymodbus 3.x. The Nix flake in test-targets/iottack-modbus/ provides a reproducible environment with the correct version pinned.

Data layout

Data typeFunction codeAddress rangeCountNotes
Holding registersFC030-9991000Status, setpoints, counters, config, alarm thresholds
Input registersFC040-99100Temperature, pressure, voltage, current, uptime
CoilsFC010-3132Alternating ON/OFF pattern
Discrete inputsFC020-3132Fixed sensor bits (door open, motor running, …)

FC43 MEI device identification (Read Device Identification) is also enabled with vendor strings: iottack Labs / SIMBUS-1000 / 1.0.0.

Usage

# Start on 0.0.0.0:5020, unit 1
nix run ./test-targets/iottack-modbus

# Loopback only
nix run ./test-targets/iottack-modbus -- --host 127.0.0.1

# Custom port and unit ID
nix run ./test-targets/iottack-modbus -- --port 502 --unit 3

Without Nix

pip install pymodbus
python test-targets/iottack-modbus/simulator.py
python test-targets/iottack-modbus/simulator.py --host 127.0.0.1 --port 5020 --unit 1

Testing with iottack

Start the simulator first, then run any of the commands below against it.

Device identification

iottack modbus device-info --host 127.0.0.1 --tcp-port 5020

Read holding registers

iottack modbus read-registers --host 127.0.0.1 --tcp-port 5020 --address 0 --count 10

Read input registers (FC04):

iottack modbus read-registers --host 127.0.0.1 --tcp-port 5020 \
    --register-type input --address 0 --count 10

Read coils

iottack modbus read-coils --host 127.0.0.1 --tcp-port 5020 --address 0 --count 32

Read discrete inputs (FC02):

iottack modbus read-coils --host 127.0.0.1 --tcp-port 5020 \
    --coil-type discrete --address 0 --count 32

Write a coil

iottack modbus write-coil --host 127.0.0.1 --tcp-port 5020 --address 0 --value on

Write a register

Single register (FC06):

iottack modbus write-register --host 127.0.0.1 --tcp-port 5020 --address 1 --value 0x00FF

Multiple registers (FC16):

iottack modbus write-register --host 127.0.0.1 --tcp-port 5020 \
    --address 200 --values 0x0001,0x09C4,0x0003

CLI options

OptionDefaultDescription
--host0.0.0.0Bind address
--port5020TCP port
--unit1Modbus unit/slave ID

Code

#!/usr/bin/env python3
"""Modbus TCP test server for IoTtack.

Starts a persistent Modbus/TCP simulator on port 5020 (configurable) with
pre-populated data across all four data types so every IoTtack Modbus plugin
can be exercised locally.

Default data layout
-------------------
  Holding registers (FC03)  0-999    : mix of fixed, counter, and sensor values
  Input registers   (FC04)  0-99     : read-only analog sensor readings
  Coils             (FC01)  0-31     : alternating ON/OFF pattern
  Discrete inputs   (FC02)  0-31     : fixed sensor bits

Device identification (FC43 MEI) is enabled with realistic vendor strings.

Usage
-----
  python simulator.py                  # listen on 0.0.0.0:5020, unit 1
  python simulator.py --port 502       # standard Modbus port (needs root)
  python simulator.py --host 127.0.0.1 # loopback only
  python simulator.py --unit 3         # respond as unit ID 3
"""

import argparse
import asyncio
import logging

from pymodbus import ModbusDeviceIdentification
from pymodbus.server import StartAsyncTcpServer
from pymodbus.simulator import DataType, SimData, SimDevice

logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s  %(levelname)-8s  %(message)s",
    datefmt="%H:%M:%S",
)
log = logging.getLogger("modbus-simulator")


def build_holding_registers() -> list[int]:
    """Return 1000 holding registers with a realistic mix of values."""
    regs = [0] * 1000
    # System status word
    regs[0] = 0x0001   # run mode
    regs[1] = 0x0064   # setpoint 100
    regs[2] = 0x01F4   # setpoint 500
    regs[3] = 0x0042   # firmware build
    # Temperature setpoints (addresses 10-19)
    for index, value in enumerate([200, 350, 400, 250, 300, 180, 220, 270, 310, 290]):
        regs[10 + index] = value
    # Process counters (addresses 100-109)
    for index in range(10):
        regs[100 + index] = index * 137 + 42
    # Config block (addresses 200-209)
    regs[200] = 0x0001  # enabled
    regs[201] = 0x09C4  # timeout 2500 ms
    regs[202] = 0x0003  # retries
    regs[203] = 0x0001  # protocol version
    # Alarm thresholds (addresses 500-509)
    for index in range(10):
        regs[500 + index] = 1000 + index * 50
    return regs


def build_input_registers() -> list[int]:
    """Return 100 input registers simulating analog sensor readings."""
    regs = [0] * 100
    # Temperature readings (0.1 °C units)
    regs[0] = 234    # 23.4 °C
    regs[1] = 251    # 25.1 °C
    regs[2] = 187    # 18.7 °C
    # Pressure (mbar)
    regs[10] = 1013
    regs[11] = 987
    # Voltage (0.01 V units)
    regs[20] = 2400  # 24.00 V
    regs[21] = 1199  # 11.99 V
    # Current (mA)
    regs[30] = 420
    regs[31] = 850
    # Uptime (seconds, low word then high word)
    regs[50] = 0xAB12
    regs[51] = 0x0002
    return regs


def build_coils() -> list[bool]:
    """Return 32 coils in an alternating ON/OFF pattern."""
    return [bool(i % 2) for i in range(32)]


def build_discrete_inputs() -> list[bool]:
    """Return 32 discrete inputs representing sensor states."""
    bits = [False] * 32
    bits[0] = True   # door open
    bits[2] = True
    bits[8] = True   # motor running
    bits[9] = True
    return bits


def build_sim_device(unit_id: int) -> SimDevice:  # noqa: ARG001
    """Build and return a simulated Modbus device with pre-populated data."""
    # id=0 is the pymodbus catch-all device: SimCore.__get_device falls back to
    # self.devices[0] when the requested unit ID is not an exact match.
    return SimDevice(
        id=0,
        simdata=(
            [SimData(address=0, values=build_coils(), datatype=DataType.BITS)],
            [SimData(address=0, values=build_discrete_inputs(), datatype=DataType.BITS)],
            [SimData(address=0, values=build_holding_registers(), datatype=DataType.REGISTERS)],
            [SimData(address=0, values=build_input_registers(), datatype=DataType.REGISTERS)],
        ),
    )


def build_identity() -> ModbusDeviceIdentification:
    """Build and return the Modbus device identity information."""
    ident = ModbusDeviceIdentification()
    ident.VendorName = "iottack Labs"
    ident.ProductCode = "SIMBUS-1000"
    ident.MajorMinorRevision = "1.0.0"
    ident.VendorUrl = "https://github.com/your-org/iottack"
    ident.ProductName = "Modbus Test Target"
    ident.ModelName = "SimBus"
    ident.UserApplicationName = "iottack modbus test"
    return ident


async def run_server(host: str, port: int, unit_id: int) -> None:
    """Run the Modbus/TCP simulator server on the specified host, port, and unit ID."""
    device = build_sim_device(unit_id)
    identity = build_identity()

    log.info("Modbus/TCP simulator starting on %s:%d  unit=%d", host, port, unit_id)
    log.info("Data layout:")
    log.info("  Holding registers (FC03)  0-999  (1000 regs)")
    log.info("  Input registers   (FC04)  0-99   (100 regs)")
    log.info("  Coils             (FC01)  0-31   (32 coils)")
    log.info("  Discrete inputs   (FC02)  0-31   (32 bits)")
    log.info("  FC43 MEI device identification: enabled")
    log.info("Press Ctrl-C to stop.")

    await StartAsyncTcpServer(
        context=device,
        identity=identity,
        address=(host, port),
    )


def main() -> None:
    """Parse command-line arguments and start the Modbus/TCP simulator."""
    parser = argparse.ArgumentParser(description="iottack Modbus/TCP test simulator")
    parser.add_argument("--host", default="0.0.0.0", help="Bind address (default: 0.0.0.0)")
    parser.add_argument("--port", type=int, default=5020, help="TCP port (default: 5020)")
    parser.add_argument("--unit", type=int, default=1, help="Modbus unit/slave ID (default: 1)")
    args = parser.parse_args()

    asyncio.run(run_server(args.host, args.port, args.unit))


if __name__ == "__main__":
    main()