最近在尝试用 Zephyr RTOS 开发一个基于 STM32F103C8T6 的小项目结果第一步安装 Zephyr SDK 就卡住了。网上资料要么版本太老要么步骤不全尤其是针对 Windows 和 Linux 不同环境的细节踩了不少坑。为了帮大家少走弯路我把自己从零开始在 Windows 和 Ubuntu 上安装 Zephyr SDK 1.0.1 版本并成功在 STM32F103C8T6 最小系统板上运行第一个 Blinky 例程的全过程整理出来。这篇文章会手把手带你完成 Zephyr 开发环境的搭建内容覆盖 SDK 下载、安装、环境变量配置、项目构建、烧录和调试。无论你是嵌入式新手想入门 Zephyr还是有一定经验的开发者想快速上手 STM32F103都能跟着步骤一步步操作最终点亮你的 LED。1. Zephyr RTOS 与 SDK 核心概念在开始动手之前我们先花几分钟理解一下 Zephyr 和它的 SDK 到底是什么这能帮你更好地理解后续每一步操作的意义。1.1 什么是 Zephyr RTOSZephyr 是一个由 Linux 基金会托管的、开源的、可扩展的实时操作系统RTOS。它专为资源受限的嵌入式设备设计支持从简单的 8 位微控制器到功能强大的 32 位应用处理器。与 FreeRTOS、uC/OS 等传统 RTOS 相比Zephyr 有几个显著特点高度模块化与可配置性通过 Kconfig 系统你可以像配置 Linux 内核一样精确地裁剪或启用你需要的功能模块生成最适合你硬件和应用的系统镜像避免资源浪费。强大的硬件抽象与驱动模型它提供了统一的设备驱动模型和硬件抽象层HAL使得应用程序代码可以相对独立于底层硬件。这意味着为一块 STM32 板子写的代码经过少量修改就能移植到另一块 Nordic 或 Espressif 的板子上。丰富的协议栈与组件内置了对蓝牙包括 Bluetooth LE Mesh、Wi-Fi、LoRaWAN、CAN、USB 等多种通信协议的支持以及文件系统、电源管理、安全框架等高级组件。活跃的社区与完善的工具链作为 Linux 基金会项目它拥有活跃的社区和持续迭代的官方工具链也就是我们马上要安装的 Zephyr SDK开发体验更接近现代软件开发。简单来说如果你想开发一个需要联网、低功耗、且可能运行在多种硬件平台上的物联网设备Zephyr 是一个非常值得考虑的选择。1.2 为什么需要 Zephyr SDKZephyr SDKSoftware Development Kit是 Zephyr 项目官方提供的软件开发工具包。它不是一个单一的软件而是一个包含了构建 Zephyr 应用所需几乎所有工具的集合。尝试手动配置这些工具尤其是针对 ARM、RISC-V 等架构的交叉编译工具链非常繁琐且容易出错SDK 则帮你一站式搞定。Zephyr SDK 主要包含以下核心组件交叉编译工具链这是 SDK 的核心。例如为了在 x86 的电脑上编译出能在 ARM 架构的 STM32 上运行的代码你需要 ARM 的 GCC 编译器arm-none-eabi-gcc、链接器、汇编器等。SDK 为你预置了针对多种架构ARM, RISC-V, Xtensa 等的 GNU 或 LLVM/Clang 工具链。主机工具QEMU一个开源的处理器模拟器。SDK 内置了定制版的 QEMU允许你在没有真实硬件的情况下在电脑上模拟运行 Zephyr 应用程序极大方便了前期开发和调试。OpenOCD开源的片上调试器。它是连接你的电脑和 STM32 这类芯片的 JTAG/SWD 调试器的桥梁用于烧录程序、单步调试、查看寄存器等。CMakeZephyr 使用 CMake 作为其构建系统。SDK 确保了 CMake 能找到正确的工具链。Python 脚本与工具Zephyr 的元工具west以及一些辅助脚本也依赖 Python 环境SDK 的安装脚本会帮助配置相关路径。简单总结没有 Zephyr SDK你就无法编译 Zephyr 项目代码。安装 SDK 是开启 Zephyr 开发之旅的第一步也是必须的一步。1.3 关于 STM32F103C8T6 与“最小系统板”STM32F103C8T6 是意法半导体ST基于 ARM Cortex-M3 内核的经典微控制器因其性价比高、资源丰富72MHz主频、64KB Flash、20KB RAM、丰富外设而被广泛用于各种嵌入式产品和教学中。“最小系统板”指的是仅包含让这颗 MCU 运行起来所必需的最少外部电路的开发板通常包括电源电路如 USB 转 5V/3.3V复位电路时钟电路外部晶振程序下载接口如 SWD 接口核心芯片STM32F103C8T6引出所有 IO 引脚你手头常见的“蓝色小板”或“黑色小板”就是它的最小系统板。在 Zephyr 中它通常对应着stm32f103c8t6或stm32_min_dev等开发板定义。我们将使用这块板子作为本次教程的硬件平台。2. 环境准备与版本说明在开始安装前请确保你的开发环境满足以下要求。我将分别给出 Windows 和 Linux (Ubuntu) 下的准备步骤。2.1 操作系统与基础软件对于 Windows 用户操作系统Windows 10 或 Windows 11。终端强烈建议使用Windows Terminal或Git Bash。系统自带的cmd或PowerShell在某些步骤中可能遇到路径或命令问题。本文后续 Windows 示例将基于 Git Bash。压缩工具确保已安装7-Zip或Bandizip等支持.7z格式的解压软件用于解压 SDK 包。PythonZephyr 工具需要 Python 3.8 或更高版本。请从 python.org 下载并安装务必在安装时勾选 “Add Python to PATH”。对于 Linux (Ubuntu/Debian) 用户操作系统Ubuntu 20.04 LTS, 22.04 LTS 或更高版本。终端使用系统自带的终端即可。基础工具打开终端运行以下命令安装编译和开发所需的基础包sudo apt update sudo apt install -y git cmake ninja-build gperf \ ccache dfu-util device-tree-compiler wget \ python3-dev python3-pip python3-setuptools python3-tk python3-wheel xz-utils file \ make gcc g libssl-dev libncurses-devPythonUbuntu 通常已预装 Python 3。可通过python3 --version确认。2.2 版本选择Zephyr SDK 1.0.1根据官方文档和项目标题我们本次安装的 SDK 版本是1.0.1。这是一个相对较新的稳定版本对 Zephyr 3.x 和 4.x 版本都有良好的兼容性。重要提示Zephyr SDK 版本与 Zephyr RTOS 源码版本存在兼容性矩阵。虽然 1.0.1 是一个通用性较好的版本但如果你计划使用某个特定版本的 Zephyr 源码例如从 GitHub 拉取main分支或某个 LTS 版本最好查阅官方的 Zephyr SDK Version Compatibility Matrix 来确认最佳匹配的 SDK 版本。对于本教程和大多数入门及一般开发场景使用Zephyr SDK 1.0.1是安全且推荐的选择。2.3 安装目录规划为了避免权限问题和路径混乱建议将 Zephyr SDK 安装在你的用户主目录下。WindowsC:\Users\你的用户名\zephyr-sdk-1.0.1或通过 Git Bash 访问的/c/Users/你的用户名/zephyr-sdk-1.0.1Linux~/zephyr-sdk-1.0.1(即/home/你的用户名/zephyr-sdk-1.0.1)官方也推荐其他位置如~/.local或/opt但主目录是最简单无脑的选择。3. 分步安装 Zephyr SDK 1.0.1现在我们开始正式的安装过程。请根据你的操作系统选择对应的章节。3.1 Windows 系统安装步骤下载 SDK 压缩包打开 Git Bash进入你的用户主目录使用wget命令下载 Windows 版本的 SDK 包。注意Windows 版本是.7z格式。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命令不存在你可以先用浏览器打开上面的链接手动下载然后将下载的文件移动到C:\Users\你的用户名\目录下。解压 SDK 包使用你安装的压缩软件如 7-Zip解压刚下载的.7z文件。解压目标目录就选择当前目录 (C:\Users\你的用户名\)。解压后会生成一个名为zephyr-sdk-1.0.1的文件夹。也可以在 Git Bash 中使用命令解压需安装p7zip:7z x zephyr-sdk-1.0.1_windows-x86_64_gnu.7z运行安装脚本解压完成后进入 SDK 目录并运行安装脚本setup.cmd。注意这个脚本必须在cmd.exe中运行而不是 Git Bash 或 PowerShell。打开cmd.exe按 WinR输入cmd回车。切换到 SDK 目录并运行脚本cd %HOMEPATH%\zephyr-sdk-1.0.1 setup.cmd脚本运行后会有一个交互式提示询问你是否要安装工具链。直接按回车选择默认的[y]即可。它会开始下载并安装所需的工具链到当前目录。这个过程需要一些时间请保持网络通畅。验证安装安装脚本运行完毕后关闭cmd.exe。重新打开一个Git Bash终端输入以下命令检查工具链是否可用arm-none-eabi-gcc --version如果安装成功你应该能看到类似gcc version 12.2.0 (Zephyr SDK 1.0.1)的输出信息。3.2 Linux (Ubuntu) 系统安装步骤下载并验证 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 wget -O - https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v1.0.1/sha256.sum | shasum --check --ignore-missing第二条命令会校验下载文件的 SHA256 哈希值如果输出显示zephyr-sdk-1.0.1_linux-x86_64_gnu.tar.xz: OK则说明文件完整无误。注意如果你的主机是 ARM64 架构例如树莓派 4B需要将下载链接中的x86_64替换为aarch64。解压 SDK 包使用tar命令解压tar xvf zephyr-sdk-1.0.1_linux-x86_64_gnu.tar.xz解压后同样会生成zephyr-sdk-1.0.1目录。运行安装脚本进入目录并运行安装脚本cd zephyr-sdk-1.0.1 ./setup.sh脚本会提示你接受许可协议并询问是否安装工具链。一路按回车选择默认选项即可。它会将工具链安装到当前目录的toolchains子目录下。安装 udev 规则重要这一步是为了让普通用户也能通过 USB 访问调试器如 ST-Link无需每次使用sudo。执行以下命令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 调试器或者重启电脑使规则生效。验证安装在终端中测试工具链arm-none-eabi-gcc --version同样你应该能看到带有 Zephyr SDK 版本的 GCC 信息。3.3 配置环境变量为了让系统在任何位置都能找到 Zephyr SDK 的工具我们需要设置一个环境变量ZEPHYR_SDK_INSTALL_DIR。对于 Windows (Git Bash)编辑你的~/.bashrc文件如果不存在就创建nano ~/.bashrc在文件末尾添加一行请根据你的实际安装路径修改export ZEPHYR_SDK_INSTALL_DIR/c/Users/你的用户名/zephyr-sdk-1.0.1保存退出CtrlX, 然后Y, 回车。然后让配置生效source ~/.bashrc对于 Linux编辑~/.bashrc或~/.zshrc取决于你的 shellnano ~/.bashrc在文件末尾添加export ZEPHYR_SDK_INSTALL_DIR~/zephyr-sdk-1.0.1保存退出并生效source ~/.bashrc验证环境变量 重新打开一个终端输入echo $ZEPHYR_SDK_INSTALL_DIR应该能正确显示你设置的路径。4. 获取 Zephyr 源码与项目初始化SDK 是工具我们还需要 Zephyr 操作系统本身的源代码和项目管理工具west。4.1 安装 West 元工具West 是 Zephyr 项目的“元工具”用于管理多个仓库Zephyr 本身由核心仓库和许多模块仓库组成、构建、烧录等。使用 pip 安装pip3 install west安装完成后运行west --version检查是否成功。4.2 初始化工作区并获取源码我们创建一个专门的工作目录并用west init来拉取代码。# 创建一个工作目录名字自定 mkdir -p ~/zephyrproject cd ~/zephyrproject # 使用 west init 初始化并指定拉取 main 分支的代码 # -m 指定 manifest 文件的 URL--mr 指定分支main 是最新开发分支稳定版可用 v3.6.0 等 west init -m https://github.com/zephyrproject-rtos/zephyr --mr main # 拉取所有子模块和依赖这一步耗时较长请耐心等待 west update4.3 导出 Zephyr 环境变量Zephyr 的构建系统需要知道核心源码的位置。我们通过一个脚本来设置一系列环境变量。# 进入 Zephyr 源码目录 cd ~/zephyrproject/zephyr # 执行环境设置脚本 # 对于 Linux/Git Bash: source zephyr-env.sh # 对于 Windows 原生 cmd (如果你在用): # zephyr-env.bat重要每打开一个新的终端窗口进行 Zephyr 开发都需要先cd到zephyr目录并source这个脚本或者将它的内容添加到你的~/.bashrc中。一个更一劳永逸的方法是把下面这行加到你的~/.bashrc末尾source ~/zephyrproject/zephyr/zephyr-env.sh5. 第一个 Zephyr 项目点亮 STM32F103C8T6 的 LED环境终于搭好了现在我们来创建一个最简单的项目——闪烁 LEDBlinky。这是嵌入式世界的“Hello World”。5.1 了解开发板标识在 Zephyr 中每块支持的开发板都有一个唯一的标识符。对于 STM32F103C8T6 最小系统板常用的标识符是stm32f103c8t6或stm32_min_dev后者是一个通用名称通常也指向这块板子。我们可以通过以下命令查看所有支持的板子列表输出很长west boards在输出中寻找stm32f103c8t6。5.2 构建 Blinky 示例Zephyr 源码中自带大量示例位于zephyr/samples/目录下。我们直接使用最基本的blinky。# 切换到示例目录 cd ~/zephyrproject/zephyr/samples/basic/blinky # 使用 west build 进行构建 # -b 指定目标板 (board) # -p auto 或 -p always 确保构建前先清理 west build -b stm32f103c8t6 -p always命令解释west build: 调用构建命令。-b stm32f103c8t6: 指定目标板。-p always: 在构建前先清理pristine构建目录确保是全新构建。第一次构建或修改了重要配置后建议使用。构建过程会持续一两分钟。如果一切顺利你会在最后看到[100%] Linking C executable zephyr/zephyr.elf和[100%] Built target zephyr_final的成功信息。构建产物位于build/zephyr/目录下其中最重要的文件是zephyr.elf: 包含调试信息的可执行文件。zephyr.bin: 纯二进制镜像用于烧录。zephyr.hex: Intel HEX 格式镜像也可用于烧录。5.3 硬件连接与烧录你需要准备STM32F103C8T6 最小系统板。ST-Link V2 调试器/编程器或其他兼容的调试器如 J-Link。连接线杜邦线。连接方式SWD 四线制ST-Link 的 3.3V- 开发板的3.3VST-Link 的 GND- 开发板的GNDST-Link 的 SWDIO- 开发板的DIO(或 PA13)ST-Link 的 SWCLK- 开发板的DCLK(或 PA14)将 ST-Link 通过 USB 线连接到电脑。5.4 使用 West 命令烧录Zephyr 的west工具集成了烧录功能非常方便。在刚才构建的目录下执行west flashwest flash命令会自动检测连接的调试器和板子类型并调用合适的工具通常是 OpenOCD它包含在 Zephyr SDK 中将zephyr.bin文件烧录到芯片的 Flash 中。如果烧录成功你应该能看到终端输出类似*** Flashing Done ***的信息并且开发板上的 LED通常是 PC13 引脚连接的 LED开始闪烁恭喜你你已经成功在 STM32F103C8T6 上运行了第一个 Zephyr 程序。5.5 使用 OpenOCD 手动烧录备用方案如果west flash失败可以尝试使用 OpenOCD 手动烧录。首先确保你的 ST-Link 被系统识别Linux 下可运行lsusb查看。# 进入构建目录 cd ~/zephyrproject/zephyr/samples/basic/blinky/build # 启动 OpenOCD 连接 ST-Link 和 STM32F1 openocd -f interface/stlink.cfg -f target/stm32f1x.cfg如果连接成功会看到 OpenOCD 在等待 Telnet 或 GDB 连接。不要关闭这个终端。另开一个终端使用telnet或gdb进行烧录。方法一使用 Telnettelnet localhost 4444在 telnet 会话中输入program zephyr/zephyr.bin verify reset exit方法二使用 GDBarm-none-eabi-gdb zephyr/zephyr.elf在 GDB 中输入target remote localhost:3333 monitor reset halt load monitor reset run detach quit6. 常见问题与排查思路安装和构建过程中难免会遇到问题。这里列出一些常见错误及其解决方法。问题现象可能原因排查与解决思路west build失败提示找不到编译器或CMake Error1. SDK 未正确安装或环境变量未设置。2. 未在 Zephyr 目录下source zephyr-env.sh。1. 运行arm-none-eabi-gcc --version确认工具链可用。2. 运行echo $ZEPHYR_SDK_INSTALL_DIR确认路径正确。3. 确保在当前终端已执行source ~/zephyrproject/zephyr/zephyr-env.sh。west flash失败提示No ST-Link detected或Cannot open USB device1. ST-Link 驱动未安装Windows。2. Linux 下 udev 规则未安装或未生效。3. 线缆接触不良或板子未供电。1.Windows安装 ST-Link 官方驱动 。2.Linux重新执行sudo cp ... 60-openocd.rules和sudo udevadm control --reload并重新插拔ST-Link。3. 检查所有连线确保板子供电灯亮。构建时出现Kconfig相关错误板子配置冲突或依赖不满足。1. 使用west build -b stm32f103c8t6 -t menuconfig打开配置界面检查并保存。2. 尝试west build -p always进行彻底清理后再构建。west update速度慢或失败网络问题特别是从 GitHub 拉取子模块。1. 尝试配置 Git 代理或使用国内镜像源。2. 分步执行先west init然后手动修改.west/config中的url-base为镜像源地址再west update。运行arm-none-eabi-gcc提示command not foundSDK 的setup.sh或setup.cmd脚本未成功运行或环境变量 PATH 未包含工具链路径。1. 进入 SDK 安装目录重新运行./setup.sh(Linux) 或setup.cmd(Windows)。2. 检查 SDK 目录下的toolchains/子目录是否存在并手动将其下的bin目录如arm-zephyr-eabi/bin添加到系统的 PATH 环境变量中。烧录成功但 LED 不闪烁1. 开发板上的 LED 连接的不是默认引脚PC13。2. 示例代码的 GPIO 配置与你的板子不匹配。1. 查看你的最小系统板原理图确认 LED 连接的是哪个 GPIO 引脚。2. 修改示例代码。打开samples/basic/blinky/src/main.c找到#define LED0_NODE DT_ALIAS(led0)相关的部分。你需要根据你的板子设备树DTS定义来调整。对于最常见的stm32f103c8t6其设备树通常已将led0别名指向 PC13。7. 进阶创建自定义项目与最佳实践学会了运行示例下一步就是创建自己的项目。7.1 使用 West 创建新项目不建议在 Zephyr 源码目录内直接开发。最佳实践是在工作区外创建独立的应用程序目录。# 回到工作区上级目录 cd ~/zephyrproject # 使用 west 创建一个名为 my_app 的新项目 west create -p app -b stm32f103c8t6 ./my_app cd my_app这会在my_app目录下生成一个包含src/,CMakeLists.txt,prj.conf等文件的标准 Zephyr 应用骨架。7.2 项目结构解析my_app/ ├── CMakeLists.txt # 告诉 CMake 如何构建这个应用 ├── prj.conf # 主要的 Kconfig 配置文件用于启用/禁用内核功能 ├── src/ │ └── main.c # 你的应用程序主文件 └── west.yml # West 清单文件定义此应用的依赖和位置7.3 编写一个简单的按键控制 LED 程序让我们修改src/main.c实现一个按下按键假设接在 PA0切换 LED 状态的功能。/* * SPDX-License-Identifier: Apache-2.0 */ #include zephyr/kernel.h #include zephyr/drivers/gpio.h /* 定义 LED 和按键的设备树节点别名 */ #define LED0_NODE DT_ALIAS(led0) #define SW0_NODE DT_ALIAS(sw0) /* 获取 GPIO 设备指针 */ static const struct gpio_dt_spec led GPIO_DT_SPEC_GET(LED0_NODE, gpios); static const struct gpio_dt_spec button GPIO_DT_SPEC_GET(SW0_NODE, gpios); /* 按键中断回调函数 */ static void button_pressed(const struct device *dev, struct gpio_callback *cb, uint32_t pins) { /* 简单的防抖处理 */ k_sleep(K_MSEC(50)); if (gpio_pin_get_dt(button) 0) { // 确认按键仍处于按下状态 /* 翻转 LED 状态 */ gpio_pin_toggle_dt(led); } } static struct gpio_callback button_cb_data; void main(void) { int ret; printk(Zephyr Button-LED Example on STM32F103C8t6\n); /* 检查 LED 和按键设备是否就绪 */ if (!device_is_ready(led.port)) { printk(Error: LED device is not ready\n); return; } if (!device_is_ready(button.port)) { printk(Error: button device is not ready\n); return; } /* 配置 LED 引脚为输出默认关闭 */ ret gpio_pin_configure_dt(led, GPIO_OUTPUT_INACTIVE); if (ret 0) { printk(Error configuring LED pin\n); return; } /* 配置按键引脚为输入启用上拉电阻假设按键按下为低电平*/ ret gpio_pin_configure_dt(button, GPIO_INPUT | GPIO_PULL_UP); if (ret 0) { printk(Error configuring button pin\n); return; } /* 配置按键中断下降沿触发按下时*/ ret gpio_pin_interrupt_configure_dt(button, GPIO_INT_EDGE_TO_ACTIVE); if (ret 0) { printk(Error configuring button interrupt\n); return; } /* 初始化并添加中断回调函数 */ gpio_init_callback(button_cb_data, button_pressed, BIT(button.pin)); gpio_add_callback(button.port, button_cb_data); printk(Press the button to toggle the LED.\n); /* 主循环什么都不做等待中断 */ while (1) { k_sleep(K_SECONDS(1)); } }7.4 配置项目并构建你需要修改prj.conf来启用 GPIO 和中断支持# 启用 GPIO 驱动 CONFIG_GPIOy # 启用打印输出 CONFIG_PRINTKy CONFIG_STDOUT_CONSOLEy # 为按钮启用中断支持 CONFIG_GPIO_GETy然后像之前一样构建和烧录west build -b stm32f103c8t6 -p always west flash7.5 工程建议与最佳实践版本控制使用 Git 管理你的应用程序代码但将build/目录添加到.gitignore。配置管理复杂的配置可以拆分到多个.conf文件使用CONFIG_前缀的宏在代码中控制功能。设备树DTS覆盖如果你的板子引脚定义与标准板不同不要直接修改 Zephyr 源码中的设备树。而是在你的应用目录下创建boards/子目录添加一个board.overlay文件来覆盖或添加节点。例如创建一个boards/stm32f103c8t6.overlay来重新定义led0或sw0的引脚。调试日志充分利用printk和LOG_MODULE_*进行日志输出。GDB 调试使用west debug或west debugserver配合arm-none-eabi-gdb进行源码级单步调试这是查找复杂 Bug 的利器。电源管理对于电池供电设备务必研究 Zephyr 的电源管理PM子系统合理使用k_sleep()和低功耗模式。至此你已经完成了从零搭建 Zephyr 开发环境到运行示例再到创建和调试自定义项目的完整流程。Zephyr 生态庞大接下来可以深入探索其网络协议栈如 Bluetooth, WiFi、文件系统、多线程管理、传感器驱动框架等模块。官方文档和samples/目录下的示例是你最好的学习资源。遇到问题多在 Zephyr 项目的 GitHub 仓库或相关技术社区搜索和提问。
