请前往：

https://gitee.com/fjiqiren3/linkzajiaozhunxitongzhunxitong

以获得更佳的阅读体验

完整资料备份（百度网盘）：https://pan.baidu.com/s/5kqMDdNAPQb1AMkCb9jJEFQ （包含打包好的上位机、演示视频等大文件，仓库中未收录的内容以网盘为准）

gitee不方便放视频，我在这放几个当时测试时的视频吧

后面的就和gitee上的README.md一样了。

超电三端自动校准系统 · 完整使用与原理文档

版本：2026-07-21
开发者：黎忠
系统组成：上位机 LinkZap（Python/PyQt5）+ 被校端超电固件 + 电源端超电固件
硬件平台：两块 STM32F334C8Tx 超电控制板（FSBB 四开关 Buck-Boost 双向 DCDC）
本文档是唯一随开源发布的文档，包含使用说明、硬件接线、通信协议、固件原理、上位机架构、常见问题全部内容。

开源包内容说明

路径	内容
`supercap-calibrator/`	上位机 LinkZap 源码（Python/PyQt5，开发者用）
`LinkZap.zip`	打包好的上位机 exe（解压后双击 LinkZap.exe 即用，无需 Python 环境，普通用户只用这个）
`V1.1板恒功率V3.1 -矫正用的电源端超电/`	电源端超电固件源码（Keil 工程，编译烧录到电源端板子）
`V1.1板恒功率V3.1 -被矫正端的超电/`	被校端超电固件源码（Keil 工程，编译烧录到被校板）
`使用演示（无声音介绍）/`	使用演示视频：一路电流校准的完整流程实录（无配音，配合本文档第 5 章观看）
`超电三端校准系统_开源说明文档.md`	本文档
SCH_InfiniteCap_Control_Ver1.1_2026-07-25.pdf	超电控制板（上板）原理图
SCH_InfiniteCap_Power_Ver1.1_2026-07-25.pdf	超电功率板（下板）原理图

普通使用者：只需 LinkZap.zip + 两块烧好固件的板子。二次开发者：固件用 Keil 打开编译（0 Error），上位机源码见第 4.2 节从源码运行。第一次接触本系统：建议先看使用演示（无声音介绍）/ 里的电流校准实录，再按第 5 章操作。

第一部分：使用说明

1. 系统简介

超电控制板用 ADC 采样电压/电流，但每块板子的元器件存在个体差异，测量值有误差。本系统用一块电源端超电板作为可编程激励源，输出一系列标准电压/电流（1–24V、0–9A 逐点扫描）；被校板在每个点记录自己的 ADC 读数，与真实值（万用表读数）对比后拟合出修正系数，从而校准每个采样通道。

系统由三部分组成：

电源端超电板：提供校准所需的电压/电流激励源，内含 PI 控制环实现恒压/恒流输出，自动扫点
被校端超电板：待校准的板子，采集实际电压/电流值并存储校准数据（RAM 中 18 个数组）
上位机 LinkZap：PC 端软件，通过 SWD 连接被校端，负责流程控制、数据导出，以及 OCR/录像（测试功能）

两块 STM32F334C8Tx 通过 USART1 通信，上位机通过 SWD 连接被校端。

1.1 超电控制板硬件简介

超电控制板基于同步 Buck-Boost 双向 DC-DC 拓扑（FSBB 四开关），最高可持续输出 24V/10A，可在裁判系统功率限制下为底盘电机提供超额瞬时功率。主控 STM32F334C8T6 带 HRTIM 高精度定时器，控制环在 HRTIM 中断中执行 PI 运算并更新占空比，实现真正的数字化电源控制。PCB 采用控制板 + 功率板分板设计，控制板通过排针排母叠在功率板上，既减少功率电路对控制电路的干扰，又缩小了体积。方案在性能、成本与可靠性间做了精细权衡：栅极驱动选用 UCC27201，MOS 选用 CSD18540，性能对实际场景有足够冗余且成本更低。

1.2 校准通道总览

共 9 个通道（CH0–CH8）：3 路电压 + 3 路电流的正反两个方向。

ch	通道名	类型	扫点范围	步进	点数	ADC 源	接线说明
0	VcapA	电压	1–24V	1V	24	SADC.VcapA_Avg	鳄鱼夹接 VcapA 采样点
1	VcapB	电压	1–24V	1V	24	SADC.VcapB_Avg	鳄鱼夹接 VcapB 采样点
2	Vreferee	电压	1–24V	1V	24	SADC.VrefereeAvg	鳄鱼夹接 Vreferee 采样点
3	IcapA	电流·正向	0–9A	1A	10	SADC.IcapA_Avg	串联进 IcapA 采样回路
4	IcapA	电流·负向	0–9A	1A	10	SADC.IcapA_Avg	对调极性后串联进 IcapA
5	IcapB	电流·正向	0–9A	1A	10	SADC.IcapB_Avg	串联进 IcapB 采样回路
6	IcapB	电流·负向	0–9A	1A	10	SADC.IcapB_Avg	对调极性后串联进 IcapB
7	Ireferee	电流·正向	0–9A	1A	10	SADC.IrefereeAvg	串联进 Ireferee 采样回路
8	Ireferee	电流·负向	0–9A	1A	10	SADC.IrefereeAvg	对调极性后串联进 Ireferee

电压校准：鳄鱼夹直接夹到采样点即可（高阻抗，不构成回路）。电流校准：需要把电源端输出串联进被校端的电流采样回路，接线由用户自行处理；负向通道把正负极对调。

2. 硬件准备与接线

2.1 器材清单

器材	数量	用途
超电控制板	2	一块烧电源端固件，一块烧被校端固件
30V/2A 以上直流电源	1	给电源端 A 端（电管端）供电（校准最高输出 24V，输入需留余量）
SWD 调试器	1	ST-Link / J-Link / DAPLink / WCH-Link 等，接被校端
杜邦线	2	两板 USART1 交叉连接（PB6↔︎PB7）
鳄鱼夹线	2	电源端 B 端（电容端）输出接到被校端采样点/电阻
万用表	1	读取真实电压/电流，人工填入上位机
校准电阻	若干	电流校准时作为负载（1A 以下与 2–9A 用不同档位）
USB/IP 摄像头	1（可选）	OCR 自动读万用表 + 录像（测试功能，见第 6 章）

