向NodeMCU Lilin V3的MicroPython上传main.py出错求助

问题背景 #

在Mac系统下使用NodeMCU开发板进行IoT开发，已通过以下命令成功刷入MicroPython：

esptool.py --port /dev/cu.usbserial-110 erase_flash
esptool.py --port /dev/cu.usbserial-110 --baud 115200 write_flash --flash_size=detect 0 sp8266-512k-20220618-v1.19.1.bin

刷入后可正常访问REPL，但执行上传命令时出现错误：

ampy --port /dev/cu.usbserial-110 -b 115200 put main.py

错误栈信息：

Traceback (most recent call last):
  File "/Library/Frameworks/Python.framework/Versions/3.10/bin/ampy", line 8, in <module>
    sys.exit(cli())
  File "/Library/Frameworks/Python.framework/Versions/3.10/lib/python3.10/site-packages/click/core.py", line 1130, in __call__
    return self.main(*args, **kwargs)
  File "/Library/Frameworks/Python.framework/Versions/3.10/lib/python3.10/site-packages/click/core.py", line 1055, in main
    rv = self.invoke(ctx)
  File "/Library/Frameworks/Python.framework/Versions/3.10/lib/python3.10/site-packages/click/core.py", line 1657, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "/Library/Frameworks/Python.framework/Versions/3.10/lib/python3.10/site-packages/click/core.py", line 1404, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "/Library/Frameworks/Python.framework/Versions/3.10/lib/python3.10/site-packages/click/core.py", line 760, in invoke
    return __callback(*args, **kwargs)
  File "/Library/Frameworks/Python.framework/Versions/3.10/lib/python3.10/site-packages/ampy/cli.py", line 264, in put
    board_files.put(remote, infile.read())
  File "/Library/Frameworks/Python.framework/Versions/3.10/lib/python3.10/site-packages/ampy/files.py", line 223, in put
    self._pyboard.exec_("f.write({0})".format(chunk))
  File "/Library/Frameworks/Python.framework/Versions/3.10/lib/python3.10/site-packages/ampy/pyboard.py", line 279, in exec_
    raise PyboardError('exception', ret, ret_err)

已尝试重置开发板、关闭screen连接、更换波特率，问题仍未解决。

排查与解决步骤 #

1. 匹配ampy与MicroPython版本兼容性 #

旧版MicroPython（如v1.19.1）与新版ampy可能存在兼容性冲突：

• 降级ampy到适配版本：

  pip install adafruit-ampy==1.1.0
  

• 或升级MicroPython至稳定新版本（如v1.20+），重新刷入固件：

  # 先下载对应ESP8266的最新稳定版固件，例如sp8266-20230426-v1.20.0.bin
  esptool.py --port /dev/cu.usbserial-110 erase_flash
  esptool.py --port /dev/cu.usbserial-110 --baud 460800 write_flash --flash_size=detect 0 sp8266-20230426-v1.20.0.bin
  

2. 修复串口权限与路径问题 #

Mac下串口设备可能因权限或路径变更导致通信异常：

• 检查设备权限，临时赋予读写权限：

  sudo chmod 666 /dev/cu.usbserial-110
  

• 确认设备路径正确性，重新插拔开发板后，用以下命令查看当前可用串口：

  ls /dev/cu.*
  

  若路径变更，替换命令中的设备名。

3. 避免REPL被阻塞 #

若main.py或boot.py存在阻塞代码（如无限循环、网络等待），会导致ampy无法通信：

• 先上传空文件覆盖现有main.py：

  touch empty.py
  ampy --port /dev/cu.usbserial-110 put empty.py main.py
  

• 或进入REPL时按Ctrl+C中断自动执行的代码，再尝试上传。

4. 替换ampy为其他工具 #

如果ampy问题持续，可使用兼容性更好的替代工具：

• rshell：

  pip install rshell
  rshell -p /dev/cu.usbserial-110 -b 115200
  # 进入rshell后执行上传
  cp main.py /pyboard/
  

• mpremote（MicroPython官方工具）：

  pip install mpremote
  mpremote connect /dev/cu.usbserial-110 cp main.py :main.py
  

5. 排查硬件问题 #

• 确认使用数据传输型USB线，劣质充电线会导致串口通信不稳定。
• 直接连接Mac主板USB端口，避免使用USB hub。
• 开发板重置后等待2-3秒，确保MicroPython完全启动后再执行上传命令。

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