ESP32-S3 批量清空与批量下载操作说明

1. 适用范围

本文档适用于在 Windows PowerShell + ESP-IDF 环境下，对多台 ESP32-S3 设备进行：

• 批量清空 Flash：使用自定义batch_erase.py脚本，多线程并行调用esptool erase_flash。
• 批量下载固件：使用esp-batch-flash工具，多端口并行烧录。

注意：esp-batch-flash当前版本用于批量烧录，不支持--erase-all擦除参数。批量擦除请使用本文档中的batch_erase.py。

2. 环境准备

2.1 进入 ESP-IDF 环境

打开 ESP-IDF PowerShell 终端，或手动执行 ESP-IDF 的export.bat，确保命令行前出现类似：

(venv)PSD:\...>

确认 Python 可用：

python--version

2.2 安装依赖库

在 ESP-IDF venv 中执行：

pip install--upgrade pyserial esptool esp-batch-flash

说明：

如果 pip 下载慢，可使用国内镜像：

pip install pyserial esptool esp-batch-flash-i https://pypi.tuna.tsinghua.edu.cn/simple

安装完成后验证：

python-m esptool version esp-batch-flash--help

3. 批量清空 Flash

3.1 保存清空脚本

在项目目录下新建文件batch_erase.py，例如：

D:\Users\Desktop\Light_Gateway_XiangMu\Light_Gateway_ESP32s3\batch_erase.py

将以下代码完整复制保存：

#!/usr/bin/env python3""" batch_erase.py - 一键并行擦除多个 ESP32 设备 适用环境: ESP-IDF venv (Windows / Linux / macOS) 依赖: pyserial (esptool 已自带) """importargparseimportsubprocessimportsysimporttimefromconcurrent.futuresimportThreadPoolExecutor,as_completedtry:fromserial.toolsimportlist_portsexceptImportError:print("错误: 缺少 pyserial，请运行: pip install pyserial")sys.exit(1)# ESP 设备常见 USB VID：Espressif 原生 USB-JTAG、CP210x、CH340/CH341、FTDIESP_VIDS={0x303A,0x10C4,0x1A86,0x0403}defdetect_ports(filter_esp=True):"""自动扫描串口，默认只保留疑似 ESP 设备的端口"""ports=[]forpinlist_ports.comports():iffilter_espandp.vidnotinESP_VIDS:continueports.append(p.device)returnsorted(ports)defrun_erase(port,chip,baud,extra_args):"""对单个端口执行擦除，实时打印输出"""cmd=[sys.executable,"-m","esptool"]ifchip:cmd+=["--chip",chip]cmd+=["-p",port,"-b",str(baud),"erase_flash"]ifextra_args:cmd+=extra_args start=time.time()lines=[]try:proc=subprocess.Popen(cmd,stdout=subprocess.PIPE,stderr=subprocess.STDOUT,text=True,encoding="utf-8",errors="replace",bufsize=1,)forlineinproc.stdout:line=line.rstrip()ifline:print(f"[{port}]{line}")lines.append(line)proc.wait()elapsed=time.time()-startifproc.returncode==0:returnport,True,elapsed,""tail=lines[-1]iflineselse"unknown error"returnport,False,elapsed,tailexceptExceptionase:returnport,False,time.time()-start,str(e)defmain():parser=argparse.ArgumentParser(description="并行擦除多个 ESP 设备")parser.add_argument("--ports",help="逗号分隔的端口，如 COM3,COM4；不填则自动检测")parser.add_argument("--chip",default="esp32s3",help="芯片类型，默认 esp32s3；传空字符串则自动检测")parser.add_argument("--baud",type=int,default=460800,help="波特率，默认 460800（不稳定可降到 230400）")parser.add_argument("--max-parallel",type=int,default=0,help="最大并行数，0 表示全部并行")parser.add_argument("--all-ports",action="store_true",help="不按 ESP VID 过滤，使用所有串口")args=parser.parse_args()ports=([p.strip()forpinargs.ports.split(",")ifp.strip()]ifargs.portselsedetect_ports(filter_esp=notargs.all_ports))ifnotports:print("未发现任何串口。请连接设备，或用 --ports COM3,COM4 手动指定。")sys.exit(1)print(f"发现{len(ports)}个端口:{', '.join(ports)}")print(f"芯片:{args.chipor'自动检测'}| 波特率:{args.baud}")print("-"*60)max_workers=len(ports)ifargs.max_parallel<=0elsemin(args.max_parallel,len(ports))results=[]withThreadPoolExecutor(max_workers=max_workers)aspool:futures={pool.submit(run_erase,p,args.chiporNone,args.baud,None):pforpinports}forfutinas_completed(futures):results.append(fut.result())print("-"*60)print("结果汇总:")success=0forport,ok,elapsed,errinsorted(results):status="OK "ifokelse"FAIL"suffix=""ifokelsef" 原因:{err}"print(f" [{status}]{port:12s}{elapsed:6.1f}s{suffix}")ifok:success+=1print(f"\n完成:{success}/{len(ports)}成功")sys.exit(0ifsuccess==len(ports)else2)if__name__=="__main__":main()

