在嵌入式开发中，Zephyr RTOS 因其模块化、可扩展性和对多种架构的支持而受到关注。然而，对于初次接触 Zephyr 的开发者，尤其是在 VSCode 环境下，如何正确配置项目、获取并理解device字段，以及解决常见的“No Cortex-M SW Device Found”等连接问题，往往是一个不小的挑战。本文将以经典的 STM32F103C8T6 最小系统板为例，手把手演示如何在 VSCode 中搭建 Zephyr 开发环境，创建一个基础项目，并深入探讨device字段的获取方式及其在驱动开发中的核心作用。无论你是从传统 IDE（如 Keil、IAR）转向 Zephyr，还是希望将 Zephyr 应用于国产替代芯片（如 GD32），本文提供的环境配置、代码分析和排错路径都将为你提供清晰的指引。

1. 理解 Zephyr 中的 Device 模型与 STM32F103C8T6

在深入实操之前，必须理解 Zephyr 设备模型的核心概念，这决定了你如何与硬件交互。

1.1 Zephyr 设备模型：驱动与硬件的桥梁

Zephyr 的设备模型是一个抽象层，它将物理硬件（如 GPIO、I2C、UART）抽象为统一的“设备”对象。开发者通过操作这些设备对象来使用硬件，而无需直接读写寄存器。这种设计带来了驱动与硬件解耦、设备树配置、电源管理等好处。

一个设备在 Zephyr 中通常由以下几部分构成：

1. 设备树（Devicetree）定义：一个硬件描述文件（.dts），以文本形式描述板卡上的硬件资源（如哪个引脚是 LED，哪个串口连接了传感器）。Zephyr 在编译时根据此文件生成对应的 C 头文件。
2. 设备驱动（Driver）：实现设备操作（如初始化、读、写、控制）的软件模块。
3. 设备实例（Device Instance）：在运行时，Zephyr 内核会根据设备树信息和驱动，创建出一个device结构体实例。这个实例包含了配置信息、操作函数指针、状态等。

device字段，通常指的是指向这个struct device实例的指针。获取到这个指针，是调用所有设备 API（如gpio_pin_set，i2c_write）的第一步。

1.2 STM32F103C8T6 在 Zephyr 中的支持情况

STM32F103C8T6（Blue Pill 开发板常用芯片）基于 ARM Cortex-M3 内核。Zephyr 官方对其有良好的支持。你需要关注以下几点：

• SoC 系列：属于stm32f1系列。在 Zephyr 的设备树中，对应st,stm32f103c8。
• 外设支持：GPIO、USART、I2C、SPI、ADC 等常用外设驱动均已实现。
• 调试接口：通常使用 SWD（Serial Wire Debug）接口，通过 ST-LINK 或 J-Link 进行程序烧录和调试。

理解这些背景后，我们就能明白，后续在 VSCode 中配置项目、获取device，本质上是在正确配置 Zephyr 环境，使其能针对stm32f103c8这个目标生成正确的设备树和驱动代码。

2. VSCode 环境搭建与 Zephyr 项目初始化

一个稳定、高效的开发环境是成功的第一步。本节将详细说明从零开始搭建环境的全过程。

2.1 基础软件安装与配置

首先，确保你的开发主机（以 Windows 为例，Linux/macOS 类似）已安装以下必要软件：

1. VSCode：从官网下载并安装。建议安装以下关键插件：

   • C/C++(Microsoft)：提供代码智能感知、跳转、调试支持。
   • CMake Tools(Microsoft)：用于配置、构建 CMake 项目（Zephyr 使用 CMake）。
   • Zephyr IDE(Zephyr Project)：非必需，但能提供设备树语法高亮等便利。

2. Python 3.8+：Zephyr 的许多工具链脚本依赖 Python。安装时务必勾选“Add Python to PATH”。安装后，在终端运行python --version确认。

3. Git：用于克隆 Zephyr 源码和项目管理。

4. West 工具：这是 Zephyr 的元构建工具，用于管理多个代码仓库（Zephyr 本体、模块、你的应用等）。通过 pip 安装：

   pip install west

   安装后，运行west --version验证。

2.2 获取 Zephyr SDK 与源码

Zephyr SDK 包含了针对多种架构（包括 ARM Cortex-M）的交叉编译工具链、调试工具等。

1. 下载 Zephyr SDK：

   • 访问 Zephyr 官网的 SDK 下载页面。
   • 选择与你的操作系统匹配的最新版本安装包。对于 STM32F103，需要 ARM 工具链。
   • 运行安装程序，记住安装路径（例如C:\zephyr-sdk-0.16.0）。
   • 安装程序通常会询问是否将工具链添加到系统 PATH，建议选择“是”。

