Zephyr 中的 Adafruit QT Py RP2040 开发板支持：硬件特性、引脚映射与 UF2 烧录实践

Zephyr 中的 Adafruit QT Py RP2040 开发板支持：硬件特性、引脚映射与 UF2 烧录实践

【免费下载链接】zephyrPrimary Git Repository for the Zephyr Project. Zephyr is a new generation, scalable, optimized, secure RTOS for multiple hardware architectures.项目地址: https://gitcode.com/GitHub_Trending/ze/zephyr

Zephyr 已原生支持 Adafruit QT Py RP2040 这块基于 RP2040 SoC 的超小尺寸开发板。本文基于 Zephyr 仓库中该开发板的官方文档与配套设备树源码，系统讲解其硬件能力、默认外设引脚映射、通过 DTS 修改引脚路由的方法，以及利用 UF2 文件免适配器拖拽烧录的完整流程，帮助读者在 Zephyr 中直接完成该开发板的应用构建与上板调试。

开发板概述

Adafruit QT Py RP2040 是 Adafruit 推出的一款小型、低成本、多功能开发板（板级标识符为adafruit_qt_py_rp2040）。其核心特点：

• 搭载 RP2040 SoC；
• 板载一颗 RGB NeoPixel 灯珠；
• 配备 USB 接口和 STEMMA QT 连接器；
• 借助板载 USB Bootloader，无需任何外部适配器，以“拖放文件”（drag-and-drop）的方式即可完成烧录。

在 Zephyr 中，该开发板由 boards/adafruit/qt_py_rp2040 目录完整定义，核心文件包括：

硬件规格

官方文档列出的硬件配置如下：

• 双核 Arm Cortex-M0+ 处理器，最高主频 133 MHz；
• 264 KB 片上 SRAM；
• 8 MB 板载 QSPI Flash，支持 XIP（执行于内存中）；
• 11 个 GPIO 引脚；
• 4 路模拟输入；
• 2 个 UART 外设；
• 2 个 SPI 控制器；
• 2 个 I2C 控制器（其中一路经 STEMMA QT 连接器引出）；
• 16 路 PWM 通道；
• USB 1.1 控制器（支持 Host/Device 角色）；
• 8 个可编程 I/O（PIO），用于实现自定义外设；
• 板载 RGB LED；
• 1 个看门狗定时器外设。

板级元数据 adafruit_qt_py_rp2040.yaml 与上述规格一一对应：flash: 8192（KB）、ram: 264（KB），arch: arm，支持的运行工具链为zephyr和gnuarmemb。Zephyr 报告的开发板支持外设（supported 列表）包括：uart、gpio、adc、i2c、spi、hwinfo、watchdog、pwm、flash、dma、counter、clock。构建时启用CONFIG_SOC_RP2040（由 Kconfig.adafruit_qt_py_rp2040 中BOARD_ADAFRUIT_QT_PY_RP2040的 select 完成），并复用 Zephyr 中 Raspberry Pi Pico 的 rp2040.dtsi 公共 SoC 描述。

引脚映射与 DTS 路由

RP2040 SoC 的外设可以路由到板上的不同引脚，这类路由配置可以直接在 DTS 中修改。查看某个外设所有可行的路由方式，需参阅 RP2040 数据手册。

默认 Zephyr 外设引脚映射

这些默认映射在 adafruit_qt_py_rp2040-pinctrl.dtsi 中以 pinctrl 组的形式定义，例如 UART1：

uart1_default: uart1_default { group1 { pinmux = <UART1_TX_P20>; }; group2 { pinmux = <UART1_RX_P5>; input-enable; }; };

引脚复用常量（如UART1_TX_P20）来自 rpi-pico-rp2040-pinctrl.h 头文件，其中枚举了 RP2040 各外设到各引脚的全部可选路由。若需要改用其他引脚，只需在应用侧的 overlay 中重新定义 pinctrl 组并指向pinctrl-0，无需改动板级默认文件。

此外，ADC 默认复用覆盖了 4 路模拟输入：ADC_CH0_P26、ADC_CH1_P27、ADC_CH2_P28、ADC_CH3_P29。

STEMMA QT 连接器与 XIAO 兼容引脚

QT Py 兼容 Seeed XIAO 引脚排列。adafruit_qt_py_rp2040.dts 中定义了stemma_connector节点，把 STEMMA QT 的两个引脚映射到 GPIO：引脚 0 → P23（SCL）、引脚 1 → P22（SDA），正好对应 I2C1。

seeed_xiao_connector.dtsi 则定义了xiao_d: connector节点（compatible 为seeed,xiao-gpio），提供 D0~D10 共 11 个逻辑引脚到 RP2040 GPIO 的映射：

该文件还同时创建了三个 alias：xiao_spi→&spi0、xiao_i2c→&i2c0、xiao_serial→&uart1，便于 XIAO 生态的驱动和代码按统一 alias 访问外设。

板级设备树的关键实现细节

板级 DTS adafruit_qt_py_rp2040.dts 在通用 RP2040 SoC 描述之上做了若干板级定制，值得在二次开发时留意：

