Modbus RTU debugging — live register monitoring with synchronized TX/RX in the terminal

Website

www.serialrun.com — feature tour, OS-aware downloads, user guide, and documentation

Download

Latest: v0.4.6 (2026-10-28) — what's new · all releases

The website detects your OS and points the main button at the right installer:
www.serialrun.com.

Windows — run the setup for Start Menu shortcuts and an uninstaller; the portable
ZIP needs no installation and also contains serialrun-cli.exe and serialrun-mcp.exe.

macOS — Apple Silicon (M1–M4) needs the arm64 build, Intel Macs need the x64 build.
The builds are ad-hoc signed (not notarized), so on first launch use
right-click → Open. If macOS reports the app as damaged, run
xattr -dr com.apple.quarantine /Applications/SerialRUN.app once and open it again.

Linux — sudo apt install ./serialrun_0.4.6_amd64.deb installs serialrun,
serialrun-cli and serialrun-mcp into /usr/bin and resolves dependencies.
For the tarball, extract and run ./serialrun. Runtime dependencies (Ubuntu/Debian):
sudo apt install libudev1 libxkbcommon0 libx11-6 libxcursor1 libxrandr2 libxi6 libgl1 libwayland-client0

All packages are built automatically by GitHub Actions for every release — see
the release workflow and docs/RELEASE_SOP.md.

Quick Start

Connect your first device

1. Plug the USB serial device into your computer.
2. Launch SerialRUN and click Refresh next to the port selector.
3. Choose the port and baud rate, then click Connect.
4. Type in the input box and press Send (or Enter). Toggle HEX, timestamp,
   CRC or the line ending in the toolbar as needed.

Every panel is an independent OS window — open Modbus, PLC, CAN, Scope
or any other tool from the top bar and drag it anywhere, including onto a second monitor.

Command line

The packages include serialrun-cli for scripted work:

# List available ports
serialrun-cli list

# Connect, send, and monitor
serialrun-cli send COM1 "Hello\r\n"
serialrun-cli monitor COM1 -t -l output.log

# Record and replay a session
serialrun-cli record COM1 -o script.txt
serialrun-cli replay COM1 script.txt

Agent mode (JSON output for automation)

serialrun-cli agent list-ports                # List ports (JSON)
serialrun-cli agent COM1 send "AT+RST"        # Send data
serialrun-cli agent COM1 read --timeout 1000  # Read data
serialrun-cli agent COM1 run-script test.txt  # Run a script

Why SerialRUN?

Serial debugging usually means juggling a terminal for raw I/O, another tool for
Modbus registers, a vendor utility for PLCs, and a separate viewer for CAN or
I²C/SPI traffic. SerialRUN puts them behind one multi-window UI and adds an MCP
server so AI assistants can operate the same port under your supervision.

Based on the default, publicly documented feature sets as of October 2026.

Features

Terminal and daily debugging

• HEX or text send/receive, optional timestamps, CRC selector, configurable line endings
• Flexible baud rates — arbitrary custom values plus presets up to 3,000,000
• Auto-send and auto-reply for repetitive test loops
• Quick commands for frequently used payloads
• DTR/RTS control for reset lines and boot modes
• Auto-wrapping toolbar — controls adapt to the window instead of being clipped
• Keep-input mode, auto-scroll, and a persistent terminal history

Industrial protocols

• Modbus RTU/TCP monitoring with 8 function codes and a configurable response timeout (50–5000 ms)
• Frame builder — visual Modbus frame construction with live hex preview
• PLC control — register polling with brand presets (Siemens, Mitsubishi, Delta, Omron)
• TCP/RTU bridge — expose a serial Modbus device to Modbus TCP clients
• HMI simulator — virtual Modbus slave (TCP/RTU) with configurable registers and coils
• Custom protocol patterns for matching and decoding proprietary frames

Analysis and visualization

• Real-time charts and communication statistics
• Serial oscilloscope with trigger and cursor measurement
• CAN bus analyzer — SLCAN parsing, ID filtering, per-ID statistics
• I²C/SPI debug — register read/write with configurable address and data width
• Register editor — CSV/JSON import/export with alarm-threshold monitoring
• Data logger — continuous CSV recording with timestamps
• Packet capture viewer — load and filter pcap files, per-packet inspection

Firmware and file transfer

• XMODEM / YMODEM / ZMODEM transfers
• STM32 ISP serial flashing
• ESP32 serial flashing

Automation and AI integration

• Script recording and playback with timing preserved
• CLI and agent mode with JSON output for CI and tooling
• MCP server — 23 tools for AI assistants, with client-IP access logging
• Auto-reply rules for scripted device conversations

Workflow and customization

• Multi-window interface — every panel runs as its own always-on-top OS window
• Bilingual UI (English/Chinese) with dark and light themes
• Plugin system — dynamic discovery, install, enable/disable and ZIP import
• Data persistence — configuration, logs, terminal history and warnings in ~/.serialrun/
• Global error system — unified notifications in the status bar with history

