Zephyr 在 Nucleo G474RE 的完整编译与模块提取指南

嵌入式开发中，将 RTOS 从源码构建到硬件运行是一项核心技能。本文以 Nucleo G474RE 为例，梳理 Zephyr 从源码获取 → Python 依赖 → HAL 模块提取 → 构建 → 烧录 → 运行 的全过程，涵盖 Windows 环境变量、遇到的坑及解决方案。

---

一、编译前工具准备

1.1 必要工具

工具	作用
Python ≥ 3.9	构建系统脚本、测试和工具依赖
pip	安装 Python 依赖包
CMake ≥ 3.20	Zephyr 构建系统生成 Make/Ninja 文件
Ninja ≥ 1.10	快速构建系统
Zephyr SDK 或 ARM 工具链 (arm-none-eabi-gcc)	交叉编译 STM32 目标
west	Zephyr meta-tool，管理源码和模块
串口工具 (minicom / PuTTY)	查看串口输出

---

1.2 Python 依赖

Zephyr 构建和测试工具依赖 Python 包，需要安装：

pip install --upgrade pip
pip install -r zephyr/scripts/requirements.txt

requirements.txt 会安装以下工具和库：

• 构建工具 ：west, pyyaml, jinja2
• 测试工具 ：pytest, pytest-xdist, pyserial, colorama
• 脚本工具 ：pyelftools, packaging

建议使用 Python 虚拟环境：

python -m venv .venv
.venv\Scripts\activate   # Windows

---

1.3 Windows 下环境变量设置

在 Windows 开发时，需要设置以下 临时环境变量：

set ZEPHYR_BASE=%~dp0
set ZEPHYR_TOOLCHAIN_VARIANT=gnuarmemb
set GNUARMEMB_TOOLCHAIN_PATH=D:\tool\armgcc
set PATH=D:\tool\armgcc\bin;D:\tool\cmake\bin;%PATH%

• ZEPHYR_BASE → 指向 Zephyr 源码目录
• ZEPHYR_TOOLCHAIN_VARIANT → 指定工具链类型
• GNUARMEMB_TOOLCHAIN_PATH → ARM GCC 工具链路径
• PATH → 包含工具链和 CMake 路径
• 使用 %~dp0 可以相对 Zephyr 脚本目录设置路径

⚠️ 临时变量仅对当前命令行窗口有效，关闭窗口后失效，适合多版本共存。

---

二、获取 Zephyr 源码

2.1 克隆源码包

git clone --recursive https://github.com/zephyrproject-rtos/zephyr.git
cd zephyr

2.2 无法拉取或中断的解决方案

• 网络慢或 Git 超时：

  • 使用浅克隆：git clone --depth 1 https://github.com/zephyrproject-rtos/zephyr.git
  • 或手动下载 GitHub zip/tar 包

• 子模块未初始化：

  git submodule update --init --recursive

• 部分模块卡住：手动单独 clone：
  *

    git clone https://github.com/zephyrproject-rtos/hal_stm32.git modules/hal/stm32

---

三、提取 HAL 模块 modules/hal/stm32

在编译 Nucleo G474RE 时，如果没有 HAL 模块，可能会报错：

fatal error: stm32g474rbtx-pinctrl.dtsi: No such file or directory

原因：Devicetree 文件在 HAL 模块中，必须先提取：

west update modules/hal/stm32

提取日志示例：

=== updating hal_stm32 (modules/hal/stm32):
--- hal_stm32: initializing
Initialized empty Git repository in D:/work/item/linux/zephyr/modules/hal/stm32/.git/
--- hal_stm32: fetching, need revision ff0f1fa5ab4e6559cfbb61d5270d38caad9ad0b0
remote: Enumerating objects: 49592, done.
Receiving objects: 100% (49592/49592), 144.39 MiB | 891.00 KiB/s, done.
Updating files: 100% (8162/8162), done.
HEAD is now at ff0f1fa5 lib: stm32wba: Add Bluetooth LE link layer for WBA2x

---

3.1 modules/hal/stm32 目录内容

提取完成后，目录下包含：

dts/        # Devicetree pinctrl 文件
lib/        # HAL 库与通用驱动
LICENSE     # 模块许可证
README.rst  # 模块说明
scripts/    # 辅助 Python / Bash 脚本
stm32cube/  # STM32Cube 封装库
zephyr/     # Zephyr HAL 接口和适配文件

这些文件保证编译 Nucleo G474RE 的 DTS、HAL 和外设驱动都完整可用。

---

四、编译示例程序

以 hello_world 为例：

cd zephyr/samples/hello_world
mkdir build
cd build
west build -b nucleo_g474re ..

• 编译完成后生成：
  • zephyr.elf → 可调试
  • zephyr.hex / zephyr.bin → 烧录用

CMake 会自动识别 workspace 下的 HAL 模块。

---

五、烧录固件

west flash
# 或使用 OpenOCD
west flash --runner openocd

---

六、查看运行效果

默认输出到 LPUART1（PA2/PA3），波特率 115200：

minicom -D /dev/ttyACM0

输出示例：

Hello World! arm

---

七、常见坑与解决方案

问题	原因	解决方法
找不到 STM32 DTS 文件	HAL 模块未提取	west update modules/hal/stm32
编译找不到头文件	modules/hal/stm32 目录位置不对	确保 workspace 根目录下存在模块
多次 update 卡住	Git 仓库大、网络慢	使用 --depth 1 或手动 clone
CMake 找不到模块	ZEPHYR_BASE 未设置	设置临时环境变量
Python 工具报错	pip install -r zephyr/scripts/requirements.txt 未执行	安装依赖包
烧录失败	板子没电或驱动未装	检查 ST-LINK 驱动

---

八、总结

1. 先安装 Python 依赖 ：pip install -r zephyr/scripts/requirements.txt，保证工具和构建脚本正常
2. 拉取完整 HAL 模块：否则 DTS、HAL、pinctrl 文件缺失
3. Windows 下使用临时环境变量：方便多版本共存
4. 独立 build 目录：避免污染源码
5. 排错策略 ：
   • CMake 报错 → 检查 ZEPHYR_BASE、modules
   • 编译报错 → 检查头文件路径和 DTS
   • 烧录报错 → 检查 USB、ST-LINK 驱动

完整流程：源码获取 → Python 依赖 → HAL 模块提取 → 编译 → 烧录 → 运行