大家好我是專注于嵌入式開發(fā)的技術(shù)博主。最近在嘗試將 Zephyr RTOS 應(yīng)用到 STM32F103C8T6 這款經(jīng)典的“藍色藥丸”最小系統(tǒng)板上時發(fā)現(xiàn)很多教程要么環(huán)境搭建不全要么編譯過程報錯不斷特別是配合 VSCode 進行開發(fā)時配置更是讓人頭疼。本文將為你梳理一套從零開始、手把手式的完整流程涵蓋 Zephyr 環(huán)境搭建、VSCode 配置、項目編譯、燒錄與調(diào)試的全過程。無論你是剛接觸 Zephyr 的新手還是想將現(xiàn)有 Keil 項目遷移到更現(xiàn)代的 VSCode Zephyr 開發(fā)流這篇文章都能提供清晰的指引和可復現(xiàn)的代碼示例。1. 背景與核心概念在深入實操之前我們有必要厘清幾個核心概念這能幫助你理解我們正在構(gòu)建的整個技術(shù)棧。1.1 什么是 Zephyr RTOSZephyr 是一款由 Linux 基金會托管的、開源、可擴展的實時操作系統(tǒng)RTOS。它專為資源受限的嵌入式設(shè)備設(shè)計支持超過 450 款開發(fā)板和 30 多種架構(gòu)包括 ARM Cortex-M如 STM32、RISC-V、Xtensa 等。與 FreeRTOS、uC/OS 等傳統(tǒng) RTOS 相比Zephyr 的特點在于其高度模塊化、強大的配置系統(tǒng)基于 Kconfig 和 Devicetree以及活躍的社區(qū)生態(tài)。它不僅僅是一個內(nèi)核更是一個完整的 SDK提供了豐富的組件如文件系統(tǒng)、網(wǎng)絡(luò)協(xié)議棧包括 LwM2M、CoAP、藍牙協(xié)議棧等非常適合物聯(lián)網(wǎng)IoT設(shè)備的開發(fā)。1.2 為什么選擇 VSCode Zephyr傳統(tǒng)的嵌入式開發(fā)往往依賴于 Keil MDK、IAR 等商業(yè) IDE。這些工具功能強大但通常價格昂貴且跨平臺支持有限。VSCode 作為一個免費、開源、跨平臺的代碼編輯器憑借其海量的插件生態(tài)和強大的可定制性已成為現(xiàn)代開發(fā)者的首選。將 Zephyr 與 VSCode 結(jié)合可以帶來以下優(yōu)勢統(tǒng)一的開發(fā)體驗在 Windows、Linux、macOS 上使用相同的工具鏈。強大的代碼智能感知通過 C/C 插件獲得代碼補全、跳轉(zhuǎn)、錯誤檢查等功能。集成化的構(gòu)建與調(diào)試可以直接在 VSCode 內(nèi)調(diào)用 Zephyr 的構(gòu)建系統(tǒng)West進行編譯并通過 Cortex-Debug 等插件進行圖形化調(diào)試。版本控制友好VSCode 與 Git 深度集成方便代碼管理。1.3 目標硬件STM32F103C8T6 最小系統(tǒng)板STM32F103C8T6 基于 ARM Cortex-M3 內(nèi)核主頻 72MHz擁有 64KB Flash 和 20KB RAM因其極高的性價比和豐富的資源常被稱為“藍色藥丸”是學習 STM32 和嵌入式開發(fā)的經(jīng)典入門型號。我們將以此板卡為目標演示如何運行一個基礎(chǔ)的 Zephyr 應(yīng)用如閃爍 LED。2. 環(huán)境準備與版本說明搭建一個穩(wěn)定可用的 Zephyr 開發(fā)環(huán)境是成功的第一步。以下步驟在 Windows 10/11 系統(tǒng)上驗證通過同樣適用于 Linux 和 macOS命令略有不同。2.1 安裝必備工具Zephyr 的開發(fā)依賴一系列工具我們使用官方推薦的安裝方式。1. 安裝 Python 3.8 或更高版本Zephyr 的工具鏈如 West由 Python 編寫。請從 Python官網(wǎng) 下載并安裝。務(wù)必在安裝時勾選 “Add Python to PATH”。2. 安裝 Git用于獲取 Zephyr 源代碼。從 Git官網(wǎng) 下載安裝。3. 安裝 WestWest 是 Zephyr 的元工具用于管理多個倉庫Manifest和執(zhí)行構(gòu)建、燒錄等命令。在命令行中執(zhí)行pip install west安裝完成后運行west --version確認安裝成功。4. 獲取 Zephyr 源代碼并安裝 Python 依賴選擇一個合適的目錄路徑不要有中文或空格執(zhí)行以下命令。這里我們使用官方 Manifest它定義了 Zephyr 項目及其所有模塊。# 初始化 west 工作區(qū)并克隆 manifest 倉庫 west init zephyrproject # 進入工作區(qū)目錄 cd zephyrproject # 拉取 Zephyr 源碼及所有模塊 west update # 導出 Zephyr 的 CMake 包使得在其他目錄也能找到 Zephyr west zephyr-export # 安裝 Zephyr 所需的 Python 依賴包 pip install -r zephyr/scripts/requirements.txt這個過程會下載大量文件請保持網(wǎng)絡(luò)通暢。5. 安裝工具鏈Zephyr 需要針對目標架構(gòu)的編譯器。對于 ARM Cortex-MSTM32我們安裝 GNU Arm Embedded Toolchain。Windows: 下載 gcc-arm-none-eabi 安裝包并安裝。建議安裝到C:\Program Files\Arm GNU Toolchain arm-none-eabi這類簡單路徑。Linux/macOS: 通常可以通過包管理器安裝如sudo apt install gcc-arm-none-eabi(Ubuntu)。安裝后需要將工具鏈的bin目錄添加到系統(tǒng)的PATH環(huán)境變量中。例如Windows 下路徑可能是C:\Program Files\Arm GNU Toolchain arm-none-eabi\13.2.rel1\bin。6. 安裝 CMake 和 NinjaCMake 是 Zephyr 的構(gòu)建系統(tǒng)生成器Ninja 是構(gòu)建后端。Windows: 從 CMake官網(wǎng) 下載安裝包安裝時選擇“為所有用戶添加 CMake 到系統(tǒng) PATH”。Ninja 可以從 其 GitHub 發(fā)布頁 下載ninja-win.zip解壓后將ninja.exe所在目錄也加入PATH。Linux/macOS:sudo apt install cmake ninja-build(Ubuntu)。2.2 安裝并配置 VSCode從 VSCode官網(wǎng) 下載并安裝。安裝以下必備擴展C/C(ms-vscode.cpptools): 提供代碼智能感知、調(diào)試支持。CMake Tools(ms-vscode.cmake-tools): 集成 CMake 構(gòu)建、配置、調(diào)試。Cortex-Debug(marus25.cortex-debug): 用于 ARM Cortex-M 芯片的圖形化調(diào)試。(可選)Zephyr IDE(zephyr.zephyr-ide): 提供 Zephyr Kconfig 和 Devicetree 的語法高亮和預(yù)覽。3. 創(chuàng)建并構(gòu)建第一個 Zephyr 項目環(huán)境就緒后我們開始創(chuàng)建第一個項目。Zephyr 提供了豐富的示例Samples我們從最簡單的blinkyLED 閃爍開始。3.1 創(chuàng)建項目工作區(qū)我們不直接在zephyrproject目錄下開發(fā)而是創(chuàng)建一個獨立的應(yīng)用目錄這樣更清晰。# 假設(shè)在 D:\ 盤根目錄 mkdir d:\my_zephyr_app cd d:\my_zephyr_app3.2 初始化應(yīng)用程序Zephyr 應(yīng)用需要遵循固定的目錄結(jié)構(gòu)。最簡單的方式是復制一個示例。# 將 zephyr 的 blinky 示例復制到當前目錄的 app 文件夾下 cp -r %ZEPHYR_BASE%\samples\basic\blinky app # 注意%ZEPHYR_BASE% 是環(huán)境變量指向 zephyrproject\zephyr。如果未設(shè)置請使用絕對路徑例如 # cp -r d:\zephyrproject\zephyr\samples\basic\blinky app現(xiàn)在你的my_zephyr_app目錄下有一個app文件夾里面就是blinky示例的源碼。3.3 為 STM32F103C8T6 配置項目默認的blinky示例可能不是針對 STM32F103C8T6 的。我們需要創(chuàng)建一個構(gòu)建配置。創(chuàng)建build目錄并進入mkdir build cd build使用 CMake 配置項目 我們需要告訴 CMake 我們的目標硬件和工具鏈。通過-DBOARD參數(shù)指定板型。STM32F103C8T6 最小系統(tǒng)板在 Zephyr 中對應(yīng)的板型名稱通常是nucleo_f103rb因為引腳兼容或者更通用的stm32f103c8t6如果社區(qū)有支持。我們以nucleo_f103rb為例它被廣泛支持。# 在 build 目錄下執(zhí)行 cmake -GNinja -DBOARDnucleo_f103rb ..\app-GNinja: 指定生成 Ninja 構(gòu)建文件。-DBOARDnucleo_f103rb: 設(shè)置目標板。..\app: 指定 CMakeLists.txt 所在的源目錄上一級的 app 文件夾。執(zhí)行成功后會在build目錄下生成一系列文件包括zephyr/.config(Kconfig 配置) 和zephyr/include/generated/(Devicetree 生成頭文件)。構(gòu)建項目 配置完成后使用 Ninja 進行編譯。ninja如果一切順利你將看到編譯進度最后輸出類似[100%] Linking C executable zephyr\zephyr.elf和[100%] Built target zephyr_final的信息。編譯產(chǎn)物位于build\zephyr目錄下最重要的文件是zephyr.hex、zephyr.bin和zephyr.elf。4. 在 VSCode 中集成與優(yōu)化工作流命令行構(gòu)建雖然強大但在 VSCode 中集成可以極大提升效率。4.1 使用 VSCode 打開項目用 VSCode 打開my_zephyr_app文件夾。4.2 配置 CMake Tools 擴展按下CtrlShiftP輸入 “CMake: Select a Kit”選擇你安裝的 GCC Arm 工具鏈例如 “GCC 13.2.1 arm-none-eabi”。再次按下CtrlShiftP輸入 “CMake: Select Variant”可以選擇Debug或Release。最后輸入 “CMake: Select Configure Preset”。如果沒有預(yù)設(shè)我們需要創(chuàng)建一個。在項目根目錄my_zephyr_app下創(chuàng)建.vscode/settings.json文件并添加 CMake 配置預(yù)設(shè){ cmake.configureSettings: { BOARD: nucleo_f103rb }, cmake.sourceDirectory: ${workspaceFolder}/app, cmake.buildDirectory: ${workspaceFolder}/build, cmake.generator: Ninja, cmake.configureArgs: [ -GNinja ] }現(xiàn)在你可以點擊 VSCode 底部狀態(tài)欄的 “Build” 按鈕或按F7來編譯項目效果與命令行運行ninja相同。輸出窗口會顯示構(gòu)建日志。4.3 配置調(diào)試環(huán)境調(diào)試是開發(fā)的關(guān)鍵。我們需要配置 Cortex-Debug 插件。確定調(diào)試探頭STM32F103C8T6 最小系統(tǒng)板通常通過 ST-LINK 或 J-Link 進行調(diào)試。這里以最常見的 ST-LINK 為例。安裝 OpenOCDOpenOCD 是開源的片上調(diào)試器。從 OpenOCD 官方 或 xPack 項目 下載 Windows 版本并解壓將其bin目錄加入PATH。創(chuàng)建調(diào)試配置在 VSCode 中切換到“運行和調(diào)試”視圖CtrlShiftD點擊“創(chuàng)建 launch.json 文件”選擇 “Cortex-Debug”。這會在.vscode文件夾下生成launch.json。修改其內(nèi)容如下{ version: 0.2.0, configurations: [ { name: Cortex Debug (ST-LINK), cwd: ${workspaceRoot}, executable: ${workspaceFolder}/build/zephyr/zephyr.elf, request: launch, type: cortex-debug, servertype: openocd, serverpath: C:/path/to/your/openocd/bin/openocd.exe, // 修改為你的 OpenOCD 路徑 interface: swd, device: STM32F103C8, configFiles: [ interface/stlink.cfg, target/stm32f1x.cfg ], runToEntryPoint: main, svdFile: ${workspaceFolder}/zephyrproject/zephyr/dts/arm/st/stm32f103.svd // SVD文件用于查看外設(shè)寄存器 } ] }關(guān)鍵是要修改serverpath和svdFile的路徑為你的實際路徑。device設(shè)置為STM32F103C8。configFiles指定了 OpenOCD 使用的配置文件用于識別 ST-LINK 接口和 STM32F1 系列目標。開始調(diào)試連接好 ST-LINK 和板子給板子上電。在 VSCode 中按F5或點擊綠色的調(diào)試按鈕Cortex-Debug 將啟動 OpenOCD連接目標板加載程序并停在main函數(shù)入口。你可以設(shè)置斷點、單步執(zhí)行、查看變量和寄存器。5. 適配自定義板型與引腳如果你的板子 LED 連接的不是nucleo_f103rb默認的引腳或者你使用的是純粹的 STM32F103C8T6 最小系統(tǒng)板就需要修改 Devicetree 覆蓋文件來匹配硬件。5.1 查找 LED 引腳查看你的板子原理圖找到 LED 連接的 GPIO 引腳。例如假設(shè) LED 陽極通過電阻連接到PC13陰極接地這是很多“藍色藥丸”板的接法。5.2 創(chuàng)建板級支持文件在app目錄下創(chuàng)建一個板級定義覆蓋目錄結(jié)構(gòu)并添加 Devicetree 覆蓋文件。# 在 app 目錄下 mkdir -p boards/arm/my_f103_board在boards/arm/my_f103_board目錄下創(chuàng)建兩個文件1.my_f103_board.dts定義板級硬件。/dts-v1/; #include st/f1/stm32f103Xb.dtsi #include st/f1/stm32f103c(8-b)tx-pinctrl.dtsi #include zephyr/dt-bindings/gpio/gpio.h / { model My Custom STM32F103C8T6 Board; compatible mycompany,my-f103-board; chosen { zephyr,console usart1; zephyr,shell-uart usart1; zephyr,sram sram0; zephyr,flash flash0; }; leds { compatible gpio-leds; led0: led_0 { gpios gpioc 13 GPIO_ACTIVE_HIGH; label User LED; }; }; aliases { led0 led0; }; }; usart1 { current-speed 115200; pinctrl-0 usart1_tx_pa9 usart1_rx_pa10; pinctrl-names default; status okay; }; usart2 { current-speed 115200; pinctrl-0 usart2_tx_pa2 usart2_rx_pa3; pinctrl-names default; status okay; };這個文件定義了板子模型、兼容性字符串并將led0映射到了GPIOC的第 13 引腳并配置了 USART1 用于控制臺輸出。2.my_f103_board.yaml板級定義元數(shù)據(jù)。identifier: my_f103_board name: My Custom F103 Board type: mcu arch: arm toolchain: - zephyr - gnuarmemb - xtools ram: 20 flash: 64 supported: - arduino_gpio - arduino_i2c - arduino_spi - uart - gpio - i2c - spi5.3 修改應(yīng)用源碼以使用自定義板現(xiàn)在修改app/src/main.c確保它使用我們定義的 LED 別名。#include zephyr/kernel.h #include zephyr/drivers/gpio.h /* 1000 msec 1 sec */ #define SLEEP_TIME_MS 1000 /* 使用設(shè)備樹中的 led0 別名獲取 LED 設(shè)備 */ static const struct gpio_dt_spec led GPIO_DT_SPEC_GET(DT_ALIAS(led0), gpios); void main(void) { int ret; // 檢查 LED 設(shè)備是否就緒 if (!gpio_is_ready_dt(led)) { return; } // 將 LED 引腳配置為輸出并初始化為低電平熄滅 ret gpio_pin_configure_dt(led, GPIO_OUTPUT_ACTIVE); if (ret 0) { return; } while (1) { // 翻轉(zhuǎn) LED 狀態(tài) ret gpio_pin_toggle_dt(led); if (ret 0) { return; } k_msleep(SLEEP_TIME_MS); } }5.4 使用自定義板型構(gòu)建在構(gòu)建時指定我們自定義的板型。# 在 build 目錄下先清空或新建一個build目錄 rm -rf * cmake -GNinja -DBOARDmy_f103_board ..\app ninja這樣編譯出的固件就會使用PC13來控制 LED。6. 燒錄與運行編譯成功后我們需要將zephyr.bin或zephyr.hex文件燒錄到開發(fā)板。6.1 使用 West 命令燒錄West 提供了便捷的燒錄命令它會自動調(diào)用合適的工具如 OpenOCD。# 在 build 目錄下 west flashwest flash會嘗試自動檢測調(diào)試探頭和板型。對于 ST-LINK 和nucleo_f103rb或我們自定義的板型如果配置了正確的燒錄器它通常能直接工作。如果失敗可能需要檢查 OpenOCD 安裝和連接。6.2 使用 STM32CubeProgrammer 或 pyOCDSTM32CubeProgrammerST 官方工具圖形化界面支持 ST-LINK 和 UART 等多種方式連接。pyOCD一個基于 Python 的 ARM Cortex-M 調(diào)試器?？梢酝ㄟ^pip install pyocd安裝然后使用pyocd flash build/zephyr/zephyr.bin --target stm32f103c8命令燒錄。燒錄完成后復位開發(fā)板你應(yīng)該能看到 LED 開始閃爍。7. 常見問題與排查思路在搭建和開發(fā)過程中你可能會遇到以下問題問題現(xiàn)象可能原因排查步驟與解決方案west init或west update失敗網(wǎng)絡(luò)錯誤網(wǎng)絡(luò)連接問題或 Git 倉庫地址訪問慢1. 檢查網(wǎng)絡(luò)。2. 嘗試使用代理。3. 可以手動修改zephyrproject/.west/config中的url-base使用國內(nèi)鏡像如 Gitee 鏡像需注意鏡像可能滯后。cmake配置時找不到編譯器或工具鏈1. 工具鏈未安裝。2. 工具鏈路徑未添加到PATH。3. 環(huán)境變量未生效。1. 運行arm-none-eabi-gcc --version確認工具鏈可用。2. 在命令行中檢查PATH是否包含工具鏈的bin目錄。3. 重啟命令行終端或 VSCode。4. 在 CMake 配置時通過-DCMAKE_C_COMPILER和-DCMAKE_CXX_COMPILER直接指定編譯器絕對路徑。ninja編譯失敗提示No such file or directory或undefined reference1. 源碼路徑錯誤。2. 依賴的 Zephyr 模塊未正確拉取。3. Kconfig 配置沖突。1. 確認cmake命令指向的源目錄正確。2. 在zephyrproject目錄下重新運行west update。3. 清除build目錄重新配置和構(gòu)建。4. 檢查build/zephyr/.config文件確保必要的配置如CONFIG_GPIOy已啟用。west flash失敗無法連接目標1. 調(diào)試器ST-LINK驅(qū)動未安裝或連接不穩(wěn)。2. OpenOCD 配置錯誤。3. 板子未上電或 Boot 引腳設(shè)置錯誤。1. 安裝 ST-LINK 驅(qū)動STSW-LINK009。2. 檢查 USB 連接嘗試重新插拔。3. 使用openocd -f interface/stlink.cfg -f target/stm32f1x.cfg命令單獨測試 OpenOCD 連接。4. 確認板子 Boot0 引腳已接地從主Flash啟動。程序已燒錄但 LED 不閃爍1. LED 引腳定義與實際硬件不符。2. 程序未正常運行時鐘、初始化問題。3. LED 極性高電平有效/低電平有效配置錯誤。1. 核對原理圖確認 LED 連接引腳并檢查 Devicetree 中的gpios屬性。2. 嘗試使用調(diào)試器單步執(zhí)行看程序是否卡在某個初始化函數(shù)。3. 將GPIO_ACTIVE_HIGH改為GPIO_ACTIVE_LOW或反之。4. 使用邏輯分析儀或萬用表測量引腳電平。VSCode 智能感知報錯找不到頭文件VSCode 的 C/C 插件未正確配置includePath和defines。1. 使用 CMake Tools 插件配置項目后通常會自動生成c_cpp_properties.json。2. 可以手動在.vscode/c_cpp_properties.json中配置將build目錄下的compile_commands.json路徑添加到compileCommands字段。這是最準確的方式。編譯出的固件大小遠超芯片 Flash 容量未啟用優(yōu)化或包含了不必要的組件。1. 使用-DCONFIG_SIZE_OPTIMIZATIONSy或-DCONFIG_NO_OPTIMIZATIONSn進行編譯優(yōu)化。2. 通過menuconfig(west build -t menuconfig) 圖形化界面關(guān)閉不需要的模塊如文件系統(tǒng)、網(wǎng)絡(luò)棧。8. 最佳實踐與工程建議掌握了基礎(chǔ)流程后遵循以下最佳實踐能讓你的 Zephyr 開發(fā)更加高效和穩(wěn)健。版本控制將你的應(yīng)用代碼app目錄納入 Git 管理。但通常不建議將龐大的zephyrproject倉庫全部提交?？梢允褂?gitignore忽略build目錄和zephyrproject通過west manifest文件來鎖定 Zephyr 版本。管理多個應(yīng)用使用 West 的多倉庫管理能力。你可以在zephyrproject目錄外創(chuàng)建一個west.yml清單文件將你的應(yīng)用倉庫也作為 West 的一個模塊管理方便依賴和版本同步。充分利用 Kconfig 和 DevicetreeKconfig用于軟件功能配置。使用west build -t menuconfig可以打開一個圖形化界面來配置內(nèi)核、驅(qū)動、協(xié)議棧等選項。配置結(jié)果保存在build/zephyr/.config。對于項目特定的配置可以在應(yīng)用目錄下創(chuàng)建prj.conf文件。Devicetree用于描述硬件。將板級硬件描述如 LED、按鍵、傳感器接口放在板級目錄boards/下的.dts文件中實現(xiàn)硬件與軟件的解耦。模塊化應(yīng)用設(shè)計將不同的功能模塊放在單獨的源文件中并利用 Zephyr 的設(shè)備驅(qū)動模型。通過DEVICE_DT_DEFINE來定義和初始化設(shè)備使用gpio_dt_spec等結(jié)構(gòu)體來傳遞設(shè)備樹信息使代碼更清晰、可移植。日志與調(diào)試積極使用 Zephyr 的日志系統(tǒng)#include zephyr/logging/log.h。通過設(shè)置不同的日志級別LOG_LEVEL_DBG,LOG_LEVEL_INF等可以在開發(fā)時輸出詳細信息而在生產(chǎn)時減少輸出。配合串口控制臺是排查問題的重要手段。電源管理對于電池供電的 IoT 設(shè)備務(wù)必關(guān)注電源管理。Zephyr 提供了電源管理框架允許在空閑時進入低功耗模式如 STOP、SLEEP。在prj.conf中啟用CONFIG_PMy并合理配置。測試Zephyr 支持單元測試Twister和硬件測試。對于關(guān)鍵驅(qū)動和模塊編寫單元測試是保證長期穩(wěn)定性的好習慣?？梢允褂脀est build -t run來在模擬器如 QEMU上運行測試。生產(chǎn)固件處理在發(fā)布固件前考慮啟用鏈接時優(yōu)化LTO、刪除調(diào)試符號、并可能需要對固件進行簽名或加密。使用west sign命令和 Zephyr 的 MCUboot 引導加載程序可以支持安全啟動和固件升級。通過本文的步驟你應(yīng)該已經(jīng)成功在 STM32F103C8T6 上運行了 Zephyr并在 VSCode 中建立了一個舒適的開發(fā)環(huán)境。這套組合為你打開了現(xiàn)代嵌入式開發(fā)的大門無論是學習 RTOS 概念還是開發(fā)實際的 IoT 產(chǎn)品原型都是一個強大的起點。接下來你可以探索 Zephyr 提供的更多示例如傳感器驅(qū)動、藍牙通信、文件系統(tǒng)等逐步構(gòu)建更復雜的應(yīng)用。如果在實踐中遇到新的問題Zephyr 的官方文檔和活躍的社區(qū)如 Discord、GitHub Discussions是尋求幫助的好地方。