使用esptool烧写ESP8266 NodeMCU固件时出现SerialTimeoutException串口超时问题

问题背景 #

正在开发基于ESP8266 NodeMCU开发板、使用MicroPython控制4路继电器的项目，最初使用esptool烧写最新MicroPython固件bin文件、上传代码均正常，后续出现COM3端口占用问题。尝试用esptool擦除原有flash后重新烧写固件，但esptool启动写入操作数秒后就抛出SerialTimeoutException异常，更换两块全新同款开发板、重新下载固件文件后问题依旧，以下是命令行执行esptool的完整输出：

(base) PS C:\development\python> esptool --port com3 --baud 9600 write_flash --flash_size detect --flash_mode dio -z 0x0000 esp8266-20210902-v1.17.bin
esptool.py v3.2
Serial port com3
Connecting...
Device PID identification is only supported on COM and /dev/ serial ports.
.
Detecting chip type... Unsupported detection protocol, switching and trying again...
Connecting...
Device PID identification is only supported on COM and /dev/ serial ports.
.
Detecting chip type... ESP8266
Chip is ESP8266EX
Features: WiFi
Crystal is 26MHz
MAC: 44:17:93:0d:50:04
Uploading stub...
Running stub...
Stub running...
Configuring flash size...
Auto-detected Flash size: 4MB
Flash will be erased from 0x00000000 to 0x0009afff...
Flash params set to 0x0240
Compressed 633688 bytes to 416263...
Writing at 0x00000000... (3 %)Traceback (most recent call last):
  File "c:\users\billa\anaconda3\lib\runpy.py", line 193, in _run_module_as_main
    "__main__", mod_spec)
  File "c:\users\billa\anaconda3\lib\runpy.py", line 85, in _run_code
    exec(code, run_globals)
  File "C:\Users\billa\Anaconda3\Scripts\esptool.exe\__main__.py", line 7, in <module>
  File "c:\users\billa\anaconda3\lib\site-packages\esptool.py", line 5136, in _main
    main()
  File "c:\users\billa\anaconda3\lib\site-packages\esptool.py", line 4602, in main
    operation_func(esp, args)
  File "c:\users\billa\anaconda3\lib\site-packages\esptool.py", line 3873, in write_flash
    esp.flash_defl_block(block, seq, timeout=timeout)
  File "c:\users\billa\anaconda3\lib\site-packages\esptool.py", line 154, in inner
    return func(*args, **kwargs)
  File "c:\users\billa\anaconda3\lib\site-packages\esptool.py", line 919, in flash_defl_block
    self.ESP_FLASH_DEFL_DATA, struct.pack('<IIII', len(data), seq, 0, 0) + data, self.checksum(data), timeout=timeout)
  File "c:\users\billa\anaconda3\lib\site-packages\esptool.py", line 495, in check_command
    val, data = self.command(op, data, chk, timeout=timeout)
  File "c:\users\billa\anaconda3\lib\site-packages\esptool.py", line 458, in command
    self.write(pkt)
  File "c:\users\billa\anaconda3\lib\site-packages\esptool.py", line 421, in write
    self._port.write(buf)
  File "c:\users\billa\anaconda3\lib\site-packages\serial\serialwin32.py", line 323, in write
    raise writeTimeoutError
