1. 从零开始为什么要在VSCode里用Zephyr搞STM32F103C8T6如果你手头有一块经典的STM32F103C8T6最小系统板想从传统的Keil、IAR或者STM32CubeIDE转向更现代、更开源的开发方式那么Zephyr RTOS加上VSCode的组合绝对值得你花时间折腾一下。这个方案解决的核心问题是让你在一个统一的、跨平台的、插件生态丰富的编辑器里完成从代码编写、项目构建、调试到固件烧录的完整嵌入式开发流程。它特别适合已经厌倦了传统IDE的笨重或者需要在Linux/macOS下进行STM32开发的工程师和爱好者。最关键的价值在于Zephyr提供了一个高度模块化、可配置的实时操作系统内核而VSCode提供了极佳的代码编辑和项目管理体验。两者结合意味着你可以用写应用层代码的舒适感去开发底层嵌入式系统。但别被“现代”这个词唬住它的落地过程依然充满了“嵌入式特色”的坑比如工具链配置、环境变量、烧录器驱动一个没对齐就可能卡住半天。这篇文章就是带你完整走一遍用VSCode在STM32F103C8T6上运行第一个Zephyr项目的全过程重点不是罗列命令而是告诉你每一步在干什么以及卡住了该往哪看。2. 动手前的准备理清工具链与硬件清单在打开VSCode之前先把“战场”打扫干净。很多失败都源于环境没准备好。你需要的东西分为软件和硬件两大部分。2.1 软件环境搭建以Windows为例Linux/macOS思路类似Zephyr的开发环境相对独立官方推荐使用其工具链管理器。我们按顺序来。第一步安装Python和包管理器Zephyr的构建系统West严重依赖Python。请确保你安装了Python 3.8或更高版本并且将Python和Pip添加到系统环境变量PATH中。安装后在命令行输入python --version和pip --version确认。第二步安装Zephyr SDK这是最核心的一步。Zephyr SDK是一个集成了编译器、调试器、烧录工具等所有必需工具的套件。前往Zephyr项目官网的下载页面找到适用于你操作系统Windows、Linux或macOS的SDK安装包。对于STM32F103ARM Cortex-M3架构你需要的是ARM工具链。下载后运行安装程序。关键点来了安装路径不要包含中文或空格。我一般直接装在C:\zephyr-sdk-0.16.0版本号以实际为准这样的路径下。安装过程中可能会询问是否将工具链添加到环境变量务必勾选“是”。如果没有这个选项安装完成后需要手动将SDK的bin目录例如C:\zephyr-sdk-0.16.0\arm-zephyr-eabi\bin添加到系统的PATH环境变量中。第三步获取Zephyr源码并初始化环境Zephyr的源码和项目管理通过west工具进行。打开命令行CMD或PowerShell创建一个干净的工作目录比如D:\zephyr_project。在这个目录下执行初始化命令。这里有个小技巧为了加快克隆速度可以使用国内镜像源如清华源# 设置镜像地址非必须但推荐 pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple # 安装west工具 pip install west # 初始化一个west工作区并指定使用镜像源克隆主仓库 west init -m https://gitee.com/mirrors/zephyr.git --mr main zephyrproject进入初始化的工作区目录并拉取所有模块cd zephyrproject west update导出Zephyr环境变量。这一步非常重要它告诉系统Zephyr的核心路径在哪# 在Windows PowerShell中 .\zephyr\zephyr-env.cmd # 在Linux/macOS的bash中 source zephyr/zephyr-env.sh每次新开命令行窗口要编译Zephyr项目前都需要执行这个命令。为了方便你可以把这条命令加到系统的启动脚本里或者使用VSCode的终端集成功能后面会讲。2.2 硬件连接与驱动硬件方面很简单主控STM32F103C8T6最小系统板一块。调试/烧录器ST-Link V2或兼容的DAPLink等。这是最常用的也是本文示例所用的。连接方式用杜邦线将ST-Link与最小系统板连接好ST-Link SWDIO-板子的SWDIO (PA13)ST-Link SWCLK-板子的SWCLK (PA14)ST-Link GND-板子的GNDST-Link 3.3V-板子的3.3V注意如果板子已有独立供电可不接VCC但GND必须共地。连接好后将ST-Link插入电脑USB口。打开设备管理器你应该能看到一个“STMicroelectronics STLink dongle”或类似的设备。如果显示为未知设备你需要安装ST-Link的驱动可以从ST官网下载“STSW-LINK009”这个软件包进行安装。3. 在VSCode中构建并运行第一个Zephyr示例环境就绪硬件连通现在进入VSCode环节。我们的目标是编译一个最简单的Blinky闪烁LED程序并烧录到板子上。3.1 VSCode插件与工作区配置首先安装必要的VSCode插件C/C(Microsoft)提供代码智能感知、跳转、错误检查。CMake Tools(Microsoft)因为Zephyr使用CMake作为构建系统这个插件至关重要。Zephyr IDE(Zephyr Project)官方插件提供项目创建、构建、烧录、调试的图形化按钮能极大提升效率。安装完插件后用VSCode打开之前创建的zephyrproject目录。这是你的工作区根目录。接下来是关键一步配置VSCode的终端环境。我们需要让VSCode内部的终端比如集成终端自动载入Zephyr环境变量。在VSCode中按CtrlShiftP打开命令面板输入Preferences: Open User Settings (JSON)。在打开的settings.json文件中添加以下配置路径请替换为你自己的实际安装路径{ terminal.integrated.shellArgs.windows: [-NoExit, -Command, C:\\zephyrproject\\zephyr\\zephyr-env.cmd], cmake.configureEnvironment: { ZEPHYR_BASE: C:\\zephyrproject\\zephyr, PATH: C:\\zephyr-sdk-0.16.0\\arm-zephyr-eabi\\bin;${env:PATH} }, zephyr-ide.sdkPath: C:\\zephyr-sdk-0.16.0 }这个配置做了三件事让终端启动时自动运行zephyr-env.cmd告诉CMake工具Zephyr的基础路径和工具链路径告诉Zephyr IDE插件SDK在哪。对于Linux/macOS配置原理类似但语法和路径不同。3.2 编译Blinky示例Zephyr源码中自带大量示例位于zephyr/samples目录下。我们以最基本的blinky为例。在VSCode的资源管理器中导航到zephyr/samples/basic/blinky。在这个文件夹上右键选择“在集成终端中打开”。在终端中首先确保环境变量已加载如果配置了上述自动加载则无需手动执行。然后使用west命令进行构建并指定我们的目标板。STM32F103C8T6最小系统板通常对应bluepill开发板配置因为很多F103C8T6板子模仿了BluePill的布局。west build -b bluepill .west build: 构建命令。-b bluepill: 指定板型Board Target。Zephyr支持大量板型bluepill就是为STM32F103C8T6这类板子预定义的配置。.: 表示在当前目录即blinky示例目录下构建。如果一切顺利你会看到编译进度最后输出[100%] Linking C executable zephyr\zephyr.elf和Memory region Used Size Region Size %age Used等信息这表示编译成功。生成的固件文件是build\zephyr\zephyr.bin。常见问题排查点west命令未找到说明Python环境或west安装有问题或者环境变量未生效。回到命令行非VSCode终端检查west --version。板型bluepill未找到检查拼写或者运行west boards查看所有支持的板型列表。编译错误提示找不到编译器或头文件99%是Zephyr SDK路径或环境变量ZEPHYR_BASE未正确设置。请仔细检查第2.1和3.1节的配置。3.3 烧录固件到STM32F103C8T6编译成功只是生成了二进制文件下一步是把它“灌”进芯片里。Zephyr的west命令也集成了烧录功能。确保ST-Link已正确连接板子和电脑。在刚才编译的终端里目录仍在blinky的build目录外运行烧录命令west flashwest flash命令会自动调用SDK中对应的烧录工具对于ST-Link和bluepill板型通常是OpenOCD找到连接的设备并将zephyr.bin文件写入芯片的Flash。观察终端输出和板子。如果成功你会看到类似以下信息-- west flash: using runner openocd Open On-Chip Debugger ... Info : Listening on port 6666 for tcl connections Info : Listening on port 4444 for telnet connections Info : clock speed 1000 kHz Info : STLINK V2J... Info : Target voltage: 3.3 V Info : stm32f1x.cpu: hardware has 6 breakpoints, 4 watchpoints ** Programming Started ** ** Programming Finished ** ** Verify Started ** ** Verified OK ** ** Resetting Target **同时板载的LED通常是PC13引脚连接的LED应该开始闪烁。烧录失败排查west flash找不到设备首先检查设备管理器里ST-Link驱动是否正常有无感叹号。然后检查杜邦线连接是否牢固特别是SWDIO、SWCLK和GND。提示“No ST-Link detected”或“Cannot connect to target”尝试给板子重新上电或者按一下板子的复位键。有时芯片处于某种状态会导致连接失败。权限问题Linux/macOS常见可能需要将当前用户添加到dialout或plugdev组或者使用sudo运行west flash不推荐长期使用。更好的方法是配置udev规则。4. 进阶理解项目结构与自定义开发跑通示例只是开始。要开发自己的项目你需要理解Zephyr项目的结构。4.1 Zephyr项目目录结构一个标准的Zephyr应用项目比如你从blinky复制出来修改通常包含以下关键文件my_app/ ├── CMakeLists.txt # 项目的CMake构建定义必须包含 find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE}) 和 target_sources(app PRIVATE src/main.c) ├── prj.conf # 项目的Kconfig配置文件用于启用/禁用Zephyr内核和驱动模块的功能 ├── src/ │ └── main.c # 你的应用程序主入口源文件 └── board.cmake (可选) # 板级特定配置如果你有自定义板型CMakeLists.txt告诉构建系统如何编译你的代码链接哪些库。prj.conf这是Zephyr的精髓之一。Zephyr内核、驱动、子系统都是可裁剪的模块。你在这里通过CONFIG_开头的宏来配置系统。例如要使用GPIO和LED就需要CONFIG_GPIOy和CONFIG_LEDy。src/main.c你的应用代码。入口函数是void main(void)。4.2 创建并构建自定义项目在zephyrproject目录外避免污染源码新建一个目录例如my_zephyr_app。按照上面的结构创建CMakeLists.txt,prj.conf,src/main.c。一个最简单的prj.conf可以只包含CONFIG_GPIOy CONFIG_LEDy在src/main.c中写一个简单的LED闪烁程序可以参考blinky示例的代码。在my_zephyr_app目录下打开终端执行构建和烧录# 先加载环境变量如果VSCode终端未自动加载 # 对于Windows: call C:\zephyrproject\zephyr\zephyr-env.cmd # 对于Linux/macOS: source /path/to/zephyrproject/zephyr/zephyr-env.sh west build -b bluepill . west flash4.3 使用VSCode Zephyr IDE插件提升效率手动敲命令虽然直接但效率不高。Zephyr IDE插件提供了图形化界面在VSCode活动栏找到Zephyr的图标一个芯片形状。在插件视图中你可以选择板型 (bluepill)、项目目录、构建目录。点击“Build”按钮进行编译点击“Flash”按钮进行烧录。插件还会在底部状态栏显示当前配置的板型和串口非常直观。更重要的是这个插件能帮你自动补全prj.conf中的CONFIG_选项。当你输入CONFIG_时它会列出所有可用的配置项及其说明这对于探索Zephyr的强大功能至关重要。5. 调试、问题排查与经验之谈开发不可能一帆风顺。以下是几个高频问题点和我的排查经验。5.1 串口打印调试信息Blinky只能看灯更复杂的调试需要输出日志。Zephyr默认使用串口UART作为控制台输出。硬件连接将STM32F103C8T6的PA9 (TX) 和PA10 (RX) 通过USB转TTL模块连接到电脑。软件配置在prj.conf中启用串口和控制台CONFIG_SERIALy CONFIG_CONSOLEy CONFIG_UART_CONSOLEy # 对于STM32F1通常使用USART1 CONFIG_UART_1y代码中使用在main.c中#include zephyr/kernel.h和#include zephyr/sys/printk.h然后就可以用printk(“Hello Zephyr!\n”);打印信息了。电脑端查看使用串口调试助手如Putty、SecureCRT、或者VSCode的串口监视器插件选择正确的COM口波特率通常设置为115200。5.2 内存不足与配置优化STM32F103C8T6只有64KB Flash和20KB RAM资源紧张。编译后留意终端输出的内存占用报告。如果接近或超出限制优化prj.conf关掉不需要的功能。例如如果不调试可以关闭CONFIG_DEBUG如果不用浮点数可以关掉CONFIG_FPU。使用west build -t menuconfig可以打开一个图形化配置界面更方便地裁剪模块。编译器优化在prj.conf中设置CONFIG_SIZE_OPTIMIZATIONSy可以开启尺寸优化。检查代码避免使用大的全局数组谨慎使用递归和动态内存分配malloc。5.3 烧录后程序不运行如果west flash成功但板子没反应LED不闪检查启动模式确保BOOT0引脚通过跳线帽接地Boot from Main Flash。这是最常见的原因。检查复位电路有些最小系统板复位电路设计或元件有问题尝试手动按一下复位键。检查时钟配置Zephyr的bluepill板型配置默认使用内部HSI时钟8MHz。如果你的板子外部接了8MHz晶振配置通常是正确的。如果接了其他频率的晶振可能需要修改设备树dts文件这属于进阶内容。验证二进制文件用west build -t rom_report可以查看编译出的固件各部分在Flash中的布局确认入口地址正确。5.4 关于国产替代芯片搜索热词里有“stm32f103c8t6国产替代”。像GD32F103、APM32F103等Pin-to-Pin兼容芯片理论上可以尝试使用相同的bluepill配置因为内核相同。但存在风险Flash/RAM大小可能不同需要修改设备树中的内存定义。外设寄存器地址或行为可能有细微差异可能导致驱动不工作。最稳妥的做法在Zephyr的boards/arm/目录下复制一份bluepill板型定义重命名为你的国产芯片板子名如my_gd32_pill然后根据芯片数据手册仔细修改dts设备树源文件和Kconfig.defconfig中的相关配置。这是一个需要耐心对照手册和源码的过程。整个过程走下来你会发现用VSCode开发Zephyr项目核心是把几个关键路径和环境变量配通。一旦配通其代码编辑的流畅度、项目管理的清晰度相比传统IDE有很大提升。对于STM32F103C8T6这类资源有限的板子Zephyr提供了精细的配置能力让你能真正掌控每一字节的Flash和RAM。建议你先从blinky和hello_world串口打印这两个最基础的示例跑通建立起“编辑-构建-烧录-观察”的闭环信心然后再逐步探索更复杂的驱动和子系统。遇到问题多查看build目录下的zephyr/.config文件它是由prj.conf生成的最终配置以及编译输出的警告和错误信息它们通常比想象中更有帮助。