《ESP32-S3/C3学习：基于PlatformIO与Arduino框架的使用和调试记录》

本文介绍了ESP32-S3/C3在PlatformIO平台上的关键配置方法：1.调试配置需在.ini文件中添加jtag调试参数；2.使用PSRAM和SPIFlash需设置8MB分区表及内存模式；3.USB-CDC串口配置说明启用CDC模式的方法及参数含义；4.系统日志打印配置支持多级日志输出和彩色显示功能。这些配置涉及调试工具、内存管理、串口通信和日志系统等核心功能模块。

Stardust__an

1214人浏览 · 2025-09-14 02:34:19

Stardust__an · 2025-09-14 02:34:19 发布

1、单步调试配置

要在PlatformIO平台进行ESP32-S3/C3调试，需要在.ini文件加上相关配置信息

debug_tool = esp-builtin        ;选择使用内置jtag调试
debug_init_break = tbreak setup     ;调试启动时停在setup函数
debug_speed = 1000     ;单位 kHz

2、PSRAM和SPI Flash配置

如果需要使用到PSRAM和SPI Flash，进行如下配置：

; 指定为8MB的FLASH分区表
board_build.arduino.partitions = default_8MB.csv
; 指定FLASH和PSRAM的运行模式
board_build.arduino.memory_type = qio_opi
; 指定FLASH容量为8MB
board_upload.flash_size = 8MB

;定义启用PSRAM
build_flags = -DBOARD_HAS_PSRAM

3、USB-CDC 串口配置

如需使用USB接口进行串口输出，进行如下配置

build_flags =
  -D ARDUINO_USB_MODE=1          ; 启用 USB 功能（CDC 模式）
  -D ARDUINO_USB_CDC_ON_BOOT=1   ; 启动时自动启用 CDC 串口

参数解释：

-D ARDUINO_USB_MODE=1：设置 USB 工作模式

作用：指定 ESP32 芯片的 USB 硬件接口工作模式（ESP32-S3 等内置 USB 控制器的型号支持，传统 ESP32 不支持）。
参数含义：
ARDUINO_USB_MODE 通常有以下取值（不同版本框架可能略有差异）：
- 0：禁用 USB 功能（默认，部分开发板）。
- 1：启用 USB 功能，将 USB 接口配置为 CDC 设备模式（即模拟串口，可与电脑通过 USB 直连通信）。
- 2：其他特殊模式（如 USB 主机模式，较少用）。

-D ARDUINO_USB_CDC_ON_BOOT=1：启动时启用 CDC 串口

作用：控制开发板上电启动时，是否自动启用 USB CDC 串口功能（即虚拟串口）。
参数含义：
- 1：启动时自动初始化 USB CDC 串口，开机即可通过 USB 虚拟串口与电脑通信（类似传统的 Serial 接口）。
- 0：不自动启用，需在代码中手动初始化 USB 串口（较少用）。
实际效果：
配置后，代码中直接使用 Serial.begin(115200); 即可通过 USB 口与电脑通信，无需关心硬件串口引脚。

4、系统日志打印配置

build_flags =
    -D CORE_DEBUG_LEVEL=ARDUHAL_LOG_LEVEL_INFO    ;日志级别配置
    -D CONFIG_ARDUHAL_LOG_COLORS=1      ; 启用彩色日志

;日志级别及解释
;define ARDUHAL_LOG_LEVEL_NONE (0) ; 关闭所有日志输出
;define ARDUHAL_LOG_LEVEL_ERROR (1) ; 仅输出错误日志（如程序崩溃、关键功能失败）
;define ARDUHAL_LOG_LEVEL_WARN (2) ; 输出警告 + 错误日志
;define ARDUHAL_LOG_LEVEL_INFO (3) ; 输出信息 + 警告 + 错误日志
;define ARDUHAL_LOG_LEVEL_DEBUG (4) ; 输出调试 + 信息 + 警告 + 错误日志
;define ARDUHAL_LOG_LEVEL_VERBOSE (5) ; 输出所有日志

CONFIG_ARDUHAL_LOG_COLORS=1 作用
启用后，串口终端输出的日志会根据级别显示不同颜色（如错误为红色、警告为黄色、信息为白色），方便快速区分日志类型，提升调试效率。
注意：该功能依赖终端支持彩色显示（如 VS Code 终端、PuTTY 等，部分老旧终端可能不支持）。

5、程序错误定位

在调试中，因为程序bug经常会进入错误中断，串口日志类似为：

Stack smashing protect failure!


Backtrace: 0x40377926:0x3fcebb40 
           0x4037b001:0x3fcebb60 
           0x40376f6e:0x3fcebb80 
           0x42001993:0x3fcebba0 
           0x4200342d:0x3fcebc50

ELF file SHA256: 735f34a3c4dd49d6

Rebooting...

我们可以利用 Backtrace 定位错误代码位置，错误日志中的Backtrace（回溯信息）是关键：

我们可以根据回溯信息里提供的PC（程序计数器）和SP（堆栈指针），通过
xtensa-esp32-elf-addr2line工具回溯触发错误的代码行
xtensa-esp32-elf-addr2line.exe使用方法：

 <工具所在目录绝对路径>\xtensa-esp32-elf-addr2line.exe -pfiaC -e <写入MCU的固件的绝对路径>\firmware.elf <Backtrace信息>

得出如下信息：

PS C:\Users\Stardust\Desktop\ESP32-S3-Dev\ESP32S3__RB_test\.pio\build\esp32-s3-devkitc-1> D:\PlatformIO_Core\packages\toolchain-xtensa-esp32s3\bin\xtensa-esp32s3-elf-addr2line -e firmware.elf 0x40377926:0x3fcebb40 0x4037b001:0x3fcebb60 0x40376f6e:0x3fcebb80 0x42001993:0x3fcebba0 0x4200342d:0x3fcebc50
/Users/ficeto/Desktop/ESP32/ESP32S2/esp-idf-public/components/esp_system/panic.c:408
/Users/ficeto/Desktop/ESP32/ESP32S2/esp-idf-public/components/esp_system/esp_system.c:137      
/Users/ficeto/Desktop/ESP32/ESP32S2/esp-idf-public/components/esp_system/stack_check.c:35      
C:\Users\Stardust\Desktop\ESP32-S3-Dev\ESP32S3__RB_test/src/main.cpp:65
D:/PlatformIO_Core/packages/framework-arduinoespressif32@3.20014.231204/cores/esp32/main.cpp:50
PS C:\Users\Stardust\Desktop\ESP32-S3-Dev\ESP32S3__RB_test\.pio\build\esp32-s3-devkitc-1>

可以看到，在了main.c的第65行后触发了堆栈检测错误