串口监视器插件（Serial Monitor + 在线调参）

在 DeepSeek Harness Web UI 中读取 Windows 串口（COM 口）数据。调参部分按 VOFA+ 的方式做成自适应的：通道数量从数据里自动识别、通道可以自己命名、通道顺序 / PID 默认值 / 限幅都能跟工程源码一键对齐，不再需要每次改固件都改插件。

安装（DSH 插件）

这是一个 DeepSeek Harness 插件 Bundle，不是独立程序；需要 DSH Desktop（Web UI）和 Windows（Host 端用 Windows PowerShell 5.1 访问 COM 口）。没有 npm 依赖，不需要编译。

方式 A：从 Git 安装（推荐给队友）

1. 在 DSH 里让 Agent 用插件管理安装 Bundle：plugin_manager → install_bundle，target 填本仓库地址，例如：
   • https://github.com/<你的用户名>/<仓库名>
   • 或 github:<你的用户名>/<仓库名>
2. 安装完成后启用 Serial Monitor（串口监视器）（list_plugins 里找到对应条目，set_plugin 设为 enabled）。
3. 刷新页面（Ctrl+R），侧边栏底部出现串口图标。

方式 B：从本地目录安装

1. git clone 或下载本仓库到任意目录，确保 package.json 在目录根。
2. 同样用 plugin_manager → install_bundle，target 填该目录的绝对路径（例如 D:\tools\dsh-serial-monitor）。
3. 启用插件并刷新页面。

从工程文件对齐的前提：DSH 的工作目录是整车工程根目录（即 Seekfree_TC264_Opensource_Library 所在目录），或者把插件放在工程的 plugins/ 下；否则请用「导入 balance.c」手动选文件。

升级：重新安装同一地址；如果提示 already-installed，先 remove_bundle 再安装。

使用

1. 侧边栏底部、设置按钮旁点击「串口监视器」图标。
2. 选择串口与波特率。板子的调试口是 UART_0 → USB 虚拟串口（vofa.c 注释里写作 COM8，以实际枚举为准），115200。
3. 点击「打开」开始收发。
4. 第一次连新固件后点一次调参页的「对齐通道」（解析 vofa.c 里的通道顺序，重置通道名和图表）和「从工程文件对齐」（同步 PID 默认值与限幅）。

数据页

文本/HEX 视图、UTF-8/GBK 解码、时间戳、自动滚动、复制与清空；接收字节数显示在底部。

调参页

• 实时信号（自适应）：不再写死通道数。任何一行「逗号分隔的数值」都会按字段个数自动建通道；当前固件是 12 路也能直接用。
  • 通道默认名来自 vofa.c 解析出的变量名；点击通道名可重命名，名字存在浏览器本地。
  • 「对齐通道」会按 vofa.c 的 sprintf(...) 参数顺序重新取通道名、清掉旧名字并重排图表。
  • 4 张趋势图，每张图两个下拉框选「主通道 / 对比通道」；对齐通道时按代码名自动配对： 速度（target_speed / speed）、倾角（pitch / angle_ref）、 航向角（yaw_angle_ref / yaw_angle）、航向角速度（yaw_ref / yaw_rate）。
  • 图表选择、通道名、通道代码都存在浏览器 localStorage。
• PID 参数：[0] 直立外环、[1] 直立内环、[2] 速度环、[3] 航向角外环、[4] 转向环（yaw 角速度），下发 @<序号>,kp,ki,kd，下发前按当前限幅夹取。
• PID 默认值与限幅：
  • 「从工程文件对齐」：Host 读取 balance.c 的 5 个 pid_init() 和 vofa.c 的 pid_limit[]，默认值和限幅一起同步。
  • 「导入 balance.c」：Host 找不到工程时手动选文件（支持 GBK 源码）。
  • 「编辑默认值」可手动改 5 个环的 kp/ki/kd；「默认」把当前参数恢复成这组值。
• 速度与航向目标：@6,<目标速度>,<目标航向或角速度>,<航向角外环 0/1>。
  • 速度 ±600（编码器计数/20 ms）。
  • 固件当前 SPEED_TARGET_FIXED = 0，上电不会自己走；停车后目标也会清 0。
  • 勾选「航向角外环」时第 2 个参数是目标航向角（±180°，固件 yaw_angle_pid 串在转向环外），不勾时是目标角速度（±300 °/s）。
  • 目标只在平衡运行时生效；「目标归零」发 @6,0,0,0（同时关外环），关闭面板时若目标非零会自动归零。
• 电机测试：@11,左占空比,右占空比,1 开启、@11,0,0,0 停止；必须勾选「车轮已悬空」才能开启，15 秒后自动停止。
• 机械中值：@9,<零位>,0,0 锁定并保存到 Flash，@10,0,0,0 解锁；「使用当前倾角」按当前固件的 pitch 通道取数。两个按钮都需要二次确认。
• 自定义命令：一行文本直接写入串口，缺少 @ 会自动补上，适合固件新增的命令（例如 @5,0,0,0 清积分、@7,120,0,0 死区补偿、@8,12,10,0 速度环倾角权限/积分上限）。最近 8 条命令作为快捷按钮保留。
  • 为保留界面上的安全保护，@11,... 电机测试命令不允许从这里发，请用上方的电机测试区。
