RT-Thread 在 STM32F412ZG 上的实战：NUCLEO-F412ZG 开发板 BSP 使用与驱动开发指南

• 操作系统
• 嵌入式
• 物联网
• 嵌入式OS
• RTOS

导读

本文以 RT-Thread 官方维护的 NUCLEO-F412ZG 开发板 BSP 为切入点，系统讲解如何在基于 STM32F412ZG（Arm Cortex-M4、主频 100 MHz、1 MB Flash / 256 KB SRAM）的 STM32 Nucleo-144 开发板上快速跑通 RT-Thread 操作系统，并通过 ENV 工具开启 GPIO、UART、ADC、PWM、I2C、SPI、USB Device 等更多片上外设，以及 RTduino Arduino 生态兼容层。读完本文，你将掌握从硬件连接、工程编译下载，到 menuconfig 外设配置、工程再生成、FinSH 控制台验证的完整 BSP 使用链路，并理解其底层时钟配置与驱动注册机制。

1. BSP 与开发板概览

1.1 什么是 STM32F412ZG BSP

bsp/stm32/stm32f412-st-nucleo/是 RT-Thread 开发团队为意法半导体 NUCLEO-F412ZG 开发板提供的板级支持包（Board Support Package）。它把 RT-Thread 内核与 STM32F4 HAL 库、CMSIS 库、链接脚本、启动代码和板载外设驱动整合在一起，使开发者无需从零移植，即可直接获得可编译、可运行、可裁剪的 RT-Thread 工程。

BSP 根目录结构如下：

1.2 开发板核心资源

• MCU：STM32F412ZG，Arm Cortex-M4（带单精度 FPU、DSP 指令、MPU），最高 100 MHz，1024 KB FLASH、256 KB RAM。
• 板载外设：3 个 LED（LD1 通信灯、LD2 用户灯、LD3 电源灯）、USER 与 RESET 两个按键、USB（虚拟串口 / 大容量存储 / 调试三合一）、板载 ST-LINK/V2-1 调试器、32.768 kHz 晶振、ST Zio（兼容 Arduino UNO V3）与 ST morpho 扩展接口。
• 通信与模拟外设：4×USART、5×SPI/I2S、4×I2C、SDIO、USB OTG FS、2×CAN、1×12-bit 2.4 MSPS ADC（最多 16 通道）、16 通道通用 DMA、最多 17 个定时器、真随机数发生器、CRC 校验单元、96-bit 唯一 ID、低功耗 RTC。

该 MCU 属于 STM32 Dynamic Efficiency™ 产品线，支持 Batch Acquisition Mode（BAM），可在批量采集数据时进一步降低功耗。这些特性详见 STM32F412ZG BSP 介绍 与 STM32_Nucleo-144_BSP_Introduction。

1.3 外设支持现状

本 BSP 默认使能的外设如下（摘自 Kconfig 与 rtconfig.h）：

2. 快速上手：让 RT-Thread 在 NUCLEO-F412ZG 上跑起来

2.1 准备环境与依赖

BSP 依赖 STM32F4 HAL 库与 CMSIS 库，这两者通过 RT-Thread 软件包机制拉取。编译前务必先在 BSP 目录打开 ENV 工具执行：

pkgs --update

该命令会根据rtconfig.h中记录的PKG_USING_STM32F4_HAL_DRIVER、PKG_USING_STM32F4_CMSIS_DRIVER、PKG_USING_CMSIS_CORE等配置下载对应版本的 HAL/CMSIS 源码包，否则工程无法通过编译。

2.2 硬件连接

使用 Type-A 转 Micro-B USB 线连接开发板与 PC，为开发板供电。上电后红色 LED LD3（PWR）与 LD1（COM）点亮，表示供电与 ST-LINK 通信正常。

2.3 编译下载（以 MDK5 为例）

1. 双击bsp/stm32/stm32f412-st-nucleo/project.uvprojx打开 MDK5 工程（注意打开的是project.uvprojx，而非template.uvprojx模板工程）。
2. 点击 "Options for Target"：
   • Debug 页选择 ST-LINK Debugger；
   • 点击 Settings，Port 选择 "SW（Serial Wire）"；
   • Flash Download 勾选 "Reset and Run"。
3. 编译并下载程序到开发板。工程默认使用 ST-LINK 下载，点击下载按钮即可。

除 MDK5 外，本 BSP 还提供 IAR 工程（project.ewp/project.eww），并支持 GCC 开发环境。

2.4 运行结果验证

下载成功后系统自动运行：红色 LD3、LD1 常亮，蓝色 LD2 周期闪烁。LED 点灯逻辑位于 applications/main.c：

#define LED2_PIN GET_PIN(B, 7) int main(void) { /* set LED0 pin mode to output */ rt_pin_mode(LED2_PIN, PIN_MODE_OUTPUT); while (1) { rt_pin_write(LED2_PIN, PIN_HIGH); rt_thread_mdelay(500); rt_pin_write(LED2_PIN, PIN_LOW); rt_thread_mdelay(500); } }

默认控制台绑定 USB 虚拟 COM 端口（内部连接 USART3）。在终端工具中打开对应串口（波特率 115200、8 数据位、1 停止位、无校验，即 115200-8-1-N），复位开发板即可看到 RT-Thread 启动信息：

\ | / - RT - Thread Operating System / | \ 4.0.2 build Oct 20 2019 2006 - 2019 Copyright by rt-thread team msh >

msh >即 RT-Thread FinSH 命令行（MSH 模式）提示符，可输入help、list_device、list_thread等命令进行交互。

2.5 时钟配置的底层支撑