2.2 整体连接图

┌─────────────┐         ┌─────────────┐         ┌─────────────┐
│   上位机PC   │  SWD    │  被校端超电  │  UART   │  电源端超电  │
│  (LinkZap)  │◄───────►│  STM32F334  │◄───────►│  STM32F334  │
│ - GUI控制    │         │ - 存储校准   │         │ - PI控制环   │
│ - 变量/波形  │         │   数据       │         │ - 恒压/恒流  │
│ - OCR/录像   │         │ - 转发命令   │         │   输出       │
└─────────────┘         └─────────────┘         └─────────────┘
      │                                              │
      │ USB 或 WiFi                                  │ B端(电容端)鳄鱼夹
      ▼                                              ▼
┌─────────────┐                              ┌─────────────┐
│ 摄像头(可选)  │                              │ 采样点/校准电阻│
│ USB摄像头/   │                              └─────────────┘
│ 手机无线摄像头│
└─────────────┘

2.3 关键接线

两板之间（USART1，必须交叉 + 共地）：

连接	引脚	说明
被校端 TX → 电源端 RX	PB6 → PB7	命令帧（0xAA 开头）
电源端 TX → 被校端 RX	PB7 → PB6	数据帧（0xBB 开头）
共地	GND ↔︎ GND	必须共地，否则通信必败

电源端（注意 A/B 端不要接反）：

电管端(A端) ← 30V/2A 以上直流电源正负极（底盘/Referee 侧；必须给 A 端供电，电源端才能工作）
电容端(B端) → 鳄鱼夹（红接 B+，黑接 B-）→ 被校端采样点 / 校准电阻（超电侧，校准输出端）

被校端：

SWD ← 调试器（3.3V/GND/SWDIO/SWCLK）
24V 电源 ← 可选（调试器供电不足时额外供电）

2.4 安全注意

电源端上电后 B 端（电容端）即有输出：空闲模式也有最小占空比 PWM（接近 0V），上电前确认鳄鱼夹没有短路
电流校准功率不大，但仍要留意发热：1A 及以下时回路功率 ≈ I²×R（串联的校准电阻）；1A 以上时负载主要是超电内部 5mΩ 采样电阻，P ≈ I²×5mΩ（9A 时也仅约 0.4W）。真正要确认的是校准电阻自身的额定功率（1A 档电阻在 1A×1A×R 下的发热）
换接线前先确认校准完成或已停止：扫点过程中换线可能导致输出异常
1A 暂停后必须换电阻再继续：0–1A 用小电流档电阻，2–9A 必须更换为大电流档电阻

3. 固件编译与烧录

用 Keil MDK 分别打开两个工程：

固件	工程路径	烧录后
电源端	`V1.1板恒功率V3.1 -矫正用的电源端超电/.../MDK-ARM/PI-ILoop.uvprojx`	不需要调试器，24V 直接供电运行
被校端	`V1.1板恒功率V3.1 -被矫正端的超电/.../MDK-ARM/PI-ILoop.uvprojx`	保持 SWD 调试器连接（上位机要用）

编译，确认 0 Error
用调试器分别烧录两块板
每次重新编译被校端后，上位机必须重新导入最新的 .axf（变量地址会变）

4. 上位机安装与功能

4.1 方式一：使用打包好的 exe（推荐普通用户）

下载发行版的LinkZap.zip，将 LinkZap/ 整个文件夹解压到任意位置
双击 LinkZap.exe 即可运行，无需安装 Python
首次使用摄像头 OCR 功能需下载 PaddleOCR 模型（约几十 MB，一次性，存到用户目录 .paddleocr/）：点「连接摄像头」时会先弹窗询问是否下载，确认后才联网；模型已下载或不用 OCR 功能则不会弹窗也不会下载

4.2 方式二：从源码运行（开发者）

环境要求：Python ≥ 3.10，Windows 10/11。

cd supercap-calibrator
pip install -r requirements.txt
python main.py

依赖版本红线（装错必崩）：

paddlepaddle==2.6.2
paddleocr==2.7.0.3
numpy>=1.20,<2.0      # PaddlePaddle 2.6 与 numpy 2.x 不兼容
opencv-python>=4.5
pyocd>=0.35           # SWD 调试
PyQt5>=5.15

调试器支持：基于 pyOCD 生态，SWD 模式支持 ST-Link、J-Link、DAPLink/CMSIS-DAP、WCH-Link 等常见调试器。其中 WCH-Link 的 8 位读写必须走 32 位对齐方式，上位机已做兼容处理。驱动方面：DAPLink/CMSIS-DAP V1 免驱；V2 需 Zadig 装 WinUSB；ST-Link 需装 STSW-LINK009；J-Link 需装 J-Link 驱动包。

4.3 上位机功能总览（不止是校准工具）

LinkZap 是一个通用的嵌入式调试上位机，校准只是它的功能之一：

三种互斥数据源（同一时间用一种，切换自动停止当前采集）：

数据源	适用场景	说明
SWD 调试器	开发调试	固件零改动，MCU 运行时直接读写 RAM 全部变量（含结构体成员），支持暂停/恢复 MCU（等价 Keil 停止/开始调试）
串口 (VOFA)	现场监控	兼容 JustFloat / FireWater / CSV 三种协议，通道数自动检测，支持 HEX/ASCII 发送、定时自动发送、断线重连
CAN 总线	车载/工业	支持 CAN FD，多 ID 组装，支持 PCAN / 周立功等硬件，可发送数据

实时波形：勾选任意变量即可看实时曲线（类 VOFA），支持多变量同图、十字光标读数、采集间隔可调。SWD 模式下支持 watch_block 结构体单次事务批量读取（5–10Hz → 几百 Hz），固件侧接入方法详见第 15.4 节。

