在嵌入式开发领域Zephyr RTOS 作为一款开源、可扩展的实时操作系统近年来在物联网和边缘计算项目中应用越来越广泛。很多开发者在使用 STM32F103C8T6 这类经典 MCU 时希望借助 Zephyr 的强大功能却往往在环境搭建和项目创建阶段遇到各种问题。本文将基于 STM32F103C8T6 最小系统板完整演示 Zephyr 项目创建和环境验证的全流程帮助开发者快速上手这一强大的嵌入式开发平台。1. Zephyr RTOS 与 STM32F103C8T6 核心板介绍1.1 Zephyr RTOS 概述Zephyr 是一款由 Linux 基金会托管的开源实时操作系统专为资源受限的嵌入式设备设计。它支持多种架构包括 ARM、x86、RISC-V 等提供了完整的操作系统功能如多线程、内存管理、设备驱动和丰富的协议栈。Zephyr 的主要特点包括高度模块化设计可根据需求裁剪功能支持多种开发板和 SOC提供完整的电源管理功能内置丰富的网络协议栈BLE、Wi-Fi、TCP/IP 等强大的配置系统 Kconfig完善的设备树支持1.2 STM32F103C8T6 最小系统板特性STM32F103C8T6 是基于 ARM Cortex-M3 内核的微控制器因其性价比高、资源丰富而广受欢迎。最小系统板通常包含以下核心部件STM32F103C8T6 主芯片64KB Flash20KB RAM8MHz 外部晶振和 32.768kHz RTC 晶振复位电路和电源电路BOOT0 和 BOOT1 选择跳线所有 GPIO 引出的排针接口该开发板特别适合学习 Zephyr因为 Zephyr 对 STM32 系列有很好的支持社区资源丰富调试工具链成熟。1.3 开发环境需求分析在进行 Zephyr 开发前需要准备以下软硬件环境主机系统Windows、Linux 或 macOS开发板STM32F103C8T6 最小系统板调试器ST-Link V2 或兼容调试器串口工具用于调试信息输出足够的磁盘空间Zephyr 及其工具链需要约 5-10GB2. 开发环境搭建2.1 安装 Zephyr SDKZephyr SDK 包含了编译、调试和烧录所需的全部工具。以下以 Ubuntu 20.04 为例演示安装过程# 下载最新版 Zephyr SDK wget https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v0.16.0/zephyr-sdk-0.16.0_linux-x86_64.tar.xz # 解压到指定目录 tar xvf zephyr-sdk-0.16.0_linux-x86_64.tar.xz -C ~/ # 运行安装脚本 cd ~/zephyr-sdk-0.16.0 ./setup.sh # 同意许可协议选择安装路径对于 Windows 用户可以使用 Chocolatey 安装choco install zephyr-sdk或者手动下载 Windows 版本的 SDK 安装包。2.2 获取 Zephyr 源码Zephyr 的源码托管在 GitHub 上使用 west 工具进行管理# 安装 west 工具 pip3 install west # 初始化 Zephyr 项目 west init ~/zephyrproject cd ~/zephyrproject west update # 导出 Zephyr 环境变量 source zephyr/zephyr-env.sh2.3 安装 Python 依赖Zephyr 构建系统依赖多个 Python 包# 安装必需的 Python 包 pip3 install -r ~/zephyrproject/zephyr/scripts/requirements.txt # 对于开发建议安装额外工具 pip3 install pyocd intelhex2.4 配置工具链路径确保工具链正确配置检查环境变量# 检查工具链版本 arm-zephyr-eabi-gcc --version # 设置环境变量可添加到 ~/.bashrc export ZEPHYR_TOOLCHAIN_VARIANTzephyr export ZEPHYR_SDK_INSTALL_DIR~/zephyr-sdk-0.16.03. 创建第一个 Zephyr 项目3.1 项目结构规划一个标准的 Zephyr 项目应包含以下结构my_zephyr_app/ ├── CMakeLists.txt ├── prj.conf ├── src/ │ └── main.c ├── boards/ │ └── stm32f103c8t6.overlay └── README.rst3.2 创建项目基础文件首先创建项目目录和基础文件# 创建项目目录 mkdir -p ~/workspace/my_zephyr_app/src cd ~/workspace/my_zephyr_app创建 CMakeLists.txt 文件# CMakeLists.txt cmake_minimum_required(VERSION 3.20.0) find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE}) project(my_zephyr_app) target_sources(app PRIVATE src/main.c)创建项目配置文件 prj.conf# prj.conf - 基础配置 CONFIG_GPIOy CONFIG_SERIALy CONFIG_UART_CONSOLEy CONFIG_PRINTKy CONFIG_STDOUT_CONSOLEy # 启用调试输出 CONFIG_DEBUGy CONFIG_LOGy CONFIG_LOG_MODE_IMMEDIATEy3.3 编写主程序代码创建 src/main.c 文件#include zephyr/kernel.h #include zephyr/device.h #include zephyr/drivers/gpio.h #include zephyr/sys/printk.h /* 定义 LED 引脚 - 根据实际板子连接调整 */ #define LED0_NODE DT_ALIAS(led0) static const struct gpio_dt_spec led GPIO_DT_SPEC_GET(LED0_NODE, gpios); void main(void) { int ret; printk(Zephyr Blinky Example started\n); /* 检查设备是否就绪 */ if (!device_is_ready(led.port)) { printk(Error: LED device is not ready\n); return; } /* 配置 LED 引脚为输出 */ ret gpio_pin_configure_dt(led, GPIO_OUTPUT_ACTIVE); if (ret 0) { printk(Error configuring LED pin: %d\n, ret); return; } while (1) { /* 切换 LED 状态 */ ret gpio_pin_toggle_dt(led); if (ret 0) { printk(Error toggling LED: %d\n, ret); return; } /* 延时 1 秒 */ k_msleep(1000); printk(LED toggled\n); } }3.4 创建设备树覆盖文件对于 STM32F103C8T6需要创建 boards/stm32f103c8t6.overlay 文件/dts-v1/; /plugin/; #include dt-bindings/gpio/gpio.h / { chosen { zephyr,console usart1; zephyr,shell-uart usart1; }; aliases { led0 led0; }; leds { compatible gpio-leds; led0: led_0 { gpios gpioa 5 GPIO_ACTIVE_HIGH; label User LED; }; }; }; usart1 { current-speed 115200; status okay; };4. 项目构建与编译4.1 配置构建环境在项目根目录下执行构建配置# 创建构建目录 mkdir build cd build # 配置项目指定开发板 cmake -DBOARDstm32f103c8t6 .. # 开始编译 make -j$(nproc)4.2 编译输出分析编译成功后会生成以下重要文件zephyr/zephyr.elf - 可调试的 ELF 文件zephyr/zephyr.bin - 二进制烧录文件zephyr/zephyr.hex - HEX 格式烧录文件检查编译输出信息确保没有警告和错误# 检查编译结果 ls -la zephyr/*.elf zephyr/*.bin # 查看固件大小 arm-zephyr-eabi-size zephyr/zephyr.elf4.3 编译优化配置根据需求调整编译选项在 prj.conf 中添加优化配置# 优化配置 CONFIG_SIZE_OPTIMIZATIONSy CONFIG_COMPILER_OPT-Os # 调试信息开发阶段启用 CONFIG_DEBUG_OPTIMIZATIONSy CONFIG_DEBUG_THREAD_INFOy5. 烧录与调试5.1 连接硬件设备将 STM32F103C8T6 开发板通过 ST-Link 连接到电脑连接 ST-Link 的 SWD 接口SWDIO、SWCLK、GND连接串口PA9/TX、PA10/RX用于调试输出确保供电正常3.3V5.2 使用 west 工具烧录Zephyr 推荐使用 west 工具进行烧录# 进入构建目录 cd build # 烧录固件 west flash # 如果自动检测失败手动指定 runner west flash --runner stm32cubeprogrammer5.3 使用 OpenOCD 烧录作为备选方案可以使用 OpenOCD# 启动 OpenOCD 服务 openocd -f interface/stlink.cfg -f target/stm32f1x.cfg # 在新终端中连接并烧录 telnet localhost 4444 program zephyr/zephyr.elf verify reset exit5.4 串口调试输出连接串口工具查看程序输出# Linux 下使用 minicom minicom -D /dev/ttyUSB0 -b 115200 # Windows 下使用 Putty 或 Tera Term # 端口COMx波特率115200预期看到类似输出*** Booting Zephyr OS build v3.4.0 *** Zephyr Blinky Example started LED toggled LED toggled ...6. 环境验证测试6.1 基础功能验证创建测试程序验证核心功能// src/test_main.c #include zephyr/kernel.h #include zephyr/sys/printk.h #include zephyr/drivers/gpio.h #include zephyr/drivers/uart.h void test_uart_output(void) { printk(UART Test: Hello from Zephyr!\n); printk(System clock: %d Hz\n, CONFIG_SYS_CLOCK_HW_CYCLES_PER_SEC); } void test_led_blink(void) { const struct device *gpio_dev DEVICE_DT_GET(DT_NODELABEL(gpioa)); if (!device_is_ready(gpio_dev)) { printk(GPIO device not ready\n); return; } gpio_pin_configure(gpio_dev, 5, GPIO_OUTPUT); for (int i 0; i 5; i) { gpio_pin_set(gpio_dev, 5, 1); k_msleep(200); gpio_pin_set(gpio_dev, 5, 0); k_msleep(200); } } void main(void) { k_msleep(1000); // 等待系统稳定 test_uart_output(); test_led_blink(); printk(Environment verification completed successfully!\n); while (1) { k_msleep(1000); } }6.2 外设功能测试创建更全面的测试程序验证各种外设// 外设测试配置 prj.conf CONFIG_GPIOy CONFIG_SERIALy CONFIG_I2Cy CONFIG_SPIy CONFIG_ADCy CONFIG_PWMy // 测试程序片段 void test_peripherals(void) { // GPIO 测试 test_gpio_functionality(); // UART 回环测试 test_uart_loopback(); // I2C 扫描测试 test_i2c_scan(); // 系统时钟测试 test_system_clock(); }7. 常见问题与解决方案7.1 编译阶段问题问题1CMake 配置错误CMake Error at CMakeLists.txt:2 (find_package): Could not find a package configuration file provided by Zephyr解决方案确保已正确设置 ZEPHYR_BASE 环境变量export ZEPHYR_BASE~/zephyrproject/zephyr source $ZEPHYR_BASE/zephyr-env.sh问题2工具链未找到arm-zephyr-eabi-gcc: command not found解决方案检查 Zephyr SDK 安装和路径配置export PATH~/zephyr-sdk-0.16.0/arm-zephyr-eabi/bin:$PATH7.2 烧录阶段问题问题3west flash 无法识别设备ERROR: Unable to find any supported devices解决方案检查 ST-Link 连接和驱动安装# 检查设备连接 lsusb | grep ST-Link # 安装 ST-Link 工具 sudo apt-get install stlink-tools问题4权限不足Error: unable to open /dev/ttyUSB0: Permission denied解决方案将用户添加到 dialout 组sudo usermod -a -G dialout $USER # 重新登录生效7.3 运行阶段问题问题5程序无法启动No output on serial port解决方案检查 BOOT0 引脚设置应设置为 0验证时钟配置问题6LED 不闪烁LED configured but not blinking解决方案检查设备树配置和实际硬件连接确认 GPIO 引脚定义正确8. 最佳实践与进阶配置8.1 项目组织规范建议的项目组织结构project/ ├── app/ # 应用程序代码 ├── drivers/ # 自定义驱动 ├── boards/ # 板级配置 ├── tests/ # 单元测试 ├── docs/ # 文档 └── scripts/ # 构建脚本8.2 配置管理策略使用 Kconfig 进行灵活的配置管理# Kconfig.app menu Application Configuration config APP_BLINK_PERIOD_MS int LED blink period in milliseconds default 1000 help Set the LED blink period in milliseconds. config APP_ENABLE_LOGGING bool Enable application logging default y help Enable debug logging output. endmenu在代码中使用配置#include zephyr/kernel.h #if defined(CONFIG_APP_ENABLE_LOGGING) #define APP_LOG printk #else #define APP_LOG(...) #endif void main(void) { APP_LOG(Application started\n); while (1) { gpio_pin_toggle(led_dev, LED_PIN); k_msleep(CONFIG_APP_BLINK_PERIOD_MS); } }8.3 调试技巧使用 Zephyr 的日志系统进行分级调试#include zephyr/logging/log.h LOG_MODULE_REGISTER(main, LOG_LEVEL_DBG); void debug_function(void) { LOG_DBG(Debug message); LOG_INF(Info message); LOG_WRN(Warning message); LOG_ERR(Error message); }配置日志级别# prj.conf CONFIG_LOGy CONFIG_LOG_DEFAULT_LEVEL4 # DEBUG level CONFIG_LOG_MODE_IMMEDIATEy8.4 电源管理优化对于电池供电设备启用电源管理# 电源管理配置 CONFIG_PMy CONFIG_PM_DEVICEy CONFIG_PM_DEVICE_RUNTIMEy # 低功耗模式 CONFIG_SYS_POWER_MANAGEMENTy CONFIG_SYS_POWER_LOW_POWER_STATEy通过本文的完整演示你应该已经成功创建了基于 STM32F103C8T6 的 Zephyr 项目并完成了环境验证。这套流程为后续更复杂的嵌入式应用开发奠定了坚实基础下一步可以尝试添加传感器驱动、网络通信或图形界面等高级功能。
