# 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-08-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Com Debug

舵偏模拟器上位机 · Modbus RTU · 固件升级

基于 **Tauri 2 + React 19 + Rust** 的桌面应用，作为舵偏模拟器（下位机）的配套调试工具，用于串口连接管理、Modbus RTU 寄存器读写和下位机固件升级。

应用采用无边框自定义标题栏窗口（默认 1280×800，可缩放），启动后进入「连接参数」页，连接串口成功后自动读取设备当前系统参数（28 寄存器）并回显。

---

## 功能模块

| 模块 | 说明 |
|------|------|
| 连接参数 | 上位机串口配置与连接/断开，连接后自动读取系统参数（28 寄存器回显） |
| 指令输入通道 | 模拟器侧 6 通道选择 + 串口参数下发（寄存器 `0x0000`） |
| 舵偏响应通道 | 模拟器侧通道 + 串口参数 + DAC 通道下发（寄存器 `0x0005`） |
| 模型参数设定 | 4 种传递函数模型编辑，写入寄存器 `0x000B`（类型 + 8×float32 大端） |
| 系统更新 | .bin 固件加载 → MD5 校验 → sjcx/cxxz 握手 → 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/
│   │   ├── cards/              # SystemParamsCard (系统参数回显卡片)
│   │   ├── layouts/            # TitleBar, Sidebar, StatusBar
│   │   └── ui/                 # 基础组件 (primitives.tsx: Card/Button/Field...)
│   ├── features/               # 功能页面
│   │   ├── connection/         # 连接参数 (串口连接 + 系统参数读取)
│   │   ├── input-channel/      # 指令输入通道
│   │   ├── output-channel/     # 舵偏响应通道
│   │   ├── model-params/       # 模型参数设定
│   │   └── system-update/      # 系统更新
│   ├── services/
│   │   └── system-params.ts    # 28 寄存器解析 (通道/波特率解码 + float32 组合)
│   ├── stores/                 # Zustand 状态管理
│   │   ├── app-store.ts        # 全局应用状态 (连接/通道/模型/升级)
│   │   └── toast-store.ts      # Toast 通知状态
│   ├── lib/
│   │   └── utils.ts            # cn() 类名合并工具 (clsx + tailwind-merge)
│   ├── 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 配置 (无边框窗口 1280×800)
├── package.json                # 前端依赖 + 脚本
├── vite.config.ts              # Vite 配置
├── tsconfig.json               # TypeScript 配置
└── pnpm-workspace.yaml
```

---

## 技术栈

| 层 | 技术 |
|----|------|
| 桌面框架 | Tauri 2 (+ dialog / shell 插件) |
| 前端框架 | React 19 + TypeScript |
| 构建工具 | Vite 6 |
| 样式 | Tailwind CSS 4 + clsx / tailwind-merge |
| 状态管理 | Zustand 5 |
| 动画 | Framer Motion 12 |
| 图标 | Lucide React |
| 串口通信 | serialport 4 (Rust) |
| 异步运行时 | Tokio (Rust) |
| 协议 | Modbus RTU (CRC16) |
| 校验 | MD5 (固件升级) |
| 日志 | log + env_logger (Rust) |

---

## 通信协议

### 串口参数（上位机侧默认）

| 参数 | 值 |
|------|-----|
| 波特率 | 256000 |
| 数据位 | 8 |
| 停止位 | 1 |
| 校验 | None |
| 流控 | None |
| 超时 | 1000 ms（升级期间自动缩短至 50 ms） |

### Modbus RTU

- 从站地址：5
- 帧格式：`[地址][功能码][数据][CRC16-L][CRC16-H]`

**寄存器映射**（基址 0x0000，紧凑布局）：

| 区域 | 起始地址 | 寄存器数 | 内容 |
|------|---------|---------|------|
| 指令输入通道 | `0x0000` | 5 | 通道 / 波特率 / 数据位 / 校验 / 停止位 |
| 舵偏响应通道 | `0x0005` | 6 | 通道 / 波特率 / 数据位 / 校验 / 停止位 / DAC |
| 模型参数 | `0x000B` | 17 | 模型类型 (1) + 8 × float32 (16，大端高字在前) |
| 升级命令 | `0x006C` | 8 | 16 字节 MD5（FC10 写入，触发升级流程） |

**通道编码**（模拟器 6 个物理通道）：

| 通道 | 编码 | | 通道 | 编码 |
|------|------|-|------|------|
| RS422-1 | 1 | | RS232-2 | 4 |
| RS422-2 | 2 | | RS485-1 | 5 |
| RS232-1 | 3 | | RS485-2 | 6 |

**波特率编码**：`01`=9600 · `02`=19200 · `03`=115200 · `04`=230400 · `05`=256000 · `06`=460800 · `07`=921600
**校验编码**：`0`=无 · `1`=奇校验 · `2`=偶校验
**DAC 通道**：`1` / `2`（仅舵偏响应通道）

**模型类型**：

| 类型 | 名称 | 传递函数 | 参数 |
|------|------|---------|------|
| 1 | 理想模型 | — | 无（全部置零） |
| 2 | 一阶惯性 | K / (Tb·s + 1) | K, Tb |
| 3 | 纯延时 | e^(-τc·s) | τc |
| 4 | 自定义模型 | 一般形式 | a0~a3, b0~b3 |

### 固件升级协议

```
1. PC  → MCU : Modbus FC10 写寄存器 0x006C（16 字节 MD5）
2. MCU → PC  : "sjcx"（进入升级模式，超时 30s）
3. PC  → MCU : JSON 格式 MD5（{"md5":"大写HEX"}，握手校验）
4. MCU → PC  : "cxxz"（固件标识确认，准备就绪，超时 30s）
5. PC  → MCU : 分块数据（256B/块，间隔 10ms）
6. MCU → PC  : "write completed successfully" 升级成功
              └─ 校验失败时 MCU 重发 "sjcx" → PC 重发 JSON MD5 → 重复步骤 4
                 （重试无次数限制，结果等待超时 60s）
```

补充说明：

- 升级期间上位机**独占串口**（从连接通道借出，结束后归还并恢复 1000ms 超时）
- 传输过程中可随时**取消**升级（`cancel_update` 命令）
- 下位机的上报内容实时转发至前端独立调试面板（`rx` 事件），与操作日志分开显示

### Tauri 命令接口（前端 invoke）

| 命令 | 说明 |
|------|------|
| `list_ports` | 枚举可用串口 |
| `connect_port` / `disconnect_port` | 连接 / 断开指定通道串口 |
| `read_registers` | Modbus FC03 读保持寄存器 |
| `write_registers` | Modbus FC10 写多个寄存器 |
| `load_firmware` | 读取 .bin 文件并计算 MD5 |
| `start_upgrade` | 启动升级（后台线程执行协议，经 `upgrade-progress` 事件推送进度） |
| `cancel_update` | 取消升级并复位固件服务器 |

---

## 调试技巧

### 查看 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 编译无警告
- [ ] 目标机器测试安装包可正常运行

---

## Roadmap

- 通信监控面板（`features/monitor/` 目录与 `app-store` 中的 commLogs/commStats 状态已预留，待实现 TX/RX 帧日志与统计）

---

## License

Private / Internal Use