RT-Thread NUCLEO-STM32H563ZI BSP 快速上手与进阶开发指南

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

本文以 RT-Thread 官方仓库中 NUCLEO-STM32H563ZI 的 BSP 说明文档 为核心，系统讲解这块基于 Arm Cortex-M33 内核开发板的板级支持包（Board Support Package）的软硬件资源、快速编译下载流程、串口运行结果验证，以及通过 ENV 工具进行外设裁剪与工程重生成的进阶玩法。读完本文，你将能够在几分钟内把 RT-Thread 5.0.1 跑上 NUCLEO-STM32H563ZIT6，并根据实际需求按源码级配置点开启 ADC、PWM、多路 UART 等片上外设。

BSP 概况与文档定位

该 BSP 由 RT-Thread 开发团队为 ST 的 NUCLEO-STM32H563ZIT6 开发板提供，文档分为三大部分：开发板资源介绍、快速上手、进阶功能。其中"快速上手"章节面向初次接触 RT-Thread 的开发者，按照简单步骤即可将操作系统跑起来并看到实验效果；"进阶功能"章节则面向需要驱动更多板载资源的开发者，通过 ENV 工具配置 BSP 实现更高级的功能。BSP 目录同时提供英文 README.md 与中文 README_zh.md 两份说明，本文内容以英文版为主体、中文版为对照。

开发板资源一览

NUCLEO-STM32H563ZIT6 是 ST 推出的 NUCLEO-144 系列开发板，核心资源如下：

• MCU：STM32H563ZI，高性能 Arm Cortex-M33 内核（带 TrustZone 安全扩展），2 MB Flash、640 KB RAM、最高 250 MHz CPU，算力可达 375 DMIPS（Dhrystone 2.1）；
• 封装与外观：LQFP144 封装，板载 3 个用户 LED、2 个用户按键与 1 个复位按键、32.768 kHz 晶振；
• 连接与扩展：SWD 调试接口、ST Zio 扩展连接器（兼容 ARDUINO® Uno V3）、ST morpho 扩展连接器；
• 供电与调试：灵活供电（ST-LINK USB VBUS、USB 连接器或外部电源）；板载 ST-LINK 调试器/编程器，具备 USB 重新枚举能力，可同时提供大容量存储、虚拟串口（Virtual COM Port）与调试端口三种功能；
• 软件生态：支持 IAR Embedded Workbench®、MDK-ARM、STM32CubeIDE 等多种 IDE，并可通过 STM32Cube MCU 软件包获得全面的免费软件库与例程。

开发板外观如下图所示：

该 BSP 仓库还提供硬件框图图片，帮助理解板级供电、调试与通信链路：

注意：以上图片在仓库中同时存在于images/与figures/两个目录（英文文档引用前者，中文文档引用后者），内容一致。

BSP 外设支持情况

原文档给出的外设支持矩阵如下：

以上支持情况与源码实际配置吻合：默认生成的 rtconfig.h 中开启了BSP_USING_GPIO、BSP_USING_UART与BSP_USING_UART3，并将控制台设备指定为RT_CONSOLE_DEVICE_NAME "uart3"（即调试串口）。同时RT_USING_SERIAL、RT_USING_ADC、RT_USING_PWM、RT_USING_PIN等设备框架宏均已使能，为后续通过 menuconfig 开启具体外设通道做好了准备。

快速上手：把 RT-Thread 跑起来

第一步：拉取 HAL 与 CMSIS 依赖

这是最容易踩坑的一步。BSP 的编译依赖 STM32H5 的 HAL 库与 CMSIS 库，而这些库以软件包（package）形式管理，并未随 BSP 源码一起提交。因此在编译前，必须先打开 ENV 工具并在 BSP 目录下执行：

pkgs --update

该命令用于拉取必要的 HAL 库及 CMSIS 库，不执行则无法通过编译。在 rtconfig.h 中可以看到对应的软件包配置项：PKG_USING_STM32H5_HAL_DRIVER、PKG_USING_STM32H5_CMSIS_DRIVER（均取 LATEST_VERSION），它们正是由pkgs --update下载到packages/目录的。

第二步：硬件连接

使用Type-C 数据线将开发板连接到 PC。注意该板载 ST-LINK 为带 Type-C 接口的 STLINK-V3EC，连接后电脑会自动枚举出虚拟串口与调试端口。

第三步：编译与下载

