SerialRUN
One serial tool for terminal work, Modbus/PLC debugging, CAN and I²C/SPI analysis, firmware flashing — plus an MCP server that lets AI agents drive the port.
English | 简体中文
Download · Features · MCP server · Documentation · Website
Website
Download
Latest: v0.4.6 — 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
- Plug the USB serial device into your computer.
- Launch SerialRUN and click Refresh next to the port selector.
- Choose the port and baud rate, then click Connect.
- 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(uucpon Arch-based distributions). - Network — the MCP server listens on
127.0.0.1:9527by 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 --allandcargo test --workspacebefore 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.
License
SerialRUN is source-available under the Business Source License 1.1, which converts to the MIT License on 2030-05-31 or on the date the licensor announces the change, whichever is earlier. Non-commercial use is unrestricted, and businesses may use it for evaluation, internal testing and development. Commercial use requires a separate license, and modified versions may not be distributed without one; unmodified copies may be redistributed. See LICENSE for the exact terms.
Made with ❤️ for embedded developers