serial.serialutil.SerialTimeoutException: Write timeout
(base) PS C:\development\python> esptool --port com3 --baud 9600 erase_flash
esptool.py v3.2
Serial port com3
Connecting...
Device PID identification is only supported on COM and /dev/ serial ports.
.
Detecting chip type... Unsupported detection protocol, switching and trying again...
Connecting...
Device PID identification is only supported on COM and /dev/ serial ports.
.
Detecting chip type... ESP8266
Chip is ESP8266EX
Features: WiFi
Crystal is 26MHz
MAC: 44:17:93:0e:3f:ce
Uploading stub...
Running stub...
Stub running...
Erasing flash (this may take a while)...
Chip erase completed successfully in 4.7s
Hard resetting via RTS pin...
(base) PS C:\development\python> esptool --port com3 --baud 9600 write_flash --flash_size detect --flash_mode dio -z 0x0000 esp8266-20210902-v1.17.bin
esptool.py v3.2
Serial port com3
Connecting...
Device PID identification is only supported on COM and /dev/ serial ports.
.
Detecting chip type... Unsupported detection protocol, switching and trying again...
Connecting...
Device PID identification is only supported on COM and /dev/ serial ports.
.
Detecting chip type... ESP8266
Chip is ESP8266EX
Features: WiFi
Crystal is 26MHz
MAC: 44:17:93:0e:3f:ce
Uploading stub...
Running stub...
Stub running...
Configuring flash size...
Auto-detected Flash size: 4MB
Flash will be erased from 0x00000000 to 0x0009afff...
Flash params set to 0x0240
Compressed 633688 bytes to 416263...
Writing at 0x00000000... (3 %)Traceback (most recent call last):
  File "c:\users\billa\anaconda3\lib\runpy.py", line 193, in _run_module_as_main
    "__main__", mod_spec)
  File "c:\users\billa\anaconda3\lib\runpy.py", line 85, in _run_code
    exec(code, run_globals)
  File "C:\Users\billa\Anaconda3\Scripts\esptool.exe\__main__.py", line 7, in <module>
  File "c:\users\billa\anaconda3\lib\site-packages\esptool.py", line 5136, in _main
    main()
  File "c:\users\billa\anaconda3\lib\site-packages\esptool.py", line 4602, in main
    operation_func(esp, args)
  File "c:\users\billa\anaconda3\lib\site-packages\esptool.py", line 3873, in write_flash
    esp.flash_defl_block(block, seq, timeout=timeout)
  File "c:\users\billa\anaconda3\lib\site-packages\esptool.py", line 154, in inner
    return func(*args, **kwargs)
  File "c:\users\billa\anaconda3\lib\site-packages\esptool.py", line 919, in flash_defl_block
    self.ESP_FLASH_DEFL_DATA, struct.pack('<IIII', len(data), seq, 0, 0) + data, self.checksum(data), timeout=timeout)
  File "c:\users\billa\anaconda3\lib\site-packages\esptool.py", line 495, in check_command
    val, data = self.command(op, data, chk, timeout=timeout)
  File "c:\users\billa\anaconda3\lib\site-packages\esptool.py", line 458, in command
    self.write(pkt)
  File "c:\users\billa\anaconda3\lib\site-packages\esptool.py", line 421, in write
    self._port.write(buf)
  File "c:\users\billa\anaconda3\lib\site-packages\serial\serialwin32.py", line 323, in write
    raise writeTimeoutError
serial.serialutil.SerialTimeoutException: Write timeout
(base) PS C:\development\python>

2021年12月3日更新 #

尝试使用Arduino IDE通过同一COM3端口上传4路继电器测试sketch，运行完全正常，但Thonny IDE和esptool均无法正常通过COM3端口连接开发板。
目前已排除ESP8266开发板、电脑COM端口、esptool和Thonny IDE工具本身故障的可能，需排查其他潜在问题。

• 检查Python串口依赖兼容性：当前esptool运行在Anaconda的base环境下，Arduino IDE自带独立的串口依赖栈，不受系统Python库影响。可尝试将环境内的pyserial库降级到3.4~3.5版本（esptool v3.2的官方适配版本），避免版本不兼容导致的写入超时。
• 调整烧写命令参数：
  • 去掉命令中的-z参数，关闭烧写后的压缩校验
  • 更换--flash_mode参数为qio或dout，部分批次NodeMCU的Flash硬件接线模式和默认dio不匹配
  • 手动指定--flash_size 4MB替代自动检测，减少协议交互开销
  • 可尝试修改烧写起始地址为0x1000，部分旧版本NodeMCU的MicroPython固件默认起始地址非0x0000
• 修正下载模式触发时序：Arduino IDE上传时会自动适配NodeMCU的下载模式电平触发时序，esptool的电平触发逻辑在部分Windows CH340/CP2102驱动下存在时序偏差，烧写时可手动按住开发板的FLASH按键，直到写入进度开始跳动后再松开。
• 排查后台串口静默占用：部分串口监控工具、物联网设备管理软件会在后台静默扫描串口，仅占用串口写入权限不占用读取权限，会出现擦除正常但写入失败的情况。可打开设备管理器卸载COM3端口后重新扫描硬件，重启电脑后第一时间执行烧写命令测试。

内容的提问来源于stack exchange，提问作者Willyd