虚拟变量（创新功能）：用数学公式基于已有变量创建新变量，如 P=U*I、U=I²*R，复杂计算在上位机完成，不占用 MCU 性能。支持链式引用——虚拟变量 A 可以引用虚拟变量 B，实现多变量叠加分析。虚拟变量同样能上波形。

变量读写：导入 .axf 后自动解析全部全局变量（DWARF 类型信息，含结构体/数组成员），可搜索、可实时查看、可修改写入。

MCP 远程控制（⚠️ 测试阶段，使用效果未知，暂不建议依赖）：内置 MCP 服务器（http://127.0.0.1:8765/sse），暴露 5 个只读资源和 11 个可执行工具，AI 助手（如 Claude Desktop）可通过自然语言指令远程启动/停止校准、读写变量、控制波形和 MCU 运行状态。

PID 整定面板（⚠️ 测试阶段，使用效果未知，暂不建议依赖）：配合电源端固件内置的继电反馈/阶跃法自动整定，可视化调参并把结果写回控制环。

4.4 界面布局

顶部工具栏：导入 .axf、调试器选择/连接、MCU 暂停/恢复、MCP 服务开关
Tab 1「校准控制」：左列为校准控制（通道/按钮/进度/导出）+ 万用表 OCR 面板；右列为校准数据表格。左右比例默认 4:6，中间分割条可拖拽调节
Tab 2「变量监控」：数据源切换栏 + Watch 变量列表/实时波形 + 底部串口/CAN 数据面板

5. 校准操作全流程

5.1 基本流程

按第 2 节接好线（电源端 A 端接 30V/2A 以上电源供电，两板 UART 交叉 + 共地，电源端 B 端输出接到目标采样点/电阻）
上位机点「导入 .axf」，选择被校端固件编译出的 .axf
选择 SWD 调试器，点「连接」
在「校准控制」Tab 选择通道（如 CH0: VcapA）
点「开始校准」：
电流通道（CH3–8）特有流程：0A、1A 两点完成后自动暂停并弹窗，提示更换电阻；换好后点「继续校准」，自动从 2A 扫到 9A
校准完成（被校端绿灯常亮、状态显示完成）后，点「导出校准数据」导出 CSV 或 xlsx
换线、换通道，重复 4–7

5.2 表格列含义

列	含义
序号	校准点序号
实际值	真实电压/电流（人工看万用表填入，或 OCR 读数）。未填入时该列是固定的目标值本身（电压通道 1–24V、电流通道 0–9A 的设定点），不是任何测量值
ADC实际值	被校端按当前系数换算出的测量值（应逼近实际值）
ADC原始值	被校端 ADC 原始读数（拟合系数的依据）

「实际值」列可以手动双击修改——看万用表读数手工填入，ADC实际值列会自动重算。这是目前推荐的使用方式。

5.3 时间估算

电压通道（CH0–2）：24 点 × 约 3.5 秒 ≈ 1.5 分钟
电流通道（CH3–8）：10 点 + 1A 暂停换电阻 ≈ 1 分钟 + 人工操作时间

6. 摄像头 OCR 与录像（测试阶段）

⚠️ 本章功能目前处于测试阶段：实测 OCR 对万用表 LCD 的识别效果较差（光线/角度敏感，数码管字体易误识别），暂不建议依赖。当前推荐的使用方式是人工看万用表、手动填「实际值」列。本章内容供愿意试用的用户参考，也欢迎改进。

6.1 摄像头连接方式

OCR 面板的摄像头下拉框有三个选项：「USB 摄像头 0」「USB 摄像头 1」「IP 摄像头（手动输入）」。

USB 摄像头：直接插电脑，选「USB 摄像头 0」（多个摄像头时试 1）
手机当摄像头（WiFi，IP 摄像头方式）：手机安装 IP 摄像头类 App，手机和电脑连同一 WiFi，App 会给出 http://手机IP:端口/video 的地址，填入即可。常用 App：
手机当摄像头（USB 线方式）：手机 App + 电脑客户端配对，连接后在电脑上表现为一个普通 USB 摄像头，按 USB 摄像头选择即可

推荐方案（本项目开发者实测可用）：iVCam（免费，Android/iOS 均有）。手机装 iVCam App + 电脑装 iVCam 客户端，支持 WiFi 无线和 USB 线两种连接；连接成功后电脑上会出现一个标准摄像头设备，上位机按「USB 摄像头」选择即可。无线方式手机摆放自由，适合把镜头架在万用表上方。

6.2 OCR 自动读数

连接摄像头，对准万用表
点「框选 LCD 区域」，在预览画面上拖拽框住万用表的数字显示区
勾选「自动填入校准值」
开始校准后，每个点稳定时自动拍照识别，读数填入「实际值」列

OCR 引擎为 PaddleOCR 深度学习模型，支持倾斜校正、负号、小数点，内置常见误识别修正（O→0、l→1、S→5 等）和过载检测（OL/Err 不填表）。

排查识别问题：勾选「调试模式（保存中间图像）」，实际送进识别的裁剪图会存到 ocr_debug/ 目录——图模糊/反光/框偏是拍摄问题，图清晰但读错是模型问题。平时不要勾，会产生大量图片。

6.3 录像

勾选「校准自动录像」（默认不勾）后，开始校准时自动录像，完成/停止时自动停止
1A 暂停期间录像不中断，两段录入同一文件
文件位置：程序当前目录 calibration_videos/cal_ch{通道}_{时间戳}.avi（XVID，20fps）
中文路径下 Windows 的 OpenCV 会录像失败，程序会弹窗明确提示（校准本身不受影响）；如需录像请把程序放到纯英文路径
已知问题：OCR 识别期间（CPU 推理数秒）录像会断帧，待后续版本修复

6.4 完全不用摄像头（推荐方式）

不连接摄像头、不勾任何选项，校准照常进行：每个点上位机自动放行，表格「实际值」列先填目标值，校准过程中或完成后人工对照万用表逐点修改「实际值」列，再导出数据。

