Modbus Device Simulator

中文 | Français | 日本語

A free Modbus TCP / RTU Serial device simulator with a real-time web dashboard.

Vibe Coding — This project is built primarily through AI-assisted rapid development.

---

Overview

Modbus Device Simulator is a full-stack Modbus device simulator built with modern web technologies. It runs both a Modbus TCP server and an RTU serial server, backed by a high-performance singleton state engine, and exposes a real-time web dashboard for monitoring and controlling registers, viewing communication logs, and configuring server settings.

Whether you are developing Modbus client applications, testing PLC integrations, or learning the Modbus protocol, this simulator provides a lightweight, zero-hardware solution.

Features

• Dual Protocol Support
  • Modbus TCP Server — Configurable port (default 502) with active client tracking
  • Modbus RTU Serial Server — Real serial port integration with configurable baud rate, parity, data bits, and stop bits
• Full Register Coverage
  • 1,000 Coils (read/write boolean)
  • 1,000 Discrete Inputs (read-only boolean)
  • 10,000 Holding Registers (read/write 16-bit)
  • 10,000 Input Registers (read-only 16-bit)
• Real-Time Dashboard
  • Live register tables with pagination and goto-address
  • Toggle coils and write holding/input register values directly from the UI
  • Advanced Register Writing — Write multi-register values using typed data formats (UInt8, Int16BE, FloatBE, DoubleLE, etc.) or raw hex byte strings
  • Communication logs in reverse chronological order (newest first)
  • Configurable log filtering (read / write / error / connection)
  • Server status, active TCP clients, and configuration panel
• Communication Logging
  • In-memory log buffer with configurable max count (100–10,000 entries)
  • Track requests, responses, errors, and TCP connections
  • Per-entry log source annotation (TCP, serial, or web)
• Internationalization
  • English, Chinese (中文), French (Français), and Japanese (日本語)
• Theme Support
  • Light / Dark / System theme modes
• REST API
  • Full HTTP API for external integration and automation, including batch register writes

Web Dashboard

Tech Stack

Layer	Technology
Framework	Next.js 16 (App Router)
UI Library	React 19
Components	HeroUI v3
Styling	Tailwind CSS v4
Language	TypeScript
Modbus TCP	modbus-serial
Modbus RTU	serialport + custom frame parser
Testing	Vitest + Playwright
Icons	Iconify (Lucide)
Animation	Framer Motion

Quick Start

Run with NPX (No Installation)

The fastest way to get started — no cloning or installation required:

npx @ruixe/modbus-simulator@latest

With options:

npx @ruixe/modbus-simulator@latest -p 8080 -t 5020 -o

See all available options:

npx @ruixe/modbus-simulator@latest --help

Prerequisites

• Node.js 20.6 or later
• npm or pnpm

Installation (Development)

# Clone the repository
git clone https://github.com/RuixeWolf/modbus-simulator.git
cd modbus-simulator

# Install dependencies
npm install
# or
pnpm install

Development

# Start the development server (default port 5000)
npm run dev

Open http://localhost:5000 in your browser.

The Modbus TCP server starts automatically on port 502 (or as configured). The RTU serial server starts only when a serial port path is configured.

Production Build

# Build for production
npm run build

# Start production server
npm start

Configuration

Create a .env.local file in the project root to customize settings:

# Next.js dev server port (default is 5000)
PORT=5000

# Modbus TCP port (used in production; dev server always starts TCP on 502)
MODBUS_TCP_PORT=502

Server settings (TCP port, slave ID, RTU serial path, baud rate, parity, log filter, log max count, etc.) can also be changed at runtime via the web dashboard or the /api/config endpoint.

Usage

Web Dashboard

1. Open the dashboard at http://localhost:5000
2. Registers — View all coils, discrete inputs, holding registers, and input registers. Toggle coils or edit register values directly. Use Advanced Write for multi-register typed values or raw hex bytes.
3. Logs — Monitor all Modbus communication in real time. Filter by log type and clear logs as needed.
4. Settings — Configure the TCP port, slave ID, RTU serial port path, serial parameters, log filter, and log max count. Changes take effect immediately after restarting the servers.

Connect with a Modbus Client

Modbus TCP (using modbus-serial):

const { ModbusTCP } = require('modbus-serial')
const client = new ModbusTCP()
await client.connectTCP('127.0.0.1', { port: 502 })

// Read holding registers
const data = await client.readHoldingRegisters(0, 10)
console.log(data.data)

// Write a coil
await client.writeCoil(0, true)

client.close()

Modbus RTU (serial port):

Configure the RTU serial path (e.g., COM3 on Windows, /dev/ttyUSB0 on Linux) in the dashboard settings, then connect with any standard Modbus RTU client.

API Reference

All API routes are prefixed with /api and require the dev server to be running.

