1. JLink 烧录器从手工下载切到命令行:为什么值得费这个劲
第一次被要求把烧录过程做成脚本时,我盯着 IDE 里那个下载按钮看了很久——JLink 烧录器明明就是一根插在电脑上的探针,为什么不能像编译、打包那样被一条命令驱动。后来才想明白,真正限制我们的是操作入口:图形界面把器件型号、接口类型、时钟速度、下载地址这些配置都藏进了一份工程文件里,点按钮只是把它们重新执行了一遍。JFlashExe 就是把这些配置搬到命令行执行的另一个入口。把配置固化成一份 .jflash 工程之后,烧录就变成了一次可重复、可写日志、可失败重试的动作,而不是“某个人坐在某台电脑前点一下”。这件事适合三类人:要批量烧同一版固件的、要把烧录塞进自动化流程的,以及被“本地能烧、换台机器就连不上”反复折腾过的。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. SWD 接线与 .jflash 工程:JFlashExe 能跑起来的前提
命令行参数写得再漂亮,接错一根线照样连不上。这一章先把两件物理层面的事定下来:线怎么接,工程怎么存。
2.1 SWD 四根线:接错一根,后面全是白忙
-if SWD 在命令里只是一句声明,真正决定能不能连上的是排针上的几根线。SWD 模式下常用的连接关系如下:
| 探针引脚 | 目标板对应 | 作用 | 漏接或接错的表现 |
|---|---|---|---|
| VTref | 目标板供电轨(如 3.3V) | 给探针提供目标电平参考 | 探针识别不到目标电压,连接阶段直接失败 |
| GND | GND | 共地 | 偶尔能连上,一进下载就断,报错位置很随机 |
| SWDIO | SWDIO(部分板上标 TMS) | 双向数据线 | 完全连不上,或读到的器件 ID 是乱的 |
| SWCLK | SWCLK(部分板上标 TCK) | 时钟线 | 完全连不上 |
| RESET | NRST | 复位控制,可选 | 多数情况能烧,但“烧完不跑”时少一个定位手段 |
VTref 是最容易被忽略的一根。很多人下意识以为探针会给目标板供电,实际上它只用这根线测量目标板的电平,目标板自己必须通电。我见过不止一次“换了三根排线还是连不上”,最后发现是目标板没上电,VTref 悬空。
排线长度也值得说一句。SWD 是同步串行,时钟拉高之后线越长、分布电容越大,边沿越糊。我一般把排线控制在十厘米出头,超过二十厘米就把速度往下调,否则会出现“能连上、烧到一半失败”这种最难查的现象。SWDIO 和 SWCLK 也不要拧成一对随便走,靠得太近、和电源线捆在一起,都是干扰来源。
提示:接线前先用万用表量一下目标板供电轨的实际电压,确认 VTref 接的是这根轨,而不是某个只在特定模式下才有电的引脚。
2.2 .jflash 工程里存的是“除固件以外的一切”
-openproject 打开的那份 .jflash 文件,装的不是固件,而是一整套环境假设:器件型号、Flash 算法、接口类型、时钟速度、烧录后是否复位运行。器件型号这一项尤其关键,它决定了 Flash 起始地址、扇区划分和擦除算法。型号选错,最常见的表现不是报错,而是“烧录成功但校验不过”,或者擦除范围覆盖到了不该动的地方。
建工程的顺序我固定成这样:
- 打开配套图形界面,新建一个工程;
- 器件按板上丝印选,例如 STM32F103CB,不要凭“差不多”猜;
- Target Interface 选 SWD,和实际接线保持一致;
- 速度先填一个保守值,等连通性确认后再往上提;
- 另存为
STM32F103CB.jflash,放到一个不会随手被挪走的固定目录; - 关掉界面,后面全部走命令行。
第 5 步的目录选择看起来是小事,实际上决定了脚本能不能在别的机器上跑。工程文件跟着项目走、进版本库,比放在某个人的桌面目录里可靠得多。我后来把所有工程的命名规则统一成“器件型号 + 接口”,一眼能看出这份工程是给哪块板子准备的。
2.3 三段式验证:连接、擦除、下载分开做
一次性把十一个参数全丢进去,失败了你根本不知道卡在哪一步。我的习惯是拆成三段,前一段过不了就不往下走。
第一段只验证连接,不带固件也不擦除:
bash复制JFlashExe -openproject "STM32F103CB.jflash" \
-if SWD \
-speed 1000 \
-autoconnect 1 \
-exit
这条命令里没有任何 -loadfile 和 -erase_chip,工具只做一件事:按工程里的配置连上目标、识别器件,然后退出。参数含义后面还会细讲,这里先记住两个点:-speed 1000 是以 kHz 为单位的保守起步值,比产线用的 4000 慢,但抗干扰余量大;-autoconnect 1 让工具在首连失败时自动重试,对付上电时序不齐的板子很有用。这一步能过,说明接线、供电、器件选型三件事至少没有硬伤。
第二段加上擦除,但仍不下载固件,用来确认 Flash 算法和供电在长时间操作下是稳的。第三段才把 -loadfile、-verify、-go 全部补上。分三段做的代价是多敲两次命令,收益是任何一次失败都能立刻定位到“连不上”“擦不动”“写不进”中的某一类,而不是对着一整条命令猜。
2.4 工程和固件分离,是这套流程能复用的根本
.jflash 里不放固件路径,固件路径一律由命令行通过 -loadfile 给出。这个分离看起来不起眼,却是“一份工程烧多个版本”的前提。同一块板子,今天的 firmware.bin 和明天的 firmware_test.bin 共用同一份工程,只换命令行里的文件名和偏移地址,不需要为每个版本改一次工程、存一次副本。
反过来说,一旦有人把固件路径写进工程里,后面所有自动化都会变成“改工程—存工程—再跑命令”,工程文件本身也就失去了作为稳定基线的作用。我现在的做法是:工程文件只描述硬件环境,固件由脚本在运行时注入,两者在版本库里分开管理。
3. 拆解一条 JFlashExe 命令:十一个开关各自管什么
先把完整命令摆出来,后面逐段拆:
bash复制JFlashExe -openproject "STM32F103CB.jflash" \
-select_device "STM32F103CB" \
-if SWD \
-speed 4000 \
-autoconnect 1 \
-erase_chip \
-loadfile "firmware.bin", 0x08000000 \
-verify \
-go \
-exit
这条命令能一次跑完,但它其实是四组参数的串联:和谁说话、说多快、怎么擦、写完做什么。下面按这个顺序拆。
3.1 前三个参数决定“跟谁说话”
-openproject 加载基线配置,-select_device 再显式声明一次器件,-if SWD 声明接口。这里有人会问:工程里已经选过器件了,为什么还要写一遍。我的理由是日志。命令行里显式写出来的东西会原样进入执行记录,事后回看某次烧录到底是按哪个器件跑的,一目了然。工程文件被同事改过、被复制错了版本,这类事故在多人协作里并不罕见,多写一个参数等于给自己留一条追溯线索。
-if SWD 要和接线严格一致。如果板子上接的是 SWD 而命令里写了别的接口,工具会按另一套时序去握手,表现就是“线明明接对了却连不上”。反过来,接了 JTAG 的板子用 SWD 模式去连,多数器件也能连上,但引脚占用和复位行为不一样,排查问题时容易误导。
3.2 -speed 4000 与 -autoconnect 1:稳定性的两个旋钮
-speed 后面的数字单位是 kHz,4000 就是 4MHz。这个值不是越高越好:时钟越快,对排线长度、目标板布线、供电纹波越挑。产线上板子结构固定、排线短,用 4000 效率高;调试台上飞线一堆、板子靠 USB 供电,我一般从 1000 起步,连稳了再往上试。
-autoconnect 1 是重试开关。批量场景里,板子上电有快有慢,探针在目标还没起来的时候去握手就会失败。打开自动重连,相当于给每次连接加了几次机会,能挡掉一批“偶发连不上”的假故障。要注意它只解决连接阶段的时序问题,解决不了接线错误和供电不足。
3.3 -erase_chip:整片擦除的代价
-erase_chip 会把整片 Flash 清空,包括某些方案放在 Flash 尾部的参数区。如果板子上有出厂标定值、序列号、掉电保存的配置,这一条命令会连它们一起抹掉。我就吃过这个亏:一批板子烧完之后功能正常,唯独序列号全变成默认值,产线那边对不上账。
这种情况下常见做法是改成按扇区擦除,在工程里配置擦除范围,命令行不再传 -erase_chip,让工具只清应用区。代价是擦除速度慢一些,还要事先把分区规划清楚。整片擦除适合“从零开始、板上没有需要保留的数据”的场景,判断标准很简单:这块板子擦完之后,有没有任何数据是烧录前必须留着的。
注意:整片擦除不可逆。第一次对某类板子用
-erase_chip之前,先确认 Flash 尾部没有标定数据或出厂参数。
3.4 下载地址 0x08000000 不是随便写的
-loadfile "firmware.bin", 0x08000000 里的第二个字段是下载偏移。.bin 是纯二进制,文件里不含任何地址信息,工具必须靠这个参数知道“这段字节该放到哪”。0x08000000 是这类 MCU 的 Flash 映射起始地址,写对了,复位后取指才落在应用代码上。
写成 0x00000000 在某些器件上会因为地址重映射看起来也能跑,或者烧录阶段一切正常、复位之后行为诡异,这类问题最难查,因为工具没报错。如果手上的固件是 .hex 或 .elf 格式,地址已经内嵌在文件里,通常可以把偏移省掉,让工具自己解析;一旦用 .bin,偏移就必须显式给出来,而且要和链接脚本里的地址一致。
| 参数 | 取值示例 | 作用 | 不写或写错的后果 |
|---|---|---|---|
-openproject |
STM32F103CB.jflash | 加载器件、接口、算法等基线配置 | 工具不知道用哪套 Flash 算法 |
-select_device |
STM32F103CB | 显式声明本次烧录的器件 | 日志里缺少可追溯信息 |
-if |
SWD | 指定调试接口 | 与接线不符时握手失败 |
-speed |
4000 | SWD 时钟,单位 kHz | 过高导致下载中断,过低拖慢批量节拍 |
-autoconnect |
1 | 连接失败自动重试 | 上电慢的板子偶发连不上 |
-erase_chip |
无值 | 整片擦除 | 不擦除时旧数据残留,可能校验不过 |
-loadfile |
firmware.bin, 0x08000000 | 指定固件与下载偏移 | 偏移错则程序不运行 |
-verify |
无值 | 回读比对 | 写入异常无法发现 |
-go |
无值 | 烧完复位运行 | 需要手动断电重启 |
-exit |
无值 | 执行完退出进程 | 脚本挂起,无法判断结束 |
3.5 -verify、-go、-exit:交付前的最后三道关
-verify 让工具在写完之后回读 Flash 并逐字节比对。它的价值在于把“写进去了”和“写对了”区分开:供电波动、速度过高都可能导致个别字节没写稳,没有校验的话,这种板子会一路流到测试工位才暴露。
-go 让芯片在烧录完成后立即复位运行。不加这一条,烧完的板子停在复位状态,必须人工断电再上电,批量场景里这一下就把效率吃回去了。有些板子对复位时序敏感,-go 之后不启动,这时候才需要回头查复位电路和启动引脚配置。
-exit 是给脚本用的。不带它,工具执行完会停在交互状态等人操作,批处理就卡在那儿不动。这条参数单独看没什么技术含量,但它是“把烧录塞进自动化”这句话能不能成立的分界线。
4. 避坑与排查:连不上、烧不进、校验不过的五个现场
下面这五条都是我自己或者身边人真实翻过的车,按“现象—原因—解决”写,顺序基本对应排查的先后。
4.1 报连接失败,探针指示灯却正常
现象:命令一执行就停在连接阶段,提示无法连接目标,但探针本身被系统识别到了。
原因通常有两个:目标板没上电,或者 VTref 没接。探针能亮灯只说明它自己和电脑之间的链路是通的,和目标板之间还没建立关系。另一个常见原因是 SWDIO 和 SWCLK 接反,两根线在排针上挨着,接错之后表现同样是连不上。
解决:先量目标板供电轨电压,确认有电;确认 VTref 接的是这根轨;对照原理图核对 SWDIO、SWCLK 的顺序,不要只看排针位置。修好之后用只连接不下载的那条命令复测,不要直接跑全量命令。
4.2 能连上,下载到一半中断
现象:连接正常,器件识别也正常,一开始写 Flash 就报错,或者进度条卡在某个百分比。
原因多半是速度与物理条件不匹配。-speed 4000 在短排线、稳定供电的产线治具上没问题,换成飞线一堆的调试台就容易出错。排线过长、目标板靠 USB 供电导致电压跌落,也会造成同样的现象。
解决:把速度降到 1000 再试,同时缩短排线、改用外部供电。如果降速后稳定,说明是信号完整性问题,不要急着怀疑芯片。
4.3 提示烧录成功,板子却不跑
现象:命令行输出正常结束,-verify 也通过了,但板子上电后没有任何反应。
原因有三类:没加 -go,芯片停在复位状态;启动引脚状态不对,芯片没有从 Flash 启动;-loadfile 的偏移地址写错,代码被放到了错误的区域。第三类最隐蔽,因为校验只比对写入内容,不判断这段内容在不在取指路径上。
解决:先确认命令里有 -go;再查启动引脚的电平配置;最后核对链接脚本里的起始地址和 -loadfile 的偏移是否一致。
4.4 校验失败,重烧一次又好了
现象:-verify 报比对不一致,重新执行同一条命令就通过了,位置不固定。
原因通常是供电或时序的边际问题:整片擦除后 Flash 尚未稳定就开始写入、目标板电源纹波偏大、速度贴着上限跑。这类问题不会稳定复现,所以最容易被当成“玄学”。
解决:降一档速度,在擦除和写入之间留出稳定时间(多数工具支持配置延迟),把目标板换成稳定电源。批量场景下,宁可把节拍放慢一点,也不要让这种偶发失败流到下一道工序。
4.5 批处理全部显示成功,实际有板子没烧进去
现象:脚本跑完,每一块都打印“OK”,抽检时发现个别板子还是旧固件。
原因有两个:脚本没有判断进程返回码,工具失败退出后脚本继续往下走;或者 -loadfile 指向的文件路径是相对路径,脚本被从别的目录调用时,读到的是另一份旧文件。
解决:在脚本里用返回码做判定,失败立即中断;固件路径改成绝对路径,并在开始前打印文件修改时间。这两条加起来,基本能堵住“假成功”。
5. 批量烧录脚本化:让 JLink 烧录器在无人值守下也可靠
单条命令跑通之后,把它变成脚本只是体力活,真正要设计的是失败处理。下面这份批处理是我现在常用骨架,重点是三件事:打印固件时间戳、判断返回码、失败立即退出。
bat复制@echo off
setlocal enabledelayedexpansion
set JFLASH=JFlashExe.exe
set PROJECT=STM32F103CB.jflash
set FW=firmware.bin
rem 打印固件修改时间,防止误烧旧文件
for %%F in ("%FW%") do set STAMP=%%~tF
echo [%date% %time%] start flash, image=%FW%, mtime=%STAMP%
%JFLASH% -openproject "%PROJECT%" ^
-select_device "STM32F103CB" ^
-if SWD ^
-speed 4000 ^
-autoconnect 1 ^
-erase_chip ^
-loadfile "%FW%", 0x08000000 ^
-verify ^
-go ^
-exit
if errorlevel 1 (
echo [%date% %time%] FAILED, stop line
exit /b 1
)
echo [%date% %time%] OK
exit /b 0
%JFLASH% 依赖环境变量 PATH 能找到可执行文件,这样脚本换机器不用改路径。%%~tF 取文件修改时间,是成本最低的防呆手段——产线上最常见的错误不是烧失败,是烧了一份上周的固件。if errorlevel 1 接住非零返回码,exit /b 把结果传给上层调用者,上层才能决定是重试还是停下整条线。整套流程里,-exit 负责让进程结束,返回码负责让脚本知道结束得对不对,两者缺一不可。
自动化跑起来之后,我还会保留两道人工验证。第一道是每天开工前的空载连接测试:不接板子、只跑工程加载和参数解析,确认环境和工程文件没被改坏。第二道是换批次时的首件全流程:烧一块、校验、上电跑一遍功能,通过了才放开整批。
| 环节 | 手工操作 | 脚本化之后 |
|---|---|---|
| 选器件与接口 | 每次开界面确认 | 固化在 .jflash 工程里 |
| 固件版本 | 靠人记 | 启动时打印文件名与修改时间 |
| 失败处理 | 看界面报错 | 返回码判定,立即中断 |
| 结果记录 | 无 | 时间戳 + 成功/失败标记 |
从那次序列号被整片擦除抹掉之后,我每次给新板子写命令都强制先跑一遍只连接不下载的验证,再确认 -erase_chip 到底该不该留。看起来多花两分钟,比事后对着几十块板子重新标定要划算得多。希望帮到你。