7. 校准数据处理（拟合系数）

导出的 CSV/xlsx 包含每个通道的「实际值—ADC原始值」数据对。用 Excel 或计算器做线性拟合：

y = k × x + b
  x = ADC原始值（cal_adc 数组）
  y = 实际值（cal_actual 数组）

求出 k（斜率）和 b（零点偏移）后，填回生产固件（如 V4.2 系列）function.c 的 ADCSample() 中对应通道的换算系数，重新编译烧录。目前这一步为人工完成。

电流通道使用"过零点"拟合（实际ADC = (测量ADC − 零点ADC) × k），因为带偏移 b 的拟合在 0A 时测量值不为 0。零点 ADC 就是电流校准第 0 点（0A）的 ADC 原始值。

8. LED 指示灯含义

电源端：

LED	状态	含义
红灯	持续翻转	系统运行中（心跳）
绿灯	翻转	收到被校端命令

被校端：

LED	状态	含义
绿灯	翻转	正在接收扫点数据
绿灯	常亮	校准完成
绿灯	不亮	空闲

9. 常见问题 FAQ

现象	排查
SWD 连接失败	检查 SWD 四线；确认调试器驱动（见 4.2 节）
校准启动超时（5 秒）	① MCU 是否在运行（非暂停态）② 导入的 .axf 是否为被校端最新固件 ③ 两板 UART 是否 PB6↔︎PB7 交叉且共地
校准中途卡住（120 秒无新点）	接线大概率正常（否则启动即失败）。优先查：负载电阻是否接对/接触良好、电源端输出是否能稳住
表格 ADC 全是 0	电源端输出没接到被校端对应采样通道（若是把电源端接电阻自测输出，则属正常现象）
OCR 识别失败/不准	该功能处于测试阶段，效果较差属已知情况；建议改人工填值
没有录像文件	是否勾了「校准自动录像」；是否看到录像失败弹窗（中文路径）；磁盘空间
exe 首次 OCR 很慢	首次需下载约 100MB PaddleOCR 模型（一次性），且模型加载需几秒
想暂停看看数据	工具栏「暂停 MCU」按钮，等价 Keil 停止调试；再继续即可

第二部分：原理与代码

10. 系统架构与职责划分

上位机 (Python/PyQt5)                被校端 (STM32F334)              电源端 (STM32F334)
├─ 流程编排：写 cal_start 启动/停止/恢复   ├─ 边沿检测 cal_start，转发命令    ├─ CalLoopCtl() PI 闭环
├─ 轮询 cal_wait_host，逐点放行          ├─ 收 0xBB 帧存入 18 个校准数组    │   恒压/恒流/零点采集
├─ 人工/OCR 填实际值、导出数据           ├─ 每点置 cal_wait_host=1 等放行   ├─ CalScanStateMachine()
├─ 变量读写、波形、录像                  ├─ 放行后发 start=3 给电源端       │   5ms 状态机逐点扫描
└─ MCP 远程控制                        └─ 完成置 cal_status=2 绿灯常亮    └─ 每点稳定后暂停等 start=3
        │  SWD 读写 RAM（pyOCD）                │  USART1 0xAA/0xBB 帧        │
        └──────────────────────────────────────┴─────────────────────────────┘

核心设计思想：时序闭环全部在固件里，上位机只做编排和读数。 电源端管"稳"（PI 闭环 + 扫点状态机），被校端管"记"（存数组 + 等放行），上位机管"放行和填表"。这样即使上位机崩溃或断开，固件也只是停在等待态，不会失控输出。

11. UART 通信协议

两板之间 USART1，115200 8N1。协议实现位于两端固件的 Core/Src/caaan.c（由 CAN 改造而来，文件名是历史遗留）。

11.1 命令帧（被校端 → 电源端，4 字节，0xAA 开头）

字节	内容	说明
0	0xAA	帧头
1	ch	通道号 0–8
2	start	1=开始，0=停止，2=从暂停点恢复，3=继续下一点
3	checksum	前 3 字节 XOR

11.2 数据帧（电源端 → 被校端，6 字节，0xBB 开头）

字节	内容	说明
0	0xBB	帧头
1–2	actual_val × 10	int16 小端（如 12.5V → 125）。注意：该值是电源端的目标值（setpoint），不是电源端的实测值
3	point_idx	点序号
4	status	0=扫点中，1=该点稳定，0xFE=电压信息帧，0xFF=全部完成
5	checksum	前 5 字节 XOR

0xFE 电压信息帧：start=1 启动时电源端发送一次，actual_val = 电源端 Vreferee×10（这个是真实测值），被校端存入 cal_vref，供上位机检查输入电压。start=2 恢复时不重发。

健壮性设计：定长帧收满即复位接收状态，丢字节最多错一帧自愈；ORE/NE/FE 串口错误有恢复处理；已知待改进——校验是 XOR 而非加和（对双字节同位翻转漏检），如改加和必须两端同步修改并一起重烧。

12. 电源端固件详解

核心文件：Core/Src/function.c（状态机）、Core/Src/CtlLoop.c（控制环）。

12.1 扫点状态机 `CalScanStateMachine()`

运行在 TIM3 中断（5ms 周期），状态流转：

CAL_IDLE → CAL_RAMP → CAL_STABLE → CAL_NEXT → (下一点) ... → CAL_DONE → CAL_IDLE

状态	行为
CAL_IDLE	等 start=1（全新开始：电压 1V 起 24 点 / 电流 0A 起 10 点，先发 0xFE 电压帧）；start=2（恢复：保留点序号）；start=3（回发 DONE 帧兜底，防双向死锁）
CAL_RAMP	更新 `cal_setpoint`（= 点序号，1V/1A 步进），等 600 tick（3 秒）让输出稳定；电流第 0 点用零点采集模式
CAL_STABLE	发 0xBB 稳定帧后暂停，等 start=3；2 秒没等到重发数据帧（防丢帧死锁）；控制环继续运行保持输出
CAL_NEXT	点序号 +1，未完回 RAMP，完成进 DONE
CAL_DONE	以 100ms 间隔重发 3 次 DONE 帧，再等 100ms 退出

