企业官网建设流程全解析

Zephyr RTOS 上的 Cytron Maker Pi RP2040 开发板指南：硬件资源、引脚映射与刷写实操

【免费下载链接】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 仓库中boards/cytron/maker_pi_rp2040的官方板级文档与配套设备树、CMake 配置编写，覆盖 Maker Pi RP2040 的硬件资源、默认外设引脚复用（PWM、UART、I2C、ADC、Grove 接口）以及 UF2 刷写与 OpenOCD 调试方法。读完后，你可以直接在该板上构建 Zephyr 应用，用 shell 命令驱动舵机、电机、蜂鸣器，读取 Grove 上的 I2C 传感器并测量供电电压。

一、板卡硬件概述

Maker Pi RP2040 是一块面向机器人教学的 RP2040 主板，板载电机驱动、舵机接口和 Grove 扩展座，在 Zephyr 中以maker_pi_rp2040作为板级标识（见 board.yml）。其完整硬件清单如下：

• 主控：Raspberry Pi RP2040，最高主频 133 MHz，双核 ARM Cortex-M0+
• 264 kByte SRAM，2 MByte QSPI flash
• 17 个 GPIO 引脚、3 个 ADC 引脚，支持供电电压测量
• I2C、UART 接口
• Micro USB 接口
• LiPo 充电器
• Reset、BOOT 键与 2 个用户按键
• 2 颗 RGB LED（Neopixel 灯珠）
• 带静音开关的压电蜂鸣器
• 4 路舵机接口
• 2 路电机驱动器，配 4 个手动测试按键
• 7 个 Grove 连接器，其中 1 个可用作 Maker/Qwiic/Stemma QT/zephyr_i2c 连接器
• 13 个数字引脚状态指示灯

从板级清单文件 maker_pi_rp2040.yaml 可以确认，Zephyr 为该板声明的受支持特性为：adc、clock、counter、dma、flash、gpio、hwinfo、i2c、pwm、uart、watchdog，闪存 2048 KB、RAM 264 KB，工具链为zephyr与gnuarmemb。Kconfig 侧则通过 Kconfig.maker_pi_rp2040 选择SOC_RP2040，并在 Kconfig 中选择RP2_FLASH_W25Q080这颗 QSPI flash 芯片，与硬件说明中的 "2 Mbyte QSPI flash" 相互印证。

二、默认 Zephyr 外设映射

板上每个引脚的默认复用关系都固化在设备树 maker_pi_rp2040.dts 与 maker_pi_rp2040-pinctrl.dtsi 中。默认 pinctrl 组pwm_default一次性把 PWM4A/B、PWM5A/B、PWM6A/B、PWM7A/B 和 PWM3A 全部使能，这正是下表中 8 个 Zephyr PWM 通道加 1 个蜂鸣器通道全部可用的原因。

板载控制资源

设备树中的对应实现：

• 两个用户按键在gpio_keys节点中定义为GPIO_ACTIVE_LOW | GPIO_PULL_UP，并分别绑定输入事件码INPUT_KEY_0、INPUT_KEY_1（maker_pi_rp2040.dts#L51-L65），因此input子系统可以直接上报按键事件；
• 两颗 Neopixel 由 RP2040 的 PIO 状态机驱动，ws2812节点配置了chain-length = <2>、GRB 颜色映射、280 us 复位延时和 800 kHz 刷新频率（maker_pi_rp2040.dts#L184-L205），并挂到led-strip别名上，led_strip_set_pixel()等 API 可直接寻址；
• 供电电压测量通过vbatt节点实现：这是一个voltage-divider传感器，挂在 ADC 通道 3（GPIO29），output-ohms = <10000>、full-ohms = <20000>，即板上用 10 kΩ/10 kΩ 电阻把 Vin 分压后送入 ADC（maker_pi_rp2040.dts#L44-L49），因此 sensor API 读出的电压就是分压恢复后的真实供电电压。

舵机接口（GP12–GP15）

RP2040 上 GPIO16 及以后的引脚可映射到"编号与引脚同号"的 PWM 通道（PWM6A 在 GP12 上对应通道 12），所以 shell 里控制舵机时用的通道号与表中的"Zephyr PWM name"完全一致。

电机驱动（M1A–M2B）

每路电机由 A、B 两相 PWM 控制：A 相决定正转占空比，B 相决定反转占空比，两相同时输出占空比为 0 即停转。这与后文 shell 示例中"正转用通道 8、反转向通道 9 输出"的用法完全对应。

Grove 连接器（7 个）

Grove 1（UART0）：

