# ComDebug

**Repository Path**: ai-agents/com-debug

## Basic Information

- **Project Name**: ComDebug
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-28
- **Last Updated**: 2026-07-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Com Debug

串口调试工具 · Modbus RTU · 固件升级

基于 **Tauri 2 + React 19 + Rust** 的跨平台桌面应用，用于串口通信调试、Modbus RTU 寄存器读写和下位机固件升级。

---

## 功能模块

| 模块 | 说明 |
|------|------|
| 指令输入通道 | RS485 串口连接，Modbus RTU 从站通信 |
| 舵偏响应通道 | RS422 串口输出 + DAC 模拟信号选择 |
| 模型参数设定 | 传递函数系数编辑，Modbus 寄存器写入 |
| 系统更新 | .bin 固件加载 → MD5 校验 → 256B 分块升级 |

---

## 环境要求

### 开发环境

| 依赖 | 版本要求 | 安装方式 |
|------|---------|---------|
| Node.js | ≥ 18 | [nodejs.org](https://nodejs.org) |
| pnpm | ≥ 9 | `npm i -g pnpm` |
| Rust | ≥ 1.77 | [rustup.rs](https://rustup.rs) |
| Visual Studio Build Tools | 2019+ | 安装"使用 C++ 的桌面开发"工作负载 |
| WebView2 Runtime | — | Win11 自带；Win10 需安装或打包时嵌入 |

### 运行环境

| 系统 | 最低版本 | 备注 |
|------|---------|------|
| Windows 10 | 1803+ | 首次运行可能提示安装 WebView2 |
| Windows 11 | 全部 | WebView2 已预装 |

- 下载 Visual Studio Build Tools
- 运行安装程序，勾选以下工作负载：

- "使用 C++ 的桌面开发"（必选）
- 右侧确认包含：
- MSVC v143 生成工具
- Windows 10/11 SDK
- CMake 工具（可选）
- 安装完成后重启电脑

---

## 快速开始

```bash
# 1. 克隆项目
git clone <repo-url>
cd com-debug

# 2. 安装前端依赖
pnpm install

# 3. 启动开发模式（前端热重载 + Rust 增量编译）
pnpm tauri:dev
```

首次运行 `tauri:dev` 会编译 Rust 依赖，可能需要几分钟。

---

## 常用命令

### 前端开发

```bash
# 仅启动前端 Vite 开发服务器（不含 Tauri 窗口）
pnpm dev

# 前端类型检查 + 构建
pnpm build

# 预览构建产物
pnpm preview
```

### Tauri 开发调试

```bash
# 完整开发模式（推荐）：前端 HMR + Rust 热重载 + 桌面窗口
pnpm tauri:dev

# 等价写法
pnpm tauri dev
```

开发模式下：
- 前端修改即时热更新，无需重启
- Rust 代码修改自动重新编译并重启窗口
- 打开 DevTools：窗口内右键 → 检查，或 `Ctrl+Shift+I`

### 打包发布

```bash
# 构建 Release 版本（生成 exe + 安装包）
pnpm tauri:build

# 等价写法
pnpm tauri build
```

构建产物位置：

```
src-tauri/target/release/
├── com-debug.exe          # 可执行文件
├── com-debug.pdb          # 调试符号（可选保留）
└── ...

src-tauri/target/release/bundle/
├── msi/
│   └── com-debug_0.1.0_x64.msi       # Windows 安装包
└── nsis/
    └── com-debug_0.1.0_x64-setup.exe  # NSIS 安装程序
```

### 指定打包目标

```bash
# 仅生成 exe（不生成安装包）
pnpm tauri build --no-bundle

# 仅生成 MSI
pnpm tauri build --bundles msi

# 仅生成 NSIS
pnpm tauri build --bundles nsis
```

### Rust 单独操作

```bash
cd src-tauri

# 检查 Rust 代码（不编译）
cargo check

# 格式化
cargo fmt

# Clippy 静态分析
cargo clippy

# 运行 Rust 测试
cargo test

# 清理编译缓存
cargo clean
```

---

## 项目结构

```
com-debug/
├── src/                        # 前端 React 源码
│   ├── components/
│   │   ├── layouts/            # Sidebar, StatusBar
│   │   └── ui/                 # 基础组件 (Button, Card, Toast...)
│   ├── features/               # 功能页面
│   │   ├── input-channel/      # 指令输入通道
│   │   ├── output-channel/     # 舵偏响应通道
│   │   ├── model-params/       # 模型参数设定
│   │   └── system-update/      # 系统更新
│   ├── stores/                 # Zustand 状态管理
│   │   ├── app-store.ts        # 全局应用状态
│   │   └── toast-store.ts      # Toast 通知状态
│   ├── styles/
│   │   └── globals.css         # 设计系统 (CSS 变量 + 动画)
│   ├── types/                  # TypeScript 类型定义
│   └── App.tsx                 # 根组件
├── src-tauri/                  # Rust 后端
│   ├── src/
│   │   ├── commands/           # Tauri 命令 (invoke 接口)
│   │   │   ├── serial.rs       # 串口连接/断开/列表
│   │   │   ├── modbus.rs       # Modbus 寄存器读写
│   │   │   └── update.rs       # 固件加载/升级/取消
│   │   ├── serial/             # 串口状态管理 (AppState)
│   │   ├── modbus/             # Modbus RTU 帧编解码 + CRC16
│   │   ├── update/             # 固件服务器 (MD5 + 分块)
│   │   ├── lib.rs              # Tauri 入口 + 插件注册
│   │   └── main.rs             # 二进制入口
│   ├── capabilities/           # Tauri 权限配置
│   ├── icons/                  # 应用图标
│   ├── Cargo.toml              # Rust 依赖
│   └── tauri.conf.json         # Tauri 配置
├── package.json                # 前端依赖 + 脚本
├── vite.config.ts              # Vite 配置
├── tsconfig.json               # TypeScript 配置
└── pnpm-workspace.yaml
```

---

## 技术栈

| 层 | 技术 |
|----|------|
| 桌面框架 | Tauri 2 |
| 前端框架 | React 19 + TypeScript |
| 构建工具 | Vite 6 |
| 样式 | Tailwind CSS 4 |
| 状态管理 | Zustand 5 |
| 动画 | Framer Motion 12 |
| 图标 | Lucide React |
| 串口通信 | serialport (Rust) |
| 协议 | Modbus RTU (CRC16) |
| 校验 | MD5 (固件升级) |

---

## 通信协议

### 串口参数（默认）

| 参数 | 值 |
|------|-----|
| 波特率 | 256000 |
| 数据位 | 8 |
| 停止位 | 1 |
| 校验 | None |
| 流控 | None |
| 超时 | 1000 ms |

### Modbus RTU

- 从站地址：5
- 帧格式：`[地址][功能码][数据][CRC16-L][CRC16-H]`
- 模型参数寄存器：`0x0020` (type) ~ `0x0030` (coefficients, 32-bit BE)

### 固件升级协议

```
1. PC → MCU : 升级命令 (含 16 字节 MD5)
2. MCU → PC : 请求更新响应
3. PC → MCU : 分块数据 (256B/块, 间隔 1~2ms)
4. MCU → PC : 升级结果 (成功/失败)
   └─ 失败时 MCU 重新请求 → PC 重发 MD5 → 重复步骤 3
```

---

## 调试技巧

### 查看 Rust 日志

开发模式下 Rust 日志输出到终端。设置日志级别：

```bash
# PowerShell
$env:RUST_LOG="debug"; pnpm tauri:dev

# 仅看串口模块
$env:RUST_LOG="com_debug_lib::commands::serial=debug"; pnpm tauri:dev
```

### 查看前端日志

开发窗口中 `Ctrl+Shift+I` 打开 DevTools → Console 面板。

### 串口调试

- 使用虚拟串口工具（如 com0com）创建串口对进行无硬件测试
- 设备管理器中确认 COM 口号
- 确保目标 COM 口未被其他程序占用

### 常见问题

| 问题 | 解决方案 |
|------|---------|
| `cargo build` 报 link 错误 | 安装 VS Build Tools "C++ 桌面开发" 工作负载 |
| 窗口白屏 | 确认 WebView2 已安装（Win10 需手动装） |
| 串口打开失败 "拒绝访问" | 关闭占用该端口的其他程序 |
| `pnpm tauri:dev` 卡住 | 首次编译 Rust 依赖较慢，耐心等待 |
| 前端 HMR 不生效 | 检查 `vite.config.ts` 端口 1420 是否被占用 |

---

## 发布清单

打包前确认：

- [ ] `src-tauri/tauri.conf.json` 中 `version` 已更新
- [ ] `package.json` 中 `version` 已同步
- [ ] 应用图标已替换 (`src-tauri/icons/`)
- [ ] `pnpm build` 前端编译无错误
- [ ] `cargo check` Rust 编译无警告
- [ ] 目标机器测试安装包可正常运行

---

## License

Private / Internal Use