任意状态收到 start=0（停止）：立即清积分、停输出、回 IDLE。

12.2 校准控制环 `CalLoopCtl()`

运行在 HRTIM 中断（50kHz），四种 cal_mode：

cal_mode	含义	反馈	目标值
1	恒压	`SADC.VcapB_Avg`（B 端=电容端=输出端）	`cal_setpoint × 4096 / 39.6`（或查表）
2	恒流	`SADC.IcapB_Avg`	`cal_setpoint × 4096 / 33.0`（或查表）
3	零点采集	—	完全关断 HRTIM，四 MOS 全关（电流 0A 点用）
0	空闲	—	占空比压到最小

PI 结构（增量式）：

i0 = Cal_Integral + Err * KP;      // 输出 = 积分量 + KP×误差
Cal_Integral += Err * KI;          // 积分量累加
// 积分限幅 [MIN_BUCK_DUTY<<12, MAX_BUCK_DUTY<<12]
// 输出限幅 [MIN_BUCK_DUTY, MAX_BUCK_DUTY]
// Buck 占空比写入 HRTIM TimerA CMP1；Boost 固定上管 93%/下管 7%

PI 参数（变量，可 SWD 在线修改，默认值参考 PID_test 实测）：

参数	默认值	用途
`cal_v_kp` / `cal_v_ki`	50 / 5	恒压环
`cal_i_kp` / `cal_i_ki`	5 / 2	恒流环

调参经验：输出震荡→减 KP 加 KI；响应慢→加 KP；稳态有静差→加 KI。

离散校准表：CAL_MODE==1 时启用 cal_v_target_adc[25] / cal_i_target_adc[11]，按整数点查表替代公式，未校准点（值为 0）回退公式。表在 RAM 中可在线修改。

PID 自动整定：内置继电反馈/阶跃法（pid_autotune 变量组控制），整定时接管控制环输出，完成后把 kp/ki 写回校准环参数。上位机有对应整定面板。

12.3 ADC 采样与保护

ADCSample()（HRTIM 触发的 PWM 中点采样，EMA 指数平均 α=1/4）将 ADC 原始值换算为物理量：电压 ×39.6/4096（3.3V 基准 ×12 倍分压），电流 ×33.0/4096（±16.5A 量程）。电源端的 ADC 系数（4181/3999 等）是已校准的。

VIUVP() 提供过压/过流/电容过放保护和 CAN 超时保护（校准系统中 CAN 停用，setpower 恒 0）。注意：这些保护只作用于原恒功率环 VILoopCtlP()，校准环 CalLoopCtl() 不看 error 标志——校准输出不受保护拦截，接线错误时靠人工停止。

13. 被校端固件详解

核心文件：Core/Src/function.c。

13.1 校准数据存储（18 个数组，RAM）

float   cal_actual_VcapA[32]; ... // 9 个：电源端实际值（每通道一个）
int32_t cal_adc_VcapA[32];    ... // 9 个：被校端 ADC 原始值

上位机经 SWD 直接读这些数组。注意：数据在 RAM 中，掉电即失；一个通道扫完先导出再扫下一个（下次校准会覆盖）。

13.2 SWD 控制变量（上位机的接口）

变量	方向	含义
`cal_start`	上位机写	1=开始，0=停止，2=恢复；边沿触发，完成自动归 0
`cal_ch`	上位机写	通道号 0–8（cal_start=0 时设置）
`cal_status`	上位机读	0=空闲，1=扫点中，2=完成
`cal_point_cnt`	上位机读	已记录点数
`cal_wait_host`	双方	固件置 1=等放行；上位机写 0=放行
`cal_vref`	上位机读	电源端输入电压（0xFE 帧）
`cal_send_cnt`/`cal_rx_cnt`	调试	发送/接收帧计数

13.3 校准处理 `CalTargetProcess()`

运行在 TIM3 中断末尾，三件事：

边沿检测 cal_start：上升沿发 0xAA 命令帧（1=全新开始并清 cal_point_cnt，2=恢复保留点序），下降沿发停止帧。上位机只写一个变量即驱动全流程
收 0xBB 帧：稳定帧按 cal_ch 存入对应数组对，cal_point_cnt = idx+1，然后无论 idx 是否合法都置 cal_wait_host=1（防 idx≥32 时永久死锁）；DONE 帧置 cal_status=2、cal_start=0、绿灯常亮
放行检测：cal_waiting && cal_wait_host==0 && cal_start!=0 时向电源端发 start=3（cal_start!=0 守卫防止停止后残余放行）

13.4 ADC 采样

结构与电源端相同，但 EMA 系数 α=1/16（更慢更稳——被校端要精度不要速度），电流零点基准 2048。源码中以 #if 0 保留了块平均、去极值均值两套备选滤波。被校端的 ADC 系数全是未校准的原始值（4096/2048）——这正是要被校准的对象。

14. 方案B逐点暂停握手机制

这是三端协作的核心时序，确保每个校准点都有机会读万用表：

电源端稳定 3 秒 → 发 0xBB 稳定帧（CAL_STABLE 停等）
被校端存数据   → cal_wait_host=1（CalTargetProcess 停等）
上位机轮询发现 → 有 OCR：识别填表后写 cal_wait_host=0
                 无 OCR：立即写 cal_wait_host=0
被校端发现放行 → 发 start=3 → 电源端 CAL_NEXT 走下一个点

全部异常路径的兜底（任何一端掉链子都不死锁）：

异常	兜底
0xBB 稳定帧丢失	电源端 2 秒重发
DONE 帧丢失	100ms×3 重发；被校端补发 start=3 时电源端 IDLE 态回发 DONE
OCR 识别超时/失败	6 秒超时自动放行，该点用电源端回报值
校准中断开摄像头	立即放行固件
上位机关闭	closeEvent 先写 cal_start=0 停输出
校准卡死	上位机 120 秒无新点报错退出
start=0 停止	电源端任何状态立即回 IDLE