2. 初始化 West 并拉取源码： 打开一个终端（如 PowerShell 或 CMD），执行以下命令。选择一个合适的目录作为工作空间（例如C:\zephyrproject）。

   # 创建工作空间目录并进入 mkdir zephyrproject && cd zephyrproject # 使用 west 初始化仓库，拉取 Zephyr 主仓库及其所有模块 west init # 拉取所有模块代码（此步骤耗时较长，取决于网络） west update

   完成后，当前目录下会有zephyr文件夹，里面就是 Zephyr RTOS 的源代码。

3. 导出环境变量： 为了让后续命令能找到 Zephyr，需要设置两个关键环境变量。在终端中执行（请替换为你的实际路径）：

   # 设置 Zephyr 根目录 $env:ZEPHYR_BASE = "C:\zephyrproject\zephyr" # 运行 Zephyr 的环境设置脚本 & "$env:ZEPHYR_BASE\zephyr-env.cmd"

   注意：每次新开终端进行 Zephyr 开发前，都需要执行这两条命令。你可以将其写入 PowerShell 的 profile 脚本或创建批处理文件来简化操作。

2.3 创建第一个 Zephyr 应用项目

Zephyr 应用是一个独立的目录，包含你的源代码和配置文件，它依赖于ZEPHYR_BASE中的框架代码。

1. 创建应用目录结构： 在zephyrproject目录外，创建一个新的项目目录，例如my_zephyr_app。

   my_zephyr_app/ ├── CMakeLists.txt ├── prj.conf └── src/ └── main.c

2. 编写核心配置文件：

   • CMakeLists.txt：告诉构建系统这是一个 Zephyr 应用，并指定源文件。

     # 最低 CMake 版本要求 cmake_minimum_required(VERSION 3.20.0) # 查找 Zephyr 包。这行代码会引入所有 Zephyr 的构建规则。 find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE}) # 将你的源文件添加到项目中 project(my_zephyr_app) # 指定目标板（Board），这是最关键的一步 set(BOARD stm32f103c8_mini) # 或者 bluepill_f103c8，取决于你的板型定义 # 添加你的应用程序源文件 target_sources(app PRIVATE src/main.c)

   • prj.conf：项目的 Kconfig 配置文件，用于启用或禁用 Zephyr 内核和驱动的特定功能。

     # 启用 GPIO 驱动（我们将用它来控制 LED） CONFIG_GPIO=y # 启用串口控制台输出，便于调试 CONFIG_SERIAL=y CONFIG_UART_CONSOLE=y CONFIG_CONSOLE=y # 启用日志系统 CONFIG_LOG=y # 为节省资源，可以设置日志默认级别 CONFIG_LOG_DEFAULT_LEVEL=3

3. 编写代码：获取并使用 Device

现在，我们进入核心部分：在main.c中编写代码，获取device并操作硬件。

3.1 基础工程：获取 GPIO Device 并闪烁 LED

假设你的 STM32F103C8T6 最小系统板上，用户 LED 连接在 PC13 引脚（这是 Blue Pill 板的常见接法）。

1. 编写src/main.c：

   #include <zephyr/kernel.h> // 内核API，如睡眠函数 #include <zephyr/device.h> // 设备相关API #include <zephyr/drivers/gpio.h> // GPIO驱动API // 定义LED设备树节点标识符 // 这个标识符需要与你的板级设备树定义匹配。 // 对于 `stm32f103c8_mini` 或 `bluepill_f103c8`，LED0 通常被定义为 GPIOC_13。 #define LED0_NODE DT_ALIAS(led0) // 检查设备树中是否正确定义了 led0 别名 #if !DT_NODE_HAS_STATUS(LED0_NODE, okay) #error "Unsupported board: led0 devicetree alias is not defined" #endif // 从设备树节点获取对应的设备指针 // 这是获取 device 字段最核心、最推荐的方式 static const struct gpio_dt_spec led = GPIO_DT_SPEC_GET(LED0_NODE, gpios); void main(void) { int ret; // 1. 检查设备是否就绪 // 这是关键一步！驱动可能因为初始化失败或未编译而不可用。 if (!device_is_ready(led.port)) { printk("Error: LED device %s is not ready\n", led.port->name); return; } // 2. 配置GPIO引脚为输出模式，并初始化为低电平（LED灭） ret = gpio_pin_configure_dt(&led, GPIO_OUTPUT_INACTIVE); if (ret < 0) { printk("Error %d: failed to configure LED pin\n", ret); return; } printk("Blinking LED on %s pin %d\n", led.port->name, led.pin); // 3. 主循环，闪烁LED while (1) { // 设置引脚为高电平（LED亮） ret = gpio_pin_set_dt(&led, 1); if (ret < 0) { printk("Error %d: failed to set LED on\n", ret); break; } k_msleep(500); // 睡眠500毫秒 // 设置引脚为低电平（LED灭） ret = gpio_pin_set_dt(&led, 0); if (ret < 0) { printk("Error %d: failed to set LED off\n", ret); break; } k_msleep(500); } }

