大家好我是专注于嵌入式开发的技术博主。最近在尝试将 Zephyr RTOS 应用到 STM32F103C8T6 这款经典的“蓝色药丸”最小系统板上时发现很多教程要么环境搭建不全要么编译过程报错不断特别是配合 VSCode 进行开发时配置更是让人头疼。本文将为你梳理一套从零开始、手把手式的完整流程涵盖 Zephyr 环境搭建、VSCode 配置、项目编译、烧录与调试的全过程。无论你是刚接触 Zephyr 的新手还是想将现有 Keil 项目迁移到更现代的 VSCode Zephyr 开发流这篇文章都能提供清晰的指引和可复现的代码示例。1. 背景与核心概念在深入实操之前我们有必要厘清几个核心概念这能帮助你理解我们正在构建的整个技术栈。1.1 什么是 Zephyr RTOSZephyr 是一款由 Linux 基金会托管的、开源、可扩展的实时操作系统RTOS。它专为资源受限的嵌入式设备设计支持超过 450 款开发板和 30 多种架构包括 ARM Cortex-M如 STM32、RISC-V、Xtensa 等。与 FreeRTOS、uC/OS 等传统 RTOS 相比Zephyr 的特点在于其高度模块化、强大的配置系统基于 Kconfig 和 Devicetree以及活跃的社区生态。它不仅仅是一个内核更是一个完整的 SDK提供了丰富的组件如文件系统、网络协议栈包括 LwM2M、CoAP、蓝牙协议栈等非常适合物联网IoT设备的开发。1.2 为什么选择 VSCode Zephyr传统的嵌入式开发往往依赖于 Keil MDK、IAR 等商业 IDE。这些工具功能强大但通常价格昂贵且跨平台支持有限。VSCode 作为一个免费、开源、跨平台的代码编辑器凭借其海量的插件生态和强大的可定制性已成为现代开发者的首选。将 Zephyr 与 VSCode 结合可以带来以下优势统一的开发体验在 Windows、Linux、macOS 上使用相同的工具链。强大的代码智能感知通过 C/C 插件获得代码补全、跳转、错误检查等功能。集成化的构建与调试可以直接在 VSCode 内调用 Zephyr 的构建系统West进行编译并通过 Cortex-Debug 等插件进行图形化调试。版本控制友好VSCode 与 Git 深度集成方便代码管理。1.3 目标硬件STM32F103C8T6 最小系统板STM32F103C8T6 基于 ARM Cortex-M3 内核主频 72MHz拥有 64KB Flash 和 20KB RAM因其极高的性价比和丰富的资源常被称为“蓝色药丸”是学习 STM32 和嵌入式开发的经典入门型号。我们将以此板卡为目标演示如何运行一个基础的 Zephyr 应用如闪烁 LED。2. 环境准备与版本说明搭建一个稳定可用的 Zephyr 开发环境是成功的第一步。以下步骤在 Windows 10/11 系统上验证通过同样适用于 Linux 和 macOS命令略有不同。2.1 安装必备工具Zephyr 的开发依赖一系列工具我们使用官方推荐的安装方式。1. 安装 Python 3.8 或更高版本Zephyr 的工具链如 West由 Python 编写。请从 Python官网 下载并安装。务必在安装时勾选 “Add Python to PATH”。2. 安装 Git用于获取 Zephyr 源代码。从 Git官网 下载安装。3. 安装 WestWest 是 Zephyr 的元工具用于管理多个仓库Manifest和执行构建、烧录等命令。在命令行中执行pip install west安装完成后运行west --version确认安装成功。4. 获取 Zephyr 源代码并安装 Python 依赖选择一个合适的目录路径不要有中文或空格执行以下命令。这里我们使用官方 Manifest它定义了 Zephyr 项目及其所有模块。# 初始化 west 工作区并克隆 manifest 仓库 west init zephyrproject # 进入工作区目录 cd zephyrproject # 拉取 Zephyr 源码及所有模块 west update # 导出 Zephyr 的 CMake 包使得在其他目录也能找到 Zephyr west zephyr-export # 安装 Zephyr 所需的 Python 依赖包 pip install -r zephyr/scripts/requirements.txt这个过程会下载大量文件请保持网络通畅。5. 安装工具链Zephyr 需要针对目标架构的编译器。对于 ARM Cortex-MSTM32我们安装 GNU Arm Embedded Toolchain。Windows: 下载 gcc-arm-none-eabi 安装包并安装。建议安装到C:\Program Files\Arm GNU Toolchain arm-none-eabi这类简单路径。Linux/macOS: 通常可以通过包管理器安装如sudo apt install gcc-arm-none-eabi(Ubuntu)。安装后需要将工具链的bin目录添加到系统的PATH环境变量中。例如Windows 下路径可能是C:\Program Files\Arm GNU Toolchain arm-none-eabi\13.2.rel1\bin。6. 安装 CMake 和 NinjaCMake 是 Zephyr 的构建系统生成器Ninja 是构建后端。Windows: 从 CMake官网 下载安装包安装时选择“为所有用户添加 CMake 到系统 PATH”。Ninja 可以从 其 GitHub 发布页 下载ninja-win.zip解压后将ninja.exe所在目录也加入PATH。Linux/macOS:sudo apt install cmake ninja-build(Ubuntu)。2.2 安装并配置 VSCode从 VSCode官网 下载并安装。安装以下必备扩展C/C(ms-vscode.cpptools): 提供代码智能感知、调试支持。CMake Tools(ms-vscode.cmake-tools): 集成 CMake 构建、配置、调试。Cortex-Debug(marus25.cortex-debug): 用于 ARM Cortex-M 芯片的图形化调试。(可选)Zephyr IDE(zephyr.zephyr-ide): 提供 Zephyr Kconfig 和 Devicetree 的语法高亮和预览。3. 创建并构建第一个 Zephyr 项目环境就绪后我们开始创建第一个项目。Zephyr 提供了丰富的示例Samples我们从最简单的blinkyLED 闪烁开始。3.1 创建项目工作区我们不直接在zephyrproject目录下开发而是创建一个独立的应用目录这样更清晰。# 假设在 D:\ 盘根目录 mkdir d:\my_zephyr_app cd d:\my_zephyr_app3.2 初始化应用程序Zephyr 应用需要遵循固定的目录结构。最简单的方式是复制一个示例。# 将 zephyr 的 blinky 示例复制到当前目录的 app 文件夹下 cp -r %ZEPHYR_BASE%\samples\basic\blinky app # 注意%ZEPHYR_BASE% 是环境变量指向 zephyrproject\zephyr。如果未设置请使用绝对路径例如 # cp -r d:\zephyrproject\zephyr\samples\basic\blinky app现在你的my_zephyr_app目录下有一个app文件夹里面就是blinky示例的源码。3.3 为 STM32F103C8T6 配置项目默认的blinky示例可能不是针对 STM32F103C8T6 的。我们需要创建一个构建配置。创建build目录并进入mkdir build cd build使用 CMake 配置项目 我们需要告诉 CMake 我们的目标硬件和工具链。通过-DBOARD参数指定板型。STM32F103C8T6 最小系统板在 Zephyr 中对应的板型名称通常是nucleo_f103rb因为引脚兼容或者更通用的stm32f103c8t6如果社区有支持。我们以nucleo_f103rb为例它被广泛支持。# 在 build 目录下执行 cmake -GNinja -DBOARDnucleo_f103rb ..\app-GNinja: 指定生成 Ninja 构建文件。-DBOARDnucleo_f103rb: 设置目标板。..\app: 指定 CMakeLists.txt 所在的源目录上一级的 app 文件夹。执行成功后会在build目录下生成一系列文件包括zephyr/.config(Kconfig 配置) 和zephyr/include/generated/(Devicetree 生成头文件)。构建项目 配置完成后使用 Ninja 进行编译。ninja如果一切顺利你将看到编译进度最后输出类似[100%] Linking C executable zephyr\zephyr.elf和[100%] Built target zephyr_final的信息。编译产物位于build\zephyr目录下最重要的文件是zephyr.hex、zephyr.bin和zephyr.elf。4. 在 VSCode 中集成与优化工作流命令行构建虽然强大但在 VSCode 中集成可以极大提升效率。4.1 使用 VSCode 打开项目用 VSCode 打开my_zephyr_app文件夹。4.2 配置 CMake Tools 扩展按下CtrlShiftP输入 “CMake: Select a Kit”选择你安装的 GCC Arm 工具链例如 “GCC 13.2.1 arm-none-eabi”。再次按下CtrlShiftP输入 “CMake: Select Variant”可以选择Debug或Release。最后输入 “CMake: Select Configure Preset”。如果没有预设我们需要创建一个。在项目根目录my_zephyr_app下创建.vscode/settings.json文件并添加 CMake 配置预设{ cmake.configureSettings: { BOARD: nucleo_f103rb }, cmake.sourceDirectory: ${workspaceFolder}/app, cmake.buildDirectory: ${workspaceFolder}/build, cmake.generator: Ninja, cmake.configureArgs: [ -GNinja ] }现在你可以点击 VSCode 底部状态栏的 “Build” 按钮或按F7来编译项目效果与命令行运行ninja相同。输出窗口会显示构建日志。4.3 配置调试环境调试是开发的关键。我们需要配置 Cortex-Debug 插件。确定调试探头STM32F103C8T6 最小系统板通常通过 ST-LINK 或 J-Link 进行调试。这里以最常见的 ST-LINK 为例。安装 OpenOCDOpenOCD 是开源的片上调试器。从 OpenOCD 官方 或 xPack 项目 下载 Windows 版本并解压将其bin目录加入PATH。创建调试配置在 VSCode 中切换到“运行和调试”视图CtrlShiftD点击“创建 launch.json 文件”选择 “Cortex-Debug”。这会在.vscode文件夹下生成launch.json。修改其内容如下{ version: 0.2.0, configurations: [ { name: Cortex Debug (ST-LINK), cwd: ${workspaceRoot}, executable: ${workspaceFolder}/build/zephyr/zephyr.elf, request: launch, type: cortex-debug, servertype: openocd, serverpath: C:/path/to/your/openocd/bin/openocd.exe, // 修改为你的 OpenOCD 路径 interface: swd, device: STM32F103C8, configFiles: [ interface/stlink.cfg, target/stm32f1x.cfg ], runToEntryPoint: main, svdFile: ${workspaceFolder}/zephyrproject/zephyr/dts/arm/st/stm32f103.svd // SVD文件用于查看外设寄存器 } ] }关键是要修改serverpath和svdFile的路径为你的实际路径。device设置为STM32F103C8。configFiles指定了 OpenOCD 使用的配置文件用于识别 ST-LINK 接口和 STM32F1 系列目标。开始调试连接好 ST-LINK 和板子给板子上电。在 VSCode 中按F5或点击绿色的调试按钮Cortex-Debug 将启动 OpenOCD连接目标板加载程序并停在main函数入口。你可以设置断点、单步执行、查看变量和寄存器。5. 适配自定义板型与引脚如果你的板子 LED 连接的不是nucleo_f103rb默认的引脚或者你使用的是纯粹的 STM32F103C8T6 最小系统板就需要修改 Devicetree 覆盖文件来匹配硬件。5.1 查找 LED 引脚查看你的板子原理图找到 LED 连接的 GPIO 引脚。例如假设 LED 阳极通过电阻连接到PC13阴极接地这是很多“蓝色药丸”板的接法。5.2 创建板级支持文件在app目录下创建一个板级定义覆盖目录结构并添加 Devicetree 覆盖文件。# 在 app 目录下 mkdir -p boards/arm/my_f103_board在boards/arm/my_f103_board目录下创建两个文件1.my_f103_board.dts定义板级硬件。/dts-v1/; #include st/f1/stm32f103Xb.dtsi #include st/f1/stm32f103c(8-b)tx-pinctrl.dtsi #include zephyr/dt-bindings/gpio/gpio.h / { model My Custom STM32F103C8T6 Board; compatible mycompany,my-f103-board; chosen { zephyr,console usart1; zephyr,shell-uart usart1; zephyr,sram sram0; zephyr,flash flash0; }; leds { compatible gpio-leds; led0: led_0 { gpios gpioc 13 GPIO_ACTIVE_HIGH; label User LED; }; }; aliases { led0 led0; }; }; usart1 { current-speed 115200; pinctrl-0 usart1_tx_pa9 usart1_rx_pa10; pinctrl-names default; status okay; }; usart2 { current-speed 115200; pinctrl-0 usart2_tx_pa2 usart2_rx_pa3; pinctrl-names default; status okay; };这个文件定义了板子模型、兼容性字符串并将led0映射到了GPIOC的第 13 引脚并配置了 USART1 用于控制台输出。2.my_f103_board.yaml板级定义元数据。identifier: my_f103_board name: My Custom F103 Board type: mcu arch: arm toolchain: - zephyr - gnuarmemb - xtools ram: 20 flash: 64 supported: - arduino_gpio - arduino_i2c - arduino_spi - uart - gpio - i2c - spi5.3 修改应用源码以使用自定义板现在修改app/src/main.c确保它使用我们定义的 LED 别名。#include zephyr/kernel.h #include zephyr/drivers/gpio.h /* 1000 msec 1 sec */ #define SLEEP_TIME_MS 1000 /* 使用设备树中的 led0 别名获取 LED 设备 */ static const struct gpio_dt_spec led GPIO_DT_SPEC_GET(DT_ALIAS(led0), gpios); void main(void) { int ret; // 检查 LED 设备是否就绪 if (!gpio_is_ready_dt(led)) { return; } // 将 LED 引脚配置为输出并初始化为低电平熄灭 ret gpio_pin_configure_dt(led, GPIO_OUTPUT_ACTIVE); if (ret 0) { return; } while (1) { // 翻转 LED 状态 ret gpio_pin_toggle_dt(led); if (ret 0) { return; } k_msleep(SLEEP_TIME_MS); } }5.4 使用自定义板型构建在构建时指定我们自定义的板型。# 在 build 目录下先清空或新建一个build目录 rm -rf * cmake -GNinja -DBOARDmy_f103_board ..\app ninja这样编译出的固件就会使用PC13来控制 LED。6. 烧录与运行编译成功后我们需要将zephyr.bin或zephyr.hex文件烧录到开发板。6.1 使用 West 命令烧录West 提供了便捷的烧录命令它会自动调用合适的工具如 OpenOCD。# 在 build 目录下 west flashwest flash会尝试自动检测调试探头和板型。对于 ST-LINK 和nucleo_f103rb或我们自定义的板型如果配置了正确的烧录器它通常能直接工作。如果失败可能需要检查 OpenOCD 安装和连接。6.2 使用 STM32CubeProgrammer 或 pyOCDSTM32CubeProgrammerST 官方工具图形化界面支持 ST-LINK 和 UART 等多种方式连接。pyOCD一个基于 Python 的 ARM Cortex-M 调试器。可以通过pip install pyocd安装然后使用pyocd flash build/zephyr/zephyr.bin --target stm32f103c8命令烧录。烧录完成后复位开发板你应该能看到 LED 开始闪烁。7. 常见问题与排查思路在搭建和开发过程中你可能会遇到以下问题问题现象可能原因排查步骤与解决方案west init或west update失败网络错误网络连接问题或 Git 仓库地址访问慢1. 检查网络。2. 尝试使用代理。3. 可以手动修改zephyrproject/.west/config中的url-base使用国内镜像如 Gitee 镜像需注意镜像可能滞后。cmake配置时找不到编译器或工具链1. 工具链未安装。2. 工具链路径未添加到PATH。3. 环境变量未生效。1. 运行arm-none-eabi-gcc --version确认工具链可用。2. 在命令行中检查PATH是否包含工具链的bin目录。3. 重启命令行终端或 VSCode。4. 在 CMake 配置时通过-DCMAKE_C_COMPILER和-DCMAKE_CXX_COMPILER直接指定编译器绝对路径。ninja编译失败提示No such file or directory或undefined reference1. 源码路径错误。2. 依赖的 Zephyr 模块未正确拉取。3. Kconfig 配置冲突。1. 确认cmake命令指向的源目录正确。2. 在zephyrproject目录下重新运行west update。3. 清除build目录重新配置和构建。4. 检查build/zephyr/.config文件确保必要的配置如CONFIG_GPIOy已启用。west flash失败无法连接目标1. 调试器ST-LINK驱动未安装或连接不稳。2. OpenOCD 配置错误。3. 板子未上电或 Boot 引脚设置错误。1. 安装 ST-LINK 驱动STSW-LINK009。2. 检查 USB 连接尝试重新插拔。3. 使用openocd -f interface/stlink.cfg -f target/stm32f1x.cfg命令单独测试 OpenOCD 连接。4. 确认板子 Boot0 引脚已接地从主Flash启动。程序已烧录但 LED 不闪烁1. LED 引脚定义与实际硬件不符。2. 程序未正常运行时钟、初始化问题。3. LED 极性高电平有效/低电平有效配置错误。1. 核对原理图确认 LED 连接引脚并检查 Devicetree 中的gpios属性。2. 尝试使用调试器单步执行看程序是否卡在某个初始化函数。3. 将GPIO_ACTIVE_HIGH改为GPIO_ACTIVE_LOW或反之。4. 使用逻辑分析仪或万用表测量引脚电平。VSCode 智能感知报错找不到头文件VSCode 的 C/C 插件未正确配置includePath和defines。1. 使用 CMake Tools 插件配置项目后通常会自动生成c_cpp_properties.json。2. 可以手动在.vscode/c_cpp_properties.json中配置将build目录下的compile_commands.json路径添加到compileCommands字段。这是最准确的方式。编译出的固件大小远超芯片 Flash 容量未启用优化或包含了不必要的组件。1. 使用-DCONFIG_SIZE_OPTIMIZATIONSy或-DCONFIG_NO_OPTIMIZATIONSn进行编译优化。2. 通过menuconfig(west build -t menuconfig) 图形化界面关闭不需要的模块如文件系统、网络栈。8. 最佳实践与工程建议掌握了基础流程后遵循以下最佳实践能让你的 Zephyr 开发更加高效和稳健。版本控制将你的应用代码app目录纳入 Git 管理。但通常不建议将庞大的zephyrproject仓库全部提交。可以使用.gitignore忽略build目录和zephyrproject通过west manifest文件来锁定 Zephyr 版本。管理多个应用使用 West 的多仓库管理能力。你可以在zephyrproject目录外创建一个west.yml清单文件将你的应用仓库也作为 West 的一个模块管理方便依赖和版本同步。充分利用 Kconfig 和 DevicetreeKconfig用于软件功能配置。使用west build -t menuconfig可以打开一个图形化界面来配置内核、驱动、协议栈等选项。配置结果保存在build/zephyr/.config。对于项目特定的配置可以在应用目录下创建prj.conf文件。Devicetree用于描述硬件。将板级硬件描述如 LED、按键、传感器接口放在板级目录boards/下的.dts文件中实现硬件与软件的解耦。模块化应用设计将不同的功能模块放在单独的源文件中并利用 Zephyr 的设备驱动模型。通过DEVICE_DT_DEFINE来定义和初始化设备使用gpio_dt_spec等结构体来传递设备树信息使代码更清晰、可移植。日志与调试积极使用 Zephyr 的日志系统#include zephyr/logging/log.h。通过设置不同的日志级别LOG_LEVEL_DBG,LOG_LEVEL_INF等可以在开发时输出详细信息而在生产时减少输出。配合串口控制台是排查问题的重要手段。电源管理对于电池供电的 IoT 设备务必关注电源管理。Zephyr 提供了电源管理框架允许在空闲时进入低功耗模式如 STOP、SLEEP。在prj.conf中启用CONFIG_PMy并合理配置。测试Zephyr 支持单元测试Twister和硬件测试。对于关键驱动和模块编写单元测试是保证长期稳定性的好习惯。可以使用west build -t run来在模拟器如 QEMU上运行测试。生产固件处理在发布固件前考虑启用链接时优化LTO、删除调试符号、并可能需要对固件进行签名或加密。使用west sign命令和 Zephyr 的 MCUboot 引导加载程序可以支持安全启动和固件升级。通过本文的步骤你应该已经成功在 STM32F103C8T6 上运行了 Zephyr并在 VSCode 中建立了一个舒适的开发环境。这套组合为你打开了现代嵌入式开发的大门无论是学习 RTOS 概念还是开发实际的 IoT 产品原型都是一个强大的起点。接下来你可以探索 Zephyr 提供的更多示例如传感器驱动、蓝牙通信、文件系统等逐步构建更复杂的应用。如果在实践中遇到新的问题Zephyr 的官方文档和活跃的社区如 Discord、GitHub Discussions是寻求帮助的好地方。
