★ FEATURED ARTICLE 做嵌入式这几年最让我头痛的其实不是写业务代码而是把固件交给别人去烧。手头这个 ESP32-S31 项目就是这样功能写完以后测试、生产、给客户演示每个环节都要重新烧录固件。每次都得先教对方装 Python、再敲命令装 esptool然后背一串参数十个人里有八个人还没走到烧录那一步就卡住了。更麻烦的是这套固件并不是把一个 bin 文件塞进去就完事还牵扯到镜像合并、地址边界和分区容量。折腾几次之后我决定做一份 Windows 一键烧录包解压、双击、等日志、拔线完事。1. 为什么我坚持做“一键烧录包”而不是教别人用命令行1.1 一个真实场景不是谁都想碰命令行写固件的人习惯把一切交给终端但拿到板子的人不一定。我遇到过不少情况驱动装了一半报错esptool 安装失败或者命令里的地址从 0x10000 被敲成了 0x1000烧完板子直接不启动。后来我意识到问题不在于对方不懂技术而在于我把“环境部署”和“操作流程”两个复杂度一股脑丢给了使用者。一键烧录包的本质就是把环境、工具、参数、固件全部封装好让使用者只做两个动作插线双击。这个项目的固件更新频率其实不算高但每次更新都牵涉到几个 bin 文件的协同写入。对使用者来说让他们理解“bootloader 在 0x0、分区表在 0x8000、app 在 0x10000”是不现实的也不该成为他们的负担。一键包只是把本该由工具链承担的事情回归到工具链内部而不是让每个烧录者都成为临时嵌入式工程师。1.2 一键包解决的四个问题环境隔离目标电脑上可能已经装了其他版本的 Python或者完全没有 Python。把 Python 和 esptool 放进工具包自身的目录不依赖系统环境也不污染系统环境。命令固化所有地址、波特率、flash 参数在脚本里写死避免人为拼错。使用者面对的不是一串命令而是一个明确的动作。日志可读正常输出和错误输出分开失败时直接告诉用户“看哪几个地方”而不是甩一段密密麻麻的报错。版本可控固件包里有版本文件、哈希校验谁烧的是哪一版什么时候烧的都能查清楚。这四条里前两条是省事后两条是省心。尤其是版本可控项目越接近交付阶段越重要。客户反馈“板子不对”的时候你第一件事就是要确定对方手里跑的是哪一版固件。如果烧录工具本身没有版本概念你连排查的起点都找不到。1.3 什么人需要这个东西嵌入式项目负责人、硬件创业小团队、学生项目演示、需要小批量产出的工厂场景都会用到。如果只是自己一个人开发调试命令行完全够用没必要做一键包。但一旦涉及多人协作、跨部门、跨公司交付一键包几乎是刚需。它不是我写代码写得烦了才做的“面子工程”而是实实在在减少沟通成本和生产事故的工具。2. “完整镜像”到底完整在哪引导加载器、分区表与应用固件2.1 ESP32-S31 上电后不是直接跑 app这个芯片系列的 flash 里住着好几个“角色”。ROM 里的第一段引导程序会先看 flash 起始位置找到 bootloaderbootloader 再根据分区表找到 app最后才跳到应用代码。所以你要烧录的从来不是单个 app.bin而是一个组合。最少需要三类文件bootloader.bin二级引导加载器负责初始化内存、外设然后跳转到 app。partition-table.bin分区表它告诉系统 flash 被划分成了哪些区域每个区域起始地址和大小是多少。app.bin真正的应用固件也就是你写的业务逻辑。如果工程里启用了 NVS 非易失存储、OTA 升级、PHY 校准数据还会有对应的分区和初始化文件。这些文件不是随便扔进 flash 的每个都必须待在自己的地址段里。这也是“完整镜像”这个概念存在的前提把整套组合打包成一个整包烧录时一次性放进去而不是分别处理。2.2 一张参考分区布局以我手上这个 ESP32-S31 项目为例分区工具生成的默认布局大致是这样的。注意具体地址以你的工程实际配置为准不要照抄。文件作用参考起始地址大小参考bootloader.bin二级引导加载器0x0000通常几十 KBpartition-table.bin描述 flash 分区划分0x8000几 KBnvs.bin非易失存储保存网络参数等0x9000十几 KBotadataOTA 升级信息0xD000几 KBapp.bin用户应用固件0x10000取决于 app 分区大小你可能会觉得 0x10000 这个起始地址很常见但它不是魔法数字。它来自分区表配置如果分区表改了app 的地址也必须跟着改。很多“能写入但起不来”的问题根源都是这里文件本身没错放的位置错了。2.3 为什么强烈建议用 merge_bin 合成一个“整包”逐个文件手工烧录最大的风险是漏文件和写错地址。比如今天只烧了 app忘了烧 bootloader板子在旧 bootloader 上跑新 app可能没反应或者同事手一抖把 app 写到了 bootloader 的地址段上板子直接变砖。用 esptool 的 merge_bin 命令可以把多个文件按照各自的偏移合成一个 merged.bin。生成之后烧录时只需要写这一个文件地址从 0x0 开始。一个典型的合并命令长这样python -m esptool merge_bin -o firmware\merged.bin --chip 请替换为实际芯片参数 --flash_mode dio --flash_freq 40m --flash_size 8MB 0x0 bootloader.bin 0x8000 partition-table.bin 0x10000 app.bin这个命令的重点有两个。第一-o指定输出文件名建议固定成 merged.bin因为后面的脚本都依赖这个文件名。第二0x0 bootloader.bin、0x8000 partition-table.bin这种“地址文件”成对出现含义是把文件放到对应的 flash 偏移位置。合并时这些偏移必须和分区表一致否则镜像本身就是错的。2.4 数据边界的三种含义标题里的“数据边界”不是玄学它就是 flash 世界里最容易出事的三个边界地址边界每个 bin 摆放的位置不能重叠。bootloader 占了 0x0 开始的一段app 就不能放到 0x1000否则会把 bootloader 尾部覆盖掉。分区容量边界app 分区大小是固定的app.bin 的实际大小不能超过这个分区。哪怕它没有覆盖别的分区只要超出运行阶段就会出诡异问题。总容量边界整包的最大偏移加上文件长度不能超过 flash 芯片的总容量。8MB flash 就是 8 * 1024 * 1024 字节末尾地址是 0x800000。镜像超过这个值写入时要么失败要么写进去的内容不完整。esptool 并不是一个智能管家它只负责按地址写数据不负责替你判断“这个 app 放在那里会不会越界”。很多越界问题恰恰是烧录成功之后才暴露出来的。这一点等到了第 5 章复盘具体事故时会看得更清楚。3. esptool 的调教从裸命令到可复制的烧录脚本3.1 工具链最小准备Windows 下基础做法是先装 Python然后打开命令行执行pip install esptool。装完可以用python -m esptool version确认版本。我不建议每次用到时临时装。最好固定一个 esptool 版本因为新版本偶尔会调整参数或输出格式。如果你要给别人做一键包那就更应该在打包前确认这个脚本在目标机器上不需要联网不需要临时装任何东西。提前下载好 esptool 的离线安装包或 wheel 文件一起放进工具包。对于目标机器可能没有 Python 的情况后面第 4 章会讲怎么用内嵌版 Python 把运行环境也一起打包。这里只先说一个原则一键包里的所有依赖都应该离线、本地、版本固定。3.2 三条主力命令识别硬件最常用的是python -m esptool --port COM3 flash_id这条命令会读取芯片信息同时能让你确认串口通不通、驱动装没装好。如果这里都不认后面就不用谈了。合并好的整包烧录最常用的是python -m esptool --port COM3 --baud 460800 write_flash 0x0 merged.bin如果坚持分开写多个文件可以这样python -m esptool --port COM3 --baud 460800 write_flash 0x0 bootloader.bin 0x8000 partition-table.bin 0x10000 app.bin擦除 flash 则用到python -m esptool --port COM3 erase_flash烧录前建议擦除尤其是设备之前跑过其他固件时。残留的分区数据容易导致各种奇怪问题。但整片擦除时间较长保守做法是只擦目标分区区域比如python -m esptool --port COM3 erase_region 0x10000 0x200000这里 0x10000 是 app 起始地址0x200000 是长度。擦除区域也要严格按分区表来超出边界同样会伤到邻居分区。3.3 写入参数里的隐形坑esptool 的 write_flash 命令里有几个参数特别容易误导人--flash_mode、--flash_freq、--flash_size。先说--flash_mode和--flash_freq。它们不是随便填的要和编译固件时使用的配置一致。比如固件编译配置用的是 DIO 模式、40MHz 频率你烧录时非要用别的值可能当场能启动但运行一段时间后随机重启或者不稳定。最稳妥的办法是看工程编译日志把里面出现的实际参数抄过来。再说--flash_size。使用detect会自动识别看起来很方便但在某些 USB 转串口线质量差或驱动不稳定的情况下识别可能失败。更可靠的做法是确认 flash 实际容量后显式写清楚。比如板子是 8MB就写--flash_size 8MB。如果写错了比如实际 16MB 你写成 8MB系统能启动但只能用一半空间逻辑分区会乱套。波特率也不是越高越好。460800 是常用稳妥档921600 在某些劣质线材或长线上会大量失败。一旦看到Invalid head of packet之类的报错第一件事就是把波特率降到 115200 重新试而不是继续加码。4. 打包流程做一份别人拿到就能用的 Windows 一键烧录包4.1 目录结构与发布思路一个标准的一键包目录结构我习惯这样设计flash-tool/ ├─ run.bat ├─ README.txt ├─ drivers/ │ └─ 说明.txt ├─ firmware/ │ ├─ merged.bin │ ├─ checksum.md5 │ └─ version.txt └─ runtime/ ├─ python/ └─ esptool/run.bat是入口用户双击它。README.txt写清楚操作步骤和常见问题。drivers目录放 USB 转串口驱动这是很多用户卡住的第一道坎。firmware目录放最终固件和校验信息。runtime目录是运行环境Python 和 esptool 都在里面。打包发布时整个文件夹压缩成一个 zip文件名带上日期和版本比如esp32-s31_flash_tool_20250113.zip。别小看这个命名习惯它能让“你用哪一版工具烧的”这个问题变得一目了然。4.2 准备免安装 Python 运行环境目标电脑不一定有 Python所以我把 Python 一并打包。方法是从官方渠道下载 Windows embeddable package也就是绿色版 Python 压缩包解压到runtime\python目录。这里有一个关键细节embeddable Python 默认不是完整的脚本环境它不会自动加载 site-packages甚至默认没有 pip。解压后你会在目录里看到一个类似python311._pth的文件用文本编辑器打开把#import site这行的注释符号去掉改成import site保存。如果不做这一步后面 esptool 即使装进去也找不到。然后在这个目录下执行runtime\python\python.exe -m pip install esptool如果这个 Python 没有 pip先用官方 get-pip 脚本装一遍再执行上面的命令。做完之后runtime\python里就有了 esptool 的代码包。目标机器不需要联网不需要再装任何环境。把整个目录原样复制走双击 run.bat 就能用。我当时第一次做的时候想偷懒直接让用户自己去装 Python结果被各种环境问题折腾到怀疑人生。后来改成内嵌 Python所有问题一次性消失。如果你也在做类似工具这一步千万别省。4.3 一键烧录脚本 run.bat脚本是整个工具包的脸面。我写了一个可以直接用的版本核心逻辑是检查环境、列出串口、等待用户输入 COM 口、调用 esptool 烧录、根据返回码提示成功或失败。echo off chcp 65001 nul setlocal cd /d %~dp0 set PY%~dp0runtime\python\python.exe set BIN%~dp0firmware\merged.bin if not exist %PY% goto missing_python if not exist %BIN% goto missing_bin echo echo ESP32-S31 一键烧录 echo echo 请先确认开发板已通过 USB 连接驱动安装成功。 echo 当前系统检测到的串口 %PY% -m serial.tools.list_ports -v echo. set /p PORT请输入串口号: if %PORT% ( echo [错误] 串口号不能为空。 pause exit /b 1 ) echo 开始烧录... %PY% -m esptool --port %PORT% --baud 460800 --before default_reset --after hard_reset write_flash --flash_mode dio --flash_freq 40m --flash_size 8MB 0x0 %BIN% if errorlevel 1 ( echo. echo [失败] 烧录过程报错。 echo 请检查串口号是否正确、驱动是否安装、BOOT 状态是否正常、波特率是否过高。 ) else ( echo. echo [成功] 固件已写入设备即将重启。 ) pause exit /b %errorlevel% :missing_python echo [错误] 未找到 runtime\python\python.exe。 echo 请确认整个文件夹被完整解压不要只拷贝 run.bat。 pause exit /b 1 :missing_bin echo [错误] 未找到 %BIN%。 echo 请确认 firmware 目录下存在 merged.bin。 pause exit /b 1几个细节值得解释。chcp 65001是为了让中文显示正常。但仅仅有它还不够保存脚本文件时最好用带 BOM 的 UTF-8 编码否则 bat 里的中文还是可能乱码。cd /d %~dp0是让脚本无论从哪里双击都先切换到脚本所在的目录。很多“双击没反应”的问题都是因为没有这一步脚本在当前目录里找不到固件和 Python。--flash_mode dio --flash_freq 40m --flash_size 8MB这些参数是我这个项目的实际值。你在自己的项目里必须按编译配置替换否则可能出现“烧录成功但设备行为异常”的情况。如果用了完整镜像 merged.bin也可以考虑把--flash_mode和--flash_freq设为keep让 esptool 保留镜像头部里的配置。脚本最后加了pause是怕用户双击后窗口一闪而过什么都没看到。失败时还根据errorlevel做了不同提示。对不懂技术的使用者来说明确的“下一步”比任何技术细节都重要。4.4 固件校验与版本管理一键包不能只是“能烧进去”还得让用户知道“烧的是哪一版”。我在firmware目录里固定放两个额外文件checksum.md5和version.txt。生成固件后先算一下哈希。在 Windows 命令行可以这样做certutil -hashfile firmware\merged.bin MD5把得到的哈希值写到checksum.md5。如果你的脚本想做自动化校验也可以直接调用内嵌 Python%PY% -c import hashlib; print(hashlib.md5(open(rfirmware\merged.bin,rb).read()).hexdigest())至于version.txt内容就一行比如v1.2.0版本号最好和固件编译时生成的版本字符串保持一致。用户烧录完成后打开设备上的信息页面或串口日志能看到同样的版本号两边一对照就确认了。这一点在多人协作时尤其有价值谁烧了旧固件、谁烧了缺功能的版本当场对一下就能查出来。merged.bin这个名字最好保持固定不要每次发布都换名字。换名字会让脚本里的路径跟着变也容易让用户手动去改文件名。更新固件时只需要替换文件内容文件名不要动。真正的版本信息放在 version.txt 里用文件内容表达版本比用文件名更可靠。4.5 USB 驱动与说明文档一键包做得再智能也绕不过 USB 驱动这道坎。不同厂家的开发板USB 转串口方案可能不一样常见的有几类驱动也各不相同。我的做法是在drivers目录里放好对应驱动程序的安装包同时在 README.txt 里写清楚安装步骤。安装驱动的步骤我会写得很“傻瓜”先不插板子打开设备管理器。插上开发板看设备管理器里出现什么设备。如果出现带感叹号的未知设备安装drivers里的驱动。重新插拔开发板确认设备管理器中出现 COM 端口记下 COM 号。我不建议在 bat 脚本里自动安装驱动。驱动安装通常需要管理员权限还要处理系统签名校验强行自动化容易弄出更多问题。驱动这一步让用户手动做反而最稳定。README.txt 不需要写得多高深但一定要把两个事情写明确第一先装驱动再烧录第二烧录过程中不要拔线不要断电。很多“烧录失败”其实是操作问题不是工具问题。5. 烧录失败复盘那些与“数据边界”有关的折腾5.1 事故一能写入但起不来地址重叠有次同事烧完板子说完全没反应串口也没有任何输出。我第一反应是 bootloader 坏了接上示波器一看flash 里的内容根本不是完整的启动链路。再用 esptool 读回 flash 才发现app 被写到了 0x1000正好覆盖了 bootloader 的一部分。原因很简单对方在手工执行 write_flash 时把 app.bin 的地址从 0x10000 写成了 0x1000。多了个零看起来像笔误代价是一块板子变砖一分钟。这个事故让我彻底放弃了“手工多文件烧录”的念头。只要用 merge_bin 生成整包烧录时统一写 0x0 地址这类错误从一开始就不会发生。esptool 是忠实执行者你给它什么地址它就写什么地址它不会保护你的分区数据边界只能由你自己把关。5.2 事故二app 超了分区容量却不报错另一个更隐蔽的问题是 app.bin 超过了 app 分区的容量但 merge 和烧录全都成功了。这是因为 merge_bin 只负责拼接数据它不检查某个文件是否超出了对应分区的边界。你给它 0x10000 的偏移它就把 app 放上去哪怕 app 尾部已经冲到了后面的 otadata 区域。那次的现象是设备能启动但重启一段时间后随机崩溃OTA 升级也一直失败。后来查编译日志发现 app 分区配置了 0x200000 这么大而这次加了不少算法之后app.bin 实际大小已经接近 0x230000超出了分区尾部。验证方法其实很简单编译完看一眼 app.bin 的实际大小再打开分区表 CSV对比一下 app 分区的大小字段。不要只看 merge 命令有没有成功生成文件它生成文件不代表你的固件真的放得下。这类问题的高发期往往是在固件功能不断膨胀、而分区表很久没更新的时候。每次功能加量都应该顺手确认一遍分区占用率。5.3 事故三整片镜像超过 flash 容量还有一次客户反馈烧录到一半就报错换了几根线都一样。我后来看了 merge 命令的参数发现我之前用--flash_size 16MB生成了镜像但客户板子上的 flash 实际是 8MB。镜像大小超过了实际 flash 容量写入到高地址时芯片根本没那么多空间可用。这个问题的本质仍然是总容量边界。merge_bin 的--flash_size参数以及 write_flash 的--flash_size参数都必须和实际 flash 容量一致。一个提醒不要只看型号标签就默认为“所有板子 flash 一样大”采购批次不同、物料替换都可能导致 flash 容量变化。批量发货前最好抽查几块板子的实际 flash 容量用flash_id读一下最保险。镜像过大通常有三种处理方式砍掉不必要的分区、压缩固件体积、换用更大 flash 的硬件版本。越早发现越好等设备发货到客户手里再发现成本完全不是一个量级。5.4 esptool 常见报错对照表我把最常见的几个现场整理成了表格方便照方抓药。现场大概率原因排查顺序Cannot open port串口被占用、驱动缺失、COM 口不对设备管理器确认端口 - 关闭串口监视工具 - 换 USB 口Invalid head of packet波特率太高、线材质量差、设备没进入下载模式降到 115200 - 按住 BOOT 再试 - 换线Chip identification failed接线错误、供电不足、芯片不在下载模式检查供电和接线 - 手动复位 - 按住 BOOT 再上电Flash write error at ...地址越界、写保护、电压不稳检查地址和容量参数 - 擦除目标区域再写 - 换短而粗的线烧录成功但无法启动地址重叠、分区超限、mode/freq 配置不一致重新 merge - 对照分区表检查偏移 - 核对 flash mode/freq如果你遇到的报错不在表里记住一个原则先判断是连接层、工具层、固件层还是写入层的问题再一层层排查。不要看到一个陌生报错就盲目改参数更不要反复重试同一个命令十次那只会浪费时间。5.5 通用排查链路我把自己的排查顺序固定成了五步每次出问题都按这个顺序走很少再陷入“瞎试”的状态。先确认连接层设备管理器里有没有 COM 口驱动是否正常。再确认工具层esptool 版本是否和打包时一致Python 环境是否被破坏。然后确认固件层文件是否齐全merge 时用的分区表是否和当前工程一致。接着确认写入层flash 容量参数、flash mode/freq、擦除区域是否匹配。最后确认行为层烧录后设备有没有起来串口日志里报了什么。这五步不是每次都需要全部走完。但只要走到第 3 步你会发现大部分问题都出在“固件层”和“写入层”的数据边界上而不是连接层。6. 我沉淀下来的一份“一键包避坑清单”6.1 边界原则先写好别等人踩坑做了几个版本的一键包之后我把一些“雷区”直接写成了团队内部约定永远不要手工记录地址一切以 merge_bin 的输出和分区表 CSV 为准。构建产物和分区表一起归档固件命名统一带版本号。每次 merge 前先看一眼分区表有没有改动。发布前在一台干净的 Windows 机器上完整跑一遍。这些原则看上去简单但每一条背后都是真实的故障。数据边界这种事靠人记住不靠谱靠流程和工具强制才靠谱。6.2 让脚本和日志替你说人话一键包的受众不一定懂技术所以脚本的输出要有意识地分成两类正常信息和错误提示。正常信息可以简短错误提示一定要告诉用户“现在该怎么办”。我在脚本里写“请检查串口号、驱动、BOOT 状态、波特率”这四样就是希望用户别盯着报错原文发愣。另一个实用技巧是把输出重定向到日志文件。在调用 esptool 的那一行末尾加上 flash_log.txt 21这样即使脚本窗口关掉了日志还在。用户截图或把日志文件发给你你一眼就能看到实际写入过程而不是听对方复述“好像报错了”。6.3 后续可以扩展的方向一键包也可以继续做得更顺手。比如用脚本自动检测唯一串口并默认选中用户连 COM 口都不用输入或者在烧录成功后读取设备里的版本号和 version.txt 对照甚至做成图形界面把串口选择、固件版本、烧录进度都展示出来。扩展空间是有的但不要一开始就上重武器。多数交付场景一个干净的批处理脚本加清晰的 README 就足够。我自己现在已经不会用手动命令去给项目外的任何人烧录了。无论是自己调试还是交付我都先把固件合成整包再把整个目录压缩成 zip文件名带上日期里面放版本说明。别小看这个习惯它帮我省下的沟通时间远超写这套脚本花掉的时间。以后改了固件只需要重新生成 merged.bin 替换进去重新打包发布就行。数据边界这件事表面上是地址和大小实际上是“让别人不犯错”的边界也是自己少背锅的边界。
阅读完成 · 觉得有帮助？
