Zephyr RTOS开发中device字段配置与STM32F103C8T6实战指南

最近在尝试使用 VSCode 配合 Zephyr RTOS 开发 STM32F103C8T6 最小系统板时，发现很多开发者，包括我自己，都卡在了如何正确获取和配置device字段这个环节。网上资料要么过于零散，要么直接跳过了这个关键步骤，导致编译失败、下载器无法识别设备等问题频发。本文将围绕这个核心痛点，为你拆解一套从环境搭建、项目创建、device字段获取到最终烧录运行的全流程闭环方案。无论你是刚接触 Zephyr 的新手，还是从 Keil/IAR 迁移过来的开发者，都能跟着本文一步步操作，彻底搞懂 Zephyr 项目中的设备树（Device Tree）和device结构体，让你的 STM32F103C8T6 在 VSCode 上成功跑起来。

1. 背景与核心概念：为什么需要device？

在开始动手之前，我们必须先理解 Zephyr RTOS 中device的概念及其重要性。这能帮你从根本上避免“盲人摸象”式的配置。

1.1 Zephyr 的设备驱动模型

Zephyr 采用了一种基于设备树（Device Tree）的硬件抽象层设计。简单来说，它把 MCU 的硬件资源（如 GPIO、UART、I2C 等外设）在编译时就用一种结构化的数据（设备树）描述清楚，而不是在运行时动态探测。

• 设备树（.dts文件）： 这是一个文本文件，以树状结构描述了硬件。例如，它定义了 STM32F103C8T6 有几个 UART、它们的基地址是什么、对应哪些引脚。Zephyr 为许多开发板提供了预定义的.dts文件。
• device结构体： 在应用程序代码中，你需要通过一个const struct device *类型的指针来访问一个具体的硬件外设。这个指针指向的device结构体，就是 Zephyr 内核根据设备树的描述，在编译时为你创建好的“设备对象”。你所有的驱动 API（如uart_poll_out,gpio_pin_set）都需要传入这个device指针来操作对应的硬件。

1.2 常见问题：No such device或NULL device

很多新手在写代码时，直接调用device_get_binding(“UART_1”)却返回NULL，或者编译时提示找不到设备。其根本原因通常是：

1. 设备树中该外设的status属性被设置为“disabled”（默认未启用）。
2. 应用程序的配置文件（prj.conf）没有启用对应的驱动（CONFIG_选项）。
3. 在代码中引用了错误的设备树节点标签（label）或兼容性字符串（compatible）。

理解了这些，我们就知道，正确开发 Zephyr 应用的关键一步，就是如何找到并启用你板子上那个具体外设所对应的device。接下来，我们将通过一个完整的 LED 闪烁案例来演示这个过程。

2. 环境准备与版本说明

工欲善其事，必先利其器。以下是我验证过的环境配置，强烈建议你保持一致以减少不必要的麻烦。

• 操作系统： Ubuntu 22.04 LTS (Windows 用户可使用 WSL2，步骤类似)
• 开发板： STM32F103C8T6 最小系统板（核心是 Cortex-M3）
• 调试器： ST-Link V2 (或兼容的 DAPLink 等)
• Zephyr RTOS 版本： v3.6.0 (LTS 版本，相对稳定)
• 工具链： Zephyr SDK 0.16.5 (包含了编译所需的 GCC 和 OpenOCD)
• IDE/编辑器： Visual Studio Code (VSCode) + 官方 Zephyr IDE 插件
• 项目管理工具： West (Zephyr 的元工具)

版本一致性提醒： Zephyr 更新较快，不同版本在设备树命名、API 上可能有细微差别。本文以 v3.6.0 为例，如果你使用其他版本，请以官方文档为准，但核心思路不变。

3. 基础环境搭建与项目创建

3.1 安装 Zephyr 开发环境

首先，我们需要安装 Zephyr 的核心环境。假设你已经在 Ubuntu/WSL2 中。

1. 更新系统并安装依赖：

   sudo apt update sudo apt upgrade 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 libmagic1

2. 获取 Zephyr 源码并安装 Python 依赖：

   # 使用 west 获取 Zephyr 源码和所有模块 west init ~/zephyrproject cd ~/zephyrproject west update # 导出 Zephyr CMake 包 west zephyr-export # 安装 Python 依赖 pip3 install --user -r ~/zephyrproject/zephyr/scripts/requirements.txt

