使用 WLED 时 ESP32-S3 的 USB 口读不到串口日志怎么排查?检查 ARDUINO_USB_CDC_ON_BOOT 设置
使用 WLED 时 ESP32-S3 的 USB 口读不到串口日志怎么排查?检查 ARDUINO_USB_CDC_ON_BOOT 设置
在 WLED(用 ESP32 通过 WiFi 控制 WS2812B 等数字 RGB LED 的固件)项目里,用 PlatformIO 自行编译 ESP32-S3 板子并查看串口日志时,一种常见的情况是:固件能编译、能烧录,但接在 S3 的 USB 口上的监视器里什么都读不到。WLED 仓库的构建配置把原因指向一个编译宏:ARDUINO_USB_CDC_ON_BOOT。这个宏决定固件的 Serial 对象走哪条串口路径,它的取值必须与板子的 USB 硬件接线一致,否则日志会输出到你看不到的一路上。本文基于仓库内的 platformio.ini、platformio_override.sample.ini、AGENTS.md 以及 wled00/wled.cpp、wled00/wled.h 中的实际配置和代码注释,给出检查与修正这个宏的操作路径。
这个宏决定了什么
在 wled00/wled.h 中,ESP32 分支包含串口头文件时有一条注释说明:
#include <HardwareSerial.h> // ensure we have the correct "Serial" on new MCUs (depends on ARDUINO_USB_MODE and ARDUINO_USB_CDC_ON_BOOT)
也就是说,固件里所有 Serial 输出最终写到哪条物理通道,取决于 ARDUINO_USB_MODE 和 ARDUINO_USB_CDC_ON_BOOT 这两个宏。而 platformio.ini 中 ESP32-S3 的通用配置段 [esp32s3] 并没有替你把值定死,而是要求你自己保证它被正确设置:
[esp32s3]
;; generic definitions for all ESP32-S3 boards
...
;; please make sure that the following flags are properly set (to 0 or 1) by your board.json, or included in your custom platformio_override.ini entry:
;; ARDUINO_USB_MODE, ARDUINO_USB_CDC_ON_BOOT
所以 S3 的取值只有两种来源:板子定义文件(board.json)或你自己的 platformio_override.ini 条目。当前环境里这个宏没设、或设的值与板子接线不符,日志就会出现在错误的通道上。
判断你的 S3 板子走哪条 USB 路径
platformio.ini 里现成的 S3 构建环境把两种情况写得很明确,取值跟着板子的 USB 硬件走:
- 板子上只有 USB-OTG 连接器(走 USBCDC,即文档注释里说的 "TinyUSB" 虚拟串口):
仓库中-D ARDUINO_USB_CDC_ON_BOOT=1 ;; -D ARDUINO_USB_MODE=1 ;; for boards with USB-OTG connector only (USBCDC or "TinyUSB")esp32s3dev_16MB_opi、esp32s3dev_8MB_opi、esp32s3dev_8MB_qspi、esp32s3dev_8MB_none、esp32s3_4M_qspi、esp32s3_4M_none等环境用的都是=1。 - 板子上带串口转 USB 芯片(serial-to-USB chip,即 USB 口接的是芯片 UART 引脚):
-D ARDUINO_USB_CDC_ON_BOOT=0 ;; -D ARDUINO_USB_MODE=1 ;; for boards with serial-to-USB chipesp32S3_wroom2和esp32S3_wroom2_32MB环境用的是=0,并且把=1那一行留作注释备查。
对照办法很简单:看板上那个 USB 口连的是 ESP32-S3 的 USB-OTG 引脚,还是通过一个 UART 桥芯片连到 UART0 的 TX/RX。前者取 1,后者取 0。platformio_override.sample.ini 里 ESP32-C3 的示例也给出了同样的两行注释(=1 对应 virtual CDC USB,=0 对应 serial-to-USB chip),可以对照理解。
检查当前构建环境里的取值
- 先确认你烧录用的是哪个环境:
pio run时的-e参数对应的环境名,或 platformio.ini /platformio_override.ini里[platformio]段的default_envs。 - 打开该环境(及其
extends继承链)的build_flags,找ARDUINO_USB_CDC_ON_BOOT。如果它完全没出现,说明当前依赖的是[esp32s3]基座段,而基座段明确把这个值的设置责任交给了 board.json 或 override 条目——这正是要修的地方。 - 如果出现了,对照上一节的两种接线确认 0/1 是否选对。
- 顺带排除一个常见误用:经典 ESP32(非 S3)在 arduino-esp32 >= 2.0.3 下构建时文档注释写明必须
-DARDUINO_USB_CDC_ON_BOOT=0,这个取值只适用于经典 ESP32,不能直接套到 S3 环境上。
修改配置并重建
如果问题出在 build_flags 缺失或取值不对,推荐按仓库给出的 override 机制修:把 platformio_override.sample.ini 复制为 platformio_override.ini 启用(文件开头注明 Copy to platformio_override.ini to activate overrides),在其中定义或修正你的 S3 环境。仓库里 esp32s3dev_8MB_qspi 环境就是一个可以直接照抄的最小形态(platformio.ini 第 944 行起):
[env:esp32s3dev_8MB_qspi]
extends = esp32s3dev_8MB_opi
board_build.arduino.memory_type = qio_qspi
board_build.flash_mode = qio
build_flags = ${common.build_flags} ${esp32s3.build_flags} -D WLED_RELEASE_NAME=\"ESP32-S3_8MB_qspi\"
-D WLED_WATCHDOG_TIMEOUT=0
-D ARDUINO_USB_CDC_ON_BOOT=1 ;; -D ARDUINO_USB_MODE=1 ;; for boards with USB-OTG connector only (USBCDC or "TinyUSB")
-DBOARD_HAS_PSRAM
如果你的板子不在仓库现成环境里,参照同样的写法新建环境,其中需要替换的占位是:[env:...] 环境名、board = 板卡定义名、WLED_RELEASE_NAME 内的名字(用于区分该环境产出的固件二进制)。注意 build_flags 不会自动继承父段的值,自定义环境要像上面那样完整写一遍,这是仓库现有 S3 环境(如 esp32s3dev_8MB_qspi 重写 esp32s3dev_8MB_opi 的 build_flags)遵循的模式。
另一条文档支持的途径是 board.json:platformio.ini 的 <a href="https://link.gitcode.com/i/5eeaf0876aee23c739072e08bf6c18e1" target="_blank">esp32s3] 注释说该宏可以由 board.json 设置,仓库的 [boards/adafruit_matrixportal_esp32s3_wled.json 就在其 build flags 里包含 -DARDUINO_USB_CDC_ON_BOOT=1。如果你的板子走自定义 board 定义,改这里等效。
修改后按 AGENTS.md 的构建流程重建,<环境名> 换成你上面的 S3 环境(例如 esp32s3dev_8MB_qspi):
npm ci && npm run build
pio run -e <环境名>
npm ci && npm run build 必须先于 pio run 执行,它会生成固件编译所需的 Web UI C 头文件(AGENTS.md 明确要求)。
读取日志时的两个已记录细节
改对宏之后,读日志前有两点仓库里写明的行为要心里有数:
- 波特率:wled00/wled.cpp 中
Serial.begin(115200),监视器按 115200 配置。S3 各环境还设置了monitor_filters = esp32_exception_decoder,异常堆栈会被自动解码。 - 调试输出的存在与否取决于
WLED_DEBUG:AGENTS.md 说明DEBUG_PRINTF()/DEBUG_PRINTLN()等宏在不定义-D WLED_DEBUG时编译为空。也就是说普通构建下,固件启动时打印的版本、esp-idf 版本、CPU 型号、Flash 大小等信息(见 wled00/wled.cpp 中的DEBUG_PRINTF_P调用)不会出现。想在串口里看到启动输出,就在环境build_flags里加-D WLED_DEBUG(platformio_override.sample.ini 将其归在 Create debug build 一类)。 - CDC 虚拟串口(
=1)下,WLED_DEBUG构建会在Serial.begin后执行delay(2500)等待 CDC USB 串口初始化(wled00/wled.cpp 注释:allow CDC USB serial to initialise);未开WLED_DEBUG的 CDC 构建则调用Serial.setDebugOutput(false)关闭内核消息。另外Serial.setTimeout(50)只在非 CDC 分支执行,注释指出它在带虚拟 USB 串口的新 MCU 上会惹麻烦——这些都是同一宏改变运行时行为的直接证据。
验证与边界
完成重建后打开 PlatformIO 串口监视器(115200),重新上电或触发烧录:
- 开了
-D WLED_DEBUG时,应看到启动信息依次出现:WLED 版本行、esp-idf版本、arduino-esp32版本、CPU 型号/频率、Flash 大小等(对应 wled00/wled.cpp 的打印顺序,CDC 构建下因 2.5 秒初始化延时,输出会稍后才出现)。 - 如果仍然读不到,按上面"判断接线"一节回到硬件层面复核:这个宏没有"安全默认值",0 和 1 分别对应 serial-to-USB 芯片与纯 USB-OTG 两种物理接线,只有与板子实际一致才能在你接的 USB 口上读到输出。
- 边界提醒:该排查路径只覆盖 S3 这类"新 MCU"的 USB 路径选择问题;经典 ESP32 固定为
=0(arduino-esp32 >= 2.0.3 起为强制要求),不适用本节的 0/1 选择讨论。文档没有给出"某个值对全部 S3 板子都有效"的结论,取值依据始终是上面两条接线条件。