xserial

跨平台串口 / TCP / UDP 数据观测工具 — 可配置分帧、协议解码、多会话管理、实时波形绘图，单二进制零依赖。

基于 Rust + egui 构建，支持 Lua 脚本扩展。

---

功能特性

传输层

• 串口 — 波特率 (300–12M)、数据位 (5/6/7/8)、校验位 (None/Odd/Even)、停止位 (1/2)、流控 (None/Software/Hardware)、DTR/RTS 控制
• TCP — 原始 TCP 客户端
• UDP — 绑定地址 + 可选远端地址

分帧与解码

每个 Session 可配置多条独立管线 — 同一字节流并行送入多个 framer→decoder 链路。

分帧器	说明
Line	按 \n 分割，可选去除 \r
Fixed	固定字节数为一帧
Length	长度前缀协议 (1/2/4/8 字节头)
COBS	Consistent Overhead Byte Stuffing
MixedTextPlot	单连接混合文本行 + COBS plot 帧
Lua	用户自定义分帧脚本

解码器	输出
Text	UTF-8 / Latin1 / ASCII
Hex	可配置分组、大小端
Plot	Interleaved / Block / XY 波形 (i8–f64)
MixedTextPlot	混合文本 + 波形
Lua	用户自定义解码脚本

视图

• 文本视图 — 带时间戳、方向标记、管线标签
• 十六进制视图 — hex dump + ASCII 侧栏
• 波形视图 — 实时波形：自适应、框选缩放、锁定坐标轴、浮动窗口

会话管理

• 多会话并发，标签页切换
• 连接 / 断开 / 重连，支持断线自动重连
• 运行时重配置（修改分帧器/解码器无需重启）
• 环形缓冲区历史记录（可配置上限）
• 日志到文件 — 后台线程写入，不阻塞 UI
• 配置自动持久化到 gui-state.json

Lua 脚本

内置 LuaJIT 运行时，自定义分帧和解码逻辑：

local buffer = ""
return {
    feed = function(bytes)
        buffer = buffer .. bytes
        local frames = {}
        while true do
            local i = buffer:find("\n", 1, true)
            if not i then break end
            frames[#frames + 1] = buffer:sub(1, i - 1)
            buffer = buffer:sub(i + 1)
        end
        return frames
    end,
    flush = function()
        if #buffer == 0 then return nil end
        local frame = buffer; buffer = ""; return frame
    end,
    reset = function() buffer = "" end,
    pending_len = function() return #buffer end,
}

会话 API：xserial.open()、xserial.list_ports()、xserial.sleep()、xserial.poll()、xserial.log()、session:on_data()、session:send()

快捷键

快捷键	操作
Ctrl+N	新建会话
Ctrl+E	编辑当前会话
Ctrl+W	删除当前会话
Ctrl+F5	切换连接
Ctrl+T/H/P	切换到文本 / 十六进制 / 波形视图
Ctrl+Tab / Ctrl+Shift+Tab	下一个 / 上一个标签页
Ctrl+L	清空输出
Ctrl+,	UI 设置
Esc	关闭浮层

---

快速开始

前置条件

• Rust ≥ 1.85
• Linux: libudev-dev（serialport 依赖）
• 所有平台: C 编译器（mlua 从源码编译 LuaJIT）

构建与运行

cargo run -p xserial-gui

测试

cargo test --workspace       # ~308 个测试
cargo clippy --workspace --all-targets -- -D warnings

配置文件位置

平台	路径
Linux	$XDG_CONFIG_HOME/xserial/ 或 ~/.config/xserial/
macOS	~/Library/Application Support/xserial/
Windows	%APPDATA%\xserial\

---

架构

┌──────────────────────────────────────────────────┐
│  xserial-gui (egui)       xserial-tui (ratatui) │
├──────────────────────────────────────────────────┤
│  xserial-client                                  │
│  SessionManager · Session · Config · History     │
│  Lua Runtime (mlua / LuaJIT)                     │
├──────────────────────────────────────────────────┤
│  xserial-core                                    │
│  Transport ──▶ Frame ──▶ Protocol ──▶ Pipeline  │
└──────────────────────────────────────────────────┘

Crate	类型	职责
xserial-core	library	传输层、分帧器、协议解码、管线
xserial-client	library	会话管理、事件分发、历史缓冲、Lua 运行时
xserial-gui	binary	egui 桌面应用（主要入口）
xserial-tui	binary	ratatui 终端应用（占位）

依赖方向: core ← client ← {gui, tui}

---

开发

Plot 测试服务器

python tools/test_plot.py --wire-format mixed --host 127.0.0.1 --port 8091
python tools/test_plot.py --wire-format mixed --format xy --channels 2

GUI 中配置：Transport TCP 127.0.0.1:8091，Framer MixedTextPlot，Decoder MixedTextPlot。

性能分析

RUST_LOG=xserial_gui::perf=info XSERIAL_GUI_PROFILE=1 cargo run -p xserial-gui
XSERIAL_GUI_PROFILE_INTERVAL_MS=500 cargo run -p xserial-gui

日志

RUST_LOG=info cargo run -p xserial-gui
RUST_LOG=xserial_gui=debug cargo run -p xserial-gui

---

技术栈

• 运行时: tokio (multi-thread)
• 串口: tokio-serial + serialport
• GUI: egui + egui_plot
• Lua: mlua 0.11, LuaJIT (vendored), async/serde/send
• 事件: tokio::sync::broadcast 多订阅者
• 零 feature flags，零 build script，零条件编译

License

MIT