15. 上位机代码架构

supercap-calibrator/
├── main.py                      # 入口
├── requirements.txt             # 依赖（版本红线见 4.2 节）
├── supercap_calibrator.spec     # PyInstaller 打包配置
└── src/
    ├── core/
    │   ├── calibration.py       # 校准流程控制器（见下）
    │   ├── workers.py           # 后台轮询线程（见下）
    │   ├── swd_interface.py     # SWD 读写（pyocd；u8 走 32 位对齐，WCH-Link 兼容）
    │   ├── axf_parser.py        # .axf/ELF + DWARF 解析，变量名→地址/类型
    │   ├── multimeter_ocr.py    # PaddleOCR 万用表识别
    │   ├── camera_worker.py     # 摄像头线程：预览/OCR 触发/录像
    │   ├── serial_interface.py  # 串口 + VOFA 协议（JustFloat/FireWater/CSV）
    │   ├── can_interface.py     # CAN 总线接口（支持 CAN FD）
    │   ├── mcp_server.py        # MCP 远程控制（5 只读资源 + 11 可执行工具）
    │   ├── pid_autotune.py      # PID 整定面板后端
    │   ├── csv_exporter.py / xlsx_exporter.py  # 数据导出
    └── gui/
        ├── main_window.py       # 主窗口（校准编排/OCR/录像/监控，约 5000 行）
        └── pid_dialog.py        # PID 整定对话框

15.1 `calibration.py` — CalibrationController

start(ch) / resume(ch)：先写 cal_start=0 等 10ms（让固件更新边沿检测），再单次 write32 原子写 cal_ch + cal_start（两变量在同一 32 位字，避免与 TIM3 中断竞争；WCH-Link 在 halt 态写入会丢，必须运行态写）
read_results(ch)：读 32 点数组后按通道裁剪——电压通道跳过 idx0（1V 起）、电流通道含 0A 零点、负向通道（4/6/8）实际值取负（统一拟合公式）

15.2 `workers.py` — CalibrationPoller（200ms 轮询）

启动检测：cal_send_cnt 变化（5 秒超时，报错提示查接线和 .axf 版本）
完成判定：status==2 或 point_cnt ≥ 阈值（电压通道阈值 = 点数+1）
停止判定：status==0 且 point_cnt>0
卡死判定：120 秒无新点 → 报错退出
另有 WaveformPoller（支持 watch_block 结构体单次 SWD 事务批量读，比逐变量快得多）和 AutotunePoller

15.3 OCR 与录像模块（测试阶段）

multimeter_ocr.py：ROI 裁剪 → PaddleOCR（方向分类器支持倾斜）→ 多帧投票（5 帧）；字符修正表（O→0、l→1、S→5、B→8、Z→2、D→0、g→9）；过载检测在字符替换之前（OL/Lo/Err → None 不填表）；多小数点粘连修正（1.234.5→1234.5）
camera_worker.py：预览 100ms 刷新；trigger_read() 触发一次识别（5 秒内部超时）；录像 XVID 20fps，文件名纯 ASCII；VideoWriter 创建失败发 error 信号（GUI 弹窗提示，不再静默）

15.4 watch_block：SWD 批量高速读取（波形加速）

解决什么问题：SWD 模式下看实时波形，默认"逐变量"方式每个变量一次 SWD 事务，N 个变量就是 N 次往返，实际只有 5–10Hz，看快信号完全不够。watch_block 把要看的变量打包进一个结构体，上位机一次 SWD 事务读整块内存再按成员偏移拆解，速率可到几百 Hz。

固件侧怎么用（三步）：

在 function.h 定义结构体和全局变量（名字必须叫 watch_block，必须是全局变量）：

// 用户可自由增删成员，上位机从 .axf 自动解析成员列表
typedef struct {
    float VcapA;
    float IcapA;
    float PcapA;
    float setpower;
    float VcapB;
    float Vreferee;
    float Ireferee;
    float Preferee;
    float Pchassis;
} WatchBlock;

extern volatile WatchBlock watch_block;

在 function.c 定义实体，并在定时更新的地方（如 ADCSample() 末尾）刷新成员：

volatile WatchBlock watch_block;

void ADCSample(void) {
    // ... 原有采样计算 ...
    watch_block.VcapA = VcapA;
    watch_block.IcapA = IcapA;
    // ... 其余成员 ...
}

重新编译，上位机重新导入 .axf——上位机通过 DWARF 调试信息自动解析成员名/偏移/类型，检测到 watch_block 后状态栏提示"SWD 批量模式可用"并自动切到批量。

上位机侧：数据源选 SWD，「SWD模式」选"批量"（该选项任何时候都可修改；无 watch_block 时选批量会自动回退逐变量）。Watch 列表里以 watch_block.成员名 引用成员（导入 .axf 后成员自动出现在变量树里），勾选即可上波形。非 watch_block 的普通变量在批量模式下仍走逐变量读取，可混用。

注意事项：

成员类型支持 float / (u)int8 / (u)int16 / (u)int32 / double；成员增删后只需重新编译 + 重新导入 .axf
结构体布局（含对齐填充）由编译器决定，上位机按 DWARF 解析，不要手动假设偏移
固件刷新 watch_block 与上位机读取无互斥，波形显示允许偶发 tearing（监控用途可接受）；要求一致性的场合请在 MCU 暂停态读取

16. 构建、打包与依赖

cd supercap-calibrator
pip install -r requirements.txt   # 注意版本红线（4.2 节）
build.bat                          # 或 pyinstaller supercap_calibrator.spec --noconfirm

输出 dist/LinkZap/（约 640MB），整个文件夹打成 zip 即可分发，用户解压双击 exe。PaddleOCR 模型不随 exe 打包，首次使用 OCR 时自动下载约 100MB（存到用户目录 .paddleocr/）。

17. 校准系统的可迁移性（换板子能用吗）

结论：可以迁移，换一块同型号板子照样能用。 三端各自的可迁移性如下：