本 BSP 为开发者提供了 MDK5（project.uvprojx）与 IAR（project.ewp/project.eww）工程，同时支持 GCC 开发环境。以 MDK5 为例：

1. 双击 project.uvprojx 打开 MDK5 工程；
2. 编译并下载程序到开发板。

工程默认配置使用 ST-LINK 仿真器下载程序，在 ST-LINK 已连接开发板的前提下，直接点击下载按钮即可。本次工程搭建使用的 MDK 版本为 5.36，建议使用较新版本的 MDK。

第四步：运行结果验证

下载成功后系统自动运行，板载LED1 会周期性闪烁。将开发板对应串口连接到 PC，在终端工具中打开该串口（参数115200-8-1-N，即波特率 115200、8 数据位、1 停止位、无校验），复位设备后可以看到 RT-Thread 的启动信息：

\ | / - RT - Thread Operating System / | \ 5.0.1 build Aug 27 2023 20:47:55 2006 - 2022 Copyright by RT-Thread team do components initialization. initialize rti_board_end:0 done initialize rt_work_sys_workqueue_init:0 done initialize finsh_system_init:0 done msh >

msh >提示符出现即代表系统正常运行，此时已可输入 RT-Thread 的 Shell（finsh/msh）命令进行交互。

LED1 闪烁背后的源码

LED 闪烁逻辑在 applications/main.c 中实现，源码确认 LED1 连接在PB0引脚：

/* defined the LED1 pin: PB0 */ #define LED1_PIN GET_PIN(B, 0) int main(void) { int count = 1; rt_pin_mode(LED1_PIN, PIN_MODE_OUTPUT); while (count++) { rt_pin_write(LED1_PIN, PIN_HIGH); rt_thread_mdelay(500); rt_pin_write(LED1_PIN, PIN_LOW); rt_thread_mdelay(500); } return RT_EOK; }

这段代码演示了 RT-Thread 统一 PIN 设备接口的典型用法：rt_pin_mode配置输出模式，rt_pin_write拉高/拉低电平，rt_thread_mdelay让出 CPU 实现 500ms 延时，构成周期 1s 的 LED 闪烁。

进阶使用：用 ENV 配置更多外设

此 BSP默认只开启 GPIO 与 UART3（调试串口）。如果需使用更多高级功能，需要利用 ENV 工具对 BSP 进行配置，完整流程如下：

1. 在 BSP 目录（bsp/stm32/stm32h563-st-nucleo）下打开 ENV 工具；
2. 输入menuconfig命令配置工程，配置好之后保存退出；
3. 输入pkgs --update命令更新软件包（使新勾选的软件包生效）；
4. 输入scons --target=mdk4/mdk5/iar命令重新生成对应 IDE 的工程文件。

注意：原文档此处提到默认开启的是"串口 1（UART1）"，但仓库实际生成的 rtconfig.h 中默认使能的是BSP_USING_UART3且控制台设备名为uart3，与"注意事项"中调试串口为 UART3 的描述一致，使用时请以配置文件为准。

Kconfig 外设开关详解

外设的可配置项集中在 board/Kconfig，与文档的外设支持矩阵一一对应，是进阶配置的"菜单地图"：

GPIO（默认开启）

• BSP_USING_GPIO：使能 GPIO，自动选择RT_USING_PIN，默认y。

UART 系列（默认开启 UART3）

• BSP_USING_UART1：默认n，可单独开启；每个 UART 下都有 DMA 与缓冲区相关选项；
• BSP_USING_UART2：默认n；
• BSP_USING_UART3：默认y，即调试串口；
• BSP_USING_LPUART1：默认y，低功耗串口；
• 通用项BSP_STM32_UART_V1_TX_TIMEOUT（默认 4000）：UART V1 框架下的发送超时（ms）；
• 各串口的 RX 缓冲区大小（*_RX_BUFSIZE，范围 64~65535，默认 256）、TX 缓冲区大小（范围 0~65535，默认 0）；
• 在使能RT_SERIAL_USING_DMA后，还可为每个串口分别开启 RX/TX DMA，以及配置 RX DMA 乒乓缓冲区大小（*_DMA_PING_BUFSIZE，默认 64）。

ADC

• BSP_USING_ADC（默认n）：总开关，使能后自动选择RT_USING_ADC；
• BSP_USING_ADC1、BSP_USING_ADC2：默认n，按需开启具体 ADC 实例。

PWM

