# PID_Helper
**Repository Path**: qianmonai/PID_Helper
## Basic Information
- **Project Name**: PID_Helper
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: GPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 3
- **Forks**: 0
- **Created**: 2026-05-19
- **Last Updated**: 2026-06-01
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# PID Helper
### 效果展示
PID 串口调参助手主界面
自动辨识与阶跃响应测试
闭环自动优化与曲线窗口
PID 串口调参助手是一个基于 Electron、React、TypeScript 的桌面工具，用于通过串口连接下位机，实时观察 `target / actual / input / error` 数据流，并完成 PID 参数下发、自动辨识、阶跃响应测试和闭环自动优化。
当前界面支持两种应用背景：
- `速度环 PID 调节模式`
- `位置环 PID 调节模式`
说明：两种背景会切换界面文案和默认采样策略，但当前自动辨识与闭环优化算法仍以单回路阶跃响应和闭环跟踪评分为基础。位置环模式可用于位置环联调参考，不等同于串级位置环专用辨识。
## 主要功能
- 串口连接与 Mock Replay：支持真实串口，也内置 `MOCK:REPLAY` 端口用于无硬件联调。
- 实时曲线：显示目标值、实际值、控制输入、误差，并支持“窗口显示”弹窗查看。
- PID 参数编辑与下发：支持修改 `P / I / D` 草稿值，并通过 ACK 确认生效。
- 已生效 PID 反馈：从串口采样帧中的 `kp / ki / kd` 持续更新，而不是只依赖本地草稿。
- 自动辨识：通过开环阶跃响应估算 PID 初值，并自动下发。
- 固定时长辨识：速度环默认采样 `5s`，位置环默认采样 `8s`，稳态检测只作为采样质量提示。
- 阶跃响应测试：按 `SP -> SP - 范围 -> SP -> SP + 范围 -> SP` 四段路径执行，并展示各段指标。
- 闭环自动优化：支持分阶段整定和 PSO 粒子群，使用多位置阶跃评分筛选更优 PID。
- 评分模板：支持平衡型、保守型、执行器保护型。
- 数据流详情：可查看串口 TX/RX 原始数据。
- 日志详情：以弹窗查看运行日志，便于定位串口、辨识和优化问题。
## 快速开始
安装依赖：
```bash
npm install
```
开发运行：
```bash
npm run dev
```
运行测试：
```bash
npm test
```
构建应用：
```bash
npm run build
```
Windows 打包：
```powershell
$env:CSC_IDENTITY_AUTO_DISCOVERY='false'
npm run build
npx electron-builder --win portable nsis --x64 --config.win.signAndEditExecutable=false
```
打包产物位于 `release/`：
- `release/win-unpacked/PID Helper.exe`：目录版，可直接运行
- `release/PID Helper-Portable-0.1.0.exe`：单文件便携版
- `release/PID Helper-Setup-0.1.0.exe`：安装包
## 基本使用流程
1. 打开应用，选择真实串口或 `Mock Replay Device`。
2. 点击“打开串口”，确认实时曲线开始刷新。
3. 在“参数编辑与下发”中选择应用背景：速度环或位置环。
4. 根据需要修改 PID 草稿值，点击“修改参数”下发。
5. 若要估算初值，进入“自动辨识”，点击“一键自动辨识”。速度环会执行 `P -> I -> D` 分阶段辨识，位置环仍使用开环阶跃辨识。
6. 若要观察闭环性能，进入“阶跃响应测试”，设置 SP 和正负范围后开始测试。
7. 若要自动调参，进入“闭环自动优化”，选择分阶段整定或 PSO，并选择评分模板。
## 自动辨识
自动辨识会根据当前应用背景采用不同策略：
- 速度环：使用闭环分阶段辨识。软件会先在 `I=0, D=0` 下逐步试探 `P`，选出纯 P 下稳态误差 `15% ~ 20%`、目标约 `18%` 的 `P`；随后固定 `P`，让 `I` 从 `0` 开始小步增加；最后固定 `P/I`，让 `D` 从 `0` 开始细调。
- 位置环：继续使用开环阶跃响应估算过程增益 `K`、滞后时间 `L`、时间常数 `T`，再计算 PID 初值。
速度环分阶段流程：
- 切换到闭环模式。
- 使用当前速度目标 `SP` 做单点闭环测试。
- `P` 阶段临时使用 `I=0, D=0`，逐步增大 `P`，按末段静差和波动选出合适的 `P`。
- `I` 阶段固定 `P`、保持 `D=0`，让 `I` 从 `0` 开始小步增加，优先消除静差。
- `D` 阶段固定 `P/I`，让 `D` 从 `0` 开始细调，优先压制超调和抖动。
- 最终自动下发推荐 PID。
位置环开环流程：
- 切换到开环模式。
- 输出先归零并短暂等待。
- 下发固定开环输出。
- 固定采样一段时间。
- 根据响应曲线计算 PID 初值。
- 自动下发推荐 PID。
- 停止开环输出并恢复闭环模式。
默认采样时长：
- 速度环：`3s`
- 位置环：`8s`
- 可在界面手动调整，范围 `1.5s ~ 30s`
采样质量提示：
- 如果响应已基本稳定，会显示“已稳定”。
- 如果固定时间内未完全稳定，仍会给出 PID，但会提示可能需要延长采样时长。
位置环开环辨识策略已针对快响应场景做保护：
- 降低 `lambda` 最小值，避免 `P` 被压得过小。
- 给积分时间 `Ti` 增加下限，避免 `I` 在快响应下过大。
- 对 `T` 很小、`L` 接近 0 的场景，优先避免 `I > P` 造成抖动。
## 阶跃响应测试
阶跃响应测试用于观察当前 PID 在闭环下的跟踪表现，不会计算综合分数，也不会自动修改 PID。
测试路径：
```text
SP -> SP - 范围 -> SP -> SP + 范围 -> SP
```
每段会记录：
- 目标值
- 调节时间
- 稳态误差
- 超调
- 控制输出抖动
## 闭环自动优化
闭环自动优化会围绕当前已生效 PID 生成候选 PID，通过实际闭环阶跃响应评分决定是否保留。
优化策略：
- 分阶段整定：按 `P -> I -> D -> 小范围微调` 执行，更稳、更接近人工调参流程。
- PSO 粒子群：围绕当前 PID 做保守粒子群搜索，适合已有较好初值后继续探索。
分阶段整定当前行为：
- P 阶段会保留当前 `I / D`，只调整 `P`。
- I 阶段小步增加积分，用于消除静差。
- D 阶段只在超调或抖动偏大时尝试加入微分。
- 候选 PID 会先做快速预筛，明显高风险时提前回退。
评分模板：
- 平衡型：兼顾误差、超调和调节时间。
- 保守型：更强调压制超调和振荡，默认更稳。
- 执行器保护型：更关注控制输出抖动和执行器负担。
## Mock Replay
应用默认提供 `MOCK:REPLAY` 端口，用于在没有真实设备时验证完整链路。
Mock 支持：
- 持续发送采样帧。
- 响应 PID、MODE、OUT、SP、APPMODE 命令。
- 返回 ACK。
- 模拟开环阶跃响应。
- 模拟闭环目标跟踪、执行器死区、延迟和噪声。
Mock 适合验证 UI、串口协议、自动辨识和闭环优化流程，但不代表真实电机的全部动态特性。真实电机仍需要现场限幅、安全保护和逐步调参。
## 串口协议
当前协议是小端二进制混合协议，不再是旧的文本 `STX / ETX + checksum` 协议。
详细协议文档：
- [docs/protocol.md](docs/protocol.md)
- [docs/lower-controller-requirements.md](docs/lower-controller-requirements.md)
上行采样帧：
```text
[timestamp_ms, actual, target, input, error, kp, ki, kd] + 00 00 80 7f
```
字段要求：
- `timestamp_ms` 为 `uint32 little-endian`
- 其余字段为 `float32 little-endian`
- 采样帧 payload 固定为 `1 * uint32 + 7 * float32 = 32 bytes`
上行 ACK 帧：
```text
[commandId, statusCode, value, seq] + 00 00 80 7f
```
下行控制命令帧：
```text
AA 55 cmd seq arg0 arg1 arg2 sum
```
命令 ID：
- `1`：PID
- `2`：MODE
- `3`：OUT
- `4`：SP
- `5`：APPMODE
`APPMODE` 用于让上位机控制当前调节背景：
- `arg0 = 0`：速度环 PID 调节模式
- `arg0 = 1`：位置环 PID 调节模式
- `arg1 / arg2 = 0`
当前仓库已实现上位机发送、Mock 响应和协议约定；真实下位机固件需要按该命令在运行时切换当前 PID 调节背景，并返回 `APPMODE` ACK。
## 项目结构
```text
src/main/ Electron 主进程、串口服务、协议解析、日志、窗口管理
src/renderer/ React 界面、状态管理、图表和各功能面板
src/shared/ PID 算法、协议工具、类型定义和通用逻辑
tests/ Vitest 单元测试和串口 Mock 流程测试
docs/ 串口协议和下位机对接说明
release/ Windows 打包产物
```
## 本地持久化
应用会保存：
- 最近一次串口配置
- 最近一次成功下发并收到 ACK 的 PID
- 当前应用背景模式
日志会写入应用日志目录，并可通过“日志详情”窗口直接查看。
## 常用排查
- 如果 PID 下发后界面没有更新“已生效”值，先检查下位机采样帧里的 `kp / ki / kd` 是否持续回传真实生效值。
- 如果自动辨识提示反馈变化过小，增大开环输出或延长采样时长。
- 如果自动辨识 `P` 偏小、`I` 偏大，优先检查 `actual` 是否过快到达稳态，以及过程增益 `K` 是否被估得过大。
- 如果闭环优化前期实际值不等于目标值，这是候选 PID 测试过程中的正常现象；最终是否保留取决于评分和安全门限。
- 如果打包时提示输出文件被占用，请关闭正在运行的旧 exe 或等待杀毒软件释放文件锁。
## 已知限制
- 当前只支持单设备、单控制环。
- 图表只保留最近 30 秒、最多 600 个样本。
- 自动辨识是初值估算，不等同于完整闭环最优控制。
- 位置环模式目前复用单回路阶跃辨识和闭环跟踪评分流程。
- 位置环目标值按角度处理，范围限制为 `-180° ~ 180°`。
- Mock Replay 用于功能联调，不保证覆盖真实电机的所有噪声、时延、饱和和机械异常。