最近在尝试将 Zephyr RTOS 移植到经典的 STM32F103C8T6 最小系统板上发现第一步安装 Zephyr SDK 就卡住了不少朋友。网上的教程要么版本过时要么步骤不全特别是针对 Windows 和国内网络环境的细节缺失严重。本文将手把手带你完成 Zephyr SDK 1.0.1 版本的完整安装并基于 STM32F103C8T6 这块“蓝色小药丸”开发板运行一个点灯案例验证整个工具链是否配置成功。无论你是刚接触嵌入式实时操作系统还是从其他 RTOS 转战 Zephyr这篇从环境搭建到实战验证的闭环指南都能让你快速上手。1. Zephyr RTOS 与 SDK 核心概念解析在开始安装之前我们有必要厘清几个核心概念这能帮助你在后续遇到问题时知道该从哪里着手排查。Zephyr™ 是一个由 Linux 基金会托管的、开源、可扩展的实时操作系统RTOS专为资源受限的嵌入式设备设计。它支持超过 450 款开发板和 200 多个传感器、驱动及协议栈其模块化架构允许开发者根据应用需求裁剪系统从几 KB 到几百 KB 的内存占用都能灵活适配。与 FreeRTOS、RT-Thread 等相比Zephyr 的优势在于其强大的硬件抽象层HAL、基于设备树Devicetree的硬件描述机制以及原生支持 CMake 的现代化构建系统。而Zephyr Software Development Kit (SDK)是整个开发环境的基石。它不是一个简单的 IDE 或编译器而是一个集成了交叉编译工具链和主机工具的完整套件。具体包含GNU/LLVM 交叉编译工具链这是核心。你的开发主机可能是 x86_64 的 Windows/Linux/Mac需要一套专门的编译器才能生成运行在 ARM Cortex-M如 STM32F103或其他架构芯片上的二进制文件。Zephyr SDK 为你预编译好了针对数十种架构ARM, RISC-V, Xtensa等的工具链无需自己从源码编译省去大量时间。主机工具包括定制版的 QEMU用于软件仿真调试和 OpenOCD用于连接真实硬件进行烧录和调试。这些工具被深度集成能与 Zephyr 的构建系统west无缝协作。构建系统集成SDK 安装后Zephyr 的构建系统基于 CMake能自动发现并使用其中的工具链无需手动配置复杂的 PATH 或 CMake 变量。为什么强烈推荐甚至在某些情况下必须使用官方 SDK因为 Zephyr 项目使用了特定的编译器标志和链接脚本并依赖 QEMU 的特定版本来运行其庞大的测试套件。使用 SDK 能最大程度保证环境一致性避免“在我电脑上能编译”的尴尬。对于我们的目标硬件STM32F103C8T6它基于 ARM Cortex-M3 内核。Zephyr SDK 中的arm-zephyr-eabi工具链就是为我们这类 ARM 设备准备的。接下来我们就开始准备安装环境。2. 安装环境准备与版本说明工欲善其事必先利其器。在下载和安装 SDK 前请确认你的主机环境。操作系统本文会覆盖 LinuxUbuntu 22.04 LTS 为例、macOSApple Silicon 和 Intel和 Windows 11 三大平台的操作。不同平台的核心步骤一致但命令和细节略有不同。Zephyr SDK 版本我们将安装1.0.1版本。这是撰写本文时一个稳定且与多数 Zephyr 版本兼容的 SDK 发布版。你可以在 Zephyr SDK Releases 页面找到所有历史版本。请注意 SDK 与 Zephyr 内核版本的兼容性一般建议使用 Zephyr 官方文档推荐的 SDK 版本。对于初学1.0.1 是一个安全的选择。磁盘空间完整安装 GNU 变体的 SDK 大约需要 2-3 GB 的磁盘空间。请确保你的目标安装路径有足够空间。网络环境由于需要从 GitHub Releases 下载数百 MB 的压缩包并可能在安装过程中下载工具链请确保网络连接通畅。如果下载缓慢可以考虑使用代理或镜像源但 SDK 安装脚本本身不直接提供镜像配置。基础依赖Linux: 确保已安装wget,tar,sha256sum等基本工具。通常这些都已预装。Windows: 需要能运行wget和7z的命令行环境。推荐使用Git for Windows附带的 Git Bash它提供了类似 Linux 的环境和这些工具。也可以使用 WSL2Windows Subsystem for Linux这样你就可以完全按照 Linux 的步骤来操作。macOS: 确保已安装curl和tar。如果需要wget可通过 Homebrew 安装brew install wget。确认环境无误后我们就可以开始下载了。3. 分步安装 Zephyr SDK 1.0.1SDK 提供了三种变体Bundle Variants供下载gnu: 包含主机工具和所有架构的 GNU 工具链GCC, Binutils, GDB。这是最全的版本推荐大多数用户使用。llvm: 包含主机工具和 LLVM/Clang 工具链。minimal: 仅包含主机工具不包含任何工具链。适合已经拥有所需工具链的高级用户。我们将以gnu变体为例进行安装。整个安装流程可以概括为下载 - 验证 - 解压 - 运行安装脚本。3.1 Linux 系统安装步骤打开你的终端Terminal跟随以下步骤步骤一下载 SDK 压缩包及校验文件建议在用户主目录下操作方便管理。cd ~ wget https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v1.0.1/zephyr-sdk-1.0.1_linux-x86_64_gnu.tar.xz如果你的主机是 ARM64 架构例如树莓派 4B需要将x86_64替换为aarch64wget https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v1.0.1/zephyr-sdk-1.0.1_linux-aarch64_gnu.tar.xz步骤二验证文件完整性下载校验和文件并与刚下载的压缩包比对确保文件在传输过程中未损坏。wget -O - https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v1.0.1/sha256.sum | shasum --check --ignore-missing如果输出显示zephyr-sdk-1.0.1_linux-x86_64_gnu.tar.xz: OK则验证通过。步骤三解压压缩包tar xvf zephyr-sdk-1.0.1_linux-x86_64_gnu.tar.xz解压后会生成一个名为zephyr-sdk-1.0.1的目录。步骤四运行安装脚本进入解压后的目录运行安装脚本。这个脚本会设置工具链并注册 SDK 到 CMake 包注册表便于后续自动发现。cd zephyr-sdk-1.0.1 ./setup.sh运行脚本后它会交互式地询问你是否要安装工具链。由于我们下载的是gnu变体工具链已经包含在压缩包中所以脚本会直接从当前目录安装而不会重新下载。你只需按照提示输入Y确认即可。步骤五重要安装 udev 规则为了让普通用户权限也能通过 OpenOCD 等工具烧录开发板需要复制 udev 规则文件。sudo cp ~/zephyr-sdk-1.0.1/hosttools/sysroots/x86_64-pokysdk-linux/usr/share/openocd/contrib/60-openocd.rules /etc/udev/rules.d/ sudo udevadm control --reload执行完上述命令后建议重新插拔一下你的 ST-Link 或其他调试器或者直接注销并重新登录用户会话以使新的设备权限生效。3.2 macOS 系统安装步骤在 macOS 的终端Terminal中执行以下命令。步骤一下载 SDK 压缩包cd ~ curl -L -O https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v1.0.1/zephyr-sdk-1.0.1_macos-aarch64_gnu.tar.xz对于 Intel 芯片的 Mac请使用macos-x86_64变体。但请注意Zephyr SDK 1.0.1 版本可能已不再提供新的 Intel 版本建议查阅发布页面确认。Apple Silicon Mac 用户请使用上面的aarch64版本。步骤二验证文件完整性curl -L https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v1.0.1/sha256.sum | shasum --check --ignore-missing步骤三解压并安装tar xvf zephyr-sdk-1.0.1_macos-aarch64_gnu.tar.xz cd zephyr-sdk-1.0.1 ./setup.sh同样根据脚本提示进行操作。macOS 通常不需要额外配置 udev 规则但如果你使用特定的 JTAG 调试器可能需要安装对应的驱动。3.3 Windows 系统安装步骤使用 Git BashWindows 环境相对复杂一些推荐使用Git Bash来获得最佳的体验。步骤一打开 Git Bash 并下载在 Git Bash 中你的主目录通常是C:\Users\YourUsername。cd ~ wget https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v1.0.1/zephyr-sdk-1.0.1_windows-x86_64_gnu.7z如果wget命令不存在你可以先用curl -LO url来下载。步骤二解压压缩包Windows 版 SDK 使用.7z格式你需要安装7-Zip软件。如果 Git Bash 环境已配置好可以使用7z命令。7z x zephyr-sdk-1.0.1_windows-x86_64_gnu.7z如果7z命令未找到你需要先安装 7-Zip 并将其bin目录如C:\Program Files\7-Zip\添加到系统的PATH环境变量中或者在图形界面下用 7-Zip 软件直接解压。步骤三运行安装脚本解压后进入目录并运行 Windows 版本的安装脚本。cd zephyr-sdk-1.0.1 ./setup.cmd注意请务必在cmd.exe或PowerShell中运行setup.cmd而不是在 Git Bash 中。你可以在文件资源管理器中双击该文件或者用管理员权限打开 CMD/PowerShell 并导航到该目录执行。安装脚本会为你设置必要的环境变量。安装完成后建议重启所有打开的终端包括 Git Bash以使环境变量生效。4. 验证 SDK 安装与环境变量配置安装完成后如何确认 SDK 已正确安装并被系统识别呢方法一检查工具链路径SDK 的工具链通常安装在sdk-ng子目录下。你可以在安装目录中查找arm-zephyr-eabi编译器。# Linux/macOS ls -la ~/zephyr-sdk-1.0.1/arm-zephyr-eabi/bin/arm-zephyr-eabi-gcc # Windows (在 Git Bash 或 PowerShell 中) dir %HOMEPATH%\zephyr-sdk-1.0.1\arm-zephyr-eabi\bin\arm-zephyr-eabi-gcc.exe如果能找到gcc可执行文件说明工具链已就位。方法二验证环境变量Zephyr 构建系统通过环境变量ZEPHYR_SDK_INSTALL_DIR或ZEPHYR_TOOLCHAIN_VARIANT来定位 SDK。如果你按照推荐路径安装如用户主目录并且运行了setup.sh/setup.cmd那么ZEPHYR_SDK_INSTALL_DIR通常会被自动设置。你可以通过以下命令检查Linux/macOSecho $ZEPHYR_SDK_INSTALL_DIR如果输出类似/home/yourname/zephyr-sdk-1.0.1则说明设置成功。在 Windows 上你可以在 PowerShell 中检查echo $env:ZEPHYR_SDK_INSTALL_DIR方法三使用 west 工具进行构建后续验证最直接的验证方法是尝试编译一个 Zephyr 示例程序。但这需要你先安装 Zephyr 源码和west工具。我们将在下一章通过一个具体的 STM32F103C8T6 点灯项目来彻底验证整个工具链。5. 实战为 STM32F103C8T6 构建并烧录 Blinky 示例现在SDK 已安装完毕。让我们用它来为“蓝色小药丸”开发板编译一个最简单的闪烁 LED 程序并烧录到硬件中运行。这将完整验证从源码到二进制再到硬件的整个链路。5.1 安装 Zephyr 开发环境West 与源码Zephyr 使用一个名为west的元工具来管理项目、构建和烧录。我们首先安装west。# Linux/macOS 上使用 pip3 安装 pip3 install west # Windows 上确保 Python3 和 pip 已安装然后在 cmd 或 PowerShell 中运行 pip install west接下来获取 Zephyr 源码。我们创建一个工作空间目录并初始化源码。# 创建一个工作目录并进入 mkdir -p ~/zephyrproject cd ~/zephyrproject # 使用 west 初始化仓库这里我们拉取一个稳定的版本分支例如 v3.7.0 (LTS) west init -m https://github.com/zephyrproject-rtos/zephyr --mr v3.7.0 . # 拉取所有必要的模块这需要一些时间因为模块较多 west update安装 Zephyr 的 Python 依赖。这些依赖用于构建系统、设备树处理等。# 进入 Zephyr 源码目录 cd zephyr # 安装依赖使用 requirements.txt 文件 pip3 install -r scripts/requirements.txt # Windows 用户同样使用 pip install5.2 导出 Zephyr 环境变量为了让west和 CMake 知道 Zephyr 的根目录需要设置环境变量。每次打开新终端进行开发时都需要执行此操作。# Linux/macOS export ZEPHYR_BASE~/zephyrproject/zephyr # 将 Zephyr 的 CMake 包注册到环境方便 west 自动找到 source ~/zephyrproject/zephyr/zephyr-env.sh # Windows (在 PowerShell 中) $env:ZEPHYR_BASE $env:HOMEPATH\zephyrproject\zephyr # 执行环境设置脚本 $env:ZEPHYR_BASE\zephyr-env.cmd5.3 为 STM32F103C8T6 配置并构建 BlinkySTM32F103C8T6 在 Zephyr 中对应的开发板名称通常是nucleo_f103rb因为其硬件设计与 ST Nucleo-F103RB 板卡高度兼容引脚和核心一致。我们将使用samples/basic/blinky这个最简单的示例。# 进入示例目录 cd ~/zephyrproject/zephyr/samples/basic/blinky # 使用 west 构建指定目标板为 nucleo_f103rb构建目录为 build west build -b nucleo_f103rb命令解释west build: 构建命令。-b nucleo_f103rb: 指定目标板Board。Zephyr 通过板级配置文件来定义芯片型号、时钟、外设引脚等。默认的构建输出目录是build。如果一切顺利你将看到大量 CMake 和编译输出最后以[100%] Linking C executable zephyr/zephyr.elf和Memory region使用情况报告结束这表示构建成功。生成的固件文件位于build/zephyr/zephyr.bin和build/zephyr/zephyr.hex。5.4 硬件连接与烧录将你的 STM32F103C8T6 最小系统板通过 ST-Link或兼容的调试器连接到电脑。确保驱动已安装Windows 可能需要安装 ST-Link USB 驱动。使用west flash命令进行烧录west会根据板型配置自动调用正确的烧录工具通常是 OpenOCD它已包含在 Zephyr SDK 中。west flash如果看到类似*** Flashing successfully ***的信息并且板载的 LED通常是 PC13 引脚连接的 LED开始闪烁恭喜你整个 Zephyr 开发环境已经成功搭建并运行如果你的板子没有自动开始闪烁或者west flash失败请跳转到下一章的故障排查部分。6. 常见问题与故障排查指南在安装和首次构建过程中你可能会遇到以下典型问题。这里提供排查思路和解决方案。问题现象可能原因排查步骤与解决方案west build失败提示找不到工具链或编译器1. SDK 未正确安装或环境变量未设置。2. 未在 Zephyr 源码目录下执行source zephyr-env.sh。1. 检查echo $ZEPHYR_SDK_INSTALL_DIR是否指向正确的 SDK 路径。2. 确认已运行 SDK 的setup.sh脚本。3. 确保在当前终端会话中已执行source $ZEPHYR_BASE/zephyr-env.sh。west flash失败提示 “No debug probe found” 或 “Cannot open ST-Link device”1. 调试器如 ST-Link驱动未安装或权限不足。2. 设备未连接或连接不稳定。3. udev 规则Linux未配置。1.Windows: 安装最新的 ST-Link USB 驱动 。2.Linux: 确保已执行sudo cp ... 60-openocd.rules ...并重新插拔设备。使用lsusb检查设备是否被识别。3. 尝试使用openocd命令手动连接查看详细错误。构建时出现Cmake Error或Kconfig错误1. Python 依赖未完全安装。2. Zephyr 源码模块未完全拉取west update不完整。3. 构建目录残留旧配置。1. 重新安装 Python 依赖pip3 install -r scripts/requirements.txt。2. 彻底删除build目录重新执行west update再尝试构建。3. 检查网络确保west update能拉取所有子模块。下载 SDK 或west update速度极慢或失败网络连接 GitHub 不畅。1. 为wget或git配置代理如果可用。2. 对于west update可以尝试多次执行或手动修改.west/config文件中的 URL 为国内镜像源如有。3. 考虑在网络条件好的环境下先完成初始化。macOS 上构建失败提示头文件错误或架构不匹配1. 可能安装了不匹配的 SDK 变体如为 Intel Mac 安装了 aarch64 版本。2. macOS 命令行工具未完整安装。1. 确认下载的 SDK 文件名与你的 Mac 芯片架构匹配。2. 运行xcode-select --install安装命令行开发者工具。west build成功但程序在板子上无任何反应1. 板载 LED 引脚定义与示例代码不符。2. 时钟配置错误。3. 二进制文件未正确烧录到起始地址。1. 检查nucleo_f103rb板级定义中 LED 的 GPIO 引脚通常是PC13。确认你的最小系统板 LED 是否连接在该引脚。2. 使用west debug或通过 OpenOCD GDB 进行调试单步执行查看程序是否运行。3. 尝试一个更简单的示例如hello_world通过串口输出信息来确认程序是否运行。7. 工程实践与进阶建议成功运行第一个示例只是起点。为了在 Zephyr 上进行高效、可靠的开发以下是一些工程实践建议1. 项目管理与 West 工作流永远在west工作空间内管理你的应用程序。使用west init和west update来保持 Zephyr 源码和模块的同步。创建自定义应用程序时建议放在工作空间内的独立目录中并在CMakeLists.txt中通过find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})来引入 Zephyr。使用west build -p auto可以在构建前自动清理之前的构建产物避免配置缓存导致的问题。2. 配置系统 (Kconfig) 与设备树 (Devicetree) 的理解Zephyr 的强大之处在于其高度可配置性。花时间学习如何使用menuconfig(west build -t menuconfig) 来裁剪内核功能、驱动和协议栈这对于优化内存占用至关重要。设备树是描述硬件的关键。对于 STM32F103C8T6其基本定义在boards/arm/nucleo_f103rb目录下。如果你需要修改引脚复用或添加自定义外设需要理解并可能覆盖设备树节点。3. 调试与日志串口打印是嵌入式调试的利器。确保在prj.conf中启用CONFIG_SERIALy和CONFIG_CONSOLEy并使用printk或LOG_*API 输出日志。利用 Zephyr SDK 自带的 GDB 进行硬件调试。west debug命令可以自动启动 OpenOCD 和 GDB连接到开发板进行单步调试和断点设置。4. 版本控制与协作将你的应用程序代码纳入 Git 版本控制。但注意不要提交庞大的build目录或 SDK 工具链。在团队协作中使用west manifest文件来精确锁定 Zephyr 及其所有模块的版本确保所有成员构建环境一致。5. 为生产环境做准备开发完成后考虑优化编译选项如尺寸优化-Os和链接脚本减少固件体积。研究 Zephyr 的电源管理、安全启动MCUboot等高级特性为产品化打下基础。充分利用 Zephyr 的测试框架Twister为你的驱动和应用编写单元测试和集成测试。从安装 Zephyr SDK 到在 STM32F103C8T6 上成功运行第一个程序你已经打通了 Zephyr 开发的核心路径。这个流程是后续所有开发的基础。接下来你可以探索更多的 Zephyr 示例如传感器驱动、网络协议栈如基于 W5500 的以太网通信或文件系统将这块经典且性价比极高的 MCU 潜力充分发挥出来。如果在实践中遇到新的问题Zephyr 项目的官方文档和活跃的社区是寻求帮助的最佳场所。