NUCLEO-H5E5ZJ Zephyr 移植记录（LED / Shell）
日期：2026-10-16**
**Zephyr 版本：v4.4.0（D:\luglZephyrproject\zephyr）**
**板级定义位置：D:\STM32\STM32H5E5\NUCLEO_H5E5ZJ\boards\st\nucleo_h5e5zj（通过 BOARD_ROOT 作为板外板使用）
1. 硬件资料来源
| 文档 |
文件 |
用途 |
| UM3601 用户手册 |
docs/um3601-stm32h5-nucleo144-board-mb2129-stmicroelectronics.pdf |
引脚分配、默认焊桥配置 |
| MB2129 原理图 |
docs/mb2129-h5e5zj-d01-schematic.pdf |
交叉核对 LED/UART/按键连线 |
板上 MCU：****STM32H5E5ZJT6**（Cortex-M33 @ 250 MHz max，4 MB Flash，1.5 MB SRAM，LQFP-144）。**
2. Zephyr 支持现状（移植前）
- Zephyr v4.4.0 已包含 ****SoC 级**支持：
SOC_STM32H5E5XX，设备树 dts/arm/st/h5/stm32h5e5Xj.dtsi；**
- pinctrl 定义在
hal_stm32 模块：dts/st/h5/stm32h5e5zjtx-pinctrl.dtsi（含 usart3_tx_pd8/usart3_rx_pd9，AF7）；
- 但****没有****
nucleo_h5e5zj 板级目录（官方仅有同系列的stm32h5f5j_dk），本次移植补齐这一层。
3. 本次移植的外设与引脚（UM3601 §7.8/§7.9/§7.12 + 原理图核对）
3.1 用户 LED
| 丝印 |
颜色 |
引脚 |
有效电平 |
Zephyr 节点 / alias |
| LD1 |
绿 |
PA3 |
高有效 |
green_led_1 / led0 |
| LD2 |
红 |
PF0 |
低有效 |
red_led_2 / led1 |
| LD3 |
蓝 |
PE5 |
低有效 |
blue_led_3 / led2 |
注意：LD2/LD3 是****低有效**（写 0 点亮），与 LD1 相反，dts 中已用 GPIO_ACTIVE_LOW 表达。**
3.2 Shell / 控制台 UART（STLINK-V3EC VCP）
| 信号 |
引脚 |
复用 |
说明 |
| USART3_TX |
PD8 |
AF7 |
接 STLINK-V3EC 的 VCP_RX |
| USART3_RX |
PD9 |
AF7 |
接 STLINK-V3EC 的 VCP_TX |
chosen 中zephyr,console 与zephyr,shell-uart 均指向usart3；- 波特率 115200 8N1，PC 侧打开 ST-LINK 虚拟串口即可；
- UM3601 §7.4 写的是 "USART1 (PD8/PD9)"，与 §7.12 矛盾；PD8/PD9 在 STM32H5 上固定为 ****USART3**，原理图网络标号
STLK_VCP_TX/RX → PD8/PD9 也证实为 USART3，§7.4 系笔误。**
3.3 用户按键（附带移植）
| 丝印 |
引脚 |
电平 |
Zephyr 节点 / alias |
| B1 (USER) |
PC13 |
按下为高 |
user_button / sw0 |
4. 时钟配置
板载 ****X3 = 48 MHz 晶振**（6 pF 负载），经 **0Ω 电阻 R3/R4** 连到 PH0/PH1（已在实物上确认 R3/R4 贴装，并实测 HSE 起振正常；UM3601 §7.5.2 文字版描述的"HSE 不使用"默认配置与实际出货不一致，以实物为准）。PLL 以 HSE 为源：**
HSE 48 MHz → PLL div-m=12 → 4 MHz → mul-n=125 → VCO 500 MHz → div-p=2 → SYSCLK 250 MHz
- AHB ÷1 = 250 MHz；APB1/APB3 ÷2 = 125 MHz；APB2 ÷1 = 250 MHz；
- PLL 源时钟必须在 dts 中显式使能**（
&clk_hse { status = "okay"; }，用 HSI 时同理需&clk_hsi）：stm32h5.dtsi 中这些时钟节点默认disabled，源时钟不使能会导致 PLL 锁定失败、系统时钟初始化挂死——调试期间实测现象为串口只吐一个乱码字符（"M"）、LED 无响应；**
- LSE 32.768 kHz 晶振（R1/R2 已焊），
clk_lse 使能并供 RTC；
- HSI/HSI48 保持使能，作为备份及后续 USB/RNG 时钟。
若某块板子 HSE 起振异常（如 R3/R4 未贴），可回退到 HSI 方案：&pll 的 clocks 改为 <&clk_hsi>、div-m = <16>（64/16×125/2 同为 250 MHz），并确认 &clk_hsi 使能。
5. 移植文件清单
D:\STM32\STM32H5E5\NUCLEO_H5E5ZJ\
├── boards\st\nucleo_h5e5zj\
│ ├── board.yml # 板卡声明（soc: stm32h5e5xx）
│ ├── Kconfig.nucleo_h5e5zj # select SOC_STM32H5E5XX
│ ├── nucleo_h5e5zj.dts # LED/按键/USART3/时钟(HSE 48MHz→PLL 250MHz)/Flash 分区
│ ├── nucleo_h5e5zj_defconfig # SERIAL/CONSOLE/UART_CONSOLE/MPU/栈保护
│ ├── nucleo_h5e5zj.yaml # twister 元数据（ram 1536 / flash 4096）
│ └── board.cmake # 烧录：stm32cubeprogrammer / stlink_gdbserver / jlink
└── apps\led_shell\ # 演示应用：shell 命令控制 LED
├── CMakeLists.txt
├── prj.conf # CONFIG_GPIO=y, CONFIG_SHELL=y
└── src\main.c # 注册 led on/off/toggle/list 子命令
Flash 分区（4 MB）：mcuboot 64 K @0x0、image-0 1984 K @0x10000、image-1 1984 K @0x200000、storage 64 K @0x3F0000。
6. 遇到并修复的问题：hal_stm32 头文件缺陷
现象**：首次编译报错**
stm32h5xx_hal_ccb.h:44:3: error: unknown type name 'CCB_TypeDef'
原因**：stm32h5xx_hal_conf.h 无条件定义 HAL_CCB_MODULE_ENABLED 并包含 stm32h5xx_hal_ccb.h，而 Cube 设备头 stm32h5e5xx.h 中**使用了** CCB_TypeDef（CCB_BASE/CCB_S 等宏）却**漏掉了 typedef 本身**（对比 stm32h5f5xx.h 第 1439 行是有的）。上游 Zephyr 目前没有任何板子编译 H5E4/H5E5，所以该缺陷一直未暴露。**
修复**（本地补丁，建议同步提给 ST / hal_stm32）：
在 D:\luglZephyrproject\modules\hal\stm32\stm32cube\stm32h5xx\soc\stm32h5e5xx.h 的 typedef XSPIM_TypeDef OCTOSPIM_TypeDef; 之后，补上从 stm32h5f5xx.h 复制的结构体：**
/**
* @brief Coupling and chaining bridge (CCB)
*/
typedef struct
{
__IO uint32_t CR; /*!< CCB ccontrol register, Address offset: 0x00 */
__IO uint32_t SR; /*!< CCB status register, Address offset: 0x04 */
uint32_t RESERVED1[2]; /*!< Reserved, Address offset: 0x08 */
__IO uint32_t REFTAGR[4]; /*!< CCB reference tag register, Address offset: 0x10 */
} CCB_TypeDef;
注意：west update 更新 hal_stm32 后需确认此补丁是否仍需保留。stm32h5e4xx.h 存在同样缺陷，本次未修改（本板用不到）。
7. 构建与验证
在 D:\luglZephyrproject 下执行（该 west 版本不支持 --board-root 选项，用 -DBOARD_ROOT 传入）：
export ZEPHYR_SDK_INSTALL_DIR=/d/luglZephyrproject/zephyr-sdk-1.0.1/zephyr-sdk-1.0.1
# LED（blinky，使用 led0 = LD1 绿灯 PA3）
west build -b nucleo_h5e5zj zephyr/samples/basic/blinky -d build_h5e5_blinky -p always -- -DBOARD_ROOT=D:/STM32/STM32H5E5/NUCLEO_H5E5ZJ
# Shell（串口控制台，USART3 PD8/PD9，115200 8N1）
west build -b nucleo_h5e5zj zephyr/samples/subsys/shell/shell_module -d build_h5e5_shell -p always -- -DBOARD_ROOT=D:/STM32/STM32H5E5/NUCLEO_H5E5ZJ
# LED shell 演示应用（led on/off/toggle/list 命令）
west build -b nucleo_h5e5zj /d/STM32/STM32H5E5/NUCLEO_H5E5ZJ/apps/led_shell -d build_h5e5_ledshell -p always -- -DBOARD_ROOT=D:/STM32/STM32H5E5/NUCLEO_H5E5ZJ
# 烧录（默认 STM32CubeProgrammer，SWD）
west flash -d build_h5e5_ledshell
验证结果（2026-10-16 硬件实测，HSE 48 MHz → PLL 250 MHz 配置）
| 固件 |
编译 |
硬件实测 |
samples/basic/blinky |
通过（FLASH 18348 B / 4 MB） |
LD1（绿灯）约 1 Hz 闪烁 ✔ |
samples/subsys/shell/shell_module |
通过（FLASH 67308 B / 4 MB） |
回车出现 uart:~$ 提示符 ✔ |
apps/led_shell |
通过 |
led on/off/toggle/list 实测可分别控制 LD1/LD2/LD3 ✔ |
linker 正确识别了 4 MB Flash 与 SRAM1~SRAM5（256 K + 128 K + 384 K ×3）。烧录用 west flash（STM32CubeProgrammer，SWD）一次成功；串口为 ST-LINK VCP（实测 COM54，115200 8N1）。注意 Windows 下串口独占，用脚本/其他终端访问前需先关闭串口助手。
led_shell 用法
uart:~$ led list # 列出 LED 及当前状态（on/off 已换算为有效电平后的逻辑状态）
uart:~$ led on 0 # LD1 绿灯亮
uart:~$ led on 1 # LD2 红灯亮（低有效，驱动内部已处理）
uart:~$ led on 2 # LD3 蓝灯亮
uart:~$ led toggle 1 # 红灯翻转
uart:~$ led off 0 # 绿灯灭
8. 备注与后续可扩展项
- 本移植聚焦 LED + Shell（USART3 VCP），
yaml 的supported 只声明了gpio、uart；
- 板上有以太网（RMII，注意 RMII_RXD1 与 LD3/PE5 冲突）、XSPI、USB HS 等，SoC dtsi 已具备节点，需要时按
stm32h5f5j_dk-common.dtsi 的方式逐个使能并核对原理图焊桥；
- OpenOCD 暂不支持 STM32H5E5（沿用上游 FIXME），烧录/调试走 STM32CubeProgrammer 或 J-Link；
- 上电默认跑演示程序（B1 切换 LD1~LD3 闪烁），烧录 Zephyr 后会被覆盖。
微信公众号
手机版
