尧图网页设计 
Marlin ESP32 HAL 深度解析I2S 步进驱动、WiFi/OTA 与构建验证指南【免费下载链接】MarlinMarlin is a firmware for RepRap 3D printers optimized for both 8 and 32 bit microcontrollers. Marlin supports all common platforms. Many commercial 3D printers come with Marlin installed. Check with your vendor if you need source code for your specific machine.项目地址: https://gitcode.com/GitHub_Trending/ma/Marlin本文是 Marlin 固件仓库中 Marlin/src/HAL/ESP32/AGENTS.md 工作笔记的展开版系统讲解 ESP32 平台 HAL硬件抽象层的架构、构建验证流程、十大易错点与开发约定。读完你将掌握如何用mftest验证 ESP32 目标、理解 I2S-DMA 步进脉冲生成与 EXIO 串行扩展两种互斥后端、正确配置分区表与 WiFi/OTA以及避开 ADC2、PWM 引脚范围等常见陷阱。一、ESP32 HAL 概述Marlin 在 Xtensa 双核芯片上的落脚点Marlin/src/HAL/ESP32/目录是 Marlin 在 Espressif ESP32Xtensa 架构平台上的硬件抽象层实现。它负责把 Marlin 核心模块步进电机、温度、串口、EEPROM、PWM 等与 ESP32 底层外设对接核心特性包括I2S-DMA 步进脉冲生成通过 I2S 外设与 DMA 将步进脉冲流式输出摆脱传统定时器中断逐引脚翻转的负担可选的串行 I/O 扩展器EXIO用于 PANDA 等通过串口扩展 IO 的板型可选的 WiFi / OTA / Web 支持WIFISUPPORTESPAsyncWebServer、ESP3D_WIFISUPPORTesp3dlib两条路线串口、EEPROM、SPI、PWM、ADC 等基础 HAL API。全部 HAL 源码均以#ifdef ARDUINO_ARCH_ESP32保护见 HAL.cpp只有目标平台为 ESP32 时才会被编译这与其它平台 HAL 的隔离方式一致。二、构建与测试循环用mftest而非裸pio run2.1 为什么要用 mftestESP32 的构建入口与其它平台一样是 PlatformIO但文档明确指出mftest会为每个测试目标重新生成Marlin/Configuration.h而裸pio run -e无法可靠地做到这一点。因此验证 ESP32 目标的推荐方式是cd $(git rev-parse --show-toplevel) buildroot/bin/mftest -t esp32 -n1 -y # BOARD_ESPRESSIF_ESP32, WIFISUPPORTWEBSUPPORTOTA buildroot/bin/mftest -t esp32 -n2 -y # BOARD_ESPRESSIF_ESP32, TMC HW serial (Serial1) buildroot/bin/mftest -t mks_tinybee -n1 -y # BOARD_MKS_TINYBEE, ESP3D_WIFISUPPORT三个命令分别覆盖三类典型配置命令测试配置覆盖路径mftest -t esp32 -n1BOARD_ESPRESSIF_ESP32开启WIFISUPPORTWEBSUPPORTOTA基础env:esp32构建 无线全套mftest -t esp32 -n2BOARD_ESPRESSIF_ESP32TMC 驱动走硬件串口 Serial1基础env:esp32构建 TMC 硬件串口mftest -t mks_tinybee -n1BOARD_MKS_TINYBEE开启ESP3D_WIFISUPPORTESP3D WiFi 路径前两个目标对应的测试配置可以在 buildroot/tests/esp32/config-01.ini 和 buildroot/tests/esp32/config-02.ini 中看到。config-01.ini依次打开了wifisupport、websupport、otasupport、gcode_macros、baud_rate_gcode、m115_geometry_report、repetier_gcode_m360等选项config-02.ini则把 X/Y/Z/E0 四路 TMC2208/2209 全部映射到Serial1硬件串口并开启hotend_idle_timeout与software_driver_enable。2.2 额外的 PlatformIO 环境ini/esp32.ini中还定义了三个没有测试目录的环境它们只能直接构建pio run -e FYSETC_E4 -y pio run -e PANDA -y pio run -e godi_esp32 -y这三个环境各自验证特殊的配置组合FYSETC_E4使用default_16MB.csv分区表PANDA与godi_esp32使用仓库自带的 esp32.csv 自定义分区表且PANDA通过-DUSE_ESP32_EXIO -DUSE_ESP32_TASK_WDT走 EXIO 扩展路径见 ini/esp32.ini。2.3 两个重要警告本环境不保证构建通过文档明确说明当前开发环境未必安装了espressif32PlatformIO 平台因此必须亲自运行上述mftest命令验证未运行前不要声称构建是绿的。禁止用rm -rf .pio/build/...强制重建交叉 profile 的写入保护会拦截该操作且不安全。正确的清重建方式是pio run -e env -t clean或者干脆让mftest自动重建。三、框架集成上游 espressif32 平台无 vendored 核心与部分平台不同ESP32 使用的不是Marlin 自带的核心AT32 是唯一的例外而是上游的 PlatformIO 平台平台espressif322.1.0mks_tinybee使用espressif32~3.5.0工具链toolchain-xtensa-esp32s3库上游 Arduino-ESP32 / ESP-IDF所有 Marlin 特定的胶水代码集中在三处Marlin/src/HAL/ESP32/—— HAL 实现I2S 步进、WiFi、OTA、SPIFFS、串口Marlin/src/pins/esp32/—— 各板型引脚表ini/esp32.ini—— 环境定义、分区表选择、构建标志。从源码结构看引脚表文件与ini/esp32.ini中的env名称一一对应如pins_FYSETC_E4.h、pins_PANDA_M4.h、pins_PANDA_ZHU.h等每个 pins 文件声明自己的env:。因为框架在上游没有镜像到已安装包这一步——直接编辑仓库文件后重新构建即可生效。四、十大易错点Gotchas逐条解析这是 AGENTS.md 的核心价值所在。以下结合源码逐一展开。4.1 Marlin 运行在 Arduino app 核而不是独占整个芯片ESP32 是双核芯片Marlin 并非独占。I2S 步进任务通过xTaskCreatePinnedToCore(...)固定在CONFIG_ARDUINO_RUNNING_CORE上运行见 i2s.cpp即与 Marlin 其余代码同核。推论不能假设单核时序避免长时间占用portENTER_CRITICAL临界区否则会拖垮另一个核。4.2DELAY_CYCLES曾导致约 17.9 秒的打印停顿DELAY_CYCLES位于 HAL.h通过读取ccount周期计数器实现纳秒/微秒级延迟。它的脆弱点在于如果 FreeRTOS 抢占或 ISR 恰好在延迟中途介入ccount可能溢出uint32_t回绕导致循环在stop已经被越过的情况下无法察觉从而重新循环等待。源码中已经保留了完整的溢出防护逻辑if (stop start) { // 未溢出只在 start 与 stop 之间循环 while (ccount start ccount stop) { ... } } else { // stop 已溢出在 stop 与 start 之外循环 while (ccount start || ccount stop) { ... } }这个看似不优雅的分支在现实中救过场DELAY_CYCLES被软件 SPI 位操作驱动 LCD高频调用一旦触发溢出就会造成约 17.9 秒0x100000000 / 240MHz或整数倍的随机打印暂停在打印件上留下大块材料鼓包。务必保留这段逻辑不要简化它。4.3MYSERIAL1是flushableSerial不是 USB 的SerialHAL.h 定义#define MYSERIAL1 flushableSerial。在 ESP32 上裸的Serial是 USB/JTAG CDC 通道而 Marlin 的 G-code 链路走的是硬件 UART默认 Serial1。两者不可混淆。FlushableHardwareSerial在 FlushableHardwareSerial.h 中定义为HardwareSerial的子类并导出flushableSerial与flushableSerial2两个实例。TMC 硬件串口重映射由 HAL.cpp 的init_board()完成若定义了HARDWARE_SERIAL1_RX/TX则用Serial1.begin(...)绑定到用户指定引脚波特率优先取TMC_BAUD_RATE否则用默认BAUDRATESerial2同理。4.4 ADC2 在 WiFi 开启时不可用HAL.cpp 的adc_init()只配置 ADC1 通道get_channel()的映射表覆盖引脚 32–39分别映射到ADC1_CHANNEL_4/5/6/7/0/1/2/3源码注释明确写道adc2 与 WiFi 模块共享WiFi 优先级更高转换可能失败因此这里不配置它。实操建议热敏电阻引脚必须放在 ADC1 上即引脚 32–39 中 ADC1 支持的通道否则 WiFi 开启后温度读数会失败。4.5 分区表按板型选择直接影响 OTA/Web 能否装下三个分区方案并存环境分区表特点esp32/mks_tinybee平台默认 CSV最简FYSETC_E4default_16MB.csv16MB 大闪存PANDA/godi_esp32自定义Marlin/src/HAL/ESP32/esp32.csvotadata 两个 0x180000 的 OTA app 槽 SPIFFS仓库自带的 esp32.csv 布局如下# Name, Type, SubType, Offset, Size, Flags nvs, data, nvs, 0x9000, 0x5000, otadata, data, ota, 0xe000, 0x2000, app0, app, ota_0, 0x10000, 0x180000, app1, app, ota_1, 0x190000, 0x180000, spiffs, data, spiffs, 0x310000, 0xF0000,WEBSUPPORT依赖 SPIFFS 分区存放 Web 资源。如果改动闪存布局必须同步保持板子的分区 CSV 与之一致否则 OTA/Web 固件会放不下。4.6 两种互斥的步进后端I2S 流与 EXIO 串行扩展I2S_STEPPER_STREAM默认DMA 驱动的 I2S GPIO 扩展器USE_ESP32_EXIO串行 I/O 扩展器PANDA 板使用。关键约束在 i2s.cpp 的文件级#if DISABLED(USE_ESP32_EXIO)i2s.cpp只在未启用 EXIO 时编译两者绝不可同时开启。init_board()的初始化也据此分支EXIO 走YSerial2.begin(460800*3, ...)否则走i2s_init()见 HAL.cpp。有意思的是扩展器引脚编号 127的 PWM 仍会绕回 I2S 路径处理set_pwm_duty()中对pin 127的引脚直接操作i2s_port_data位见 HAL.cpp。4.7 EEPROM 自动选择 ArduinoEEPROM类eeprom.cpp 用 ESP32EEPROMNVS 闪存模拟支撑PersistentStore容量MARLIN_EEPROM_SIZE默认 4KB0x1000生命周期EEPROM.begin(MARLIN_EEPROM_SIZE)/EEPROM.end()读写write_data/read_data逐字节写入并伴随crc16校验。与 AT32 不同ESP32 无需任何SDCARD_EEPROM_EMULATION/I2C_EEPROM定义。4.8 硬件 PWM 引脚仅限 GPIO 0–33MAX_PWM_IOPIN 33HAL.hget_pwm_channel()在 HAL.cpp 中第一行就做范围检查if (!WITHIN(pin, 1, MAX_PWM_IOPIN)) return -1; // Not a hardware PWM pin!原因ESP32 的GPIO 34–39 是纯输入引脚。通道上限为 15 个 LEDC 通道。永远不要把加热棒/风扇 PWM 分配给引脚 34–39否则 PWM 静默失败。4.9 看门狗是分裂且部分为桩实现USE_WATCHDOG通过esp_task_wdt_reset()刷新任务看门狗watchdog_refresh()但 HAL.cpp 中watchdog_init()是显式的 TODO 空实现USE_ESP32_TASK_WDT在init_board()中执行esp_task_wdt_init(10, true)初始化 10 秒任务看门狗见 HAL.cpp。不要依赖watchdog_init()做任何初始化工作。4.10 WiFi 构建对体积极其敏感WIFISUPPORT引入 ESPAsyncWebServer Wi-FiESP3D_WIFISUPPORT引入 esp3dlib。为了压体积ini/esp32.ini 为esp32环境设置了-DCORE_DEBUG_LEVEL0关闭核心调试输出而mks_tinybee额外添加build_src_flags -O3优化。如果 WiFi 配置固件溢出先检查分区 CSV 和调试级别再动 HAL 代码。五、开发约定Conventions所有 HAL 源码必须由#ifdef ARDUINO_ARCH_ESP32保护HAL 改动放在Marlin/src/HAL/ESP32/板级引脚改动放在Marlin/src/pins/esp32/构建/分区/env 胶水放在ini/esp32.ini框架在上游直接改仓库文件重新构建没有需要镜像的 vendored 包三条硬性红线不要同时启用I2S_STEPPER_STREAM与USE_ESP32_EXIOWiFi 开启时不要给热敏电阻分配 ADC2 引脚不要把加热棒/风扇引脚分配在 GPIO ≥ 34。六、相关文件索引Marlin/src/HAL/ESP32/ —— 本目录无README.md本 AGENTS.md 即主要开发笔记Marlin/src/HAL/shared/ —— ESP32 HAL 复用的共享 HAL APIeeprom_api、SPI 辅助等ini/esp32.ini —— 所有 ESP32 板型的环境/分区/构建标志定义buildroot/tests/esp32/ —— 两个mftest测试目标的配置快照buildroot/tests/mks_tinybee/config-01.ini —— MKS TinyBee 的 ESP3D WiFi 测试配置。七、快速自查清单改动 ESP32 HAL 或新增板型时对照这份清单逐项检查✅ 用mftest而非裸pio run验证它会正确重生成Configuration.h✅ 双核时序避免长临界区确认 I2S 任务固定核正确✅DELAY_CYCLES的溢出保护分支未被优化掉✅ G-code 串口走硬件 UARTflushableSerial未误用 USBSerial✅ 热敏电阻在 ADC1 引脚上WiFi 开启时避免 ADC2✅ 分区表与板型匹配SPIFFS 分区存在且 Web/OTA 放得下✅I2S_STEPPER_STREAM与USE_ESP32_EXIO二选一✅ 加热棒/风扇 PWM 引脚 34✅ 不依赖watchdog_init()的初始化行为✅ WiFi 固件溢出时先查分区 CSV 与CORE_DEBUG_LEVEL。【免费下载链接】MarlinMarlin is a firmware for RepRap 3D printers optimized for both 8 and 32 bit microcontrollers. Marlin supports all common platforms. Many commercial 3D printers come with Marlin installed. Check with your vendor if you need source code for your specific machine.项目地址: https://gitcode.com/GitHub_Trending/ma/Marlin创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Marlin ESP32 HAL 深度解析：I2S 步进驱动、WiFi/OTA 与构建验证指南
Marlin ESP32 HAL 深度解析I2S 步进驱动、WiFi/OTA 与构建验证指南【免费下载链接】MarlinMarlin is a firmware for RepRap 3D printers optimized for both 8 and 32 bit microcontrollers. Marlin supports all common platforms. Many commercial 3D printers come with Marlin installed. Check with your vendor if you need source code for your specific machine.项目地址: https://gitcode.com/GitHub_Trending/ma/Marlin本文是 Marlin 固件仓库中 Marlin/src/HAL/ESP32/AGENTS.md 工作笔记的展开版系统讲解 ESP32 平台 HAL硬件抽象层的架构、构建验证流程、十大易错点与开发约定。读完你将掌握如何用mftest验证 ESP32 目标、理解 I2S-DMA 步进脉冲生成与 EXIO 串行扩展两种互斥后端、正确配置分区表与 WiFi/OTA以及避开 ADC2、PWM 引脚范围等常见陷阱。一、ESP32 HAL 概述Marlin 在 Xtensa 双核芯片上的落脚点Marlin/src/HAL/ESP32/目录是 Marlin 在 Espressif ESP32Xtensa 架构平台上的硬件抽象层实现。它负责把 Marlin 核心模块步进电机、温度、串口、EEPROM、PWM 等与 ESP32 底层外设对接核心特性包括I2S-DMA 步进脉冲生成通过 I2S 外设与 DMA 将步进脉冲流式输出摆脱传统定时器中断逐引脚翻转的负担可选的串行 I/O 扩展器EXIO用于 PANDA 等通过串口扩展 IO 的板型可选的 WiFi / OTA / Web 支持WIFISUPPORTESPAsyncWebServer、ESP3D_WIFISUPPORTesp3dlib两条路线串口、EEPROM、SPI、PWM、ADC 等基础 HAL API。全部 HAL 源码均以#ifdef ARDUINO_ARCH_ESP32保护见 HAL.cpp只有目标平台为 ESP32 时才会被编译这与其它平台 HAL 的隔离方式一致。二、构建与测试循环用mftest而非裸pio run2.1 为什么要用 mftestESP32 的构建入口与其它平台一样是 PlatformIO但文档明确指出mftest会为每个测试目标重新生成Marlin/Configuration.h而裸pio run -e无法可靠地做到这一点。因此验证 ESP32 目标的推荐方式是cd $(git rev-parse --show-toplevel) buildroot/bin/mftest -t esp32 -n1 -y # BOARD_ESPRESSIF_ESP32, WIFISUPPORTWEBSUPPORTOTA buildroot/bin/mftest -t esp32 -n2 -y # BOARD_ESPRESSIF_ESP32, TMC HW serial (Serial1) buildroot/bin/mftest -t mks_tinybee -n1 -y # BOARD_MKS_TINYBEE, ESP3D_WIFISUPPORT三个命令分别覆盖三类典型配置命令测试配置覆盖路径mftest -t esp32 -n1BOARD_ESPRESSIF_ESP32开启WIFISUPPORTWEBSUPPORTOTA基础env:esp32构建 无线全套mftest -t esp32 -n2BOARD_ESPRESSIF_ESP32TMC 驱动走硬件串口 Serial1基础env:esp32构建 TMC 硬件串口mftest -t mks_tinybee -n1BOARD_MKS_TINYBEE开启ESP3D_WIFISUPPORTESP3D WiFi 路径前两个目标对应的测试配置可以在 buildroot/tests/esp32/config-01.ini 和 buildroot/tests/esp32/config-02.ini 中看到。config-01.ini依次打开了wifisupport、websupport、otasupport、gcode_macros、baud_rate_gcode、m115_geometry_report、repetier_gcode_m360等选项config-02.ini则把 X/Y/Z/E0 四路 TMC2208/2209 全部映射到Serial1硬件串口并开启hotend_idle_timeout与software_driver_enable。2.2 额外的 PlatformIO 环境ini/esp32.ini中还定义了三个没有测试目录的环境它们只能直接构建pio run -e FYSETC_E4 -y pio run -e PANDA -y pio run -e godi_esp32 -y这三个环境各自验证特殊的配置组合FYSETC_E4使用default_16MB.csv分区表PANDA与godi_esp32使用仓库自带的 esp32.csv 自定义分区表且PANDA通过-DUSE_ESP32_EXIO -DUSE_ESP32_TASK_WDT走 EXIO 扩展路径见 ini/esp32.ini。2.3 两个重要警告本环境不保证构建通过文档明确说明当前开发环境未必安装了espressif32PlatformIO 平台因此必须亲自运行上述mftest命令验证未运行前不要声称构建是绿的。禁止用rm -rf .pio/build/...强制重建交叉 profile 的写入保护会拦截该操作且不安全。正确的清重建方式是pio run -e env -t clean或者干脆让mftest自动重建。三、框架集成上游 espressif32 平台无 vendored 核心与部分平台不同ESP32 使用的不是Marlin 自带的核心AT32 是唯一的例外而是上游的 PlatformIO 平台平台espressif322.1.0mks_tinybee使用espressif32~3.5.0工具链toolchain-xtensa-esp32s3库上游 Arduino-ESP32 / ESP-IDF所有 Marlin 特定的胶水代码集中在三处Marlin/src/HAL/ESP32/—— HAL 实现I2S 步进、WiFi、OTA、SPIFFS、串口Marlin/src/pins/esp32/—— 各板型引脚表ini/esp32.ini—— 环境定义、分区表选择、构建标志。从源码结构看引脚表文件与ini/esp32.ini中的env名称一一对应如pins_FYSETC_E4.h、pins_PANDA_M4.h、pins_PANDA_ZHU.h等每个 pins 文件声明自己的env:。因为框架在上游没有镜像到已安装包这一步——直接编辑仓库文件后重新构建即可生效。四、十大易错点Gotchas逐条解析这是 AGENTS.md 的核心价值所在。以下结合源码逐一展开。4.1 Marlin 运行在 Arduino app 核而不是独占整个芯片ESP32 是双核芯片Marlin 并非独占。I2S 步进任务通过xTaskCreatePinnedToCore(...)固定在CONFIG_ARDUINO_RUNNING_CORE上运行见 i2s.cpp即与 Marlin 其余代码同核。推论不能假设单核时序避免长时间占用portENTER_CRITICAL临界区否则会拖垮另一个核。4.2DELAY_CYCLES曾导致约 17.9 秒的打印停顿DELAY_CYCLES位于 HAL.h通过读取ccount周期计数器实现纳秒/微秒级延迟。它的脆弱点在于如果 FreeRTOS 抢占或 ISR 恰好在延迟中途介入ccount可能溢出uint32_t回绕导致循环在stop已经被越过的情况下无法察觉从而重新循环等待。源码中已经保留了完整的溢出防护逻辑if (stop start) { // 未溢出只在 start 与 stop 之间循环 while (ccount start ccount stop) { ... } } else { // stop 已溢出在 stop 与 start 之外循环 while (ccount start || ccount stop) { ... } }这个看似不优雅的分支在现实中救过场DELAY_CYCLES被软件 SPI 位操作驱动 LCD高频调用一旦触发溢出就会造成约 17.9 秒0x100000000 / 240MHz或整数倍的随机打印暂停在打印件上留下大块材料鼓包。务必保留这段逻辑不要简化它。4.3MYSERIAL1是flushableSerial不是 USB 的SerialHAL.h 定义#define MYSERIAL1 flushableSerial。在 ESP32 上裸的Serial是 USB/JTAG CDC 通道而 Marlin 的 G-code 链路走的是硬件 UART默认 Serial1。两者不可混淆。FlushableHardwareSerial在 FlushableHardwareSerial.h 中定义为HardwareSerial的子类并导出flushableSerial与flushableSerial2两个实例。TMC 硬件串口重映射由 HAL.cpp 的init_board()完成若定义了HARDWARE_SERIAL1_RX/TX则用Serial1.begin(...)绑定到用户指定引脚波特率优先取TMC_BAUD_RATE否则用默认BAUDRATESerial2同理。4.4 ADC2 在 WiFi 开启时不可用HAL.cpp 的adc_init()只配置 ADC1 通道get_channel()的映射表覆盖引脚 32–39分别映射到ADC1_CHANNEL_4/5/6/7/0/1/2/3源码注释明确写道adc2 与 WiFi 模块共享WiFi 优先级更高转换可能失败因此这里不配置它。实操建议热敏电阻引脚必须放在 ADC1 上即引脚 32–39 中 ADC1 支持的通道否则 WiFi 开启后温度读数会失败。4.5 分区表按板型选择直接影响 OTA/Web 能否装下三个分区方案并存环境分区表特点esp32/mks_tinybee平台默认 CSV最简FYSETC_E4default_16MB.csv16MB 大闪存PANDA/godi_esp32自定义Marlin/src/HAL/ESP32/esp32.csvotadata 两个 0x180000 的 OTA app 槽 SPIFFS仓库自带的 esp32.csv 布局如下# Name, Type, SubType, Offset, Size, Flags nvs, data, nvs, 0x9000, 0x5000, otadata, data, ota, 0xe000, 0x2000, app0, app, ota_0, 0x10000, 0x180000, app1, app, ota_1, 0x190000, 0x180000, spiffs, data, spiffs, 0x310000, 0xF0000,WEBSUPPORT依赖 SPIFFS 分区存放 Web 资源。如果改动闪存布局必须同步保持板子的分区 CSV 与之一致否则 OTA/Web 固件会放不下。4.6 两种互斥的步进后端I2S 流与 EXIO 串行扩展I2S_STEPPER_STREAM默认DMA 驱动的 I2S GPIO 扩展器USE_ESP32_EXIO串行 I/O 扩展器PANDA 板使用。关键约束在 i2s.cpp 的文件级#if DISABLED(USE_ESP32_EXIO)i2s.cpp只在未启用 EXIO 时编译两者绝不可同时开启。init_board()的初始化也据此分支EXIO 走YSerial2.begin(460800*3, ...)否则走i2s_init()见 HAL.cpp。有意思的是扩展器引脚编号 127的 PWM 仍会绕回 I2S 路径处理set_pwm_duty()中对pin 127的引脚直接操作i2s_port_data位见 HAL.cpp。4.7 EEPROM 自动选择 ArduinoEEPROM类eeprom.cpp 用 ESP32EEPROMNVS 闪存模拟支撑PersistentStore容量MARLIN_EEPROM_SIZE默认 4KB0x1000生命周期EEPROM.begin(MARLIN_EEPROM_SIZE)/EEPROM.end()读写write_data/read_data逐字节写入并伴随crc16校验。与 AT32 不同ESP32 无需任何SDCARD_EEPROM_EMULATION/I2C_EEPROM定义。4.8 硬件 PWM 引脚仅限 GPIO 0–33MAX_PWM_IOPIN 33HAL.hget_pwm_channel()在 HAL.cpp 中第一行就做范围检查if (!WITHIN(pin, 1, MAX_PWM_IOPIN)) return -1; // Not a hardware PWM pin!原因ESP32 的GPIO 34–39 是纯输入引脚。通道上限为 15 个 LEDC 通道。永远不要把加热棒/风扇 PWM 分配给引脚 34–39否则 PWM 静默失败。4.9 看门狗是分裂且部分为桩实现USE_WATCHDOG通过esp_task_wdt_reset()刷新任务看门狗watchdog_refresh()但 HAL.cpp 中watchdog_init()是显式的 TODO 空实现USE_ESP32_TASK_WDT在init_board()中执行esp_task_wdt_init(10, true)初始化 10 秒任务看门狗见 HAL.cpp。不要依赖watchdog_init()做任何初始化工作。4.10 WiFi 构建对体积极其敏感WIFISUPPORT引入 ESPAsyncWebServer Wi-FiESP3D_WIFISUPPORT引入 esp3dlib。为了压体积ini/esp32.ini 为esp32环境设置了-DCORE_DEBUG_LEVEL0关闭核心调试输出而mks_tinybee额外添加build_src_flags -O3优化。如果 WiFi 配置固件溢出先检查分区 CSV 和调试级别再动 HAL 代码。五、开发约定Conventions所有 HAL 源码必须由#ifdef ARDUINO_ARCH_ESP32保护HAL 改动放在Marlin/src/HAL/ESP32/板级引脚改动放在Marlin/src/pins/esp32/构建/分区/env 胶水放在ini/esp32.ini框架在上游直接改仓库文件重新构建没有需要镜像的 vendored 包三条硬性红线不要同时启用I2S_STEPPER_STREAM与USE_ESP32_EXIOWiFi 开启时不要给热敏电阻分配 ADC2 引脚不要把加热棒/风扇引脚分配在 GPIO ≥ 34。六、相关文件索引Marlin/src/HAL/ESP32/ —— 本目录无README.md本 AGENTS.md 即主要开发笔记Marlin/src/HAL/shared/ —— ESP32 HAL 复用的共享 HAL APIeeprom_api、SPI 辅助等ini/esp32.ini —— 所有 ESP32 板型的环境/分区/构建标志定义buildroot/tests/esp32/ —— 两个mftest测试目标的配置快照buildroot/tests/mks_tinybee/config-01.ini —— MKS TinyBee 的 ESP3D WiFi 测试配置。七、快速自查清单改动 ESP32 HAL 或新增板型时对照这份清单逐项检查✅ 用mftest而非裸pio run验证它会正确重生成Configuration.h✅ 双核时序避免长临界区确认 I2S 任务固定核正确✅DELAY_CYCLES的溢出保护分支未被优化掉✅ G-code 串口走硬件 UARTflushableSerial未误用 USBSerial✅ 热敏电阻在 ADC1 引脚上WiFi 开启时避免 ADC2✅ 分区表与板型匹配SPIFFS 分区存在且 Web/OTA 放得下✅I2S_STEPPER_STREAM与USE_ESP32_EXIO二选一✅ 加热棒/风扇 PWM 引脚 34✅ 不依赖watchdog_init()的初始化行为✅ WiFi 固件溢出时先查分区 CSV 与CORE_DEBUG_LEVEL。【免费下载链接】MarlinMarlin is a firmware for RepRap 3D printers optimized for both 8 and 32 bit microcontrollers. Marlin supports all common platforms. Many commercial 3D printers come with Marlin installed. Check with your vendor if you need source code for your specific machine.项目地址: https://gitcode.com/GitHub_Trending/ma/Marlin创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考