如果你正在寻找一个能替代 FreeRTOS、RT-Thread 的现代化实时操作系统并且希望它能原生支持你手头那块经典的“蓝色药丸”STM32F103C8T6开发板那么 Zephyr RTOS 很可能就是你下一个需要认真评估的选择。但当你兴冲冲地打开 Zephyr 官网准备大干一场时很可能会被它的开发环境搭建过程“劝退”。它不像 Keil 或 STM32CubeIDE 那样提供一个集成的安装包而是依赖一整套基于命令行的工具链其中最关键、也最容易出问题的环节就是Zephyr SDK的安装与配置。很多人卡在这一步误以为 Zephyr 门槛极高最终无奈放弃。这篇文章要解决的核心问题就是如何干净利落地完成 Zephyr SDK 1.0.1 版本的安装并以此为基础在 STM32F103C8T6 最小系统板上跑通你的第一个 Zephyr 应用程序。我们将避开官方文档中可能存在的“跳步”和隐含假设用一个完整的、可复现的案例带你从零开始直到点灯成功。你会发现一旦跨过 SDK 安装这个“坎”Zephyr 强大的模块化、高度可配置性和对大量硬件支持超过 190 款 STM32 板卡的原生支持将为你打开嵌入式开发的新大门。1. 为什么是 Zephyr它解决了什么痛点在开始动手之前我们需要先明确 Zephyr 的价值。你可能会问已经有 FreeRTOS、RT-Thread 这些成熟方案了为什么还要折腾 ZephyrZephyr 的核心优势在于其高度模块化、高度可配置性和强大的硬件抽象层。它不是一个“一体式”的固件而是一个由数百个独立模块Kconfig 配置项组成的“乐高积木”系统。这意味着你可以为资源极其有限的设备比如只有 8KB RAM 的 MCU裁剪出一个极简内核也可以为功能复杂的设备如带 WiFi/BLE 的 SoC构建一个功能丰富的系统而它们共享同一套代码库和开发流程。对于 STM32F103C8T6 这类经典 Cortex-M3 芯片Zephyr 的优势具体体现在统一的开发体验无论你开发的是 STM32、Nordic nRF52 还是 ESP32使用的工具链west、构建系统CMake和配置方式Kconfig是完全一致的。这极大降低了学习多种平台的成本。丰富的驱动和组件Zephyr 社区提供了大量经过验证的驱动GPIO、UART、I2C、SPI、ADC 等和高级组件文件系统、网络协议栈、蓝牙栈等。你不需要从零开始写驱动更多时候是进行配置和集成。强大的配置系统通过menuconfig或guiconfig图形化界面你可以直观地启用/禁用任何功能并自动解决依赖关系避免了手动修改头文件带来的混乱和错误。面向未来的安全性Zephyr 在设计之初就考虑了安全特性如内存保护、线程隔离等这对于需要连接网络的物联网设备尤为重要。而Zephyr SDK正是解锁这一切的“钥匙”。它不是一个 IDE而是一个包含了交叉编译工具链GCC、OpenOCD调试、QEMU模拟等所有必要工具的集合包。安装并正确配置 SDK是后续所有开发工作的基石。2. 环境准备明确你的“战场”在开始安装前请确保你的开发环境符合以下要求。我们将以Windows 10/11 系统配合WSL2 (Ubuntu 22.04 LTS)作为主要演示环境。这是目前 Zephyr 官方推荐且问题最少的开发方式。当然你也可以使用纯 Linux 系统或 macOS核心步骤是相通的。必备条件清单操作系统Windows 10/11 并已安装 WSL2。如果你尚未安装请参考微软官方文档启用 WSL2 并安装一个 Ubuntu 发行版建议 22.04 LTS。WSL 内的 Ubuntu确保系统已更新。sudo apt update sudo apt upgrade -y基础依赖安装编译 Zephyr 所需的依赖包。sudo apt install --no-install-recommends 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 libmagic1Python 环境Zephyr 的工具west是基于 Python 的。建议使用pip3安装并确保~/.local/bin在 PATH 环境变量中。pip3 install --user -U pip echo export PATH~/.local/bin:$PATH ~/.bashrc source ~/.bashrc准备好以上环境我们就可以开始安装最关键的 Zephyr SDK 了。3. 核心步骤安装 Zephyr SDK 1.0.1这是本文的重中之重。我们将采用手动下载安装包的方式进行这种方式比在线安装脚本更可控尤其适合网络环境不稳定或需要特定版本的情况。3.1 下载 SDK 安装包首先在 WSL 的 Ubuntu 中选择一个合适的目录例如~/zephyrproject然后下载 SDK。# 创建项目目录并进入 mkdir -p ~/zephyrproject cd ~/zephyrproject # 下载 Zephyr SDK 1.0.1 的安装包 # 注意版本号可能更新请以实际需求为准。1.0.1是一个稳定的长期支持版本。 wget https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v1.0.1/zephyr-sdk-1.0.1_linux-x86_64.tar.xz # 下载对应的校验文件 wget https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v1.0.1/sha256.sum3.2 验证与解压下载完成后务必验证文件的完整性这是保证后续编译不出奇怪错误的重要一步。# 校验下载文件的 SHA256 哈希值 sha256sum -c sha256.sum 2/dev/null | grep OK如果看到zephyr-sdk-1.0.1_linux-x86_64.tar.xz: OK的输出说明文件完整无误。接着解压安装包到/opt目录推荐或你的用户目录。# 解压到 /opt 目录需要 sudo 权限 sudo tar xf zephyr-sdk-1.0.1_linux-x86_64.tar.xz -C /opt # 或者解压到用户目录 # tar xf zephyr-sdk-1.0.1_linux-x86_64.tar.xz -C ~我们以安装到/opt为例。3.3 运行安装脚本解压后进入 SDK 目录运行安装脚本。这个脚本会设置工具链的权限并安装必要的 udev 规则用于调试器访问设备权限。# 进入 SDK 目录 cd /opt/zephyr-sdk-1.0.1 # 运行安装脚本 # 对于所有用户使用 sudo ./setup.sh # 或者仅为当前用户安装不推荐可能遇到权限问题 # ./setup.sh -h在安装过程中脚本可能会询问是否安装用于 QEMU 模拟器的额外工具链对于 STM32 开发你可以选择n。但对于全面学习安装所有工具链也无妨。3.4 配置环境变量安装脚本通常会自动尝试修改你的 shell 配置文件如~/.bashrc或~/.zshrc但为了确保万无一失我们手动检查并添加。 打开你的~/.bashrc文件nano ~/.bashrc在文件末尾添加以下两行将 SDK 的交叉编译工具链路径加入到系统 PATH 中export ZEPHYR_SDK_INSTALL_DIR/opt/zephyr-sdk-1.0.1 export PATH$ZEPHYR_SDK_INSTALL_DIR/sysroots/x86_64-pokysdk-linux/usr/bin:$PATH保存并退出编辑器在 nano 中按CtrlX然后按Y最后回车。让配置立即生效source ~/.bashrc3.5 验证 SDK 安装运行以下命令检查工具链是否可用# 检查 ARM 交叉编译器 arm-zephyr-eabi-gcc --version # 检查 CMake 和 Ninja cmake --version ninja --version # 检查 west 是否已安装如果之前没装过 west --version如果arm-zephyr-eabi-gcc能正确输出版本信息如gcc version 12.2.0恭喜你Zephyr SDK 已经成功安装4. 获取 Zephyr 源码并设置环境有了 SDK我们还需要 Zephyr 操作系统本身的源代码。4.1 使用 West 工具获取源码west是 Zephyr 的元工具用于管理多个仓库主仓库和众多的模块仓库。我们用它来初始化工作区。# 回到项目目录 cd ~/zephyrproject # 使用 west 初始化并获取主仓库和所有必要的模块 # 这里我们获取 v3.6.0 版本一个稳定的 LTS 版本与 SDK 1.0.1 兼容性好 west init -m https://github.com/zephyrproject-rtos/zephyr --mr v3.6.0 # 拉取所有模块代码这一步耗时较长取决于网络 west update4.2 导出 Zephyr 环境变量Zephyr 构建系统需要知道 SDK 和源码的位置。通过一个脚本可以一次性设置好所有必要的环境变量。# 导出 Zephyr 环境 source ~/zephyrproject/zephyr/zephyr-env.sh为了方便你也可以将这一行添加到你的~/.bashrc文件中这样每次打开终端都会自动设置好 Zephyr 环境。echo source ~/zephyrproject/zephyr/zephyr-env.sh ~/.bashrc source ~/.bashrc5. 第一个案例在 STM32F103C8T6 上点亮 LED现在激动人心的时刻到了。我们将编译一个最简单的blinky闪烁 LED例程并将其烧录到你的 STM32F103C8T6 最小系统板也就是常说的“蓝色药丸” Blue Pill上。硬件连接准备将 STM32F103C8T6 通过 USB 转 TTL 串口模块连接到电脑用于查看日志。连接方式MCU 的PA9(TX) 接串口模块的 RXPA10(RX) 接串口模块的 TXGND 互连。将 ST-Link V2 调试器连接到板子。连接方式SWDIO-DIO,SWCLK-CLK,3.3V-3.3V,GND-GND。找到板载 LED 对应的引脚。对于最常见的 Blue Pill用户 LED 通常连接在PC13引脚。5.1 配置项目Zephyr 为许多开发板提供了现成的配置。STM32F103C8T6 最小系统板对应的板型名称通常是stm32f103c8t6或bluepill。我们以bluepill为例。# 进入一个临时目录构建项目 mkdir -p ~/zephyrproject/blinky_test cd ~/zephyrproject/blinky_test # 使用 west 创建基于 blinky 示例的构建目录并指定目标板为 bluepill west build -p always -b bluepill ~/zephyrproject/zephyr/samples/basic/blinky-p always: 表示总是重新构建如果目录已存在则先清理。-b bluepill: 指定目标开发板。最后是示例程序的路径。5.2 检查与自定义配置可选在构建前你可以使用图形化配置工具来查看或修改配置例如确认 LED 引脚是否正确。# 进入构建目录并启动 menuconfig cd build west build -t menuconfig在menuconfig界面中你可以通过箭头键导航。对于 LED路径通常是Device Drivers-LED drivers-[ ] LED driver for GPIO(确保启用)。 然后检查GPIO配置。不过对于bluepill板型这些通常已在设备树中定义好。你可以先尝试默认配置。5.3 编译项目如果你跳过了上一步的配置或者配置完成后直接编译即可# 在构建目录中或回到项目目录使用 west 编译 west build如果一切顺利你将在最后看到类似以下的输出[XX/XX] Linking C executable zephyr/zephyr.elf Memory region Used Size Region Size %age Used FLASH: XXXXX B YYYY B ZZ% RAM: AAAAA B BBBB B CC% [XX/XX] Generating zephyr/zephyr.bin [XX/XX] Generating zephyr/zephyr.hex这表示编译成功并生成了zephyr.bin和zephyr.hex等烧录文件。5.4 烧录与调试我们将使用 OpenOCD已包含在 Zephyr SDK 中通过 ST-Link 进行烧录。# 使用 west 和 openocd 烧录 west flashwest flash命令会自动调用正确的烧录 runner这里是openocd并找到生成的zephyr.elf文件进行烧录。看到** Flashing Success**之类的提示即表示烧录成功。5.5 验证结果烧录完成后STM32F103C8T6 板子上的 LEDPC13应该开始以大约 1Hz 的频率闪烁。如果没有闪烁请检查硬件连接是否正确特别是 ST-Link 的连接和供电。板载 LED 的引脚是否是PC13有些板子可能不同。串口日志连接串口工具如minicom,picocom或 Windows 下的 Putty、SecureCRT波特率设置为 115200可以看到 Zephyr 的启动日志帮助诊断问题。# 在 WSL 中安装并使用 picocom sudo apt install picocom picocom -b 115200 /dev/ttyUSB0 # 请将 /dev/ttyUSB0 替换为你的实际串口设备6. 进阶案例实现 UART 串口打印仅仅点灯还不够串口通信是嵌入式调试的“生命线”。让我们创建一个简单的程序通过串口打印“Hello Zephyr from STM32F103C8T6!”。6.1 创建自定义项目我们不直接修改示例而是创建一个新的项目目录。mkdir -p ~/zephyrproject/uart_hello cd ~/zephyrproject/uart_hello6.2 编写主程序代码创建src目录和主文件main.cmkdir src nano src/main.c将以下代码写入main.c#include zephyr/kernel.h #include zephyr/drivers/uart.h #include zephyr/device.h /* 获取 UART1 设备实例。在 STM32F103C8T6 上UART1 通常对应 PA9(TX)/PA10(RX) */ #define UART1_NODE DT_NODELABEL(usart1) static const struct device *uart_dev DEVICE_DT_GET(UART1_NODE); void main(void) { int ret; const char *tx_data Hello Zephyr from STM32F103C8T6!\r\n; /* 检查 UART 设备是否就绪 */ if (!device_is_ready(uart_dev)) { printk(UART device not ready!\n); return; } printk(UART1 is ready, start printing...\n); while (1) { /* 通过 UART 发送字符串 */ for (int i 0; tx_data[i] ! \0; i) { uart_poll_out(uart_dev, tx_data[i]); } /* 等待 1 秒 */ k_sleep(K_SECONDS(1)); } }6.3 编写项目配置文件在项目根目录创建CMakeLists.txtnano CMakeLists.txt写入以下内容# 设置 Zephyr 所需的最小 CMake 版本 cmake_minimum_required(VERSION 3.20.0) # 查找 Zephyr 包。这会将 Zephyr 构建系统引入项目。 find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE}) # 将 src 目录添加到项目中 project(uart_hello) # 将源文件添加到目标 target_sources(app PRIVATE src/main.c)创建板型覆盖文件可选但推荐。由于bluepill板型默认可能未使能 UART1我们可以创建一个设备树覆盖文件来确保它被启用。mkdir -p boards nano boards/bluepill.overlay写入以下内容明确启用 USART1/ { chosen { zephyr,console usart1; }; }; usart1 { status okay; current-speed 115200; pinctrl-0 usart1_tx_pa9 usart1_rx_pa10; pinctrl-names default; };6.4 构建与烧录现在像之前一样构建和烧录项目但指定我们自定义的项目目录。# 在项目根目录执行 west build -p always -b bluepill . -- -DOVERLAY_CONFIGboards/bluepill.overlay.表示当前目录是项目目录。--之后是传递给 CMake 的参数这里指定了我们的设备树覆盖文件。构建成功后进行烧录west flash6.5 验证串口输出使用串口工具如picocom -b 115200 /dev/ttyUSB0连接开发板。你应该能看到每秒输出一次 “Hello Zephyr from STM32F103C8T6!” 字符串同时开发板上的 LED 可能也在闪烁因为默认的prj.conf可能继承了某些配置。这证明你的 UART 驱动和应用程序都工作正常。7. 常见问题与排查思路在安装和开发过程中你几乎一定会遇到一些问题。下表列出了最常见的问题及其解决方法问题现象可能原因排查方式解决方案west命令未找到1.pip3安装的west不在 PATH 中。2. 未执行source ~/.bashrc。执行which west或west --version。1. 确认~/.local/bin在 PATH 中并source ~/.bashrc。2. 重新安装pip3 install --user west。arm-zephyr-eabi-gcc未找到1. SDK 环境变量未设置。2. SDK 安装路径错误。执行echo $ZEPHYR_SDK_INSTALL_DIR和which arm-zephyr-eabi-gcc。1. 检查~/.bashrc中的ZEPHYR_SDK_INSTALL_DIR和PATH设置是否正确。2. 重新运行 SDK 的setup.sh。west build失败提示找不到板型1. 板型名称拼写错误。2. Zephyr 源码中不支持该板型。执行west boards查看所有支持的板型列表。1. 使用 west boards编译错误提示内存溢出STM32F103C8T6 的 Flash/RAM 资源不足64KB Flash, 20KB RAM。查看编译输出的内存占用报告。1. 通过menuconfig裁剪不需要的功能模块如文件系统、网络。2. 优化代码减少全局变量和缓冲区大小。west flash失败无法连接 ST-Link1. ST-Link 驱动未安装Windows。2. 在 Linux/WSL 下缺少 udev 规则或权限。3. 硬件连接问题。1. 在设备管理器中检查 ST-Link。2. 在 WSL 中执行lsusb查看是否能识别到 ST-Link 设备。1. Windows 安装 ST-Link 官方驱动。2. WSL/Linux确保已运行 SDK 的setup.sh安装 udev 规则或将用户加入plugdev组。3. 检查接线尤其是SWDIO和SWCLK。串口无输出1. 串口引脚接错TX/RX 交叉。2. 波特率不匹配。3. 设备树中 UART 未启用或引脚映射错误。1. 确认硬件连接。2. 检查代码和设备树中的波特率设置应为 115200。3. 使用west build -t menuconfig检查 UART 驱动是否启用。1. 交换 TX 和 RX 接线。2. 确保代码、设备树和串口工具波特率一致。3. 使用本文提供的设备树覆盖文件 (bluepill.overlay)。下载速度慢 (west update)网络连接 GitHub 不稳定。观察下载进度。1. 使用代理需自行配置 git 和 wget 的代理。2. 使用国内镜像源如 Gitee 镜像但可能不是最新。8. 最佳实践与工程建议当你成功运行了第一个程序后为了进行更严肃的项目开发请遵循以下建议版本控制你的应用程序代码src/目录、CMakeLists.txt、prj.conf、设备树覆盖文件等应该用 Git 管理。但不要将build/目录和 Zephyr 源码本身zephyr/目录提交到你的仓库。使用.gitignore文件忽略它们。配置管理使用prj.conf文件进行应用程序级别的 Kconfig 配置。使用设备树覆盖文件.overlay进行板级硬件定制而不是直接修改 Zephyr 内部的设备树文件。对于不同的构建类型如调试版、发布版可以创建prj_release.conf等文件并通过-DOVERLAY_CONFIG和-DCONF_FILECMake 参数指定。调试日志充分利用 Zephyr 的printk或更高级的日志系统进行调试。可以通过menuconfig调整日志级别。GDB 调试Zephyr SDK 集成了 GDB。你可以使用west debug或west debugserver配合 ST-Link 进行源码级单步调试这比单纯打印日志强大得多。资源管理对于 STM32F103C8T6 这类资源紧张的芯片要时刻关注内存和 Flash 使用情况。定期使用west build -t rom_report和west build -t ram_report命令生成内存报告指导你进行功能裁剪。电源管理如果开发电池供电设备务必研究 Zephyr 的电源管理框架合理使用低功耗模式。社区与文档遇到复杂问题优先查阅 Zephyr 官方文档 。在 Zephyr Discord 或 GitHub Issues 上提问时提供尽可能多的信息Zephyr 版本、SDK 版本、板型、你的prj.conf、错误日志等。通过本文的步骤你已经成功搭建了 Zephyr 开发环境并在 STM32F103C8T6 上运行了两个基础示例。这个过程的真正价值在于你掌握了一套标准化、可复现的嵌入式 RTOS 开发流程。接下来你可以尝试集成传感器驱动、连接网络模块如 W5500甚至探索 Zephyr 对蓝牙或 LoRa 的支持将这块经典的核心板潜力充分发挥出来。建议你将此环境保存为虚拟机或 Docker 镜像作为未来所有 Zephyr 项目的可靠起点。