From 09bee86a089e3b945b50784175586410042ecef4 Mon Sep 17 00:00:00 2001
From: FallenSigh <fallensigh@gmail.com>
Date: Wed, 10 Jun 2026 13:41:56 +0800
Subject: [PATCH] add README.md

---
 README.md | 166 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 166 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..755fcf0
--- /dev/null
+++ b/README.md
@@ -0,0 +1,166 @@
+# xserial
+
+`xserial` 是一个基于 Rust workspace 的串口 / TCP / UDP 数据观测工具，支持可配置分帧、协议解码、会话管理，以及以文本、十六进制和绘图为核心的桌面 GUI。
+
+## 工作区结构
+
+仓库当前包含 4 个 crate：
+
+- `xserial-core`
+  负责传输层、分帧器、协议解码器和 pipeline 基础能力。
+- `xserial-client`
+  负责会话生命周期、配置、事件分发、历史缓冲和 Lua 相关接口。
+- `xserial-gui`
+  当前主要使用入口，基于 `egui` / `eframe`。
+- `xserial-tui`
+  终端 UI crate，目前还只是占位实现。
+
+## 当前功能
+
+- 在一个 GUI 中管理多个 session。
+- 支持 `Serial`、`TCP`、`UDP` 三种传输方式。
+- 支持以下 framer：
+  `Line`、`Fixed`、`Length`、`Cobs`、`MixedTextPlot`。
+- 支持以下 decoder：
+  `Text`、`Hex`、`Plot`、`MixedTextPlot`。
+- 每个 session 可在 `Text`、`Hex`、`Plot` 三种视图之间切换。
+- 支持单连接 mixed text + plot 数据流。
+- 支持 `Interleaved`、`Block`、`XY` 三种 plot 格式。
+- 可在 sidebar 中直接编辑 session 配置。
+- plot 视图支持嵌入主界面，也支持在 GUI 内部弹出为浮动窗口。
+
+## 构建
+
+```bash
+cargo check --workspace
+```
+
+## 运行
+
+启动 GUI：
+
+```bash
+cargo run -p xserial-gui
+```
+
+当前 `xserial-tui` 还不是完整实现：
+
+```bash
+cargo run -p xserial-tui
+```
+
+## 测试
+
+运行整个 workspace 的测试：
+
+```bash
+cargo test --workspace
+```
+
+常用本地检查命令：
+
+```bash
+cargo fmt --all
+cargo clippy --workspace --all-targets -- -D warnings
+```
+
+## GUI 快速开始
+
+1. 启动 `xserial-gui`。
+2. 在 sidebar 中创建一个 session。
+3. 选择传输方式：`Serial`、`TCP` 或 `UDP`。
+4. 添加一个或多个 pipeline，并选择匹配的 framer / decoder。
+5. 连接 session。
+6. 在 `Text`、`Hex`、`Plot` 视图之间切换。
+
+补充说明：
+
+- session 配置入口在 sidebar 的齿轮按钮。
+- 连接控制是单个切换按钮，不再区分独立的 `Connect` / `Disconnect`。
+- plot 视图支持内嵌和浮动窗口两种显示方式。
+
+## Plot 测试服务器
+
+仓库自带一个本地波形测试工具：
+
+```bash
+python tools/test_plot.py --help
+```
+
+示例：通过 TCP 发送 mixed text + plot 数据流：
+
+```bash
+python tools/test_plot.py --wire-format mixed --host 127.0.0.1 --port 8091
+```
+
+GUI 中对应配置为：
+
+- Transport：`TCP 127.0.0.1:8091`
+- Framer：`MixedTextPlot`
+- Decoder：`MixedTextPlot`
+
+示例：发送 `XY` plot 数据：
+
+```bash
+python tools/test_plot.py --wire-format mixed --format xy --channels 2
+```
+
+示例：发送固定长度 raw plot 帧：
+
+```bash
+python tools/test_plot.py --wire-format raw --channels 2 --framelen 256
+```
+
+GUI 中对应配置为：
+
+- Framer：`Fixed`
+- Decoder：`Plot`
+- Sample type：`F32`
+- Endian：`Little`
+- `Channels` / `Format` 与脚本参数保持一致
+
+## Profiling
+
+GUI 内置了一套轻量级性能日志，默认关闭。
+
+开启方式：
+
+```bash
+RUST_LOG=xserial_gui::perf=info XSERIAL_GUI_PROFILE=1 cargo run -p xserial-gui
+```
+
+修改统计输出间隔：
+
+```bash
+RUST_LOG=xserial_gui::perf=info XSERIAL_GUI_PROFILE=1 XSERIAL_GUI_PROFILE_INTERVAL_MS=500 cargo run -p xserial-gui
+```
+
+日志会输出：
+
+- frame 耗时
+- 事件 drain 耗时
+- text / hex / plot 渲染耗时
+- plot 点数量统计
+
+## 仓库目录
+
+```text
+crates/
+  xserial-core/
+  xserial-client/
+  xserial-gui/
+  xserial-tui/
+tools/
+  test_plot.py
+```
+
+## 开发约定
+
+- 传输层、协议和 pipeline 逻辑优先放在 `xserial-core`。
+- 会话管理和状态编排优先放在 `xserial-client`。
+- UI 相关状态放在 `xserial-gui` 或 `xserial-tui`。
+- 集成测试位于 `crates/*/tests`。
+
+## 当前状态
+
+目前项目中最完整的是 GUI 路径。`xserial-tui` 已经在 workspace 中，但还没有达到和 GUI 同等的可用程度。