3.2 批量清空命令

在脚本所在目录执行：

# 自动检测所有疑似 ESP 设备并全部并行擦除python batch_erase.py

常用变体：

# 只擦除指定端口python batch_erase.py--ports COM17,COM18,COM19,COM20# 设备较多时限制最多 4 路并行python batch_erase.py--max-parallel4# 波特率降低以提高稳定性python batch_erase.py--baud 230400# 如果设备 VID 不在常见 ESP 集合中，强制使用所有串口python batch_erase.py--all-ports

3.3 清空注意事项

1. 擦除后设备无法正常启动是正常的
   erase_flash会清空整个 Flash，包括 bootloader、分区表和应用程序。擦除后必须重新烧录固件。

2. 多设备并行时注意 USB 供电和 Hub 带宽
   10 个设备同时擦除容易随机失败。建议：

   • 使用带独立供电的 USB Hub；
   • 加--max-parallel 4分批；
   • 不稳定时把波特率降到230400。

3. 脚本默认只识别常见 ESP USB VID
   包括 Espressif、CP210x、CH340、FTDI。若漏设备，用--all-ports或--ports手动指定。

4. 批量下载固件

4.1 先构建项目

在 ESP-IDF 项目目录下执行：

idf.py build

构建成功后，build\目录下会生成flash_args和固件 bin 文件。

4.2 使用 esp-batch-flash 批量烧录

进入项目目录，执行：

esp-batch-flash--flash-args build\flash_args--chip esp32s3--baud 460800--max-parallel4

说明：

4.3 指定端口烧录

esp-batch-flash--ports COM17,COM18,COM19,COM20--flash-args build\flash_args--chip esp32s3--baud 460800--max-parallel4

4.4 使用所有端口

推荐直接省略--ports：

esp-batch-flash--flash-args build\flash_args--chip esp32s3--baud 460800--max-parallel4

Windows 下esp-batch-flash只检测物理连接的 COM 口。蓝牙虚拟串口等可能不会被列出；如需包含虚拟口，用 PowerShell 动态生成端口列表：

$ports=[System.IO.Ports.SerialPort]::GetPortNames()-join","esp-batch-flash--ports$ports--flash-args build\flash_args--chip esp32s3--baud 460800--max-parallel4

4.5 常用批量下载命令汇总

# 自动所有物理串口，最多 4 路并行esp-batch-flash--flash-args build\flash_args--chip esp32s3--baud 460800--max-parallel4# 指定端口esp-batch-flash--ports COM17,COM18,COM19,COM20--flash-args build\flash_args--chip esp32s3--baud 460800# 降低波特率提高稳定性esp-batch-flash--flash-args build\flash_args--chip esp32s3--baud 230400--max-parallel4# 查看完整帮助esp-batch-flash--help

5. 推荐操作流程

5.1 量产前首次验证

1. 连接 1 台设备。
2. 执行单设备擦除验证：

   python-m esptool-p COM17-b 460800 erase_flash

3. 执行单设备烧录验证：

   idf.py-p COM17 flash

4. 确认设备启动正常后，再扩展到多设备。

5.2 批量清空流程

python batch_erase.py--max-parallel4--baud 460800

5.3 批量烧录流程

idf.py build esp-batch-flash--flash-args build\flash_args--chip esp32s3--baud 460800--max-parallel4

5.4 清空后重新烧录

如果先批量清空，再批量烧录，注意：

• 清空后设备进入 ROM 下载模式，串口仍可识别；
• 直接执行批量烧录即可；
• 烧录完成后按复位或重新上电启动。

6. 故障排查

7. 附录：一键流程示例

# 1. 进入 ESP-IDF 环境后安装依赖pip install pyserial esptool esp-batch-flash# 2. 批量清空python batch_erase.py--max-parallel4--baud 460800# 3. 构建固件idf.py build# 4. 批量烧录esp-batch-flash--flash-args build\flash_args--chip esp32s3--baud 460800--max-parallel4