📚 课程目录第4章 STM32CubeProgrammer与CLI工具链

4. STM32CubeProgrammer与CLI工具链

STM32CubeProgrammer（下文简称 CubeProg）是 ST 官方提供的统一烧录与读写工具，它同时提供图形界面（GUI）和命令行（CLI）两套入口。在 STM32N6 的生产测试场景中，真正被产线使用的是 CLI：它可被批处理脚本、Python、CI 流水线调用，能对多块板卡做无人值守的重复烧录，并把结果写入日志供追溯。本节围绕 CLI 工具链的安装配置、参数体系、脚本模式、批量操作与日志输出展开，目标是让读者能独立写出一条可复现的烧录命令，并把它组织成可批量执行的产线脚本。

安装与目录结构

CubeProg 的安装包在 ST 官网以 STM32CubeProgrammer 名称发布，Windows 下默认安装到 C:\Program Files\STMicroelectronics\STM32Cube\STM32CubeProgrammer。CLI 可执行文件位于 bin\STM32_Programmer_CLI.exe，同目录下还有 STM32_Programmer_CLI 依赖的 DLL、外部加载器（External Loader）目录以及 ST-LINK 驱动。Linux 下解压后通过 ./setup.sh 安装，CLI 位于 bin/STM32_Programmer_CLI，需要把 bin 加入 PATH，并配置 udev 规则让普通用户可访问 ST-LINK。

安装完成后第一件事是验证版本与连接：

STM32_Programmer_CLI --version
STM32_Programmer_CLI -c port=SWD mode=UR freq=4000

第一条输出工具版本与支持的器件列表；第二条以 SWD、UR（Connect Under Reset）模式、4 MHz 时钟连接目标。若返回 Device ID、Device name 等信息，说明链路正常。STM32N6 属于较新器件，务必确认 CubeProg 版本足够新（建议 2.17 及以上），否则可能出现器件识别失败或外部加载器缺失。

命令行参数体系

CLI 的参数按“动作”分组，每个动作以短横线开头，动作内部用 key=value 传参。常用动作如下：

-c：连接，参数 port=SWD|USB1、mode=UR|HOTPLUG、freq=、reset=HWrst|SWrst。
-e：擦除，all 全片擦除，或 [start end] 指定扇区/地址范围。
-w：写文件，file.bin 0x08000000 指定文件与起始地址，可加 -v 校验。
-r：读回，0x08000000 0x1000 file.bin 读地址、长度、输出文件。
-ob：读写选项字节，如 -ob RDP=0xBB。
-hardRst / -rst：硬件复位或软复位。
-q：静默模式，减少输出，适合脚本。
-log：把输出写入日志文件。

一条典型的 STM32N6 烧录命令如下（示例参数，实际地址以工程链接脚本为准）：

STM32_Programmer_CLI -c port=SWD mode=UR freq=4000 \
  -e all \
  -w app.bin 0x08000000 -v \
  -w fsbl.bin 0x70000000 -v \
  -ob RDP=0xAA \
  -hardRst -q -log flash.log

这里先全片擦除，再依次写入应用镜像与 FSBL（First Stage Boot Loader），写入后校验，随后写选项字节，最后硬件复位并输出日志。-v 是关键：它让工具在写入后回读比对，能发现通信不稳定导致的位翻转，是产线判断“烧录是否真的成功”的依据。

脚本模式与批量操作

当烧录动作超过两三条命令时，应把参数写进脚本文件，用 -s 调用：

STM32_Programmer_CLI -c port=SWD mode=UR freq=4000 -s flash_script.txt

脚本文件内每行一条命令，例如：

-e all
-w app.bin 0x08000000 -v
-w fsbl.bin 0x70000000 -v
-ob RDP=0xAA
-hardRst

脚本模式的好处是参数集中、便于版本管理，产线换固件时只改脚本与 bin 文件，不必改调用命令。批量操作则是在脚本外层再套一层循环：把待烧板卡的序列号或工位号写入列表文件，逐行读取，每块板卡执行一次完整脚本，并把返回码与日志按 SN 归档。Windows 批处理可用 %ERRORLEVEL% 判断，Linux 用 $?。关键点是：每块板卡必须独立连接、独立复位、独立记录，不能复用上一次的连接状态，否则一块板卡失败会污染后续结果。

日志输出与结果判读

日志是产线追溯的核心。-log flash.log 会把完整输出写入文件，同时仍打印到终端。日志中需要重点关注的字段包括：连接阶段的 Device ID 与 Device name（确认识别到正确器件）、擦除阶段的扇区范围、写入阶段的 Download verified successfully、选项字节写入后的回读值，以及最后的复位结果。若出现 Error: No STM32 target found，通常是供电、SWD 接线或复位模式问题；若出现 Verification failed，则优先怀疑时钟频率过高或线缆过长，可把 freq 从 4000 降到 1000 再试。

建议在脚本中固定使用 -q 减少冗余输出，但不要关闭 -v。静默模式只影响打印量，不影响校验行为，二者可以同时使用。

写选项字节（如 RDP）属于不可逆或半不可逆操作，量产脚本中应把 -ob 放在写入与校验成功之后，并单独记录该步骤的日志。一旦 RDP 等级设置错误，可能导致后续无法连接，需要专用手段恢复。

一条可复用的产线命令模板

综合以上要点，下面给出一份可直接改造使用的批处理片段（示例，路径与地址需按实际工程替换）：

@echo off
set CLI="C:\Program Files\STMicroelectronics\STM32Cube\STM32CubeProgrammer\bin\STM32_Programmer_CLI.exe"
set FW=app.bin
set LOGDIR=logs
if not exist %LOGDIR% mkdir %LOGDIR%

for /f %%S in (sn_list.txt) do (
  echo [%date% %time%] SN=%%S >> %LOGDIR%\batch.log
  %CLI% -c port=SWD mode=UR freq=4000 -e all ^
    -w %FW% 0x08000000 -v -hardRst -q ^
    -log %LOGDIR%\%%S.log
  if errorlevel 1 (
    echo SN=%%S RESULT=FAIL >> %LOGDIR%\batch.log
  ) else (
    echo SN=%%S RESULT=PASS >> %LOGDIR%\batch.log
  )
)

这段脚本完成了“遍历序列号—烧录—校验—复位—按 SN 归档日志—汇总 PASS/FAIL”的闭环。实际使用时，把 sn_list.txt 换成工位读取到的序列号列表，把 app.bin 换成当前固件版本，即可接入现有产线流程。判断烧录是否真正成功，不能只看脚本是否跑完，而应同时满足：CLI 返回码为 0、日志中出现校验成功记录、目标板复位后能正常启动。三者缺一，都应判为 FAIL 并保留日志。