ESP32-C3 + W5500 + MicroPython 编译记录-海口c网

前言

我本来是想连个网，结果连上了无数个坑……

在这个项目中，我的目标是用 ESP32-C3 + W5500 作为有线网关，运行 MicroPython。听上去简单，实操下来却是一场跨平台 + 编译环境 + 烧录流程的大混战。

为了避免你也在这些坑里打转，这篇文章详细记录了我几天以来的所有血泪经验，涵盖：

• macOS + Windows 下的编译与烧录对比

• MicroPython 与 ESP-IDF 的正确版本组合

• 烧录时如何使用正确的 bin 文件

• W5500 实际驱动使用方式

坑的开端：macOS 无法识别 CH343

一切的混乱始于我用的开发板串口芯片是 CH343，macOS 下驱动兼容不太好。无奈切到 Windows 环境开始编译和烧录。可以买两个TpyeC的那种，我的S3就是两个头的，是可以正常使用的。

在MacOS使用Thonney烧录报错：Downloading from https://micropython.org/resources/firmware/ESP32_GENERIC_C3-20250415-v1.25.0.bin
Writing to /var/folders/dy/t1n7jgcs48389c2_ct1vqqk00000gn/T/tmpisppkp6z/ESP32_GENERIC_C3-20250415-v1.25.0.bin
100%/Applications/Thonny.app/Contents/Frameworks/Python.framework/Versions/3.10/bin/python3.10 -u -m esptool --port /dev/cu.usbmodem5A450120851 --chip esp32c3 --baud 115200 write_flash --flash_mode keep --flash_size keep --erase-all 0x0 /var/folders/dy/t1n7jgcs48389c2_ct1vqqk00000gn/T/tmpisppkp6z/ESP32_GENERIC_C3-20250415-v1.25.0.bin
esptool.py v4.7.0
Serial port /dev/cu.usbmodem5A450120851
Connecting....
Chip is ESP32-C3 (QFN32) (revision v0.4)
Features: WiFi, BLE
Crystal is 40MHz
MAC: 9c:9e:6e:ee:a4:28
Uploading stub...A fatal error occurred: Failed to write to target RAM (result was 01070000: Operation timed out)Command returned with error code 2（注：插上线，按住boot，按一下reset，点安装，我是一直按住boot，直到安装完成）

ESP-IDF 版本的混乱：5.5 ➜ 5.1.1 ➜ 5.4 ➜ 5.2.2

根据一众Ai的指导，我开始尝试用 ESP-IDF v5.5，一堆错误：