3. 安装 Zephyr SDK：

   # 下载 SDK 安装脚本 cd /tmp wget https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v0.16.5/zephyr-sdk-0.16.5_linux-x86_64.tar.xz wget -O - https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v0.16.5/sha256.sum | shasum --check --ignore-missing # 解压并安装 tar xvf zephyr-sdk-0.16.5_linux-x86_64.tar.xz cd zephyr-sdk-0.16.5 ./setup.sh # 安装 udev 规则，让普通用户能访问调试器 sudo cp ~/zephyr-sdk-0.16.5/sysroots/x86_64-pokysdk-linux/usr/share/openocd/contrib/60-openocd.rules /etc/udev/rules.d/ sudo udevadm control --reload

3.2 在 VSCode 中配置 Zephyr 插件

VSCode 的 Zephyr IDE 插件能极大提升开发体验，提供智能提示、构建、烧录等功能。

1. 打开 VSCode，进入扩展市场。
2. 搜索并安装Zephyr IDE插件（由zephyrproject-rtos发布）。
3. 安装后，按下Ctrl+Shift+P打开命令面板，输入Zephyr: Setup。
4. 插件会引导你设置 Zephyr 基目录（~/zephyrproject）和工具链路径（通常 SDK 安装后会自动设置好）。

3.3 创建你的第一个 Zephyr 应用

我们不在zephyrproject目录内直接开发。按照最佳实践，在外部创建一个独立的应用目录。

# 在 home 目录或其他位置创建项目文件夹 mkdir -p ~/my_zephyr_apps/blinky_f103 cd ~/my_zephyr_apps/blinky_f103

一个最简化的 Zephyr 应用需要以下三个文件：

1. src/main.c： 应用程序源代码。
2. CMakeLists.txt： 告诉 CMake 如何构建你的应用。
3. prj.conf： Kconfig 配置文件，用于启用/禁用内核和驱动特性。

我们先创建文件结构并填写基础内容：

mkdir src touch src/main.c CMakeLists.txt prj.conf

CMakeLists.txt内容：

# 指定所需的最低 CMake 版本 cmake_minimum_required(VERSION 3.20.0) # 将当前目录添加到构建系统，并命名为 APP_DIR find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE}) project(blinky) # 将 src 目录下的源文件添加到构建目标 target_sources(app PRIVATE src/main.c)

prj.conf初始内容（我们先启用最基础的配置）：

# 启用 GPIO 驱动（控制LED需要） CONFIG_GPIO=y # 启用日志输出，方便调试 CONFIG_LOG=y # 为了简化，先使用最小化内核配置 CONFIG_MINIMAL_LIBC=y

src/main.c初始内容：

#include <zephyr/kernel.h> #include <zephyr/logging/log.h> // 定义日志模块 LOG_MODULE_REGISTER(main, LOG_LEVEL_DBG); void main(void) { LOG_INF(“Hello Zephyr on STM32F103C8T6!”); while (1) { // 稍后在这里添加LED闪烁代码 k_sleep(K_SECONDS(1)); } }

4. 核心实战：获取并控制 LED 对应的device

现在进入最关键的部分：如何找到并操作板载 LED。STM32F103C8T6 最小系统板通常有一颗连接在 PC13 引脚上的 LED（低电平点亮）。

4.1 确定板型（Board）与设备树

Zephyr 通过“板型”来组织针对特定开发板的设备树和配置文件。我们需要找到最接近我们板子的定义。

1. 查找现有板型定义：

   # 在 Zephyr 源码目录中搜索 cd ~/zephyrproject/zephyr find . -name “*.dts” -type f | grep -i stm32f103 | head -10

   你会发现类似./boards/arm/stm32f103c8t6_minimal/或./boards/arm/bluepill/的目录。bluepill板型就是针对 STM32F103C8T6 最小系统板的，它更常用。

