RIOT 开发指南：ESP32-S3-USB-OTG 板卡支持、外设配置与 USB 设备开发实践
发布时间：2026/9/19 13:41:16 作者：尧图编辑部 阅读量：1,286
RIOT 开发指南ESP32-S3-USB-OTG 板卡支持、外设配置与 USB 设备开发实践【免费下载链接】RIOTRIOT - The friendly OS for IoT项目地址: https://gitcode.com/GitHub_Trending/riot/RIOT本篇技术指南围绕 RIOT 操作系统中对Espressif ESP32-S3-USB-OTG开发板的板级支持Board Support展开系统梳理该板卡在 RIOT 中的硬件资源映射、外设配置、固件烧录方式以及 STDIO 选择策略。读完本文你将能够为这块以 USB 为设计核心的板卡正确配置应用工程、理解其 GPIO/SPI/SDMMC/USB 外设的底层接线逻辑并掌握两种烧录途径与串口控制台切换方法可直接基于该板卡开展 USB 设备类应用的开发。板卡概览OverviewESP32-S3-USB-OTG 是 Espressif 官方推出的开发板其设计目标是为使用 USB 接口的应用开发提供硬件平台。为此板卡同时配备了两个 USB Type-A 端口USB_DEV公口male用于将开发板作为 USB 设备连接到主机HostUSB_HOST母口female用于将其他 USB 设备连接到开发板。需要特别注意的是如 boards/esp32s3-usb-otg/doc.md 中的明确说明RIOT-OS 目前仅支持USB_DEV端口即该板卡在 RIOT 中只能作为 USB 设备USB Device使用USB_HOST主机口暂不支持。该板卡的主要特性如下表所示FeatureSupportESP32-S3 SoCyes (1 core)2.4 GHz WiFi 802.11b/g/nyesBluetooth5, BLEyes8 MByte FlashyesUSB Type-A Host InterfacenoUSB Type-A Device InterfaceyesSD Card SlotyesLCD Color Display 240 x 240yes从特性表可以看出除 USB Host 之外该板卡在 WiFi/BLE、Flash 容量、SD 卡槽与 LCD 显示方面能力齐全是一个适合做带屏、带存储、带 USB 设备功能的嵌入式应用平台。硬件组成HardwareSoC 与模组板卡的大多数功能由ESP32-S3 SoC提供。ESP32-S3 属于 Espressif 的 ESP32x SoC 系列具体到该板卡使用的是ESP32-S3-MINI-1 模组。这一点在板级构建文件中也有直接体现boards/esp32s3-usb-otg/Makefile.features 首行即声明了 CPU 型号CPU_MODEL esp32s3_mini_1x_n8对应的 Kconfig 选择逻辑位于 boards/esp32s3-usb-otg/Kconfig其中select CPU_MODEL_ESP32S3_MINI_1X_N8与 Makefile 中的声明保持一致。关于 ESP32-S3 SoC 系列family的详细信息可参阅仓库中 ESP32 通用文档及 boards/common/esp32s3/doc.md 所述的各 ESP32-S3 板卡公共定义。板载外设该开发板最重要的板载资源包括Micro-SD 卡接口1.3 英寸彩色 LCD 显示屏显示控制器为ST7789USB-to-UART 桥接电路USB_DEVType-A 公口USB_HOSTType-A 母口其中 ST7789 LCD 与 SD 卡槽在板级软件配置中均有完整定义下文将结合源码逐一展开。板卡资源配置Board Configuration板卡的 GPIO 功能分配是应用开发中最关键的参考信息。官方文档给出了完整的引脚功能表FunctionGPIOsRemarksConfigurationBTN0GPIO0OK ButtonBTN1GPIO14MENU ButtonBTN2GPIO11DW- ButtonBTN3GPIO10UP activeLED0GPIO15Green LEDLED1GPIO16Yellow LEDLCD_DCGPIO4LCD_ENGPIO5LCD_RSTGPIO8LCD_BLGPIO9LCD BacklightADC_LINE(0)GPIO1USB_HOST VoltageADC ChannelsADC_LINE(1)GPIO2Battery VoltageADC ChannelsPWM_DEV(0):0GPIO15LED0PWM ChannelsPWM_DEV(0):1GPIO16LED1PWM ChannelsSPI_DEV(0):SCKGPIO6LCD_SCLKSPI InterfacesSPI_DEV(0):MOSIGPIO7LCD_SDASPI InterfacesSPI_DEV(0):MISOGPIO3not usedSPI InterfacesSPI_DEV(0):CS0GPIO5LCD_ENSPI InterfacesSPI_DEV(1):SCKGPIO36SD_CLKSPI InterfacesSPI_DEV(1):MOSIGPIO35SD_CMDSPI InterfacesSPI_DEV(1):MISOGPIO37SD_DATA0SPI InterfacesSPI_DEV(1):CS0GPIO34SD_DATA3SPI InterfacesUART_DEV(0):TxDGPIO43USB-to-UART bridgeUART interfacesUART_DEV(0):RxDGPIO44USB-to-UART bridgeUART interfaces引脚定义在源码中的落实上述功能表并非孤立的文档描述在板级源码中均有对应定义可以对照验证按键与 LED定义在 boards/esp32s3-usb-otg/include/board.h。四个按键BTN0~BTN3分别对应 GPIO0/GPIO14/GPIO11/GPIO10均为低电平有效LOW active并配置为内部上拉输入GPIO_IN_PU默认下降沿触发中断GPIO_FALLING。板载两颗 LED 中LED0GPIO15为绿色高电平点亮LED1GPIO16为黄色高电平点亮LED0_ACTIVE/LED1_ACTIVE均为1。SAUL 注册在 boards/esp32s3-usb-otg/include/gpio_params.h 中上述外设被注册为 SAUL 设备名称分别为OK、MENU、DW-、UP均带SAUL_GPIO_INVERTED标志与低电平有效一致以及LED red、LED yellowSAUL_GPIO_INIT_CLEAR上电初始为熄灭。启用saul_default模块时Makefile.dep 会自动引入saul_gpio从而可通过 SAUL 抽象层直接读写这些按键与 LED。ADC在 periph_conf.h 中ADC_GPIOS定义为{ GPIO1, GPIO2 }与表中 ADC_LINE(0)USB_HOST 电压监测和 ADC_LINE(1)电池电压监测一一对应。PWMPWM0_GPIOS定义为{ LED0_PIN, LED1_PIN }即两颗板载 LED 同时复用为 PWM_DEV(0) 的 0/1 通道可用于 LED 亮度调节。SPISPI_DEV(0)配置为 FSPISPI2_HOSTSCKGPIO6、MOSIGPIO7、MISOGPIO3表中标注 not used源码注释为 dummy pin、CS0GPIO5专用于 LCD。SPI_DEV(1)配置为SPI3_HOSTSCKGPIO36、MOSIGPIO35、MISOGPIO37、CS0GPIO34用于 SPI 模式的 SD 卡。UARTUART0_TXDGPIO43、UART0_RXDGPIO44对应 USB-to-UART 桥接电路且源码注明这两个引脚为固定标准配置、不可更改。关于 SD 卡接口的重要说明官方文档特别强调SPI_DEV(1)只有在应用的 Makefile 中显式将sdcard_spi模块加入USEMODULE时才会被配置用于以 SPI 模式访问 SD 卡。默认情况下SDMMC 主机被配置并由periph_sdmmc模块用于访问 SD 卡。这一逻辑在源码中可交叉印证periph_conf.h 中 SPI_DEV(1) 的全部定义都被包裹在#if IS_USED(MODULE_SDCARD_SPI)条件编译之内同文件定义的sdmmc_config[]使用SDMMC_SLOT_1CLKGPIO36、CMDGPIO35、DAT0~DAT3GPIO37/38/33/34CD/WP 引脚未定义GPIO_UNDEFMakefile.dep 中给出了自动选择逻辑当使用mtd模块时若显式启用了sdcard_spi则加入mtd_sdcard_default否则加入mtd_sdmmc_default若应用启用vfs_defaultMakefile.dep 会自动追加fatfs_vfs与mtd即默认在 SD 卡上挂载 FATFS 文件系统。此外在 board.h 中SDCARD_SPI_PARAM_*系列宏SPI_DEV(1)、SPI1_CS0等同样被#if (MODULE_SDCARD_SPI) || DOXYGEN保护与文档描述完全一致。板级特性与 LCD 初始化Makefile.features 声明了板卡提供的特性FEATURES_PROVIDED periph_adc FEATURES_PROVIDED periph_pwm FEATURES_PROVIDED periph_sdmmc FEATURES_PROVIDED periph_spi FEATURES_PROVIDED periph_uart FEATURES_PROVIDED periph_usbdev FEATURES_PROVIDED esp_jtag FEATURES_PROVIDED highlevel_stdio FEATURES_PROVIDED sdcard_spi FEATURES_PROVIDED tinyusb_device其中periph_usbdev、tinyusb_device、highlevel_stdio是 USB 设备类应用的关键支撑特性。LCD 相关配置集中在 board.h 的MODULE_ST77XX条件块中控制器类型为ST77XX_CNTRL_ST7789240×240 分辨率、旋转角 0、反色INVERTED且 RGB 顺序DC/CS/RST/背光引脚分别为 GPIO4/5/8/9。板级初始化函数 board.c 在启用 ST77XX 时会把背光引脚LCD_BACKLIGHT初始化为输出。若应用启用disp_dev模块Makefile.dep 会自动引入st7789显示驱动实现一行 Makefile 点亮屏幕的接入体验。烧录固件Flashing the Device板卡提供两种烧录方式可按需选择通过USB_DEV口的USB Serial/JTAG 接口默认方式通过USB-to-UART 桥接编程口。方式一通过 USB Serial/JTAG 接口USB_DEV口默认将开发板用USB_DEV公口连接到主机后执行标准的 RIOT 烧录命令即可BOARDesp32s3_usb_otg make flash ...通常构建系统会在烧录前自动复位板卡以启用 USB Serial/JTAG 控制器并使 ESP32-S3 进入下载模式download mode。在少数特殊情况下自动复位可能失效导致烧录器无法连接并出现超时错误Serial port /dev/ttyACM0 Connecting... ... serial.serialutil.SerialTimeoutException: Write timeout文档指出这种超时可能出现在两种场景RIOTbootloader/固件尚未安装USB 端口此前曾被USB OTG 控制器占用例如用于 USBUS 或 tinyUSB 栈。此时需要手动将板卡复位进入下载模式按住BOOT按钮的同时按下并松开RESET按钮。在下载模式下USB Serial/JTAG 接口始终可用。此外还有一个重要注意点如果 USB 端口之前被 USB OTG 控制器使用过则烧录后无法自动重启运行新固件必须手动按 RESET 按钮复位板卡其他情况下 ESP32-S3 会在烧录后自动重启并运行刚烧录的应用。这一行为在 boards/common/esp32s3/stdio_esp32s3_default.dep.mk 中也有佐证——该文件注释说明即使仅启用stdio_usb_serial_jtag也会同时启用usb_board_reset模块因为板卡上应始终存在一个 CDC ACM 接口用于在之前使用过stdio_cdc_acm或stdio_tinyusb_cdc_acm的情况下复位板卡。方式二通过 USB-to-UART 桥接使用 USB-to-UART 桥接方式烧录同样简单板卡自带 Micro-USB 编程口并内置复位/BOOT/烧录逻辑。连接主机后通过编程口指定串口设备烧录BOARDesp32s3-usb-otg make flash ... PORT/dev/ttyUSB0从 boards/esp32s3-usb-otg/Makefile.include 可以看到默认串口设备为/dev/ttyACM0Linux对应 USB Serial/JTAG 接口使用 USB-to-UART 桥时则应显式指定如/dev/ttyUSB0的串口。同时该文件还定义了 OpenOCD 配置为board/esp32s3-builtin.cfg为基于 USB Serial/JTAG 的调试提供了默认配置。关于 ESP32-S3 的更多烧录、配置与编译细节可参考仓库中 ESP32 CPU 相关文档cpu/esp32目录及 ESP32-S3 板卡公共文档 boards/common/esp32s3/doc.md 指向的esp32_riot章节。STDIO 配置Using STDIOSTDIO标准输入输出的选择策略是 ESP32-S3-USB-OTG 板卡上最容易踩坑的配置点之一其默认行为如下默认情况下USB_DEV口与 USB Serial/JTAG 接口被用作 STDIO对应模块为stdio_usb_serial_jtag。默认 STDIO 的完整选择逻辑位于 boards/common/esp32s3/stdio_esp32s3_default.dep.mk若启用了USBUS 栈usbus模块则自动使用stdio_cdc_acm通过 USB CDC ACM 接口提供控制台否则若启用了tinyUSB 设备tinyusb_device模块则自动使用stdio_tinyusb_cdc_acm否则未显式指定其他 STDIO 且未使用 USB 栈时默认使用stdio_usb_serial_jtag。也就是说当你的应用引入 USBUS 或 tinyUSB 栈时STDIO 会隐式地从 USB Serial/JTAG 切换到 USB CDC ACM控制台输出将从 CDC ACM 虚拟串口呈现。这正是前文USB 端口被 USB OTG 控制器占用后自动复位失效问题的根源也是文档中专门提示需手动复位的原因。改用 UART 控制台如果不想依赖 USB 栈也可以改用 USB-to-UART 桥接与UART_DEV(0)作为 STDIO。只需在编译时显式加入stdio_uart模块BOARDesp32s3-usb-otg USEMODULEstdio_uart make flash ...此时控制台将走 GPIO43/GPIO44UART_DEV(0)连接 USB-to-UART 桥通过 Micro-USB 编程口即可在主机上以常规串口终端访问例如/dev/ttyUSB0。小结基于该板卡的 RIOT 应用开发建议综合官方文档与板级源码可以得出以下工程实践要点USB 设备应用以USB_DEV口为核心依赖periph_usbdev与tinyusb_device/usbus特性STDIO 会随之自动切换到 CDC ACM烧录与复位时需留意 USB OTG 占用导致的异常。显示与存储启用disp_dev可自动接入 ST7789 LCD默认用 SDMMC 访问 SD 卡mtd_sdmmc_default FATFS显式启用sdcard_spi才切换到 SPI_DEV(1) 模式。外设速查GPIO 功能分配以官方表格为准并与 board.h、periph_conf.h、gpio_params.h 三份头文件一一对应必要时可在应用工程中通过应用级配置覆盖机制esp32_application_specific_configurations按需调整。从板级定义到构建逻辑ESP32-S3-USB-OTG 在 RIOT 中的支持完整且自洽既能作为带屏、带 SD 卡的多媒体平台也能依托 USB 设备控制器快速落地 CDC/UVC/HID 等 USB 应用是学习与调试 RIOT USB 设备栈的理想硬件。【免费下载链接】RIOTRIOT - The friendly OS for IoT项目地址: https://gitcode.com/GitHub_Trending/riot/RIOT创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
尧图网站开发 