摘要本文面向第一次接触 Zephyr 的嵌入式开发者介绍 Zephyr、Kconfig、设备树、west 和 Zephyr SDK 的作用并严格参考官方入门流程在 Ubuntu 上搭建开发环境。后半部分使用官方samples/basic/blinky示例和 Nucleo F401RE 开发板演示编译、烧录、串口观察及常见问题排查。标签Zephyr、RTOS、嵌入式开发、STM32、Nucleo如果你之前主要使用裸机、HAL 库或厂商 IDE第一次打开 Zephyr 源码时很容易被west、Kconfig、设备树和大量仓库目录绕晕。本文先把这些概念梳理清楚再完全使用 Zephyr 官方自带的 Blinky 示例完成第一次编译和烧录。本文选择 Nucleo F401RE 作为演示开发板原因很简单Zephyr 官方持续维护该板卡板载用户 LED 已配置为led0同时自带 ST-LINK/V2-1不需要额外连接下载器。文章目录一、Zephyr 是什么二、Zephyr 工作区为什么有很多目录三、Ubuntu 开发环境安装1. 更新系统2. 安装主机依赖四、创建 Python 虚拟环境五、下载 Zephyr 源码和依赖六、安装 Zephyr SDK七、认识官方 Blinky 示例八、编译 Blinky 示例九、使用 ST-LINK 烧录开发板1. 查看可用 runner2. 使用默认 runner3. 使用 OpenOCD十、查看串口输出十一、常见问题排查问题 1west: command not found问题 2CMake 或 Python 版本过低问题 3提示未知板卡问题 4Blinky 提示没有 led0问题 5切换开发板后仍使用旧配置问题 6找不到烧录 runner问题 7普通用户无法访问 ST-LINK 或串口十二、从编译到运行的检查清单总结参考资料一、Zephyr 是什么Zephyr 是面向资源受限设备的开源实时操作系统不只是一个普通的外设库。它提供线程调度、同步机制、内存管理、统一驱动模型、网络协议、USB、文件系统、电源管理等组件并支持 ARM、RISC-V、x86 等多种架构。传统单片机工程经常把时钟、GPIO、驱动和业务代码混在一起。Zephyr 更强调分层组成主要作用Kernel线程、调度、中断、定时器、同步和内存管理Driver Model为 GPIO、UART、I2C、SPI、CAN 等外设提供统一接口Kconfig选择需要编译的系统功能和驱动DeviceTree描述开发板上的芯片、外设、引脚和连接关系CMake组织源文件并生成 Ninja/Make 构建系统west管理多仓库并统一执行构建、烧录和调试命令Zephyr SDK提供交叉编译器、链接器、GDB、OpenOCD 等工具最值得先记住的一句话是设备树描述硬件Kconfig 选择功能C/C 代码实现业务。二、Zephyr 工作区为什么有很多目录Zephyr 使用 west 管理多仓库工作区。执行west init和west update后典型目录如下zephyrproject/ ├── .west/ # west 工作区配置 ├── .venv/ # Python 虚拟环境 ├── zephyr/ # Zephyr 主仓库和官方示例 ├── modules/ # 芯片厂商 HAL、协议栈和第三方模块 ├── bootloader/ # MCUboot 等启动程序 ├── tools/ # 部分辅助工具 └── ....west/所在目录是工作区根目录。Zephyr 主仓库中的west.yml是 manifest 文件记录需要拉取的模块、路径和版本。west 会根据该文件让整个工作区保持一致。常用命令可以先记住这几个west topdir# 显示工作区根目录west list# 显示工作区中的项目west update# 按 manifest 更新依赖west build# 编译应用west flash# 烧录应用west debug# 启动调试三、Ubuntu 开发环境安装Zephyr 最新官方入门文档以 Ubuntu 24.04 LTS 及以上版本为主要演示环境。当前文档列出的关键最低版本为工具最低版本CMake3.28.0Python3.12DeviceTree Compiler1.4.6如果使用 Ubuntu 22.04 或其他发行版系统仓库中的 Python、CMake 可能偏旧需要根据官方 Linux Host Dependencies 文档单独升级。1. 更新系统sudoaptupdatesudoaptupgrade2. 安装主机依赖以下命令来自 Zephyr 官方 Ubuntu 安装流程sudoaptinstall--no-install-recommends\gitcmake ninja-build gperf ccache dfu-util\device-tree-compilerwgetpython3-dev python3-venv python3-tk\xz-utilsfilemakegcc gcc-multilib g-multilib\libsdl2-dev libmagic1如果主机是 AArch64/ARM64官方文档提示可能没有gcc-multilib和g-multilib此时可以从命令中移除这两个包。安装后检查关键版本cmake--versionpython3--versiondtc--versionninja--version不要跳过版本检查。很多“west 安装成功但 CMake 配置失败”的问题本质上是 Ubuntu 版本较旧系统自带 CMake 或 Python 不满足当前 Zephyr 要求。四、创建 Python 虚拟环境建议把 Zephyr 的 Python 包放进独立虚拟环境避免和系统 Python 冲突mkdir-p~/zephyrproject python3-mvenv ~/zephyrproject/.venvsource~/zephyrproject/.venv/bin/activate python-mpipinstall--upgradepip pipinstallwest激活后终端提示符通常会出现(.venv)。检查 westwest--version以后每次打开新终端都需要重新激活环境source~/zephyrproject/.venv/bin/activate如果忘记这一步可能出现west: command not found或者误用另一套 Python 环境。五、下载 Zephyr 源码和依赖使用 Zephyr 官方仓库创建工作区west init-mhttps://github.com/zephyrproject-rtos/zephyr ~/zephyrprojectcd~/zephyrproject west updatewest init主要完成两件事创建.west/并把 Zephyr 设置为 manifest 仓库。west update才会根据west.yml下载 HAL、库和其他模块因此第一次执行会花费较长时间并占用较多磁盘空间。安装与当前源码版本匹配的 Python 依赖west packages pip--install再把当前 Zephyr 注册为 CMake packagewest zephyr-export最后检查工作区west topdir west list zephyr预期的工作区根目录是~/zephyrprojectZephyr 主仓库位于~/zephyrproject/zephyr。六、安装 Zephyr SDKZephyr SDK 提供目标架构对应的编译器和调试工具。进入 Zephyr 仓库后先查看可安装版本cd~/zephyrproject/zephyr west sdk list本文只编译 ARM 开发板可以只安装 ARM 工具链减少下载量west sdkinstall--toolchainsarm-zephyr-eabi如果准备同时开发其他架构也可以直接安装默认 SDKwest sdkinstall安装后正常执行west build时CMake 会自动查找 Zephyr SDK。一般不需要手动写完整的 GCC 路径。七、认识官方 Blinky 示例本文使用的示例位于zephyr/samples/basic/blinky/ ├── CMakeLists.txt ├── README.rst ├── prj.conf └── src/main.cBlinky 的功能非常简单从设备树led0alias 获取 LED 的 GPIO 配置把 GPIO 配置为输出在循环中翻转电平让 LED 持续闪烁在控制台打印 LED 当前状态。这个示例虽小但同时验证了编译器、内核、设备树、GPIO 驱动、系统时钟、下载工具和目标板运行状态很适合做环境验收。官方示例要求开发板存在用户 LED并且设备树已经定义led0。Nucleo F401RE 的板载用户灯 LD2 连接到 PA5Zephyr 板卡定义已完成对应配置。八、编译 Blinky 示例确保虚拟环境已经激活然后进入 Zephyr 根目录source~/zephyrproject/.venv/bin/activatecd~/zephyrproject/zephyr先确认板卡名称west boards|grepnucleo_f401re执行官方示例构建west build-palways-bnucleo_f401re samples/basic/blinky参数含义如下-p always构建前清理旧缓存适合第一次构建或切换开发板-b nucleo_f401re选择 Nucleo F401RE 板卡samples/basic/blinky应用源码目录。成功后默认构建目录为~/zephyrproject/zephyr/build。主要产物位于build/zephyr/文件用途zephyr.elf包含调试符号用于 GDBzephyr.hexIntel HEX 固件zephyr.bin裸二进制镜像zephyr.dts合并后的最终设备树.config最终 Kconfig 配置可以查看镜像大小arm-zephyr-eabi-size build/zephyr/zephyr.elf本文命令已使用 Zephyr 4.4.99、Zephyr SDK 1.0.1 实际构建通过结果为FLASH: 18160 B / 512 KB3.46% RAM: 4544 B / 96 KB4.62%后续只修改了少量源代码时可以直接运行增量构建west build如果切换板卡、修改设备树或遇到缓存异常重新执行带-p always的完整命令。九、使用 ST-LINK 烧录开发板Nucleo F401RE 自带 ST-LINK/V2-1。使用板载 ST-LINK USB 接口连接电脑不需要另外连接 SWDIO、SWCLK。1. 查看可用 runnerwest flash--contextZephyr 官方板卡文档显示该开发板默认 flash runner 是 STM32CubeProgrammer同时也支持 OpenOCD 和 J-Link。2. 使用默认 runner安装 STM32CubeProgrammer 并确保STM32_Programmer_CLI位于PATH后执行west flashwest 会使用当前build/目录中的固件烧录前默认还会检查是否需要重新编译。3. 使用 OpenOCD如果没有安装 STM32CubeProgrammer可以尝试 Zephyr 板卡支持的 OpenOCD runnerwest flash--runneropenocd也可以使用缩写west flash-ropenocd需要指定其他构建目录时使用-dwest flash-dbuild-ropenocd烧录成功后开发板会复位并开始运行 Blinky板载 LD2 应持续闪烁。十、查看串口输出Nucleo F401RE 的 Zephyr 默认控制台使用 UART2并通过板载 ST-LINK 虚拟串口连接到主机默认参数为 115200、8N1。先查看设备节点ls-l/dev/ttyACM*安装并打开串口工具sudoaptinstallminicom minicom-D/dev/ttyACM0-b115200如果当前用户没有串口权限sudousermod-aGdialout$USER执行后注销并重新登录再打开串口。Blinky 运行时会输出 LED 状态信息能够同时观察到“LED 闪烁”和“串口日志”说明程序已经在目标板正常执行。十一、常见问题排查问题 1west: command not found先激活虚拟环境source~/zephyrproject/.venv/bin/activatewhichwest west--version问题 2CMake 或 Python 版本过低重新检查cmake--versionpython3--version当前官方入门文档要求 CMake 不低于 3.28.0、Python 不低于 3.12。旧版 Ubuntu 的系统包不一定满足要求应先升级工具而不是反复修改示例源码。问题 3提示未知板卡Board not found: nucleo_f401re检查当前目录是否位于正确的 west 工作区并确认依赖已经更新cd~/zephyrproject west topdir west updatecdzephyr west boards|grepnucleo_f401re问题 4Blinky 提示没有led0官方 Blinky 要求目标板存在用户 LED并在设备树中定义led0alias。若换成其他开发板先打开其 Zephyr 板卡文档确认是否满足要求没有板载 LED 时需要添加 overlay不能简单照抄 GPIO 编号。问题 5切换开发板后仍使用旧配置删除旧缓存重新构建west build-palways-bnucleo_f401re samples/basic/blinky也可以清理当前构建目录west build-tpristine问题 6找不到烧录 runner先查看构建目录支持的 runnerwest flash--context如果默认 STM32CubeProgrammer 不可用可以安装该工具或者明确选择 OpenOCDwest flash-ropenocd问题 7普通用户无法访问 ST-LINK 或串口先用lsusb和dmesg确认设备是否被主机识别lsusbsudodmesg|tail-50如果使用sudo west flash才能烧录说明通常是 udev 权限问题。应安装调试器对应的 udev 规则并重新插拔设备不建议长期用 root 身份维护整个 Zephyr 工作区。十二、从编译到运行的检查清单第一次搭建环境时可以按下面的顺序逐项确认主机工具版本满足要求 ↓ Python 虚拟环境已激活 ↓ west update 下载完成 ↓ Zephyr SDK 可被 CMake 找到 ↓ west boards 能找到目标板 ↓ west build 生成 zephyr.elf/hex/bin ↓ west flash 成功写入并复位 ↓ 板载 LED 闪烁串口输出正常不要把“编译成功”和“开发板运行正常”当作同一个检查点。编译只证明软件能够生成镜像runner、USB 权限、调试器、供电和开发板配置仍需要分别验证。总结Zephyr 的入门主线可以归纳为五步# 1. 创建工作区west init-mhttps://github.com/zephyrproject-rtos/zephyr ~/zephyrproject# 2. 下载依赖cd~/zephyrproject west update west packages pip--install# 3. 安装 SDKcdzephyr west sdkinstall--toolchainsarm-zephyr-eabi# 4. 编译官方 Blinkywest build-palways-bnucleo_f401re samples/basic/blinky# 5. 烧录west flash完成 Blinky 闭环后再开始修改设备树、Kconfig 和业务代码会比直接从复杂项目入手更容易定位问题。遇到报错时优先判断它属于环境、构建、烧录还是运行阶段排查思路会清晰很多。参考资料Zephyr Getting Started Guidehttps://docs.zephyrproject.org/latest/develop/getting_started/index.htmlBlinky 官方示例https://docs.zephyrproject.org/latest/samples/basic/blinky/README.htmlNucleo F401RE 板卡文档https://docs.zephyrproject.org/latest/boards/st/nucleo_f401re/doc/index.htmlwest 编译、烧录与调试https://docs.zephyrproject.org/latest/develop/west/build-flash-debug.html