2. 查看设备树定义：

   cat ./boards/arm/bluepill/bluepill.dts

   你会看到类似以下内容（已简化）：

   / { model = “Blue Pill STM32F103C8T6”; compatible = “st,stm32f103c8”; // ... 其他定义 leds { compatible = “gpio-leds”; led0: led_0 { gpios = <&gpioc 13 GPIO_ACTIVE_LOW>; label = “User LED”; }; }; // ... 其他节点 };

   关键信息提取：

   • led0是一个节点标签。
   • label = “User LED”;这就是我们在代码中可以通过device_get_binding查找的字符串。
   • gpios = <&gpioc 13 GPIO_ACTIVE_LOW>;表示 LED 连接在 GPIOC 的第 13 脚，低电平有效。

4.2 在应用中获取 LED 设备

现在，我们修改src/main.c来获取这个 LED 设备并控制它。

#include <zephyr/kernel.h> #include <zephyr/drivers/gpio.h> // 引入 GPIO 驱动头文件 #include <zephyr/logging/log.h> LOG_MODULE_REGISTER(main, LOG_LEVEL_DBG); // 定义 LED 设备的指针 static const struct device *led_dev; // 根据设备树定义，LED 引脚号是 13 static const gpio_pin_t led_pin = 13; void main(void) { int ret; LOG_INF(“Application started.”); // 关键步骤1：通过设备树中的 label 获取设备指针 led_dev = device_get_binding(DT_LABEL(DT_ALIAS(led0))); // 注意：在 Zephyr v3.6+，更推荐使用 DEVICE_DT_GET 宏 // 但 device_get_binding 对于理解原理更直观 if (led_dev == NULL) { LOG_ERR(“Failed to get LED device binding.”); return; } LOG_INF(“Found LED device: %s”, led_dev->name); // 关键步骤2：配置 GPIO 引脚为输出模式 ret = gpio_pin_configure(led_dev, led_pin, GPIO_OUTPUT_ACTIVE); if (ret < 0) { LOG_ERR(“Failed to configure GPIO pin: %d”, ret); return; } // 关键步骤3：控制 LED 闪烁 bool led_state = true; while (1) { ret = gpio_pin_set(led_dev, led_pin, (int)led_state); if (ret < 0) { LOG_ERR(“Failed to set GPIO pin: %d”, ret); } led_state = !led_state; LOG_INF(“LED state: %s”, led_state ? “ON” : “OFF”); k_sleep(K_MSEC(500)); // 延时 500 毫秒 } }

代码解析：

• device_get_binding(DT_LABEL(DT_ALIAS(led0)))： 这是获取设备的传统方式。DT_ALIAS(led0)获取设备树中led0这个别名的节点标识符，DT_LABEL再从中提取出label属性（即“User LED”），最后用这个字符串去查找设备。
• 更现代的方式： Zephyr 新版本推荐使用DEVICE_DT_GET(DT_ALIAS(led0))宏，它直接在编译时获取设备指针，效率更高，且不需要label属性。我们将稍后介绍。
• gpio_pin_configure和gpio_pin_set是标准的 Zephyr GPIO 驱动 API，需要传入我们获取到的led_dev。

4.3 更新配置文件并指定板型

为了让构建系统知道我们为哪个板子编译，以及启用必要的驱动，需要更新prj.conf并使用 west 命令指定板型。

更新prj.conf：

# 启用 GPIO 驱动 CONFIG_GPIO=y # 启用日志 CONFIG_LOG=y CONFIG_LOG_PRINTK=y # 启用硬件时钟（STM32需要） CONFIG_CLOCK_CONTROL=y CONFIG_CLOCK_CONTROL_STM32_CUBE=y # 启用引脚控制驱动 CONFIG_PINCTRL=y CONFIG_PINCTRL_STM32=y

4.4 构建与烧录

一切就绪，现在可以编译并将程序烧录到板子上了。

1. 使用 west 构建： 在项目目录 (~/my_zephyr_apps/blinky_f103) 下打开终端，执行：

   west build -b bluepill ./

   • -b bluepill： 指定目标板型为bluepill。
   • ./： 源代码在当前目录。 如果一切顺利，会在当前目录下生成build文件夹，里面包含编译出的zephyr.elf,zephyr.bin,zephyr.hex等文件。

2. 连接硬件：

   • 用 USB 线将 ST-Link V2 调试器连接到电脑。
   • ST-Link 的 SWDIO、SWCLK、GND、3.3V 分别连接到 STM32F103C8T6 的对应引脚。
   • 给最小系统板上电。

3. 使用 west 烧录：

   west flash

   west flash命令会自动调用 OpenOCD 或 pyOCD，通过 ST-Link 将程序烧录到芯片中。看到终端提示成功，并且板载 LED 开始闪烁，就大功告成了！

4. 查看日志（可选）： 如果你的串口连接正确（PA9/PA10），还可以查看日志输出：

   west flash --runner=pyocd # 或者使用 openocd # 在另一个终端，使用 screen 或 minicom 查看串口 sudo screen /dev/ttyACM0 115200

   你应该能看到”Application started.”和”LED state: ON/OFF”的交替输出。

5. 深入理解：DEVICE_DT_GET与现代设备获取方式

上面的例子使用了device_get_binding，这是为了理解设备与标签的绑定关系。在实际新项目中，Zephyr 更推荐使用设备树依赖（Device Tree dependencies）和DEVICE_DT_GET宏，它更安全、高效，且不依赖字符串比较。

改进后的src/main.c：

#include <zephyr/kernel.h> #include <zephyr/drivers/gpio.h> #include <zephyr/logging/log.h> #include <zephyr/devicetree.h> // 引入设备树头文件 LOG_MODULE_REGISTER(main, LOG_LEVEL_DBG); // 使用设备树宏直接获取 LED 设备节点 #define LED0_NODE DT_ALIAS(led0) // 编译时检查该节点是否存在且状态为 okay #if DT_NODE_HAS_STATUS(LED0_NODE, okay) // 使用 DEVICE_DT_GET 在编译时获取设备指针 static const struct device *const led_dev = DEVICE_DT_GET(LED0_NODE); #else #error “Unsupported board: led0 alias is not defined” static const struct device *led_dev; #endif // 直接从设备树节点获取引脚号 static const gpio_pin_t led_pin = DT_GPIO_PIN(LED0_NODE, gpios); void main(void) { int ret; LOG_INF(“Application started (using DT macros).”); // 检查设备是否已准备就绪（驱动初始化成功） if (!device_is_ready(led_dev)) { LOG_ERR(“LED device %s is not ready”, led_dev->name); return; } LOG_INF(“Found and ready LED device: %s”, led_dev->name); ret = gpio_pin_configure(led_dev, led_pin, GPIO_OUTPUT_ACTIVE); if (ret < 0) { LOG_ERR(“Failed to configure GPIO pin: %d”, ret); return; } bool led_state = true; while (1) { gpio_pin_set(led_dev, led_pin, (int)led_state); led_state = !led_state; k_sleep(K_MSEC(500)); } }

这种方法的好处：

1. 编译期检查：#if DT_NODE_HAS_STATUS会在编译时检查设备树中led0节点是否存在且状态为okay。如果板型不支持，直接报错，避免运行时才发现问题。
2. 效率更高：DEVICE_DT_GET在编译时就解析出设备地址，无需运行时进行字符串查找。
3. 不依赖label： 直接使用节点标识符，即使设备树节点没有label属性也能工作。

6. 常见问题与排查思路

在实践过程中，你可能会遇到以下问题。这里提供一个排查清单：

7. 最佳实践与工程建议

掌握了基础操作后，遵循以下建议能让你的 Zephyr 开发更加顺畅和专业。

1. 使用设备树覆盖文件： 不要直接修改 Zephyr 源码中的板型定义。对于自定义硬件修改（如更换LED引脚），应在你的项目目录下创建boards/文件夹，里面放置设备树覆盖文件。

   • 例如，在项目根目录创建：boards/bluepill.overlay
   • 内容如下，将 LED 改到 PA1 引脚：

     &led0 { gpios = <&gpioa 1 GPIO_ACTIVE_LOW>; };

   这样修改是局部的，不会影响其他项目。

2. 善用prj.conf和 Kconfig`：

   • prj.conf用于启用基础驱动和内核特性。
   • 对于复杂的配置，可以使用Kconfig文件定义自己的配置选项。
   • 使用menuconfig进行可视化配置：west build -t menuconfig。

3. 模块化与代码组织：

   • 将不同外设的初始化、操作封装到独立的.c/.h文件中去。
   • 使用 Zephyr 的SYS_INIT宏在启动早期初始化设备。
   • 例如，创建一个led.c：

     // led.h #ifndef LED_H #define LED_H int led_init(void); int led_toggle(void); #endif // led.c #include “led.h” #include <zephyr/drivers/gpio.h> #include <zephyr/devicetree.h> static const struct device *const led_dev = DEVICE_DT_GET(DT_ALIAS(led0)); static bool led_is_on; int led_init(void) { if (!device_is_ready(led_dev)) { return -ENODEV; } // ... 配置引脚 return 0; } int led_toggle(void) { led_is_on = !led_is_on; return gpio_pin_set(led_dev, DT_GPIO_PIN(DT_ALIAS(led0), gpios), led_is_on); }

4. 调试与日志：

   • 充分利用CONFIG_LOG和LOG_*宏进行分级日志输出。
   • 对于复杂问题，可以启用CONFIG_DEBUG和CONFIG_ASSERT。
   • 使用west debug启动 GDB 进行源码级调试。

5. 版本控制：

   • 将你的应用代码、自定义的boards/文件、prj.conf等纳入 Git 管理。
   • 在README.md中清晰说明依赖的 Zephyr 版本和板型。

通过本文的梳理，你应该已经掌握了在 VSCode 环境下，为 STM32F103C8T6 最小系统板开发 Zephyr 应用的核心流程，特别是如何正确获取和操作device。从理解设备树概念，到环境搭建、项目创建、代码编写、构建烧录，再到问题排查和最佳实践，形成了一个完整的闭环。接下来，你可以尝试用同样的方法去操作 UART、I2C、SPI 等其他外设，将它们对应的device获取并运用起来，从而构建更复杂的嵌入式应用。