如果你手上有一块 STM32F103C8T6 最小系统板想用 Zephyr RTOS 来开发那么第一步也是最关键的一步就是搞定 Zephyr SDK。很多人卡在这一步不是因为 SDK 本身多复杂而是因为环境、路径、版本和后续的编译、烧录环节没理顺。这篇文章我会以Zephyr SDK 1.0.1版本为例结合 STM32F103C8T6 这块经典“蓝板”把从下载、安装、配置到跑通第一个例程的完整流程拆解清楚。我会重点讲清楚为什么推荐用 SDK、安装时最容易踩的坑、以及如何验证你的安装是否真的能为后续开发服务。1. 为什么是 Zephyr SDK它和 STM32F103C8T6 有什么关系很多人第一次接触 Zephyr会疑惑为什么不能直接用自己电脑上已有的 GCC 或者 Keil 工具链。这里的关键在于“开箱即用”的完整性和一致性。Zephyr SDK 不是一个单一的编译器它是一个工具链集合包。对于 STM32F103C8T6基于 ARM Cortex-M3 内核来说你需要一个针对 ARM 架构的交叉编译工具链比如arm-zephyr-eabi-gcc。Zephyr SDK 不仅提供了这个还打包了 QEMU 模拟器、OpenOCD 调试器、以及一系列主机工具。这意味着你安装完 SDK就相当于一次性配齐了编译、模拟运行、硬件调试的全套环境而且版本是经过 Zephyr 项目官方测试和确认兼容的。对于 STM32F103C8T6 开发使用 SDK 有这几个直接好处避免工具链冲突你自己安装的 ARM GCC 可能版本不对或者路径设置有问题导致编译时找不到正确的库或头文件。简化调试和烧录SDK 自带的 OpenOCD 配置通常已经支持常见的调试器如 ST-Link、J-Link省去自己找配置文件的麻烦。保证与 Zephyr 版本的兼容性Zephyr 的构建系统CMake能自动发现并使用 SDK 中的工具链减少了因工具链版本不匹配导致的诡异编译错误。所以虽然理论上你可以手动配置其他工具链但对于新手或者希望快速上手的开发者直接使用 Zephyr SDK 是最高效、最稳妥的选择。我们的目标不是研究工具链本身而是尽快让板子跑起来。2. 安装前准备理清你的开发环境在动手下载任何东西之前先花两分钟确认你的开发环境。这能避免一半的“安装成功但用不了”的问题。2.1 确认操作系统和权限Zephyr SDK 支持 Linux、macOS 和 Windows。但它们的安装细节和后续使用习惯有差异Linux (如 Ubuntu, Fedora)最推荐的环境。命令行操作直接权限管理清晰。你需要有sudo权限来安装一些系统依赖和 udev 规则。macOS体验接近 Linux。确保已安装 Homebrew 或 MacPorts 来补充一些基础工具如wget或curl。Windows可以使用 WSL2 (Windows Subsystem for Linux) 或纯 Windows 环境。强烈建议使用 WSL2因为你可以获得一个近乎原生的 Linux 环境后续所有命令和脚本都与 Linux 一致避开了 Windows 特有的路径和终端问题。如果必须在纯 Windows 下请准备好7z解压工具和兼容的终端如 PowerShell。2.2 安装系统基础依赖无论哪个系统都需要先安装一些基础软件包。这里以Ubuntu 22.04 LTS为例这是目前非常稳定的选择。打开终端执行以下命令来更新软件源并安装编译 Zephyr 所需的依赖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 gcc-multilib g-multilib libsdl2-dev libmagic1关键点解释cmake,ninja-build: Zephyr 使用 CMake 作为构建系统Ninja 作为后端构建工具这是核心。dfu-util,device-tree-compiler: 用于固件烧录和设备树编译。python3-pip等 Python 相关包Zephyr 的辅助工具west是 Python 写的需要 Python 环境。libsdl2-dev: 如果你后续想用 QEMU 运行带有图形显示的模拟需要这个库。对于macOS你可以使用 Homebrewbrew install cmake ninja gperf python3 ccache qemu dtc。 对于Windows (WSL2)就按照上面的 Ubuntu 命令来操作。2.3 准备一个干净的工作目录建议在你的用户目录下创建一个专门用于 Zephyr 开发的工作空间避免文件散落各处。cd ~ mkdir -p zephyrproject cd zephyrproject后续所有操作包括下载 SDK 和 Zephyr 源码都可以在这个~/zephyrproject目录下进行。3. 下载与安装 Zephyr SDK 1.0.1步步为营现在进入核心环节。我们将严格按照官方推荐流程进行并指出每个步骤的注意事项。3.1 下载 SDK 捆绑包根据你的操作系统和架构下载对应的文件。我们以Linux x86_64系统为例。进入你准备好的工作目录然后下载cd ~/zephyrproject wget https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v1.0.1/zephyr-sdk-1.0.1_linux-x86_64_gnu.tar.xz注意版本号URL 中的v1.0.1和文件名中的1.0.1要对应。如果你想安装其他版本替换即可。变体选择我们下载的是_gnu变体它包含 GNU 工具链和所有主机工具这是最全的版本。还有_llvm(LLVM/Clang) 和_minimal(仅主机工具) 可选。对于初学者_gnu是默认且安全的选择。架构如果你的主机是 ARM64例如树莓派 4B需要将x86_64替换为aarch64。3.2 验证文件完整性可选但推荐下载完成后验证 SHA256 校验和确保文件在下载过程中没有损坏。wget -O - https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v1.0.1/sha256.sum | shasum --check --ignore-missing如果输出显示你下载的文件名后面跟着OK说明文件完好。3.3 解压 SDK 到推荐位置官方推荐了几个解压位置目的是为了让构建系统能自动发现 SDK。我们选择解压到用户主目录~下这样最省事。tar xvf zephyr-sdk-1.0.1_linux-x86_64_gnu.tar.xz -C ~这个命令会将 SDK 解压到~/zephyr-sdk-1.0.1。为什么是这个位置Zephyr 的构建系统会按照固定顺序在一些默认路径中搜索zephyr-sdk-目录。$HOME即~是搜索路径之一。放在这里后续编译时就不需要手动设置环境变量了。3.4 运行安装脚本这是最关键的一步。安装脚本会设置工具链并将其注册到系统中。cd ~/zephyr-sdk-1.0.1 ./setup.sh运行脚本后它会交互式地询问你是否要安装工具链。直接按回车选择默认的“是”。脚本会检查已有的工具链。下载缺失的工具链如果你下载的是完整捆绑包这一步应该很快因为工具链已经在压缩包里了。将 SDK 的路径信息写入 CMake 的包注册表这样 Zephyr 的 CMake 系统就能自动找到它。重要提示这个setup.sh只需要在初次解压后运行一次。如果你之后把zephyr-sdk-1.0.1文件夹移动到了其他位置必须再次进入新位置的文件夹重新运行setup.sh。安装脚本可能会提示你添加环境变量到~/.bashrc或~/.zshrc请按照提示操作然后执行source ~/.bashrc使配置生效。3.5 仅 Linux安装 udev 规则为了让普通用户权限就能通过 USB 调试器如 ST-Link烧录程序到 STM32F103C8T6需要复制 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 调试器新的规则才会生效。这步做完你就不需要每次烧录都sudo了。3.6 验证 SDK 安装安装完成后快速验证一下工具链是否可用。~/.local/zephyr-sdk-1.0.1/arm-zephyr-eabi/bin/arm-zephyr-eabi-gcc --version你应该能看到类似gcc (Zephyr SDK 1.0.1)的输出后面跟着 GCC 的版本号。如果提示“命令未找到”请检查是否运行了setup.sh环境变量是否已生效可以尝试新开一个终端窗口。工具链路径是否正确可以用find ~ -name arm-zephyr-eabi-gcc来查找。4. 获取 Zephyr 源码并配置环境SDK 是工具Zephyr RTOS 本身是我们要用的“原材料”。我们需要用west这个元工具来管理 Zephyr 项目和它的所有模块。4.1 安装 West 工具west是 Zephyr 项目的多仓库管理工具用 pip 安装即可。pip3 install --user -U west安装后将用户 Python 脚本目录添加到 PATHecho export PATH~/.local/bin:$PATH ~/.bashrc source ~/.bashrc验证安装west --version应输出版本号。4.2 拉取 Zephyr 主仓库及所有模块在工作目录下使用west init初始化并用west update拉取所有子模块。cd ~/zephyrproject west init -m https://github.com/zephyrproject-rtos/zephyr --mr v4.2.0 west update注意这里我们指定了--mr v4.2.0表示拉取 4.2.0 这个长期支持LTS版本。版本兼容性更稳定。你也可以拉取最新的主分支--mr main但可能有未预见的变更。SDK 1.0.1 与 Zephyr v4.2.0 是兼容的。4.3 导出 Zephyr 环境变量Zephyr 的构建系统需要知道 Zephyr 的根目录在哪里。通过 source 一个脚本来设置所有必需的环境变量。cd ~/zephyrproject/zephyr source zephyr-env.sh务必注意每次新开一个终端窗口进行 Zephyr 开发时都需要先进入zephyr目录然后执行source zephyr-env.sh。为了方便你可以把这条命令加到~/.bashrc末尾但更推荐手动执行避免环境变量污染其他项目。5. 为 STM32F103C8T6 编译并烧录第一个示例环境终于齐了。现在用最简单的blinkyLED 闪烁例程来测试整个工具链和硬件。5.1 确认开发板标识在 Zephyr 中每一款开发板都有一个唯一的标识符。对于最常见的 STM32F103C8T6 最小系统板通常指那种蓝色板核心芯片是 STM32F103C8T6对应的板型名称是bluepill。你可以通过以下命令查看 Zephyr 支持的所有板型west boards在输出列表中你应该能找到bluepill。5.2 编译 Blinky 示例进入示例目录使用west build命令进行编译。-b参数指定板型-p auto或-p always表示始终重新构建。cd ~/zephyrproject/zephyr/samples/basic/blinky west build -b bluepill如果一切顺利你会在终端看到 CMake 配置和 Ninja 编译的输出最后以[100%] Built target zephyr_final结束。编译产物位于build/zephyr/目录下其中最重要的文件是zephyr.bin二进制文件和zephyr.elf带调试信息的文件。编译过程可能遇到的问题找不到编译器错误信息如The CMAKE_C_COMPILER is not set。这说明 Zephyr 没找到 SDK。请确认是否source了zephyr-env.shSDK 的setup.sh是否运行成功可以尝试手动设置环境变量export ZEPHYR_TOOLCHAIN_VARIANTzephyr和export ZEPHYR_SDK_INSTALL_DIR~/zephyr-sdk-1.0.1。内存不足编译需要一定内存。如果虚拟机或实体机内存太小可能会失败。确保至少有 4GB 可用内存。5.3 连接硬件并烧录将 STM32F103C8T6 最小系统板通过 ST-Link (或兼容的调试器) 连接到电脑。确保连接正确ST-Link 的 SWDIO- 板子的DIOST-Link 的 SWCLK- 板子的DCLKST-Link 的 GND- 板子的GNDST-Link 的 3.3V- 板子的3.3V(如果板子无独立供电)使用west flash命令烧录程序west flashwest flash命令会尝试自动检测连接的调试器和板子并调用 SDK 中集成的 OpenOCD 或 pyOCD 来烧录zephyr.bin文件。烧录过程可能遇到的问题没有权限如果之前没安装 udev 规则可能会报LIBUSB_ERROR_ACCESS。请返回3.5节安装规则并重新插拔调试器。找不到调试器确认 ST-Link 驱动已安装Linux 下一般无需额外驱动且设备管理器或lsusb命令能识别到设备。烧录成功但板子没反应检查板上的 LED 引脚。bluepill板型的默认 LED 引脚是PC13。确认你的板子 LED 是否接在 PC13。有些板子的 LED 可能需要低电平点亮可以尝试修改示例代码中的电平逻辑。5.4 进阶使用 OpenOCD 或 pyOCD 手动烧录与调试west flash是封装好的命令。了解其底层原理有助于排查问题。它本质上是在调用类似以下的命令使用 OpenOCD:openocd -f interface/stlink.cfg -f target/stm32f1x.cfg -c program build/zephyr/zephyr.bin verify reset exit使用 pyOCD:pyocd flash -t stm32f103c8 build/zephyr/zephyr.bin你可以直接运行这些命令来烧录如果west flash失败用这些命令通常能获得更详细的错误信息。6. 从示例到自己的项目创建与构建跑通例程后你肯定想创建自己的项目。Zephyr 推荐使用west来创建和管理应用。6.1 在 workspace 中创建新应用假设我们的应用叫my_app放在~/zephyrproject下。cd ~/zephyrproject west create -t app -b bluepill ./my_app这会在当前目录创建my_app文件夹里面包含一个基本的src/main.c和CMakeLists.txt并且已经配置为bluepill板型。6.2 编写你的代码编辑my_app/src/main.c写一个简单的 LED 闪烁程序比如让闪烁频率和例程不同。#include zephyr/kernel.h #include zephyr/drivers/gpio.h #define LED0_NODE DT_ALIAS(led0) static const struct gpio_dt_spec led GPIO_DT_SPEC_GET(LED0_NODE, gpios); void main(void) { int ret; if (!device_is_ready(led.port)) { return; } ret gpio_pin_configure_dt(led, GPIO_OUTPUT_ACTIVE); if (ret 0) { return; } while (1) { gpio_pin_toggle_dt(led); k_msleep(500); // 修改这里的延时改为500ms } }6.3 构建与烧录构建和烧录命令与例程完全一样只是目录不同。cd ~/zephyrproject/my_app west build -b bluepill west flash6.4 项目结构解析理解项目结构有助于后续开发CMakeLists.txt: 告诉构建系统如何编译你的应用以及它依赖哪些 Zephyr 组件。prj.conf: Kconfig 配置文件用于启用或禁用 Zephyr 内核和驱动的特定功能。例如你可以在这里开启串口、I2C、SPI 等驱动。src/: 存放你的应用源代码。build/: 编译输出目录执行west build后生成。7. 常见问题深度排查与解决思路即使按照步骤也可能遇到问题。这里提供一个排查清单按照顺序检查。7.1 编译阶段问题现象west build失败报 CMake 错误。检查1确认终端当前目录在应用文件夹内并且已执行source ~/zephyrproject/zephyr/zephyr-env.sh。检查2运行echo $ZEPHYR_TOOLCHAIN_VARIANT应该输出zephyr。如果不是手动设置。检查3运行which arm-zephyr-eabi-gcc确认路径指向 SDK 内的编译器。如果不是检查 SDK 的setup.sh是否运行。检查4清除构建目录重试rm -rf build west build -b bluepill。现象编译报错找不到头文件或函数定义。检查很可能prj.conf中未启用对应的驱动或子系统。去 Zephyr 源码的samples/目录下找类似功能的示例参考它的prj.conf配置。7.2 烧录阶段问题现象west flash报错无法连接调试器。检查1运行lsusb(Linux) 或检查设备管理器 (Windows)看 ST-Link 设备是否被识别。检查2确认接线是否正确特别是 SWDIO 和 SWCLK。检查3尝试使用openocd或pyocd list命令手动连接看是否有更具体的错误信息。检查4有些克隆版 ST-Link 需要更新固件才能被新版 OpenOCD 识别。可以尝试使用st-info(来自stlink工具包) 来检测。现象烧录成功但板子无任何反应LED 不亮。检查1确认代码中控制的 GPIO 引脚与你板子上 LED 的实际连接引脚一致。bluepill的led0别名默认是PC13但你的板子可能不是。查看开发板文档或原理图。检查2用万用表或逻辑分析仪测量该 GPIO 引脚在程序运行后是否有电平变化。如果没有可能是时钟配置问题。STM32F1 系列需要正确配置时钟树但 Zephyr 的板级定义通常已处理好。可以尝试其他更简单的示例如hello_world通过串口打印来验证系统是否真的在运行。检查3检查prj.conf是否启用了 GPIO 和正确的引脚控制驱动。对于blinky通常需要CONFIG_GPIOy。7.3 调试与日志启用串口日志这是最有效的调试手段。在prj.conf中添加CONFIG_SERIALy CONFIG_CONSOLEy CONFIG_UART_CONSOLEy然后连接板子的 USART1 (PA9/PA10) 到 USB 转串口模块在电脑上用串口工具如minicom,picocom, PuTTY查看输出。hello_world示例就是最好的测试。使用 GDB 调试通过 OpenOCD 启动 GDB 服务器然后用arm-zephyr-eabi-gdb连接进行单步调试。这需要一些配置但对于复杂问题定位非常有用。整个流程走下来核心其实就三点环境装对、路径设对、板子选对。Zephyr SDK 把复杂的工具链整合好了west把项目管理和构建流程标准化了你要做的就是理解这个框架然后把自己的业务逻辑填进去。对于 STM32F103C8T6 这类经典芯片Zephyr 的支持已经非常成熟遇到问题多去查官方文档和社区大部分都能找到答案。