版本不匹配错误：D:/A_GitCode/esp-idf/components/mbedtls/mbedtls/library/platform_util.c:261:2: error: #error "No mbedtls_ms_time available"261 | #error "No mbedtls_ms_time available"|  ^~~~~#error "No mbedtls_ms_time available"还是版本不对：In file included from /Users/chenph/.espressif/tools/riscv32-esp-elf/esp-14.2.0_20241119/riscv32-esp-elf/riscv32-esp-elf/include/sys/reent.h:458,from /Users/chenph/esp-idf/components/newlib/platform_include/sys/reent.h:13,from /Users/chenph/.espressif/tools/riscv32-esp-elf/esp-14.2.0_20241119/riscv32-esp-elf/riscv32-esp-elf/include/alloca.h:11,from /Users/chenph/Work/micropython/ports/esp32/mpconfigport.h:8,from /Users/chenph/Work/micropython/py/mpconfig.h:91,from /Users/chenph/Work/micropython/py/mpstate.h:31,from /Users/chenph/Work/micropython/py/runtime.h:29,from /Users/chenph/Work/micropython/extmod/nimble/modbluetooth_nimble.c:28:
/Users/chenph/Work/micropython/extmod/nimble/modbluetooth_nimble.c: In function 'ble_secret_store_read':
/Users/chenph/Work/micropython/extmod/nimble/modbluetooth_nimble.c:1914:33: error: 'const struct ble_store_key_sec' has no member named 'ediv_rand_present'1914 |                 assert(!key->sec.ediv_rand_present);|                                 ^
/Users/chenph/Work/micropython/extmod/nimble/modbluetooth_nimble.c:1920:33: error: 'const struct ble_store_key_sec' has no member named 'ediv_rand_present'1920 |                 assert(!key->sec.ediv_rand_present);|                                 ^
/Users/chenph/Work/micropython/extmod/nimble/modbluetooth_nimble.c:1931:28: error: 'const struct ble_store_key_sec' has no member named 'ediv_rand_present'1931 |             assert(key->sec.ediv_rand_present);|                            ^
/Users/chenph/Work/micropython/extmod/nimble/modbluetooth_nimble.c: In function 'ble_secret_store_write':
/Users/chenph/Work/micropython/extmod/nimble/modbluetooth_nimble.c:1980:27: error: 'struct ble_store_key_sec' has no member named 'ediv_rand_present'1980 |             assert(key_sec.ediv_rand_present);|                           ^
make[3]: *** [esp-idf/main_esp32c3/CMakeFiles/__idf_main_esp32c3.dir/Users/chenph/Work/micropython/extmod/nimble/modbluetooth_nimble.c.obj] Error 1
make[3]: *** Waiting for unfinished jobs....
make[2]: *** [esp-idf/main_esp32c3/CMakeFiles/__idf_main_esp32c3.dir/all] Error 2
make[1]: *** [all] Error 2
make failed with exit code 2, output of the command is in the /Users/chenph/Work/micropython/ports/esp32/build-ESP32_GENERIC_C3/log/idf_py_stderr_output_38444 and /Users/chenph/Work/micropython/ports/esp32/build-ESP32_GENERIC_C3/log/idf_py_stdout_output_38444
-e See https://github.com/micropython/micropython/wiki/Build-Troubleshooting
make: *** [all] Error 1

❌ v5.5 版本过新，构建失败

❌ v5.1.1 也报错

⚠️ v5.4 是给 MicroPython v1.25 用的

网上说AI各种厉害的，纯扯淡，我用了最新版本的ChatGPT，Grok，Claude，没一个靠谱的，还是老老实实啃文档吧！！

最终确认：

• MicroPython v1.24 要配 ESP-IDF v5.2.2

我当前用的是 v1.24，回退到 ESP-IDF v5.2.2 后，很快就成功了。

Windows CMD噩梦：命令太长 + 编码格式爆炸

本来觉得烧录和编码只能用Windows了，那也在Windows下来吧，但 Windows 下编译 MicroPython 的体验极差：

• CMD 命令太长，频繁触发路径长度限制；（需要装wsl，我没有装，直接劝退，换回MacOS编译）