2. 代码详解：如何获取device：

   • DT_ALIAS(led0)：这是一个宏，用于从设备树中查找名为led0的“别名”（alias）所指向的实际节点。板级定义文件（如boards/arm/stm32f103c8_mini/stm32f103c8_mini.dts）中会定义类似/ { aliases { led0 = &gpioa_5; }; }的内容。
   • GPIO_DT_SPEC_GET(LED0_NODE, gpios)：这是另一个宏，它从给定的设备树节点（LED0_NODE）中提取gpios属性，并填充到一个gpio_dt_spec结构体中。这个结构体就包含了我们最需要的device指针（led.port）和引脚号（led.pin）。
   • device_is_ready(led.port)：至关重要。它检查驱动是否成功初始化并可用。如果返回false，通常意味着：
     • Kconfig 中未启用对应驱动（CONFIG_GPIO=y已设置）。
     • 设备树定义有误。
     • 驱动初始化失败（如时钟未配置）。

3.2 更通用的 Device 获取方式

除了通过设备树宏，有时你可能需要直接通过设备标签（label）或名称来获取设备。

1. 通过设备树标签（Label）获取： 如果设备树节点定义了label属性（例如my_uart: usart1@...，其中my_uart就是标签），你可以使用：

   const struct device *uart_dev = DEVICE_DT_GET(DT_NODELABEL(my_uart)); if (!device_is_ready(uart_dev)) { // 处理错误 }

2. 通过设备名称获取（不推荐）： 这是一种运行时查找的方式，效率较低，且依赖设备名称字符串。设备名称通常由驱动和实例号构成。

   const struct device *gpioa_dev = device_get_binding("GPIOA"); if (gpioa_dev == NULL) { // 处理错误：未找到名为 "GPIOA" 的设备 }

   注意：现代 Zephyr 开发强烈推荐使用基于设备树宏（DT_和*_DT_SPEC_GET）的方式，因为它在编译时就能检查节点是否存在，更安全、高效。

4. 构建、烧录与调试

代码写好后，需要在 VSCode 中构建并烧录到开发板。

4.1 使用 VSCode 与 CMake Tools 进行构建

1. 打开项目文件夹：在 VSCode 中，打开你的my_zephyr_app文件夹。
2. 配置 CMake Tools：
   • 确保已安装 “CMake Tools” 插件。
   • 按Ctrl+Shift+P打开命令面板，输入 “CMake: Configure”，选择它。
   • 首次配置时，会要求你选择一个“Kit”。选择你之前安装的 Zephyr SDK 中的工具链，通常名称包含 “Zephyr” 和 “arm-zephyr-eabi”。
   • 配置过程中，CMake 会读取CMakeLists.txt，设置BOARD变量，并生成构建目录（如build）。
3. 执行构建：
   • 配置成功后，在 VSCode 底部状态栏，可以看到构建目标（如[build]）和选择的板型（如stm32f103c8_mini）。
   • 点击状态栏的[Build]按钮，或按Ctrl+Shift+P执行 “CMake: Build”。构建输出会显示在终端中。

4.2 烧录程序到开发板

构建成功后，会在build目录下生成zephyr文件夹，里面包含zephyr.bin或zephyr.hex等镜像文件。

1. 硬件连接：使用 USB 转串口工具和 ST-LINK（或 J-LINK）调试器连接你的 STM32F103C8T6 最小系统板。确保连接了 SWDIO、SWCLK、GND，以及为板子供电。
2. 使用 West 命令烧录： 在 VSCode 的终端中，确保已设置好 Zephyr 环境变量，然后切换到你的应用目录，执行：

   west flash

   west flash命令会自动调用正确的烧录工具（如 openocd 或 pyocd）和脚本，将程序烧录到开发板。如果一切顺利，你将看到开发板上的 LED 开始闪烁。

4.3 查看串口输出

为了看到printk打印的日志，你需要连接串口。

1. 将 USB 转串口工具的 RX、TX、GND 分别连接到开发板的 PA9（TX）、PA10（RX）、GND。
2. 在电脑上使用串口终端工具（如 PuTTY、Tera Term、VSCode 的 Serial Monitor 插件），设置正确的串口号和波特率（Zephyr 默认通常是 115200）。
3. 复位开发板，你将在终端中看到 “Blinking LED on GPIOC pin 13” 的输出。

5. 常见问题排查与解决

在实际操作中，你几乎一定会遇到问题。以下是基于热搜词和常见错误的排查指南。

5.1 “No Cortex-M SW Device Found” 或 “Could not stop Cortex-M device”

这是调试器连接失败的最常见错误。

5.2 编译错误：未找到设备树节点或驱动

5.3 运行时错误：设备未就绪（Device Not Ready）

5.4 关于国产替代芯片（如 GD32）的说明

热搜词中提到了“stm32f103c8t6国产替代”和“zephyr在gd32的适用”。Zephyr 社区对许多国产 MCU 也有支持，但完善度可能不及 STM32。

• 可行性：GD32F103 系列与 STM32F103 引脚兼容，但内核和部分外设有差异。Zephyr 中可能有针对 GD32 的 SoC 支持文件。
• 操作步骤：
  1. 在west boards列表中查找是否有gd32f103c*相关的板型。
  2. 如果没有，你可能需要基于现有的 STM32F103 板型创建新的板级支持包（BSP），修改设备树和时钟配置。
  3. 关键点在于确保 Zephyr 的 HAL 层（drivers目录下）有对应 GD32 的驱动实现，或者确认其与 ST 的驱动兼容。
• 建议：初次接触 Zephyr，强烈建议使用官方支持良好的 STM32F103C8T6 完成整个流程。熟悉后再迁移到国产芯片，届时你需要仔细对比数据手册，并可能需要参与或借鉴社区移植工作。

6. 最佳实践与扩展方向

掌握了基础操作后，遵循以下实践能让你的 Zephyr 开发更顺畅。

6.1 设备操作最佳实践

1. 始终检查设备就绪状态：在调用任何设备操作函数前，使用device_is_ready()进行检查。这是防御性编程的关键。
2. 优先使用设备树（DT）宏：GPIO_DT_SPEC_GET、I2C_DT_SPEC_GET等宏是首选。它们提供编译时检查，避免运行时字符串查找的开销和错误。
3. 理解错误码：Zephyr API 通常返回0表示成功，负数表示错误码。查阅include/zephyr/errno.h或驱动头文件了解具体错误含义，不要忽略返回值。
4. 合理配置 Kconfig：在prj.conf或板级配置中，只启用项目需要的功能。过度启用驱动和特性会增加固件大小和内存占用。

6.2 项目结构与调试建议

1. 分离配置：对于复杂的项目，考虑使用boards目录下的板级覆盖文件（.overlay）来修改设备树，而不是直接修改应用代码。使用prj.conf、extra.conf等文件管理不同构建配置。
2. 善用日志：Zephyr 的日志系统非常强大。除了printk，可以使用LOG_MODULE_REGISTER和LOG_*系列宏进行模块化、分级别的日志记录。
3. 使用 VSCode 调试：配置launch.json文件，结合 CMake Tools 和 Cortex-Debug 插件，可以在 VSCode 内实现源码级单步调试、查看变量和寄存器，极大提升效率。

6.3 下一步学习方向

1. 深入设备树：学习.dts语法，理解如何为自定义硬件添加设备树节点和绑定（bindings）。
2. 探索更多驱动：尝试使用 I2C 驱动读取传感器（如 AS5600），使用 PWM 驱动控制电机，使用 ADC 驱动采集模拟量。
3. 内核特性：学习使用线程（Threads）、信号量（Semaphores）、消息队列（Queues）等 Zephyr 内核服务，构建多任务应用。
4. 电源管理：了解 Zephyr 的电源管理框架，为低功耗设备开发做准备。
5. 移植到新硬件：当你在现有板子上游刃有余后，可以尝试为一块新的、Zephyr 尚未支持的开发板创建 BSP，这是深入理解 Zephyr 架构的绝佳途径。

通过本文的步骤，你不仅能在 VSCode 中让 Zephyr 在 STM32F103C8T6 上运行起来，更重要的是理解了 Zephyr 设备模型的核心——如何安全、高效地获取和使用device字段。记住，从环境配置、编译构建到硬件调试，每一步的耐心验证和问题排查，都是嵌入式开发的常态。当你成功点亮第一个 LED 并看到串口日志时，你已经搭建起了通往更复杂 Zephyr 应用开发的坚实桥梁。