Requirements and permissions

• USB serial drivers — install the vendor driver if your adapter is not detected:
  CH340/CH341, CP210x, FTDI or PL2303. CDC-ACM devices work with the built-in driver.
• Linux serial permissions — add your user to the serial group, then log out and back in:
  sudo usermod -aG dialout $USER (uucp on Arch-based distributions).
• Network — the MCP server listens on 127.0.0.1:9527 by default and can be switched
  to LAN mode in the GUI; the port is configurable.
• Building from source — a current stable Rust toolchain; see Development.

MCP Server

SerialRUN embeds an MCP server so AI assistants and scripts can inspect the port,
send commands and read Modbus registers through the same connection the GUI uses.
Enable it in the GUI sidebar (default 127.0.0.1:9527); every call is written to the
access log with the client IP.

Connect in 30 seconds

The server speaks JSON-RPC 2.0 over TCP:

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"list_ports","arguments":{}}}' \
  | nc 127.0.0.1 9527

From an MCP client, call tools such as connect, send_command, modbus_read or
read. A stdio bridge and Python/Node examples are in
docs/MCP_API.md.

Available tools

All operations are logged with the client IP, multiple clients can connect
concurrently, and the access log is visible in the GUI settings panel.

Troubleshooting

If a problem persists, open an issue with your OS version, adapter model, and the
relevant log lines. Device dumps may contain sensitive payloads — redact them first.

GUI Panels

All panels run as independent OS windows — drag, resize, and arrange freely. Child windows always stay on top of the main window.

Project Structure

SerialRUN/
├── crates/
│   ├── serialrun-core/       # Core library (port, protocol, checksum, data logger)
│   ├── serialrun-cli/        # CLI application
│   ├── serialrun-gui/        # GUI application (egui/eframe)
│   ├── serialrun-mcp/        # MCP server for AI integration
│   ├── serialrun-mobile/     # Android USB serial adapter
│   ├── serialrun-mobile-app/ # Android app (eframe/egui)
│   └── serialrun-plugin-api/ # Plugin API definitions
├── plugins/
│   └── serialrun-example-plugin/  # Plugin example (C FFI)
├── assets/                   # Embedded images and icons
├── docs/                     # Documentation
├── tests/                    # Integration tests
└── benches/                  # Benchmarks

Data Persistence

SerialRUN automatically saves data to ~/.serialrun/ directory:

Plugin Development

#[no_mangle]
pub extern "C" fn plugin_get_info() -> *mut c_char { /* ... */ }

#[no_mangle]
pub extern "C" fn plugin_execute(command: *const c_char, params: *const c_char) -> *mut c_char { /* ... */ }

See plugins/serialrun-example-plugin/ for a complete example.

Development

cargo build       # Build all crates
cargo test        # Run tests
cargo bench       # Run benchmarks

Build from Source

git clone https://github.com/YaoIsAI/SerialRUN.git
cd SerialRUN
cargo build --release

# Windows:  target/release/serialrun.exe
# macOS:    target/release/serialrun
# Linux:    target/release/serialrun

# macOS .app bundle:
make app

See docs/BUILD.md for detailed platform-specific instructions.

Documentation

Contributing

Contributions are welcome — bug reports, protocol corrections, translations and
pull requests all help.

• Found a bug or have an idea? Use the issue templates. Include OS, adapter
  model, and steps to reproduce; redact serial payloads that contain secrets.
• Sending a PR? Fork the repository, keep the change focused, and run
  cargo fmt --all and cargo test --workspace before opening it. CI builds on
  Windows, macOS and Linux.
• Adding a plugin? Start from plugins/serialrun-example-plugin/ and see
  docs/MCP_API.md for the tool surface.
• Read CONTRIBUTING.md for the full workflow.

Roadmap

Planned work, subject to change — discuss priorities in
Discussions:

• Signed and notarized macOS builds (remove the Gatekeeper workaround)
• Community plugin search inside the Plugin Manager
• Broader PLC presets and Modbus function-code coverage
• Continued Android app parity with the desktop panels

Community and Support

• GitHub Discussions — questions, ideas and show-and-tell
• GitHub Issues — bug reports and feature requests
• www.serialrun.com — guides, downloads and project news

If SerialRUN helps your work, consider giving the project a star — it helps other
embedded developers find it.

Support the project

Donations help cover build machines, code-signing and hosting.

WeChat Pay

License

SerialRUN is released under the Business Source License 1.1. The
license converts to the MIT License on 2030-05-31, or earlier if a
Change Date/Change License notice is published in LICENSE. Usage in
production is permitted except for offering SerialRUN itself as a commercial
serial-debugging product; see LICENSE for the exact terms.