# TuiSerial - 终端串口调试助手
一个用 Rust + Ratatui 构建的现代化 TUI 串口调试工具，支持完整的键盘和鼠标交互。
## 📦 安装
### 从 crates.io 安装
```bash
cargo install tuiserial
```
运行
```bash
tuiserial
```
### 从源码构建
1. 克隆仓库：`git clone https://github.com/yourusername/tuiserial.git`
2. 进入目录：`cd tuiserial`
3. 构建：`cargo build --release`
4. 运行：`cargo run --release`
### 使用预编译二进制文件
1. 下载二进制文件：[下载链接](https://github.com/yourusername/tuiserial/releases)
2. 解压文件
3. 运行：`./tuiserial`
## ✨ 功能特性
### 核心功能
- **完整串口配置**：端口选择、波特率、数据位、校验位、停止位、流控制
- **配置持久化**：自动保存/加载配置到 `~/.config/tuiserial/config.json` 💾
- **配置锁定机制**：连接后自动锁定配置，防止误操作，断开后解锁 🔒
- **智能状态显示**：实时显示连接状态和完整配置信息（8-N-1 格式）
- **国际化支持**：支持中英文切换，默认英文 🌍
- **菜单栏导航**：标准菜单栏（文件/设置/帮助），支持键盘和鼠标操作
- **双模式显示**：HEX 和 TEXT 两种显示模式，实时切换
- **简洁消息格式**：`[时间] ◄ RX (字节数) 数据` - 清晰直观
- **双向数据传输**：支持 HEX/ASCII 两种发送模式
- **灵活追加选项**：可选择追加 `\n`、`\r`、`\r\n`、`\n\r` 或无追加
- **实时数据接收**：高效的环形缓冲区，支持最多 10000 行日志
- **自动/手动滚动**：智能自动跟踪或手动浏览历史数据
- **快捷操作**：快速切换配置和显示模式
### 交互特性
- **完整键盘控制**：vim 风格快捷键 + 标准导航键 + F10 菜单
- **全面鼠标支持**：点击、右键、中键、滚轮全支持，菜单栏点击
- **实时统计**：Tx/Rx 字节数统计和连接状态
- **通知系统**：操作反馈和错误提示，支持多语言
### UI 优化
- **状态面板重构**：
- 连接状态：`✓ 已连接` / `✗ 未连接`
- 配置状态：`🔓 可修改` / `🔒 已锁定`
- 完整配置信息：串口、波特率、配置格式（8-N-1）
- **消息日志优化**：
- 简洁标题：`消息 - HEX | 123 条 [x 切换 | c 清空]`
- 统一格式：`[时间] ◄ RX (字节数) 数据`
- 智能提示：空日志时显示连接状态和快捷键
- **配置锁定提示**：连接后配置面板显示 `[已锁定]` 标记，边框变灰
- **追加选项选择器**：右侧独立面板快速选择换行符类型
- **高亮提示**：焦点字段黄色高亮，选中项加粗显示，锁定字段灰色显示
## 📦 项目结构
采用 Cargo Workspace 管理的模块化架构：
```
tuiserial/
├── Cargo.toml # Workspace 配置
├── crates/
│ ├── tuiserial-core/ # 核心数据模型和状态管理
│ ├── tuiserial-serial/ # 串口通信库（封装 serialport）
│ ├── tuiserial-ui/ # UI 渲染组件（基于 ratatui）
│ └── tuiserial-cli/ # 命令行主程序和事件处理
├── ARCHITECTURE.md # 详细架构文档
├── LOGIC_VALIDATION.md # 逻辑验证和测试清单
├── QUICK_REFERENCE.md # 快速参考指南
└── README.md # 本文档
```
## 🚀 快速开始
### 编译
```bash
cd tuiserial
cargo build --release
```
### 运行
```bash
./target/release/tuiserial
```
或直接运行：
```bash
cargo run --release --bin tuiserial
```
## ⌨️ 键盘快捷键
### 全局控制
| `F10` | 打开/关闭菜单栏 |
| `q` / `Esc` | 退出程序（或关闭菜单） |
| `Tab` | 切换焦点到下一个字段 |
| `Shift+Tab` | 切换焦点到上一个字段 |
| `o` | 打开/关闭串口连接（连接后锁定配置） |
| `r` | 刷新串口列表 |
### 菜单栏导航（F10 激活）
| `←` / `→` | 切换菜单项 |
| `↑` / `↓` | 在下拉菜单中选择 |
| `Enter` | 执行选中的菜单项 |
| `Esc` | 关闭菜单/返回上级 |
### 配置面板导航（⚠️ 连接后自动锁定）
| `↑` / `k` | 列表向上/减小值 |
| `↓` / `j` | 列表向下/增大值 |
| `←` / `h` | 减小波特率 |
| `→` / `l` | 增大波特率 |
| `p` | 切换校验位（None → Even → Odd） |
| `f` | 切换流控制（None → Hardware → Software） |
**注意**：连接串口后，所有配置参数自动锁定，无法修改。必须先断开连接才能调整配置。
### 日志区域
| `x` | 切换 HEX/TEXT 显示模式 |
| `c` | 清空日志 |
| `a` | 切换自动滚动 |
| `PgUp` | 向上翻页（10行） |
| `PgDn` | 向下翻页（10行） |
| `Home` | 跳到日志开头 |
| `End` | 跳到日志末尾（并开启自动滚动） |
### 发送区域（焦点在发送框时）
| `字符键` | 输入字符 |
| `Backspace` | 删除前一个字符 |
| `Delete` | 删除后一个字符 |
| `←` / `→` | 移动光标 |
| `Home` / `End` | 光标移到开头/结尾 |
| `↑` / `↓` | 切换 HEX/ASCII 模式 |
| `n` | 循环切换追加选项 |
| `Enter` | 发送数据 |
| `Esc` | 清空输入 |
## 🖱️ 鼠标交互
### 左键点击
- **菜单栏** → 打开菜单下拉列表
- **菜单项** → 执行对应功能
- **配置面板** → 切换焦点并直接选择列表项
- **日志区域** → 切换焦点到日志区域
- **发送框** → 切换焦点并定位光标位置
- **追加选项** → 直接选择追加模式
### 右键点击
- **日志区域** → 快速切换 HEX/TEXT 显示模式
- **发送框** → 快速切换 HEX/ASCII 发送模式
- **追加选项** → 循环切换追加模式
- **统计信息区** → 切换自动滚动开关
### 中键点击
- **日志区域** → 快速清空日志
- **发送框** → 快速清空输入
### 滚轮滚动
- **日志区域** → 向上/向下滚动日志（3行）
- **配置列表** → 在列表中向上/向下选择
- **追加选项** → 循环切换追加模式
## 📊 数据格式
### 接收显示格式
```
[14:32:45.123] ◄ RX ( 5 B) 48 65 6C 6C 6F
[14:32:45.456] ◄ RX ( 5 B) Hello
```
**格式说明**：
- 时间戳精确到毫秒
- `◄ RX` 接收方向（青色加粗）
- `► TX` 发送方向（绿色加粗）
- 字节数右对齐，便于查看
### 发送模式
1. **ASCII 模式**：直接输入文本，如 `Hello`
2. **HEX 模式**：输入十六进制，空格分隔，如 `48 65 6C 6C 6F`
### 追加选项
- **无追加**：不添加任何字符
- **\n**：添加换行符（LF，0x0A）
- **\r**：添加回车符（CR，0x0D）
- **\r\n**：添加回车换行（CRLF，0x0D 0x0A）
- **\n\r**：添加换行回车（LFCR，0x0A 0x0D）
## 🛠️ 技术栈
- **Ratatui 0.29**：现代的 Rust TUI 框架
- **Crossterm 0.28**：跨平台终端控制
- **Serialport 4.3+**：跨平台串口访问
- **Tokio 1.40**：异步运行时
- **Chrono 0.4**：时间戳处理
- **Color-eyre 0.6**：错误处理
## 📈 开发状态
### ✅ 已实现
- ✅ 串口配置管理（所有常用参数）
- ✅ **配置持久化**（自动保存/加载配置文件）
- ✅ **菜单栏系统**（文件/设置/帮助，支持键盘和鼠标）
- ✅ **国际化支持**（中英文切换，编译时零开销）
- ✅ **配置锁定机制**（连接后自动锁定，防止误操作）
- ✅ **智能状态显示**（连接状态、配置状态、完整配置信息）
- ✅ 数据接收显示（HEX/TEXT 模式）
- ✅ 数据发送功能（HEX/ASCII 模式）
- ✅ 追加选项（\n, \r, \r\n, \n\r, 无）
- ✅ 完整键盘控制（含 F10 菜单快捷键）
- ✅ 完整鼠标交互（点击、右键、中键、滚轮、菜单栏）
- ✅ **优化消息格式**（简洁直观的日志显示）
- ✅ 自动/手动滚动
- ✅ 实时统计和通知系统
- ✅ 完整逻辑验证（见 LOGIC_VALIDATION.md）
- ✅ 模块化架构（Workspace）
### 🔄 计划中
- 🔄 命令预设和快速发送
- 🔄 日志导出（TXT/CSV/JSON）
- 🔄 搜索和过滤功能
- 🔄 数据分析和图表
- 🔄 协议解析器插件
- 🔄 更多语言支持（日语、韩语等）
- 🔄 多串口同时监控
- 🔄 宏录制和回放
## 📚 文档
- [ARCHITECTURE.md](ARCHITECTURE.md) - 详细架构设计文档
- [LOGIC_VALIDATION.md](LOGIC_VALIDATION.md) - 逻辑验证和测试清单
- [QUICK_REFERENCE.md](QUICK_REFERENCE.md) - 快速参考指南
- [Cargo Workspace](https://doc.rust-lang.org/book/ch14-03-cargo-workspaces.html) - Cargo Workspace 官方文档
## 🔐 核心特性：配置锁定机制
**为什么需要配置锁定？**
在串口通信中，连接建立后修改参数可能导致：
- 通信中断或数据损坏
- 设备响应异常
- 调试信息混乱
**我们的解决方案：**
1. ✅ **连接时自动锁定** - 按 `o` 连接后，所有配置参数立即锁定
2. ✅ **视觉反馈** - 配置面板显示 `[已锁定]` 标记，边框变灰
3. ✅ **操作拦截** - 任何修改尝试都会显示警告："配置已锁定，请先断开连接"
4. ✅ **断开解锁** - 再次按 `o` 断开后，配置恢复可修改状态
5. ✅ **状态同步** - 状态面板实时显示当前配置和锁定状态
**实际效果：**
```
未连接时：
状态：✗ 未连接
配置：🔓 可修改
→ 可以自由调整所有参数
连接后：
状态：✓ 已连接
配置：🔒 已锁定
串口：/dev/ttyUSB0
波特：115200
配置：8-N-1
→ 参数锁定，无法修改
断开后：
状态：✗ 未连接
配置：🔓 可修改
→ 恢复可修改状态
```
## 🤝 贡献指南
欢迎提交 Issue 和 Pull Request！
1. Fork 本项目
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request
## 📝 许可证
MIT License
## 👨💻 作者
Your Name <your.email@example.com>
## 🌍 国际化
目前支持：
- **English** (默认)
- **中文**
切换语言：
- 按 `F10` 打开菜单
- 选择 `Settings` → `Toggle Language`
- 或直接点击菜单栏
技术实现：
- 使用 `phf` 实现编译时静态 HashMap
- 零运行时开销，所有翻译在编译时嵌入
- Fallback 机制：找不到翻译时返回 key 本身
- 简单直接，无复杂框架依赖
## 💾 配置文件
配置自动保存到：
- **Linux/macOS**: `~/.config/tuiserial/config.json`
- **Windows**: `%APPDATA%\tuiserial\config.json`
配置内容：
```json
{
"port": "/dev/ttyUSB0",
"baud_rate": 115200,
"data_bits": 8,
"parity": "None",
"stop_bits": 1,
"flow_control": "None"
}
```
操作：
- **保存配置**：菜单 → File → Save Config
- **加载配置**：菜单 → File → Load Config（启动时自动加载）
- 配置文件损坏时自动使用默认配置，不会崩溃
---
**⭐ 如果这个项目对你有帮助，请给一个 Star！**