设备树中uart0节点设为 115200 波特率并绑定uart0_defaultpinctrl 组，同时zephyr,console与zephyr,shell-uart都指向uart0（maker_pi_rp2040.dts#L116-L121）——也就是说这个 Grove 口既是板级控制台，也能当作普通 UART 扩展口使用。

Grove 2（I2C1，即 zephyr_i2c 节点）：使用转接线可接入 Qwiic/Stemma QT 等 I2C 传感器，该连接器映射到设备树标签zephyr_i2c。

对应节点将 I2C 总线速率设为I2C_BITRATE_FAST（快速模式，通常 400 kbit/s）。

Grove 3（LED）：GP4 为led0别名（GPIO4，高电平点亮），GP5 为led1别名（GPIO5），定义见 maker_pi_rp2040.dts#L67-L79。

Grove 4：GP16、GP17 两路普通 GPIO。

Grove 5：GP6（普通 GPIO）、GP26（ADC0，与 Grove 6 共用）。

Grove 6：GP26（ADC0，与 Grove 5 共用）、GP27（ADC1）。

Grove 7：GP7（普通 GPIO）、GP28（ADC2）。

这些 Grove 座在设备树中统一用grove-header兼容串描述，gpio-map把每个座的信号线映射到具体 GPIO：例如 Grove 1 的 RX/TX 分别映射到 GPIO1/GPIO0，Grove 2 的 SCL/SDA 映射到 GPIO3/GPIO2，Grove 5/6 均把 ADC0 映射到 GPIO26（见 grove_connectors.dtsi）。ADC 三个通道（ADC0/1/2 对应 GP26/27/28）在设备树中都配置为ADC_GAIN_1、内部参考、12 位分辨率（maker_pi_rp2040.dts#L138-L176），加上电压检测用的 ADC3，共 4 个通道被暴露给zephyr,user的io-channels。

三、编程与调试

UF2 大容量存储模式（默认方式）

默认通过 USB 接口烧录：先按住 BOOT 键再按下 RST 键，设备即进入 USB 大容量存储模式。构建应用会产出build/zephyr/zephyr.uf2文件，直接拖拽到 U 盘盘符即可重新编程。UF2 输出由 maker_pi_rp2040_defconfig 中的CONFIG_BUILD_OUTPUT_UF2=y默认开启。

SWD 调试（OpenOCD）

也可以经 DEBUG 座上的 SWDIO/SWCLK 引脚烧录和调试，需要先给板子焊接 3 针排针，并准备独立调试器（如 DAP 类探针）。构建时通常要设置OPENOCD与OPENOCD_DEFAULT_PATH，烧录时加--runner openocd。

板级 CMake 文件 board.cmake 为该板注册了 openocd、jlink、uf2、blackmagicprobe、pyocd 五类 runner，并允许用-DRPI_PICO_DEBUG_ADAPTER=<name>选择 OpenOCD 的 interface 配置文件（默认cmsis-dap）。OpenOCD 的 runner 参数为：

--cmd-pre-init "source [find interface/${RPI_PICO_DEBUG_ADAPTER}.cfg]" --cmd-pre-init "transport select swd" --cmd-pre-init "source [find target/rp2040.cfg]" --cmd-pre-init "set_adapter_speed_if_not_set 2000"

其中set_adapter_speed_if_not_set过程定义在板内自带的 support/openocd.cfg：若 interface 配置未设置探针速度，则默认取 2000 kHz。UF2 runner 也指定了--board-id=RPI-RP2，说明该板复用 RP2040 的标准 UF2 板级标识。更完整的 RP2040 系烧录与调试说明可参考仓库中 rpi_pico 板级文档（boards/raspberrypi/rpi_pico）。

四、刷写示例与 shell 实操

以下示例均针对maker_pi_rp2040板，命令格式遵循 Zephyr 的 west 工作流（west build -b maker_pi_rp2040 <app>+west flash）。

4.1 blinky 与常用基础样例

先跑blinky样例验证环境：

west build -b maker_pi_rp2040 samples/basic/blinky west flash

官方文档同时推荐尝试led-strip、hello_world、button、input-dump和adc_dt样例，分别对应板上的 Neopixel、UART 控制台、双按键输入上报与 ADC 通道。

4.2 用 shell 控制 GPIO

以 sensor_shell 样例配合 GPIO shell 为例：

west build -b maker_pi_rp2040 samples/sensor/sensor_shell -- -DCONFIG_GPIO=y -DCONFIG_GPIO_SHELL=y west flash

在 shell 中把某个 GPIO 配置为输出并拉高，可观察板上对应的状态指示灯：