• chosen 节点：指定控制台与 shell 均使用uart1（默认波特率 115200，见&uart1节点的current-speed），SRAM 使用sram0，flash 控制器使用 QSPI 的ssi控制器，并将代码分区指向code_partition。
• 8 MB QSPI flash 分区：flash0挂载在0x10000000。分区表中第一个 0x100 字节的second_stage_bootloader分区为 RP2040 的二阶段引导程序保留区（只读），Zephyr 镜像实际写入紧随其后的code-partition（起始 0x100，大小为 8MB - 0x100）。这也解释了默认配置中CONFIG_USE_DT_CODE_PARTITION=y的作用——按设备树分区定位 flash 的可用范围。
• NeoPixel 电源使能：与部分 Adafruit 开发板不同，QT Py RP2040 的板载 NeoPixel 正极接在 GPIO 上而非正电源轨上以节省功耗，因此设备树中用 GPIO hog 在初始化时将 P11 拉高点亮 LED：

neopixel-power-enable { gpio-hog; gpios = <11 GPIO_ACTIVE_HIGH>; output-high; };

• 板载 WS2812：通过 PIO1 上的pio-ws2812节点驱动（compatible 为worldsemi,ws2812-rpi_pico-pio），数据信号在 P12（PIO1_P12）。DTS 中的注释特别说明必须放在 PIO1 上——放在 PIO0 会导致 GPIO hog 不生效。参数包括bit-waveform = <3>, <3>, <4>、chain-length = <1>（单颗灯珠）、frequency = <800000>、reset-delay = <280>，颜色映射顺序为 G、R、B。该节点通过 aliasled-strip暴露，可直接用 Zephyr 的led_stripAPI 控制。
• USB Device：zephyr_udc0: &usbd节点使能板载 USB Device 控制器，因此该板支持 Zephyr USB 设备类（CDC、HID 等）。
• 其他使能节点：timer、wdt0（看门狗）、adc、pio0、vreg均置status = "okay"；外部晶振xosc设置startup-delay-multiplier = <64>以确保晶振启动时序；I2C0/I2C1 均按 FAST 速率（I2C_BITRATE_FAST）配置，SPI0 时钟频率为 8 MHz。

默认 Kconfig 配置

adafruit_qt_py_rp2040_defconfig 提供了板上开箱即用的默认配置：

# Enable UART driver CONFIG_SERIAL=y CONFIG_UART_INTERRUPT_DRIVEN=y # Enable console CONFIG_CONSOLE=y CONFIG_UART_CONSOLE=y # Enable reset by default CONFIG_RESET=y # Enable clock control by default CONFIG_CLOCK_CONTROL=y # Code partition needed to target the correct flash range CONFIG_USE_DT_CODE_PARTITION=y # Output UF2 by default, native bootloader supports it. CONFIG_BUILD_OUTPUT_UF2=y

要点：

• 串口控制台默认启用且为中断驱动，配合zephyr,console = &uart1可在 P20（TX）上直接看到日志；
• CONFIG_USE_DT_CODE_PARTITION=y使链接地址对准设备树中定义的code-partition，避免覆盖 RP2040 二阶段引导区；
• CONFIG_BUILD_OUTPUT_UF2=y让构建流程自动产出 UF2 文件，这正是该板唯一推荐的烧录载体。

编程与调试：UF2 烧录流程

由于该开发板没有引出 SWD 调试引脚，只能通过 UF2 文件烧录，无法使用 SWD 调试器。具体流程：

1. 构建应用。为该开发板构建应用后，构建目录会默认生成build/zephyr/zephyr.uf2文件（由CONFIG_BUILD_OUTPUT_UF2=y保证）。例如：

   west build -b adafruit_qt_py_rp2040 <应用目录>

2. 进入 Bootloader 模式。按住板上的BOOTSEL按钮的同时给 QT Py RP2040 上电，主机会识别出一个大容量存储设备（RP2040 的 BOOTSEL UDF2）。

3. 拖拽烧录。将zephyr.uf2文件拖放到该存储设备上，RP2040 会自动完成 flash 写入并重启运行 Zephyr 应用。

在 Zephyr 构建系统中，UF2 转换由 board.cmake 配置：board_runner_args(uf2 "--board-id=RPI-RP2")指定 UF2 容器使用RPI-RP2板级 ID（RP2040 家族通用），并通过 boards/common/uf2.board.cmake 将uf2设为默认 flasher。因此也可以使用 Zephyr 的烧录命令：

west flash --runner uf2

在west flash路径下同样需要先把板子切到 BOOTSEL 模式（或触发 RP2040 的 USB 重枚举），使主机看到 RP2040 的 UF2 磁盘。

关于调试的说明

• 因为 SWD 引脚未引出，J-Link/ST-Link 等硬件调试器在该板上不可用；
• 日常调试建议依赖 UART1 控制台（P20 TX / P5 RX，115200 波特率）输出的日志，或结合west flash的 UF2 流程反复迭代；
• 若需要更底层的分析，RP2040 的 PIO 与 QSPI 等特性在设备树中均已使能，可通过板级 overlay 进一步定制。

小结

QT Py RP2040 在 Zephyr 中的支持相当完整：板级 DTS 精确表达了 XIAO/STEMMA QT 引脚兼容映射、8 MB QSPI flash 的引导分区布局、PIO 驱动的 NeoPixel、以及 USB Device 能力；默认配置开箱即用地提供了串口控制台与 UF2 构建产物；烧录则完全依赖 BOOTSEL + UF2 拖拽这一零适配器流程。掌握以上内容后，读者即可直接在该开发板上构建、烧录并迭代 Zephyr 应用，并通过 DTS overlay 自由调整外设引脚路由。

【免费下载链接】zephyrPrimary Git Repository for the Zephyr Project. Zephyr is a new generation, scalable, optimized, secure RTOS for multiple hardware architectures.项目地址: https://gitcode.com/GitHub_Trending/ze/zephyr