最近在尝试使用 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或者编译时提示找不到设备。其根本原因通常是设备树中该外设的status属性被设置为“disabled”默认未启用。应用程序的配置文件prj.conf没有启用对应的驱动CONFIG_选项。在代码中引用了错误的设备树节点标签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 中。更新系统并安装依赖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获取 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安装 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 --reload3.2 在 VSCode 中配置 Zephyr 插件VSCode 的 Zephyr IDE 插件能极大提升开发体验提供智能提示、构建、烧录等功能。打开 VSCode进入扩展市场。搜索并安装Zephyr IDE插件由zephyrproject-rtos发布。安装后按下CtrlShiftP打开命令面板输入Zephyr: Setup。插件会引导你设置 Zephyr 基目录~/zephyrproject和工具链路径通常 SDK 安装后会自动设置好。3.3 创建你的第一个 Zephyr 应用我们不在zephyrproject目录内直接开发。按照最佳实践在外部创建一个独立的应用目录。# 在 home 目录或其他位置创建项目文件夹 mkdir -p ~/my_zephyr_apps/blinky_f103 cd ~/my_zephyr_apps/blinky_f103一个最简化的 Zephyr 应用需要以下三个文件src/main.c 应用程序源代码。CMakeLists.txt 告诉 CMake 如何构建你的应用。prj.conf Kconfig 配置文件用于启用/禁用内核和驱动特性。我们先创建文件结构并填写基础内容mkdir src touch src/main.c CMakeLists.txt prj.confCMakeLists.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_GPIOy # 启用日志输出方便调试 CONFIG_LOGy # 为了简化先使用最小化内核配置 CONFIG_MINIMAL_LIBCysrc/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 通过“板型”来组织针对特定开发板的设备树和配置文件。我们需要找到最接近我们板子的定义。查找现有板型定义# 在 Zephyr 源码目录中搜索 cd ~/zephyrproject/zephyr find . -name “*.dts” -type f | grep -i stm32f103 | head -10你会发现类似./boards/arm/stm32f103c8t6_minimal/或./boards/arm/bluepill/的目录。bluepill板型就是针对 STM32F103C8T6 最小系统板的它更常用。查看设备树定义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_GPIOy # 启用日志 CONFIG_LOGy CONFIG_LOG_PRINTKy # 启用硬件时钟STM32需要 CONFIG_CLOCK_CONTROLy CONFIG_CLOCK_CONTROL_STM32_CUBEy # 启用引脚控制驱动 CONFIG_PINCTRLy CONFIG_PINCTRL_STM32y4.4 构建与烧录一切就绪现在可以编译并将程序烧录到板子上了。使用 west 构建 在项目目录 (~/my_zephyr_apps/blinky_f103) 下打开终端执行west build -b bluepill ./-b bluepill 指定目标板型为bluepill。./ 源代码在当前目录。 如果一切顺利会在当前目录下生成build文件夹里面包含编译出的zephyr.elf,zephyr.bin,zephyr.hex等文件。连接硬件用 USB 线将 ST-Link V2 调试器连接到电脑。ST-Link 的 SWDIO、SWCLK、GND、3.3V 分别连接到 STM32F103C8T6 的对应引脚。给最小系统板上电。使用 west 烧录west flashwest flash命令会自动调用 OpenOCD 或 pyOCD通过 ST-Link 将程序烧录到芯片中。看到终端提示成功并且板载 LED 开始闪烁就大功告成了查看日志可选 如果你的串口连接正确PA9/PA10还可以查看日志输出west flash --runnerpyocd # 或者使用 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)); } }这种方法的好处编译期检查#if DT_NODE_HAS_STATUS会在编译时检查设备树中led0节点是否存在且状态为okay。如果板型不支持直接报错避免运行时才发现问题。效率更高DEVICE_DT_GET在编译时就解析出设备地址无需运行时进行字符串查找。不依赖label 直接使用节点标识符即使设备树节点没有label属性也能工作。6. 常见问题与排查思路在实践过程中你可能会遇到以下问题。这里提供一个排查清单问题现象可能原因排查步骤与解决方案west build失败提示找不到板型1. 板型名称拼写错误。2. 使用的 Zephyr 版本不支持该板型。1. 运行west boards查看所有支持的板型列表确认bluepill是否存在。2. 检查boards/arm/目录下是否有bluepill文件夹。west flash失败提示No CMSIS-DAP device found或Cannot connect to target1. 调试器ST-Link未连接或驱动问题。2. 接线错误SWDIO, SWCLK, GND。3. 板子未上电或复位引脚被拉低。1. 运行lsusb(Linux) 检查是否有 ST-Link 设备。2. 确认接线正确尤其是 GND 共地。3. 尝试给板子复位后再烧录。4. 尝试使用west flash –runneropenocd指定不同的烧录工具。程序运行但 LED 不闪烁1. 设备获取失败 (led_dev为NULL)。2. GPIO 引脚配置错误。3. 设备树中 LED 引脚定义与实际板子不符。1. 检查日志输出看是否有Failed to get LED device错误。2. 确认prj.conf中CONFIG_GPIOy已启用。3. 查阅你的具体板子原理图确认 LED 连接引脚。修改设备树覆盖文件或直接修改代码中的引脚号。device_get_binding返回NULL1. 传入的字符串与设备树label不匹配。2. 对应的驱动未在prj.conf中启用。3. 设备树中该节点status “disabled”;。1. 仔细核对设备树文件.dts中节点的label属性值大小写敏感。2. 确保prj.conf启用了必要的驱动如CONFIG_UARTy对于串口。3. 查看设备树确保节点状态是okay。可以创建项目级的设备树覆盖文件boards/bluepill.overlay来修改或启用节点。编译警告__device_dts_ord_XX未定义使用了DEVICE_DT_GET但对应的设备树节点未启用或驱动未编译。1. 确认prj.conf启用了对应驱动。2. 确认设备树节点存在且status “okay”;。3. 使用DT_NODE_HAS_STATUS宏做好编译保护。7. 最佳实践与工程建议掌握了基础操作后遵循以下建议能让你的 Zephyr 开发更加顺畅和专业。使用设备树覆盖文件 不要直接修改 Zephyr 源码中的板型定义。对于自定义硬件修改如更换LED引脚应在你的项目目录下创建boards/文件夹里面放置设备树覆盖文件。例如在项目根目录创建boards/bluepill.overlay内容如下将 LED 改到 PA1 引脚led0 { gpios gpioa 1 GPIO_ACTIVE_LOW; };这样修改是局部的不会影响其他项目。善用prj.conf和 Kconfigprj.conf用于启用基础驱动和内核特性。对于复杂的配置可以使用Kconfig文件定义自己的配置选项。使用menuconfig进行可视化配置west build -t menuconfig。模块化与代码组织将不同外设的初始化、操作封装到独立的.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); }调试与日志充分利用CONFIG_LOG和LOG_*宏进行分级日志输出。对于复杂问题可以启用CONFIG_DEBUG和CONFIG_ASSERT。使用west debug启动 GDB 进行源码级调试。版本控制将你的应用代码、自定义的boards/文件、prj.conf等纳入 Git 管理。在README.md中清晰说明依赖的 Zephyr 版本和板型。通过本文的梳理你应该已经掌握了在 VSCode 环境下为 STM32F103C8T6 最小系统板开发 Zephyr 应用的核心流程特别是如何正确获取和操作device。从理解设备树概念到环境搭建、项目创建、代码编写、构建烧录再到问题排查和最佳实践形成了一个完整的闭环。接下来你可以尝试用同样的方法去操作 UART、I2C、SPI 等其他外设将它们对应的device获取并运用起来从而构建更复杂的嵌入式应用。
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或者编译时提示找不到设备。其根本原因通常是设备树中该外设的status属性被设置为“disabled”默认未启用。应用程序的配置文件prj.conf没有启用对应的驱动CONFIG_选项。在代码中引用了错误的设备树节点标签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 中。更新系统并安装依赖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获取 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安装 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 --reload3.2 在 VSCode 中配置 Zephyr 插件VSCode 的 Zephyr IDE 插件能极大提升开发体验提供智能提示、构建、烧录等功能。打开 VSCode进入扩展市场。搜索并安装Zephyr IDE插件由zephyrproject-rtos发布。安装后按下CtrlShiftP打开命令面板输入Zephyr: Setup。插件会引导你设置 Zephyr 基目录~/zephyrproject和工具链路径通常 SDK 安装后会自动设置好。3.3 创建你的第一个 Zephyr 应用我们不在zephyrproject目录内直接开发。按照最佳实践在外部创建一个独立的应用目录。# 在 home 目录或其他位置创建项目文件夹 mkdir -p ~/my_zephyr_apps/blinky_f103 cd ~/my_zephyr_apps/blinky_f103一个最简化的 Zephyr 应用需要以下三个文件src/main.c 应用程序源代码。CMakeLists.txt 告诉 CMake 如何构建你的应用。prj.conf Kconfig 配置文件用于启用/禁用内核和驱动特性。我们先创建文件结构并填写基础内容mkdir src touch src/main.c CMakeLists.txt prj.confCMakeLists.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_GPIOy # 启用日志输出方便调试 CONFIG_LOGy # 为了简化先使用最小化内核配置 CONFIG_MINIMAL_LIBCysrc/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 通过“板型”来组织针对特定开发板的设备树和配置文件。我们需要找到最接近我们板子的定义。查找现有板型定义# 在 Zephyr 源码目录中搜索 cd ~/zephyrproject/zephyr find . -name “*.dts” -type f | grep -i stm32f103 | head -10你会发现类似./boards/arm/stm32f103c8t6_minimal/或./boards/arm/bluepill/的目录。bluepill板型就是针对 STM32F103C8T6 最小系统板的它更常用。查看设备树定义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_GPIOy # 启用日志 CONFIG_LOGy CONFIG_LOG_PRINTKy # 启用硬件时钟STM32需要 CONFIG_CLOCK_CONTROLy CONFIG_CLOCK_CONTROL_STM32_CUBEy # 启用引脚控制驱动 CONFIG_PINCTRLy CONFIG_PINCTRL_STM32y4.4 构建与烧录一切就绪现在可以编译并将程序烧录到板子上了。使用 west 构建 在项目目录 (~/my_zephyr_apps/blinky_f103) 下打开终端执行west build -b bluepill ./-b bluepill 指定目标板型为bluepill。./ 源代码在当前目录。 如果一切顺利会在当前目录下生成build文件夹里面包含编译出的zephyr.elf,zephyr.bin,zephyr.hex等文件。连接硬件用 USB 线将 ST-Link V2 调试器连接到电脑。ST-Link 的 SWDIO、SWCLK、GND、3.3V 分别连接到 STM32F103C8T6 的对应引脚。给最小系统板上电。使用 west 烧录west flashwest flash命令会自动调用 OpenOCD 或 pyOCD通过 ST-Link 将程序烧录到芯片中。看到终端提示成功并且板载 LED 开始闪烁就大功告成了查看日志可选 如果你的串口连接正确PA9/PA10还可以查看日志输出west flash --runnerpyocd # 或者使用 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)); } }这种方法的好处编译期检查#if DT_NODE_HAS_STATUS会在编译时检查设备树中led0节点是否存在且状态为okay。如果板型不支持直接报错避免运行时才发现问题。效率更高DEVICE_DT_GET在编译时就解析出设备地址无需运行时进行字符串查找。不依赖label 直接使用节点标识符即使设备树节点没有label属性也能工作。6. 常见问题与排查思路在实践过程中你可能会遇到以下问题。这里提供一个排查清单问题现象可能原因排查步骤与解决方案west build失败提示找不到板型1. 板型名称拼写错误。2. 使用的 Zephyr 版本不支持该板型。1. 运行west boards查看所有支持的板型列表确认bluepill是否存在。2. 检查boards/arm/目录下是否有bluepill文件夹。west flash失败提示No CMSIS-DAP device found或Cannot connect to target1. 调试器ST-Link未连接或驱动问题。2. 接线错误SWDIO, SWCLK, GND。3. 板子未上电或复位引脚被拉低。1. 运行lsusb(Linux) 检查是否有 ST-Link 设备。2. 确认接线正确尤其是 GND 共地。3. 尝试给板子复位后再烧录。4. 尝试使用west flash –runneropenocd指定不同的烧录工具。程序运行但 LED 不闪烁1. 设备获取失败 (led_dev为NULL)。2. GPIO 引脚配置错误。3. 设备树中 LED 引脚定义与实际板子不符。1. 检查日志输出看是否有Failed to get LED device错误。2. 确认prj.conf中CONFIG_GPIOy已启用。3. 查阅你的具体板子原理图确认 LED 连接引脚。修改设备树覆盖文件或直接修改代码中的引脚号。device_get_binding返回NULL1. 传入的字符串与设备树label不匹配。2. 对应的驱动未在prj.conf中启用。3. 设备树中该节点status “disabled”;。1. 仔细核对设备树文件.dts中节点的label属性值大小写敏感。2. 确保prj.conf启用了必要的驱动如CONFIG_UARTy对于串口。3. 查看设备树确保节点状态是okay。可以创建项目级的设备树覆盖文件boards/bluepill.overlay来修改或启用节点。编译警告__device_dts_ord_XX未定义使用了DEVICE_DT_GET但对应的设备树节点未启用或驱动未编译。1. 确认prj.conf启用了对应驱动。2. 确认设备树节点存在且status “okay”;。3. 使用DT_NODE_HAS_STATUS宏做好编译保护。7. 最佳实践与工程建议掌握了基础操作后遵循以下建议能让你的 Zephyr 开发更加顺畅和专业。使用设备树覆盖文件 不要直接修改 Zephyr 源码中的板型定义。对于自定义硬件修改如更换LED引脚应在你的项目目录下创建boards/文件夹里面放置设备树覆盖文件。例如在项目根目录创建boards/bluepill.overlay内容如下将 LED 改到 PA1 引脚led0 { gpios gpioa 1 GPIO_ACTIVE_LOW; };这样修改是局部的不会影响其他项目。善用prj.conf和 Kconfigprj.conf用于启用基础驱动和内核特性。对于复杂的配置可以使用Kconfig文件定义自己的配置选项。使用menuconfig进行可视化配置west build -t menuconfig。模块化与代码组织将不同外设的初始化、操作封装到独立的.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); }调试与日志充分利用CONFIG_LOG和LOG_*宏进行分级日志输出。对于复杂问题可以启用CONFIG_DEBUG和CONFIG_ASSERT。使用west debug启动 GDB 进行源码级调试。版本控制将你的应用代码、自定义的boards/文件、prj.conf等纳入 Git 管理。在README.md中清晰说明依赖的 Zephyr 版本和板型。通过本文的梳理你应该已经掌握了在 VSCode 环境下为 STM32F103C8T6 最小系统板开发 Zephyr 应用的核心流程特别是如何正确获取和操作device。从理解设备树概念到环境搭建、项目创建、代码编写、构建烧录再到问题排查和最佳实践形成了一个完整的闭环。接下来你可以尝试用同样的方法去操作 UART、I2C、SPI 等其他外设将它们对应的device获取并运用起来从而构建更复杂的嵌入式应用。
