如果你正在寻找一个能让你在熟悉的 VSCode 环境中用 Zephyr RTOS 快速上手 STM32F103C8T6 最小系统板的完整方案那么这篇文章就是为你准备的。Zephyr 作为一个功能强大的开源实时操作系统其模块化设计和丰富的驱动支持使其成为嵌入式开发的优秀选择。然而对于初学者或习惯了传统 IDE 的开发者来说其基于命令行的构建系统和复杂的工具链配置往往是一道门槛。本文将聚焦于一个核心目标在 Windows 环境下使用 VSCode 作为主要开发工具完成从 Zephyr 环境搭建、项目创建、代码编写到最终将程序烧录到 STM32F103C8T6 最小系统板的全过程。我们会避开繁琐的理论直接进入实战重点关注每一步的操作细节、可能遇到的坑以及如何验证结果。无论你是想评估 Zephyr 的开发体验还是希望为手头的“蓝色药丸”开发板寻找一个现代化的开发框架这套流程都能让你快速跑通第一个点灯程序。1. 核心能力速览在开始动手之前我们先快速了解这套方案的核心特性和你需要准备的东西。能力项说明目标硬件STM32F103C8T6 最小系统板俗称“蓝色药丸”开发环境Windows 10/11 VSCode操作系统Zephyr RTOS (v3.6.x LTS 或更新版本)核心工具Zephyr SDK, CMake, Ninja, Python, Git, VSCode 插件调试/烧录器ST-Link V2 (或兼容的 DAPLink 等)主要功能在 VSCode 内完成代码编辑、构建、烧录、调试需额外配置全流程适合场景学习 Zephyr RTOS、为资源受限的 Cortex-M3 MCU 进行原型开发、评估 Zephyr 对常见外设GPIO, UART, I2C, SPI等的支持前置知识基础的 C 语言、嵌入式概念、命令行操作、Git 使用这套方案的优势在于它利用 VSCode 强大的扩展生态和 Zephyr 官方工具将原本分散的命令行操作整合到一个相对统一的界面中提升了开发效率尤其适合从 Arduino、STM32CubeIDE 等环境过渡过来的开发者。2. 适用场景与使用边界适合谁嵌入式初学者希望通过一个具体的硬件平台STM32F103C8T6来学习 RTOS 和现代嵌入式开发流程。Zephyr 评估者想在实际硬件上快速体验 Zephyr 的开发模式、驱动丰富度和性能。项目原型开发者需要为基于 Cortex-M3 内核的 MCU 快速搭建一个稳定、可扩展的软件基础。VSCode 忠实用户希望在嵌入式开发中也延续使用 VSCode 的高效编辑和插件生态。能解决什么问题环境配置标准化通过 Zephyr SDK 和工具链避免手动配置编译器、OpenOCD 的繁琐和版本冲突。项目构建自动化基于 CMake 和 Kconfig实现跨平台的一键构建管理依赖清晰。开发体验现代化在 VSCode 中获得代码补全、语法高亮、跳转定义、构建任务集成等 IDE 级体验。烧录流程简化通过集成好的命令或脚本一键完成编译和烧录无需切换多个工具。不适合什么场景极度追求编译速度Zephyr 的构建系统CMake Kconfig在首次配置或大幅修改配置时可能较慢对于需要极速迭代的简单项目可能不如直接寄存器编程或 CubeIDE 快捷。资源极度受限虽然 Zephyr 可裁剪但其内核本身会占用一定的 ROM/RAM。如果项目对几 KB 的 Flash/ROM 都锱铢必较可能需要精细配置或考虑更轻量的 RTOS。仅需裸机开发如果项目非常简单完全不需要任务调度、IPC 等 RTOS 功能使用 Zephyr 可能会引入不必要的复杂度。安全与合规边界硬件操作连接和烧录开发板时请确保电源和接口连接正确避免短路。软件版权Zephyr 采用 Apache 2.0 许可证可免费用于商业和个人项目但需遵守其许可证要求。固件安全本文涉及的烧录操作会擦写 MCU 内部 Flash操作前请确认板载无重要数据。3. 环境准备与前置条件请确保你的 Windows 系统满足以下条件并提前下载好必要的安装包。3.1 硬件准备STM32F103C8T6 最小系统板一块。ST-Link V2 调试器或兼容的 DAPLink 调试器一个。Micro-USB 数据线两条一条用于给开发板供电/通信另一条用于连接 ST-Link 到电脑。杜邦线若干用于连接 ST-Link 与开发板。3.2 软件准备下载安装包在开始安装前建议先下载好以下软件VSCode: 从官网下载并安装。Git for Windows: 从官网下载并安装安装时记得勾选“将 Git 添加到系统 PATH”。Python 3.8 或更高版本: 从官网下载 Windows 安装包安装时务必勾选“Add Python to PATH”。Zephyr SDK: 这是包含编译器、调试器等工具链的集成包。从 Zephyr SDK 发布页面下载适用于 Windows 的安装程序如zephyr-sdk-0.16.5_windows-x86_64.exe或更新版本。4. 安装部署与启动方式接下来我们一步步安装和配置所有软件。4.1 安装 Python 及必要包完成 Python 安装后以管理员身份打开命令提示符CMD或 PowerShell。安装用于 Zephyr 环境管理的west工具和其他依赖pip install west pip install pyelftools pip install pyyaml pip install packagingwest是 Zephyr 项目的元工具用于管理多个仓库和构建命令。4.2 安装 Zephyr SDK运行之前下载的 Zephyr SDK 安装程序。安装路径建议保持默认如C:\zephyr-sdk-0.16.5避免中文和空格。在安装最后一步务必勾选“将工具链添加到系统 PATH”的选项这样后续命令才能找到编译器。4.3 获取 Zephyr 源码并设置环境选择一个合适的目录作为工作空间例如D:\zephyrproject。在命令行中进入该目录cd /d D:\zephyrproject使用west初始化 Zephyr 源码仓库west init拉取 Zephyr 主仓库及其所有模块此过程耗时较长依赖网络环境west update导出 Zephyr 环境变量。这是一个关键步骤让系统知道 Zephyr 的根目录在哪里west zephyr-export安装 Zephyr 的 Python 依赖。在D:\zephyrproject目录下运行pip install -r zephyr\scripts\requirements.txt4.4 安装 VSCode 插件打开 VSCode安装以下核心插件以提升开发体验C/C(Microsoft): 提供代码智能感知、跳转、调试支持。CMake Tools(Microsoft): 集成 CMake 构建、配置、调试。Zephyr IDE(Zephyr Project): 官方插件提供 Kconfig 图形化配置、项目模板等可选但推荐。5. 硬件连接与驱动检查在烧录之前必须确保电脑能正确识别调试器。5.1 ST-Link 与开发板连接ST-Link V2 通常有 4 个关键引脚需要连接到 STM32F103C8T6SWDIO-PA13(JTMS)SWCLK-PA14(JTCK)GND-GND3.3V-3.3V(为开发板供电如果开发板已通过 USB 供电则可不接)注意连接时务必断电操作确认线序无误后再通电。5.2 安装 ST-Link 驱动将 ST-Link 通过 USB 线连接到电脑。打开设备管理器查看“通用串行总线设备”或“其他设备”中是否有“STM32 STLink”或未知设备。如果未自动安装可以下载 ST 官方的STSW-LINK009(ST-Link USB driver) 进行手动安装。更简单的方法是安装STM32CubeProgrammer软件其安装包内包含所需驱动。安装成功后在设备管理器的“通用串行总线设备”中应能看到 “STM32 STLink”。5.3 验证工具链和连接打开一个新的命令行窗口执行以下命令进行验证# 验证编译器 arm-zephyr-eabi-gcc --version # 验证 west 工具 west --version # 验证设备连接需要先安装 OpenOCDZephyr SDK 已包含 # 以下命令会尝试通过 ST-Link 连接目标板如果成功会显示芯片 ID openocd -f interface/stlink.cfg -f target/stm32f1x.cfg -c init -c reset halt -c flash probe 0 -c exit如果openocd命令能成功执行并识别到芯片例如显示stm32f1x.cpu说明硬件连接和驱动一切正常。如果失败请检查连接、驱动以及是否有其他软件如 Keil, IAR占用了 ST-Link。6. 创建并构建第一个 Zephyr 项目现在我们创建一个最简单的 Blinky闪烁 LED项目。6.1 使用 west 创建项目在D:\zephyrproject目录外找一个地方存放你的应用项目例如D:\my_zephyr_apps。cd /d D:\my_zephyr_apps west build -p always -b stm32f103c8t6 zephyr/samples/basic/blinky命令解释-p always: 总是清理之前的构建目录。-b stm32f103c8t6: 指定目标开发板为stm32f103c8t6。Zephyr 已经内置了对这块板子的支持。zephyr/samples/basic/blinky: 指定要构建的示例项目路径。构建成功后输出会显示生成的文件位于D:\my_zephyr_apps\build\zephyr目录下其中zephyr.bin和zephyr.hex就是我们要烧录的固件。6.2 在 VSCode 中打开并构建项目虽然命令行可以构建但在 VSCode 中操作更直观。在 VSCode 中打开文件夹D:\my_zephyr_apps。VSCode 可能会自动检测到 CMake 项目。如果没有可以按CtrlShiftP输入 “CMake: Configure” 来配置。底部的状态栏会显示构建目标Kit。点击它选择[Unspecified]然后从列表中选择GCC arm-none-eabi或Zephyr arm之类的工具链。再次按CtrlShiftP输入 “CMake: Build”即可开始构建。构建输出会显示在终端面板中。7. 烧录固件到开发板烧录是将编译好的二进制文件写入单片机 Flash 的过程。这里介绍几种常用方法。7.1 使用 west flash 命令推荐这是最集成化的方式。确保开发板已通过 ST-Link 连接好且驱动正常在项目构建目录下执行cd /d D:\my_zephyr_apps\build west flashwest flash命令会自动调用正确的烧录工具如 OpenOCD和配置文件将固件烧录到板子上。如果看到类似 “** Programming Finished**” 和 “** verify OK**” 的输出即表示烧录成功。此时STM32F103C8T6 板载的 PC13 引脚连接的 LED如果板子有应该开始闪烁。7.2 使用 STM32CubeProgrammer图形化如果你更喜欢图形界面打开 STM32CubeProgrammer。在连接方式中选择 “ST-LINK”并点击刷新按钮连接到设备。连接成功后在 “Binary File” 一栏选择之前生成的zephyr.hex或zephyr.bin文件。点击 “Download” 按钮开始烧录。进度条完成后按一下板子的复位键LED 应开始闪烁。7.3 使用 OpenOCD 命令底层对于想了解底层过程的开发者可以直接使用 OpenOCDopenocd -f interface/stlink.cfg -f target/stm32f1x.cfg -c program D:/my_zephyr_apps/build/zephyr/zephyr.bin verify reset exit 0x08000000此命令会连接芯片、擦除、编程、校验并复位芯片。8. 功能测试与效果验证烧录完成后需要进行验证以确保系统按预期工作。8.1 基础验证LED 闪烁预期结果STM32F103C8T6 最小系统板上与 PC13 引脚连接的 LED通常是蓝色或绿色以大约 1Hz 的频率闪烁。验证方法肉眼观察。如果 LED 不闪检查硬件连接特别是 SWDIO 和 SWCLK 是否接反。确认烧录过程是否真的成功查看命令行输出或 CubeProgrammer 日志。有些最小系统板的 LED 连接在别的引脚如 PA1。需要查看板子的原理图并修改 Zephyr 项目中的设备树dts或prj.conf文件中的 LED 引脚定义。对于blinky示例默认就是 PC13。8.2 串口输出验证进阶Blinky 示例默认没有串口输出。我们可以创建一个包含串口打印的项目来验证更复杂的功能。创建一个新应用目录例如hello_world。创建src/main.c文件写入以下内容#include zephyr/kernel.h #include zephyr/drivers/uart.h #include zephyr/sys/printk.h void main(void) { const struct device *uart_dev DEVICE_DT_GET(DT_NODELABEL(usart1)); if (!device_is_ready(uart_dev)) { printk(UART device not ready!\n); return; } printk(Hello Zephyr on STM32F103C8T6!\n); while (1) { printk(Tick...\n); k_sleep(K_SECONDS(1)); } }创建CMakeLists.txt:cmake_minimum_required(VERSION 3.20.0) find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE}) project(hello_world) target_sources(app PRIVATE src/main.c)创建prj.conf配置文件启用 UART1CONFIG_SERIALy CONFIG_UART_CONSOLEy CONFIG_UART_ASYNC_APIn构建并烧录west build -p always -b stm32f103c8t6 west flash使用串口调试助手如 Putty、SecureCRT连接开发板的 USART1 (PA9: TX, PA10: RX)波特率设置为 115200即可看到输出的 “Hello Zephyr…” 和 “Tick…” 信息。9. 在 VSCode 中配置调试可选但重要虽然烧录运行成功了但高效的开发离不开调试。Zephyr 结合 VSCode 和 Cortex-Debug 插件可以实现源码级调试。9.1 安装 Cortex-Debug 插件在 VSCode 扩展商店中搜索并安装 “Cortex-Debug”。9.2 创建调试配置文件在项目根目录D:\my_zephyr_apps\blinky下创建.vscode/launch.json文件{ version: 0.2.0, configurations: [ { name: Cortex Debug (ST-Link), cwd: ${workspaceRoot}, executable: ${workspaceRoot}/build/zephyr/zephyr.elf, request: launch, type: cortex-debug, servertype: openocd, serverpath: C:/zephyr-sdk-0.16.5/sysroots/x86_64-pokysdk-mingw32/usr/bin/openocd.exe, device: STM32F103C8, interface: swd, runToEntryPoint: main, openOCDConfigFiles: [ interface/stlink.cfg, target/stm32f1x.cfg ], svdFile: ${env:ZEPHYR_BASE}/../modules/hal/stm32/svd/stm32f103.svd } ] }注意serverpath需要修改为你本地 Zephyr SDK 中 OpenOCD 的实际路径。svdFile路径指向 SVD 文件它帮助调试器解析外设寄存器。9.3 开始调试确保开发板已连接。在 VSCode 中打开src/main.c在printk语句处设置断点。按F5或点击运行与调试视图中的绿色开始按钮。程序会在断点处暂停此时可以查看变量、单步执行、查看外设寄存器等。10. 常见问题与排查方法在实践过程中你很可能遇到以下问题。这里提供快速的排查思路。问题现象可能原因排查方式解决方案west命令未找到Python 或west未安装或 PATH 未设置在命令行输入west --version重新安装 Python 并勾选添加 PATH或使用pip install west构建时提示编译器错误Zephyr SDK 未安装或环境变量未设置检查arm-zephyr-eabi-gcc --version运行 SDK 安装程序并确保安装时勾选添加 PATH重新执行west zephyr-exportwest flash失败提示找不到设备1. ST-Link 驱动未安装2. 硬件连接错误3. 其他软件占用1. 检查设备管理器2. 检查杜邦线连接3. 关闭 Keil, IAR, CubeIDE 等1. 安装 ST-Link 驱动2. 重新连接确认线序3. 结束占用 ST-Link 的进程烧录成功但 LED 不闪烁1. LED 引脚非 PC132. 程序未运行时钟问题3. 硬件故障1. 查看开发板原理图2. 用串口打印调试信息3. 用万用表测量引脚电平1. 修改设备树或配置匹配正确引脚2. 检查系统时钟配置 (CONFIG_SYS_CLOCK_HW_CYCLES_PER_SEC)3. 更换开发板或元件VSCode 智能感知报错C/C 插件未正确配置包含路径查看 C/C 插件的 “问题” 面板生成compile_commands.json文件west build -t然后在 VSCode 中配置C_Cpp.default.configurationProvider为ms-vscode.cmake-toolsOpenOCD 连接超时1. 芯片处于低功耗模式或锁住2. 接线接触不良3. 芯片型号选择错误1. 尝试给芯片断电再上电2. 按压接线头3. 检查stm32f1x.cfg是否匹配1. 硬件复位2. 重新接线或使用质量好的杜邦线3. 确认是 F1 系列并尝试stm32f1x.cfg构建时内存不足项目配置过大超出 STM32F103C8T6 的 64KB Flash/20KB RAM查看build/zephyr/zephyr.map文件末尾的尺寸报告通过prj.conf裁剪不需要的功能如关闭调试、减少线程栈大小11. 最佳实践与使用建议为了获得更顺畅的 Zephyr 开发体验这里有一些建议项目结构清晰将自己的应用代码放在src/目录下配置文件prj.conf,boards/下的板级覆盖放在项目根目录。与 Zephyr 源码分离。善用 Kconfig 配置不要直接修改Kconfig文件。使用prj.conf进行应用级配置使用boards/子目录下的.conf文件进行板级覆盖。使用menuconfig工具west build -t menuconfig可以图形化查看和修改配置。版本控制将你的应用项目用 Git 管理起来。但切记将build/目录添加到.gitignore中。可以考虑将 Zephyr 本身作为 Git 子模块Submodule或者依赖west管理以保证团队环境一致。调试是利器尽早配置好 VSCode 的调试环境。单步执行、查看变量和寄存器能极大提升排查问题的效率。查阅官方文档Zephyr 官方文档是宝库。遇到驱动、内核 API 或构建系统的问题首先去 docs.zephyrproject.org 搜索。从示例开始zephyr/samples/目录下有大量示例涵盖了从传感器、网络到文件系统的方方面面。在开发新功能前先看看有没有现成的示例可以参考。管理多个板子如果你有多个不同型号的开发板可以使用west build -b board_name来指定目标板并为每个板子创建不同的构建目录或配置覆盖。通过以上步骤你应该已经成功地在 STM32F103C8T6 上运行了 Zephyr并在 VSCode 中建立了一套从编码、构建、烧录到调试的完整工作流。这套流程的核心价值在于将强大的 Zephyr RTOS 与高效的 VSCode 编辑器相结合为嵌入式开发提供了现代化、可扩展的解决方案。接下来你可以基于此环境去探索 Zephyr 提供的更多功能如线程、信号量、消息队列、设备驱动模型以及丰富的网络协议栈从而构建更复杂的嵌入式应用。