端	可迁移性	说明
电源端固件	与板子无关（前提是这块板自身已校准）	任何一块 ADC 系数已校准的超电板烧上电源端固件，就能当激励源。它不依赖具体某块板
被校端固件	烧到谁身上就校准谁	同型号硬件（同 PCB、同引脚）的新板子直接烧被校端固件即可；不同硬件（引脚/ADC 通道不同）需适配 `ADCSample()` 和 CubeMX 配置
上位机	完全通用	变量地址靠导入该板的 .axf 自动解析（DWARF），换板子只需重新导入新编译的 .axf，上位机代码零改动

整套流程对新板子是可复制的：新板烧被校端固件 → 上位机导入它的 .axf → 跑校准导出数据 → 把拟合出的系数填回这块板自己的生产固件（V4.2 系列）ADCSample() → 重新编译烧录。事实上"5 号板 / 董源板"两个 V4.2 实例就是这样来的——同一份代码，只差各自校准出的 VcapB 系数。

唯一不具备迁移性的是校准结果本身：系数是每块板的"指纹"，不能互用。

17.1 换主控 / 全新板子的迁移清单

如果未来重做板子（引脚、主控都变），校准代码按"平台无关 / 硬件相关"分两类：

直接抄走（平台无关，约占校准代码 70%）：

UART 协议本身：0xAA/0xBB 帧格式、start 命令字、status 含义、XOR 校验，与硬件无关
被校端 CalTargetProcess() 全部逻辑：18 个校准数组、cal_* 变量组、边沿检测、稳定帧存数、cal_wait_host 等放行
电源端 CalScanStateMachine() 状态机：IDLE/RAMP/STABLE/NEXT/DONE 及全部重发兜底逻辑
上位机：零改动。只要新固件保持 cal_* 变量同名同类型，导入新 .axf 即可用（pyOCD 支持绝大多数 ARM Cortex-M；换非 ARM 主控才需重新评估）

必须重写（硬件相关，只有薄薄两层）：

电源端 CalLoopCtl() 的 PWM 操作部分：HRTIM 是 F334 特有外设，新芯片的 PWM 配置、占空比写入、ADC 触发点都要重来；但 PI 算法骨架（积分+限幅）可以抄
ADCSample()：ADC 通道映射、分压/量程系数由新板硬件决定
CubeMX 配置：引脚、时钟树、外设

迁移步骤（约 1–2 天）：

新工程配好：一个 5ms 定时中断、一个 UART（115200）、PWM 输出、ADC 采样
抄入 caaan.c/h、CalTargetProcess()、CalScanStateMachine()、cal_* 变量与 18 个数组（保持变量名不变）
重写 CalLoopCtl() 的 PWM 部分和 ADCSample()
编译出新 .axf，上位机导入即用

18. 备用方案：不用上位机（Keil 手动校准）

没有上位机时，可用 Keil 调试模式手动驱动（适合应急/单通道验证）：

进入 Debug（Ctrl+F5），开启「Periodic Window Update」——这是 Keil µVision 的"窗口周期刷新"功能（调试工具栏上的刷新图标，或 Debug 设置里的 Periodic Window Update 选项）。开启后 Watch 窗口会在 MCU 运行中周期性更新变量值，无需 halt 暂停。不开的话只能 halt 才能看到新值，而长时间 halt 期间电源端照常输出、UART 帧会丢，应避免
先写 cal_ch，再写 cal_start=1（顺序不能反：固件靠 cal_start 上升沿启动；上位机是原子写两个值，手动操作没这个保护）
每个点稳定后固件置 cal_wait_host=1 停等——手动把它写 0 放行（电压通道要放 24 次；忘了放不会出错，就是停着等）
cal_status=2（绿灯常亮）后，Watch/内存窗口读 cal_actual_xxx[] 和 cal_adc_xxx[] 数组，手动抄出（数组显示不全时右键在 Memory 窗口查看）
中途停止：cal_start 写 0

代价：无自动导出、无 OCR、无录像，结果全手抄。

19. 已知限制与待改进

项	说明
实际值来源	数据帧里的"实际值"是电源端的目标值（setpoint），真实值依赖万用表人工读取（OCR 功能在测试阶段，效果较差）
结果不持久	校准数组在 RAM，掉电即失；系数需人工拟合后填回生产固件重新编译
UART 校验	XOR 校验对双字节同位翻转漏检；改加和需两端同步改+重烧
数组读写竞争	上位机读数组与固件写数组无互斥（tearing）；目前靠"数组只增不改 + 完成后终读"规避，改为边校准边实时用数时需注意
OCR 期间录像	OCR 推理（CPU 数秒）在摄像头线程内同步执行，期间录像断帧（待重构为独立线程）
中文路径录像	OpenCV VideoWriter 会失败（已加弹窗提示）；程序放纯英文路径
无 UART 看门狗	通信中断会停在等待态，需人工停止
中断负载	TIM3(5ms) 中断内负载偏重（VOFA 打印约 3.5ms），校准期叠加发送有超周期风险

20. 参考项目与原创声明

本系统在底层驱动、硬件方案和部分功能交互上参考了以下公开项目与商业软件，在此说明并致谢；其上的三端校准架构、状态机、协议、上位机核心模块均为本项目原创（AI 辅助生成）。

20.1 上位机（LinkZap）参考的外部项目

参考对象	类型	参考方式	借鉴了什么
STM32CubeMonitor（ST 官方）	商业软件	技术路线验证 + 对标	SWD 非侵入式读写 RAM、从 ELF/AXF 解析变量、实时波形、on-the-fly 变量修改；本系统定位为其"轻量开源定制版"
SEGGER Ozone	商业调试器	功能差距分析	13 项功能对比矩阵，源码级调试/内存窗口/SVD 外设寄存器等设计参考
Serial-Studio（开源 C++/Qt6）	开源	功能借鉴	协议解析抽象、Quick Plot、HEX/ASCII 发送、发送历史、定时自动发送、行尾选项、帧率统计、自动重连
CieNTi/serial_port_plotter（开源）	开源	功能借鉴	通道名双击修改、通道可见性切换、COM 刷新、PNG 导出、14 色循环调色板（本项目扩展为 24 色）
VOFA+	商业软件	协议兼容 + 交互借鉴	JustFloat / FireWater / RawData 三协议实现；波形勾选、十字光标交互
SSCOM 串口助手	商业软件	发送面板借鉴	HEX/ASCII 双模式、发送历史、定时发送、发送文件、DTR/RTS 控制
pyOCD（开源）	开源库	API 参考	ConnectHelper、ELF 解析、MemoryInterface、FileProgrammer 等 SWD 通信接口
PaddleOCR（开源）	开源库	直接使用引擎	万用表 LCD 数字识别（方向分类器 + 深度学习模型），后处理逻辑为自研