• BSP_USING_PWM（默认n）：总开关，使能后自动选择RT_USING_PWM；
• BSP_USING_PWM1（定时器 1 输出 PWM，含 CH1/CH2/CH3）、BSP_USING_PWM3（定时器 3，CH2）、BSP_USING_PWM4（定时器 4，CH3/CH4）：均为默认n，按通道粒度使能。

软件 I2C

• BSP_USING_SOFT_I2C与BSP_USING_SOFT_I2C1：默认n；开启后可配置软件 I2C 的 SCL（默认引脚号 24）与 SDA（默认引脚号 25）引脚号。

RTduino（Arduino 生态兼容）

• BSP_USING_ARDUINO（默认n）：开启后自动选择PKG_USING_RTDUINO，并连带开启 STLINK_TO_USART、LPUART1、GPIO、ADC1/2、PWM1/3/4 多个通道、软件 I2C 等一揽子外设。仓库 applications/arduino_main.cpp 提供了对应的 Arduino 风格示例（setup/loop+Serial2.println("Hello Arduino!")），说明该 BSP 具备 RTduino 兼容能力。

以上选项保存退出后，需重新执行pkgs --update与scons --target=mdk4/mdk5/iar生成包含新外设驱动的工程。更完整的 STM32 外设驱动使用说明，可参阅仓库内 STM32 系列 BSP 外设驱动使用教程。

时钟、内存与工具链配置（源码级补充）

为了让读者对 BSP 有更深的理解，这里结合仓库源码补充文档未展开的底层配置：

系统时钟：board/board.c 中的SystemClock_Config()将主频配置到250 MHz：PLL 以 HSE 为源（RCC_PLL1_SOURCE_HSE），分频系数PLLM=4、倍频PLLN=250、PLLP=2，最终得到 250 MHz 内核时钟，并配套FLASH_LATENCY_5等待周期。同时开启了 HSI48（供 USB 使用）。该文件由 STM32CubeMX 生成，对应的工程配置见 board/CubeMX_Config/CubeMX_Config.ioc。

内存与堆：board/board.h 定义了 Flash 起始地址0x08000000、大小 2 MB（2048 * 1024），SRAM1 起始0x20000000、大小 640 KB，堆（HEAP）从各编译器的 ZI/bss 段末尾延伸到 SRAM1 末尾，分别适配了 MDK（Image$$RW_IRAM1$$ZI$$Limit）、IAR（CSTACK段末尾）与 GCC（__bss_end）三种工具链的堆起点计算方式。链接脚本统一放在 board/linker_scripts（link.lds/link.sct/link.icf分别对应 GCC/MDK/IAR）。

工具链选择：rtconfig.py 支持 gcc、keil（armclang）、iar 三套工具链，通过RTT_CC环境变量或修改CROSS_TOOL切换；GCC 环境下目标 CPU 为cortex-m33，浮点采用fpv5-sp-d16/hard-float，生成产物除rtthread.elf外还会输出rtthread.bin。BSP 根目录的 SConscript 则为整个工程注入了STM32H563xx宏，供 HAL 库裁剪使用。

注意事项

• 调试串口 UART3 的引脚映射（详见 STM32CubeMX 中的配置）：

  PD8 ------> USART3_TX（T_VCP_TX） PD9 ------> USART3_RX（T_VCP_RX）

  这意味着调试串口复用到了 ST-LINK 的虚拟串口（VCP）通道，因此直接用 Type-C 线即可观察系统日志，无需额外外接 USB 转串口模块；

• MDK 版本：建议使用较新版本的 MDK，本项目搭建时使用 MDK 5.36；
• 依赖完整性问题：任何情况下都不要跳过pkgs --update，否则缺少 HAL/CMSIS 库必然导致编译失败；
• 重新生成工程后的行为：scons --target=...会按 menuconfig 的配置重新生成工程文件，改动外设配置后必须重新执行，否则新配置不会反映到 IDE 工程中。

参考资料与深入阅读

• 开发板原理图（MB1404-H563ZI-C01）、STM32H563 官方介绍页、开发板用户手册（UM3115）等资料可从 ST 官网对应页面获取（原文档以外部链接形式给出，此处不重复粘贴）；
• 本 BSP 完整工程文件：project.uvprojx（MDK5）、project.ewp（IAR）；
• 外设驱动使用教程：STM32 系列 BSP 外设驱动使用教程；
• 中文版 BSP 说明：README_zh.md；
• 维护人：yuanzihao（联系邮箱 y@yzh.email）。

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