命令过长：（esp-idf\main_esp32c3\CMakeFiles\qstr.i.last-417609e.bat）[790/1349] Generating ../../genhdr/qstr.i.lastFAILED: genhdr/qstr.i.last D:/A_GitCode/micropython/ports/esp32/build-ESP32_GENERIC_C3/genhdr/qstr.i.last esp-idf\main_esp32c3\CMakeFiles\qstr.i.last-417609e.bat 08f08957beaee5a6The system cannot execute the specified program.Batch file failed at line 3 with errorcode 1[791/1349] Building ASM object esp-idf/riscv/CMakeFiles/__idf_riscv.dir/vectors.S.obj[792/1349] Linking C static library esp-idf\hal\libhal.a[793/1349] Building C object esp-idf/riscv/CMakeFiles/__idf_riscv.dir/instruction_decode.c.obj[794/1349] Building C object esp-idf/riscv/CMakeFiles/__idf_riscv.dir/interrupt.c.obj[795/1349] Building C object esp-idf/riscv/CMakeFiles/__idf_riscv.dir/interrupt_intc.c.objninja: build stopped: subcommand failed.ninja failed with exit code 1, output of the command is in the D:\A_GitCode\micropython\ports\esp32\build-ESP32_GENERIC_C3\log\idf_py_stderr_output_6864 and D:\A_GitCode\micropython\ports\esp32\build-ESP32_GENERIC_C3\log\idf_py_stdout_output_6864
See [1;31mhttps://github.com/micropython/micropython/wiki/Build-Troubleshooting[0m
make: *** [Makefile:71: all] Error 1

• Python 构建脚本中带有 Unicode 字符时，命令行编码乱掉；（可以设置chcp 65001）

乱码报错：（这个不知道是什么玩意："ϵͳ޷ִָĳ"，设置编码后可以解决）GEN D:/A_GitCode/micropython/ports/esp32/build-ESP32_GENERIC_C3/genhdr/mpversion.h
[787/1349] Generating ../../genhdr/qstr.i.last
FAILED: genhdr/qstr.i.last D:/A_GitCode/micropython/ports/esp32/build-ESP32_GENERIC_C3/genhdr/qstr.i.last
esp-idf\main_esp32c3\CMakeFiles\qstr.i.last-417609e.bat c45bc19e3ff53715
ϵͳ޷ִָĳ
Batch file failed at line 3 with errorcode 1
[792/1349] Building C object esp-idf/esp_driver_gpio/CMakeFiles/__idf_esp_driver_gpio.dir/src/gpio.c.obj
ninja: build stopped: subcommand failed.
ninja failed with exit code 1, output of the command is in the D:\A_GitCode\micropython\ports\esp32\build-ESP32_GENERIC_C3\log\idf_py_stderr_output_2176 and D:\A_GitCode\micropython\ports\esp32\build-ESP32_GENERIC_C3\log\idf_py_stdout_output_2176
See https://github.com/micropython/micropython/wiki/Build-Troubleshooting
make: *** [Makefile:71: all] Error 1

烧录失败的原因：用了错误的 bin 文件

构建成功后，我直接切回Windows烧录 micropython.bin，结果设备无法正常启动。后来才发现：

• 构建目录里还有一个自动生成的 firmware.bin

• 这个 firmware.bin 是 MicroPython 工程自动合并的成品，已经包含了 bootloader、partitions 和 micropython.bin，我烧录的micropython.bin

烧录之后控制台循环报错：ESP-ROM:esp32c3-api1-20210207
Build:Feb  7 2021
rst:0x7 (TG0WDT_SYS_RST),boot:0xc (SPI_FAST_FLASH_BOOT)
Saved PC:0x40047ed2
SPIWP:0xee
mode:DIO, clock div:1
load:0x3c150020,len:0x3cd28
load:0x3fc96600,len:0x3044
load:0x40380000,len:0x27c
load:0x42000020,len:0x14c444
Invalid image block, can't boot.
ets_main.c 333

只需要烧这个 firmware.bin就可以了！

真相大白：W5500 默认就支持了！

我一开始被Ai误导，需要使用 network.WIZNET5K() 来手动配置驱动，结果发现：

官网下载的 Esp32C3 的MicroPython v1.25版本，W5500 已经内置支持，可以直接用 network.LAN() 调用！

无需额外驱动、无需自己编译，开箱即用！

总结，正确的顺序（micropython1.24为例）

esp-idf 搭建

$ git clone -b v5.2.2 --recursive https://github.com/espressif/esp-idf.git
$ cd esp-idf
$ git checkout v5.2.2
$ git submodule update --init --recursive
$ cd esp-idf
$ ./install.sh       # (or install.bat on Windows)
$ source export.sh   # (or export.bat on Windows)

micropython 搭建

$ git clone -b v1.24.0 --recursive https://github.com/micropython/micropython.git
$ cd mpy-cross
$ make
$ cd ports/name
$ make submodules

micropython 编译

$ make BOARD=ESP32_GENERIC_S3