Method	Endpoint	Description
GET	/api/registers	Dump full Modbus engine state
POST	/api/registers	Write a coil or register. Body: { registerType, address, value }
POST	/api/registers/batch	Batch write registers. Body: { registerType, startAddress, mode, dataType, value } or { registerType, startAddress, mode, hexString }
GET	/api/logs	Get all communication logs
DELETE	/api/logs	Clear all communication logs
GET	/api/status	Server status: { tcp: boolean, rtu: boolean }
GET	/api/config	Get current configuration (includes logFilter and logMaxCount)
POST	/api/config	Update configuration and restart servers. Body: partial config object
GET	/api/serial-ports	List available serial ports
GET	/api/tcp-clients	List active TCP client connections
GET	/api/tcp-clients/:id	Get details for a specific TCP client

Batch Write API

The batch write endpoint supports two modes:

Number mode — Convert a numeric value into registers using a typed data format:

curl -X POST http://localhost:5000/api/registers/batch \
  -H "Content-Type: application/json" \
  -d '{
    "registerType": "holdingRegister",
    "startAddress": 0,
    "mode": "number",
    "dataType": "FloatBE",
    "value": 3.14
  }'

Supported data types: UInt8, UInt16BE, UInt16LE, UInt32BE, UInt32LE, UIntBE, UIntLE, Int8, Int16BE, Int16LE, Int32BE, Int32LE, IntBE, IntLE, FloatBE, FloatLE, Float1234, Float2143, Float3412, Float4321, DoubleBE, DoubleLE.

Bytes mode — Write raw bytes from a hex string:

curl -X POST http://localhost:5000/api/registers/batch \
  -H "Content-Type: application/json" \
  -d '{
    "registerType": "holdingRegister",
    "startAddress": 10,
    "mode": "bytes",
    "hexString": "0A 45 B1 30"
  }'

Project Structure

modbus-simulator/
├── app/
│   ├── api/                    # Next.js API routes
│   │   ├── config/route.ts
│   │   ├── logs/route.ts
│   │   ├── registers/route.ts
│   │   ├── registers/batch/route.ts
│   │   ├── serial-ports/route.ts
│   │   ├── status/route.ts
│   │   ├── tcp-clients/route.ts
│   │   └── tcp-clients/[id]/route.ts
│   ├── globals.css             # Tailwind CSS v4 entry + theme variables
│   ├── layout.tsx              # Root layout with i18n & theme
│   └── page.tsx                # Dashboard page (client component)
├── src/
│   ├── components/
│   │   ├── AdvancedWriteModal.tsx   # Advanced multi-register write modal
│   │   ├── LanguageSwitcher.tsx     # Language switcher
│   │   ├── LogPanel.tsx             # Communication log panel
│   │   ├── RegisterTable.tsx        # Paginated register table
│   │   ├── SettingsPanel.tsx        # Server settings panel
│   │   ├── StatusIndicator.tsx      # Server status indicator
│   │   ├── TcpClientPanel.tsx       # Active TCP client list
│   │   └── ThemeToggle.tsx          # Light/dark/system theme toggle
│   ├── hooks/
│   │   ├── useModbusData.ts    # React hook for polling Modbus data
│   │   └── useTheme.ts         # Theme (light/dark/system) management
│   ├── i18n/
│   │   └── index.ts            # i18next initialization (EN / CN / FR / JA)
│   ├── lib/
│   │   └── modbus/
│   │       ├── buffer-convert.ts     # Typed data type ↔ buffer conversions
│   │       ├── engine.ts             # Singleton ModbusEngine (state + events)
│   │       ├── engine.test.ts        # Unit tests for engine
│   │       ├── index.ts              # Server manager (start/stop/config)
│   │       ├── log-context.ts        # AsyncLocalStorage for log source context
│   │       ├── mock-client.ts        # Mock client for E2E tests
│   │       ├── rtu-serial-server.ts  # Modbus RTU serial server
│   │       └── tcp-server.ts         # Modbus TCP server
│   └── types/
│       └── modbus-serial.d.ts  # Custom type declarations
├── docs/                       # Documentation and screenshots
├── e2e/                        # Playwright E2E tests
├── public/locales/             # Translation JSON files (en, zh, fr, ja)
├── next.config.ts
├── vitest.config.ts
├── playwright.config.ts
└── package.json

Testing

# Run unit tests (Vitest)
npm run test:unit

# Run E2E tests (Playwright)
npm run test:e2e

# Run all tests
npm run test

# Run a specific unit test file
npx vitest run src/lib/modbus/engine.test.ts

# Run a specific E2E test
npx playwright test e2e/modbus.spec.ts --grep "UI to Protocol"

Available Scripts

Script	Description
npm run dev	Start development server (default port 5000)
npm run build	Production build
npm run start	Start production server
npm run lint	Run ESLint
npm run format	Format all files with Prettier
npm run type-check	Run TypeScript compiler (no emit)
npm run test:unit	Run Vitest unit tests
npm run test:e2e	Run Playwright E2E tests
npm run test	Run unit tests then E2E tests

License

MIT