20.2 固件参考的外部项目

参考对象	类型	参考方式
香港科技大学（HKUST）	队伍公开方案	硬件方案参考
深圳大学（SZU）RobotPilots 战队	队伍公开方案	硬件方案参考
哈尔滨工业大学（深圳）（HITsz）	队伍公开代码	CAN 通信框架参考
STM32F3xx HAL + CMSIS + CubeMX	ST 官方驱动	底层驱动
仓库内 PID_test(1) 子项目	内部项目	PI 参数标定

说明：未引用 ST 官方的 HRTIM Buck-Boost 控制例程（如 X-CUBE 或 AN 应用笔记）——控制环算法本身是自研，ST 资源仅作为 HAL 底层驱动。参考链接：港科大 HKUST：https://github.com/hkustenterprize/RM2024-SuperCapacitorController 深大 SZU RobotPilots 战队：https://b23.tv/NTn8VtV（B 站视频：超级电容控制器开源）哈工深 HITsz：暂无公开链接

20.3 首创部分（未找到外部参考）

以下模块为本项目原创设计，未参考任何现有项目或标准协议：

模块	归属	说明
三端校准系统整体架构	自研	电源端 + 被校端 + 上位机的三端协作模式，未见同类方案
CalScanStateMachine 状态机	自研	5 状态 FSM（IDLE/RAMP/STABLE/NEXT/DONE）+ 方案B 暂停握手 + 2 秒重传 + DONE 重发
0xAA/0xBB UART 校准协议	自研	自定义定长帧 + XOR 校验，非 Modbus 或任何标准协议
SWD 非侵入式校准	自研	通过 SWD 读写 MCU 内存变量控制校准流程，不占被校端任何调试资源
watch_block 批量读取	自研	固件定义 struct + 上位机一次 read 整块内存，把 SWD 波形采样率从 5–10Hz 提升到几百 Hz
虚拟变量	自研	类似 Excel 公式的链式引用，`^`→`**` 转换，math 函数支持，循环引用检测
PID 自动整定（三种算法）	自研	继电反馈 / 阶跃响应 / 梯度下降，通过约定变量名实现跨固件通用
PI 控制环算法	自研	位置式 PI + Q12 定点 + 积分/输出双限幅，未引用 ST 官方 AN 例程
方案B 逐点暂停等待机制	自研	固件每个稳定点暂停等上位机放行，配合 OCR 读数
AppBridge 线程安全桥	自研	GUI 主线程与 MCP 后台线程的 Event 同步通信机制
采样健康监测器	自研	读取耗时颜色指示（绿 <30% / 黄 30–60% / 红 >60%）
OCR 后处理逻辑	自研	字符修正表（O→0、l→1、S→5、B→8、Z→2、D→0、g→9）、过载检测、多点粘连合并
WCH-Link 兼容处理	自研	8 位读写用 32 位对齐实现（read-modify-write），绕过 WCH-Link 非对齐访问不可靠问题
CSV 跨会话追加导出	自研	`# ===== 通道 X =====` 分隔符追加模式

20.4 原创性总结

底子是外部的，上层是自研的：

底层驱动：ST 官方 HAL + CMSIS + CubeMX（常规做法）
硬件拓扑：参考 HKUST / SZU 公开方案
CAN 通信框架：参考 HITsz 公开代码
波形/串口交互：借鉴 Serial-Studio / VOFA+ / SSCOM
OCR 引擎：使用 PaddleOCR 开源库
其上整套三端校准架构（状态机、UART 协议、SWD 非侵入控制、watch_block、虚拟变量、方案B 暂停等待、PID 自动整定等）：本项目原创，且绝大部分代码由 AI 辅助生成（详见第 22 章）

21. 致谢

本系统的超电控制板硬件及基础固件由洪炯嘉、李智等长安大学 VGD 战队无限动力硬件组成员开发，上位机 LinkZap 与三端自校正系统在此基础上由黎忠完成开发。在此向他们以及以下提供了公开方案的队伍致谢：

洪炯嘉、李智等长安大学 VGD 战队 · 无限动力硬件组成员 — 超电控制板硬件设计与基础固件
香港科技大学 HKUST — 超级电容功率拓扑方案
深圳大学 SZU RobotPilots 战队 — 超级电容控制器开源方案
哈尔滨工业大学（深圳）HITsz — CAN 通信公开代码
PaddleOCR / pyOCD / Serial-Studio / serial_port_plotter 等开源项目 — 上位机依赖或借鉴的开源库

22. AI 使用情况说明

本项目在开发过程中大量使用了 AI 辅助编程，如实说明如下：

上位机（LinkZap）与三端自校正系统的绝大部分代码由 AI 编写（使用的工具包括但不限于 TRAE、Claude、Kimi 等）
人工负责：需求定义、硬件接线与实机测试、关键设计决策、代码审查与验收
部分模块（OCR 识别、录像、MCP 远程控制等）尚未经过充分实机验证，已在本文档相应章节如实标注"测试阶段"

使用本项目代码时请注意：AI 生成的代码可能存在尚未发现的问题，涉及功率硬件的操作请先在安全条件下充分验证。

文档结束。源码即文档：固件关键逻辑见两端 Core/Src/function.c、Core/Src/CtlLoop.c；上位机见 supercap-calibrator/src/。