• 命令记录：最近 12 条下发记录（含失败原因），显示实际写入的 @...。

打开连接后自动发一次 @11,0,0,0（安全停止）。关闭面板或点「关闭」时，如果电机测试仍开启会先发 @11,0,0,0，如果速度/航向目标非零会先发 @6,0,0,0，再释放串口。

当前固件协议（vofa.c / balance.c）

波形（12 路，FireWater 文本）

#	代码	含义
1	target_speed	速度目标 v*（编码器计数/20 ms）
2	speed	速度实际 v（滤波，计数/20 ms）
3	zero	机械平衡角 θ0（度）
4	angle_ref	速度环给出的倾角修正量 -S（度）
5	pitch	倾角实际（互补滤波，度）
6	rate_ref	直立内环目标角速度 ω*
7	pitch_rate	俯仰角速度
8	bal	平衡分量 B
9	yaw_angle_ref	目标航向角（度）
10	yaw_angle	航向角（度，对 yaw_rate 积分）
11	yaw_ref	角速度环给定（°/s）
12	yaw_rate	实测 yaw 角速度（°/s）

命令（必须以 @ 开头，例如 @6,100,0,1）

命令	含义
@0,kp,ki,kd	直立外环（角度）
@1,kp,ki,kd	直立内环（角速度）
@2,kp,ki,kd	速度环
@3,kp,ki,kd	航向角外环（yaw 角度）
@4,kp,ki,kd	转向环（yaw 角速度）
@5,0,0,0	清五个环的积分
@6,目标速度,目标航向/角速度,外环 0/1	速度目标 ±600；外环开时第 2 参数为航向角 ±180°，关时为角速度 ±300 °/s
@7,死区补偿,0,0	电机死区补偿，0–600
@8,out_max,int_max,0	速度环倾角权限 0.5–20、积分上限 0–20
@9,零位,0,0	设定机械中值并锁定、存 Flash
@10,0,0,0	解锁零位并擦除 Flash 记录
@11,左,右,1 / @11,0,0,0	电机开环测试开 / 关

命令以 \r\n 结尾，pid_tune_poll() 在主循环里约 20 ms 解析一次。固件现在要求行首 @，不带 @ 的命令直接丢弃（防止串口噪声凑成命令误触发）；插件会自动补 @。固件对序号越界、解析失败、NaN 一律静默丢弃；PID 和目标值会再夹到安全范围。当前默认值以 balance.c 的 pid_config_init() 为准（10 / 20 / 0.1,0.0004 / 2 / 8,2）。波形保留 2 位小数；无线口另发 7 路短帧（speed, pitch, yaw_angle, yaw_rate, turn, bal, target_speed），USB 口仍是 12 路。

实现

• Host 端（index.js）：Windows PowerShell 子进程持有 System.IO.Ports.SerialPort，串口数据以 base64 行写到 stdout；浏览器下发的命令行经子进程 stdin（base64）写入同一串口句柄。关闭时先结束 stdin，让子进程排空待发命令并关闭端口，超时才强杀。/serial-monitor/firmware 从工程目录读取 balance.c / vofa.c，返回 PID 默认值、限幅和通道代码列表。所有功能通过 /serial-monitor/* JSON 路由暴露。
• Client 端（client.js）：sidebar.footer.action 注册开关，shell.overlay 注册浮动面板；打开期间每 150 ms 轮询增量数据，自动识别 CSV 通道数并渲染调参界面。通道名、通道代码、图表选择、PID 默认值/限幅和自定义命令历史都存在浏览器 localStorage。

无需任何原生 Node 模块，依赖 Windows 自带的 Windows PowerShell 5.1。

注意

• 仅支持 Windows；同一端口同一时间只能被一个程序打开。
• 本次协议改版把命令整体重新编号（电机测试从 9 → 11，零位 10/11 → 9/10，目标 4 → 6），并要求所有命令以 @ 开头；插件已按新协议对齐，旧固件需要旧版插件。
• 电机测试绕过平衡闭环，请务必架空车轮并短时使用。如果连接在测试中意外断开，固件可能仍保持测试状态，请断电或重新连接后点「停止」。
• 速度/航向目标会让车实际运动，请确保场地可控；关闭面板会自动归零，但如果浏览器进程被强杀，固件会保留最后一次目标直到停机。
• 自定义命令会绕过界面上的数值限制和部分安全联动（11,... 已被拦截），只发你确认过的内容；不带 @ 会自动补齐。
• 插件不主动拉高 DTR/RTS，避免复位 Arduino 类开发板；若设备需要 DTR 才发送数据，需要另行扩展。
• 当前固件 USE_WIRELESS_UART = 1，USB 调试口和无线口同时发波形；插件只读你选的 COM 口。

开发

• Host 端改动：修改 index.js 后在插件管理里禁用再启用该插件（或重启应用）。
• Client 端改动：刷新页面（Ctrl+R）加载新的浏览器端代码。
• 语法检查：node --check index.js / node --check client.js。