gpio conf gpio0 16 o gpio set gpio0 16 1

4.3 舵机控制

PWM 设备节点名为pwm@40050000（RP2040 PWM 外设的基地址）。两种方式：

1. 使用 servo-motor 样例，它通过 overlay 文件为 GP12 输出口预置舵机位置时序；
2. 在 pwm shell 中直接设占空比：

west build -b maker_pi_rp2040 samples/sensor/sensor_shell -- -DCONFIG_PWM=y -DCONFIG_PWM_SHELL=y west flash

pwm usec pwm@40050000 12 20000 800 pwm usec pwm@40050000 12 20000 2000

含义：通道 12（GP12），周期 20000 us，脉宽 800 us 与 2000 us。多数舵机支持 800–2000 us 的脉宽范围，分别对应行程两端。

4.4 蜂鸣器

先把板子短边侧的蜂鸣器开关拨到 ON，再使用与 sensor_shell 相同的构建命令，然后：

pwm usec pwm@40050000 6 1000 500 pwm usec pwm@40050000 6 1000 0

通道 6 即 GPIO22 上的 PWM3A，1000 us 周期 500 us 脉宽（500 Hz）鸣响，脉宽 0 关闭。

4.5 电机控制

控制 1 号电机的四个速度档位：

pwm usec pwm@40050000 8 1000 1000 # 100% pwm usec pwm@40050000 8 1000 500 # 50% pwm usec pwm@40050000 8 1000 200 # 20% pwm usec pwm@40050000 8 1000 0 # 停

反方向 80% 转速：

pwm usec pwm@40050000 9 1000 800

即 M1B（GPIO9）输出反转 PWM，占空比 80%。

4.6 Grove 2 上的 I2C 传感器（光敏 + shield）

使用 light_polling 样例搭配仓库内置的 adafruit_veml7700 屏蔽板（Veml7700 光照传感器）演示 Grove 2 的 I2C 用法，构建时同时指定--shield adafruit_veml7700。

4.7 测量供电电压

sensor_shell 样例同样可用于读取vbatt（即第二节的voltage-divider节点）。在 Vin 略低于 6 V 供电时，输出类似：

sensor get vbatt channel type=33(voltage) index=0 shift=3 num_samples=1 value=32688380776ns (5.977999)

其中type=33表示电压类型通道，括号内的 5.977999 单位为伏特，验证了设备树中 10 kΩ/10 kΩ 分压参数配置正确。

五、Flash 分区与其他默认配置

从 maker_pi_rp2040.dts#L82-L110 看，该板把 2 MB QSPI flash 映射到0x10000000，并划分两个只读映射分区：

• second_stage_bootloader：0x00000000起 0x100 字节，为 RP2040 二阶段 bootloader 保留；
• code_partition：0x100起，大小为 2 MB 减去 0x100 字节，应用代码写入此分区，对应zephyr,code-partition别名。

默认配置（maker_pi_rp2040_defconfig）还开启了CONFIG_BUILD_OUTPUT_HEX、CONFIG_CONSOLE、CONFIG_UART_CONSOLE、CONFIG_UART_INTERRUPT_DRIVEN、CONFIG_GPIO、CONFIG_PIO_RPI_PICO（Neopixel 依赖 PIO）、CONFIG_CLOCK_CONTROL、CONFIG_RESET与CONFIG_USE_DT_CODE_PARTITION，与本文各节演示的能力一一对应：UART 控制台、GPIO/PIO/PWM 外设以及按设备树分区定位代码加载地址。

六、小结与要点核对

• 板级标识maker_pi_rp2040，SOC 为rp2040，2 MB flash / 264 KB RAM；
• 烧录首选 BOOT+RST 进入 UF2 拖拽模式，调试需焊接 SWD 排针并使用 OpenOCD（可经-DRPI_PICO_DEBUG_ADAPTER=指定 interface）；
• PWM 统一挂在pwm@40050000，通道号与表格中的"Zephyr PWM name"一致：舵机 GP12–15 对应通道 12–15，电机 M1/M2 对应通道 8–11，蜂鸣器对应通道 6；
• Grove 1 是板级 UART0 控制台，Grove 2 是zephyr_i2c（I2C1 快速模式），Grove 3 是 led0/led1，Grove 5/6/7 提供 ADC0/1/2；
• 供电电压经vbattvoltage-divider 节点（ADC3，10 kΩ/10 kΩ 分压）通过sensor get vbatt读取。

主要参考文件：board documentation、maker_pi_rp2040.dts、grove_connectors.dtsi、pinctrl、board.cmake、defconfig。

【免费下载链接】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