BSP 之所以能跑在 100 MHz 主频，依赖 board/board.c 中的SystemClock_Config()：以 HSE（旁路模式，开发板 ST-LINK 提供 8 MHz 时钟）为 PLL 源，PLLM=8、PLLN=384、PLLP=4得到 96 MHz SYSCLK（实际按 CubeMX 配置生成，Flash 等待周期为 3），APB1 二分频、APB2 一分频，并配置 48 MHz 时钟（CLK48CLKSOURCE_PLLQ）供 USB OTG 使用。该函数由 RT-Thread 系统启动流程在板级初始化阶段调用。

3. 进阶使用：用 ENV 工具开启更多外设

BSP 默认只开启了 GPIO 与 UART3（外加 UART2）。如需 SPI、I2C、ADC、PWM、USB Device 等高级功能，需使用 ENV 工具配置，步骤如下：

1. 在 BSP 目录（bsp/stm32/stm32f412-st-nucleo/）下打开 ENV 工具；
2. 输入menuconfig配置工程，保存后退出；
3. 输入pkgs --update更新软件包；
4. 输入scons --target=mdk5（或mdk4/iar，GCC 环境可省略 target）重新生成工程。

更完整的图文流程参见 STM32 系列 BSP 外设驱动使用教程，其中以开启 SPI Flash 驱动为例，展示了menuconfig→pkgs --update→scons --target=mdk5 -s→ 编译下载 →list_device验证的完整链路。

3.1 配置菜单结构

board/Kconfig 定义了三级驱动配置菜单：

• Onboard Peripheral Drivers（板载外设）：BSP_USING_STLINK_TO_USART（ST-LINK 虚拟串口，即 uart3，默认开启）、BSP_USING_ARDUINO（RTduino 兼容，默认关闭）。
• On-chip Peripheral Drivers（片上外设）：GPIO、UART（UART2/UART3，含 DMA 与缓冲区大小配置）、ADC（ADC1）、PWM（PWM1/PWM4/PWM14 及其通道）、TIM（TIM6）、软件 I2C（swi2c1，可配置 SCL/SDA 引脚）、SPI（SPI1，含 TX/RX DMA）、片上 Flash、USB Device（OTGFS）。
• Board extended module Drivers（扩展模块）：当前为空，用于挂载扩展板驱动。

3.2 常用外设配置项速查

注意：UART 的 DMA 选项依赖RT_SERIAL_USING_DMA；在RT_USING_SERIAL_V1与RT_USING_SERIAL_V2两种串口框架下，可配置项略有差异（V2 提供独立的 TX/RX 缓冲区大小配置）。

3.3 配置生效后的工程组织

执行scons --target=mdk5后，SCons 构建脚本会根据rtconfig.h中的宏自动挑选 HAL 驱动源文件（如drv_gpio.c、drv_usart.c、drv_spi.c、drv_i2c.c、drv_adc.c、drv_pwm.c等，位于 bsp/stm32/libraries/ 下）加入工程。因此每开启一个外设，重新生成工程后对应驱动文件即被编译进来，并通过 RT-Thread 设备框架注册为同名设备，开发者可直接使用统一的设备操作 API。

4. RTduino：兼容 Arduino 生态

NUCLEO-F412ZG BSP 还支持 RTduino——RT-Thread 的 Arduino 生态兼容层。开启方式：

Hardware Drivers Config ---> Onboard Peripheral Drivers ---> [*] Compatible with Arduino Ecosystem (RTduino)

开启后，BSP_USING_ARDUINO会自动联动开启 ST-LINK 虚拟串口、GPIO、ADC1、TIM6、PWM1/4/14（含通道）、软件 I2C1、SPI1（含 DMA）等配置，并引入RT_USING_I2C、RT_USING_SPI等内核依赖。应用可使用 Arduino 的setup()/loop()编程模型，默认示例 arduino_main.cpp 演示了 LED_BUILTIN 的点灯逻辑：

void setup(void) { pinMode(LED_BUILTIN, OUTPUT); } void loop(void) { digitalWrite(LED_BUILTIN, !digitalRead(LED_BUILTIN)); delay(100); }

引脚映射遵循 Arduino UNO 布局，详见 arduino_pinout 说明 与 pins_arduino.c，关键映射如下：

注意：同一硬件定时器的 4 个 PWM 通道只能输出同一频率，因此不要同时用同一个定时器驱动 PWM（analogWrite）和舵机，否则可能导致舵机驱动失败。使用 SPI 后，D10、D11 的 PWM 功能会被不可逆地切换为 SPI 功能。

5. 常见问题与排查建议

• 编译报错缺少 HAL 头文件：未执行pkgs --update拉取 STM32F4 HAL 与 CMSIS 软件包。请先在 BSP 目录执行该命令。
• 下载失败：确认 MDK 调试器选择 ST-LINK、SW 端口连接正常，并勾选 "Reset and Run"；也可换用 IAR 工程或 GCC 工具链对比排查。
• 串口无输出：确认终端参数为 115200-8-1-N，且打开的是虚拟 COM 端口（对应 uart3）；复位开发板后应看到启动 LOG。
• 配置后外设未生效：修改 menuconfig 后必须依次执行pkgs --update与scons --target=mdk5重新生成工程，否则驱动文件不会进入编译。

6. 参考资料

• STM32F412ZG BSP 说明（英文原版）
• STM32 Nucleo-144 BSP 使用介绍
• STM32 系列 BSP 外设驱动使用教程
• STM32F412ZG 芯片数据手册与资源（ST 官方，外部资料仅供芯片级参考）

本 BSP 由 RT-Thread 社区维护（flybreak、Meco Man 等），仓库中该目录同时提供 中文版 README，两者内容互为补充，可对照阅读。

• 操作系统
• 嵌入式
• 物联网
• 嵌入式OS
• RTOS