📚 课程目录第3章 Zephyr RTOS快速入门

3、Zephyr RTOS快速入门：Zephyr项目结构、开发环境搭建（west、toolchain）、编译与烧录流程

Zephyr RTOS 并非一个传统意义上的“裸机库”，而是一个高度模块化、构建系统驱动、面向多架构的实时操作系统。对于 TinyML 开发者而言，理解 Zephyr 的项目结构与环境搭建，是打通“模型训练”到“设备端推理”的关键桥梁。本章将围绕 Zephyr 的源码树布局、west 工作流、工具链配置以及编译烧录的完整链路展开，帮助你在 30 分钟内建立起一套可复用的嵌入式 AI 开发基线。

3.1 Zephyr 项目结构：从顶层到底层的模块化设计

Zephyr 的源码树并非一个简单的 Git 仓库，而是一个由 west manifest 管理的多仓库集合。这种设计使得 Zephyr 核心、可选模块（如 TensorFlow Lite Micro）、第三方库（如 CMSIS）能够独立演进，同时保持版本兼容性。理解这一结构是后续配置 TinyML 推理栈的前提。

3.1.1 核心目录与职责

目录/文件	作用	TinyML 相关要点
`zephyr/`	内核、调度器、IPC、内存管理	线程优先级、栈大小配置影响推理延迟
`boards/`	板级支持包（BSP），包含 DTS 和 defconfig	定义传感器引脚、时钟频率、Flash 大小
`drivers/`	外设驱动（GPIO、I2C、SPI、UART）	传感器数据采集路径的关键
`dts/`	设备树源文件，描述硬件拓扑	通过 DTS 配置传感器地址、中断优先级
`modules/`	外部模块挂载点（如 TFLM）	通过 west.yml 引入 AI 推理库
`samples/`	官方示例工程	`samples/hello_world` 是最小验证

在 TinyML 场景中，设备树（DTS） 是连接硬件与软件的关键抽象。例如，当你在 nRF52840 上挂载 BMI270 加速度计时，需要在 DTS 中声明 I2C 总线地址和中断 GPIO，Zephyr 的驱动框架会根据 DTS 自动生成配置结构体，无需手动硬编码引脚。

  核心原理：Zephyr 使用 Kconfig 进行编译时配置，使用 设备树 进行运行时硬件描述。两者结合，实现了“一次编写，多板复用”的移植性。对于 TinyML，这意味着你可以为不同 MCU 编写相同的推理代码，仅需调整 DTS 和 defconfig。

3.2 开发环境搭建：west 与工具链的协同

Zephyr 的构建系统基于 CMake，但直接使用 CMake 会非常繁琐。因此官方推荐使用 west（Zephyr's meta-tool）作为统一入口。west 不仅管理多仓库，还封装了构建、烧录、调试等命令。

3.2.1 环境准备清单

操作系统：Ubuntu 22.04 LTS（推荐）或 Windows 10/11 + WSL2。
依赖包：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
Python 虚拟环境：建议使用 venv 隔离 west 和 pip 包。
Zephyr SDK：包含交叉编译器、QEMU、OpenOCD 等。下载 zephyr-sdk-0.16.5-1 并解压到 ~/zephyr-sdk。

3.2.2 操作流程：从零到可编译

# 1. 安装 west
pip install west

# 2. 初始化 Zephyr 工作区（假设在 ~/zephyrproject 下）
cd ~
mkdir zephyrproject && cd zephyrproject
west init -m https://github.com/zephyrproject-rtos/zephyr.git --mr v3.7.0
cd zephyr
west update

# 3. 安装 Python 依赖
pip install -r zephyr/scripts/requirements.txt

# 4. 导出 Zephyr CMake 包（可选，便于 IDE 识别）
west zephyr-export

# 5. 设置环境变量（建议写入 ~/.bashrc）
export ZEPHYR_BASE=~/zephyrproject/zephyr
export ZEPHYR_TOOLCHAIN_VARIANT=zephyr
export ZEPHYR_SDK_INSTALL_DIR=~/zephyr-sdk-0.16.5

经验提醒：如果使用 STM32 系列，可以额外安装 west flash 依赖的 stm32flash 或 openocd。对于 nRF52 系列，nrfjprog 是官方烧录工具，但 west 默认调用 J-Link 接口，需确保 J-Link 驱动已安装。

3.3 编译与烧录流程：以 TinyML 示例工程为案例

我们以 samples/modules/tflite-micro/hello_world 为例，演示从编译到烧录的完整闭环。该示例使用 TensorFlow Lite Micro 在 MCU 上运行正弦波拟合模型，是 TinyML 入门的经典案例。

3.3.1 编译操作与参数解析

# 进入示例目录
cd ~/zephyrproject/zephyr/samples/modules/tflite-micro/hello_world

# 编译（指定板卡为 nRF52840DK）
west build -b nrf52840dk_nrf52840 .

# 查看构建产物
ls build/zephyr/
# 输出：zephyr.elf, zephyr.bin, zephyr.hex, zephyr.map

编译过程的核心参数包括：

-b：指定目标板卡，对应 boards/ 目录下的 DTS 和 defconfig。
-d：指定构建目录（默认 build）。
-t：指定构建目标（如 menuconfig 可交互式配置 Kconfig）。
-p：自动执行 pristine 清理，避免缓存冲突。

3.3.2 烧录与验证

# 连接 nRF52840DK 后，执行烧录
west flash

# 查看串口输出（默认 115200 波特率）
screen /dev/ttyACM0 115200
# 或使用 minicom / PuTTY

预期输出：串口终端会周期性打印 0x...: x: 0.000000, y: 0.000000 之类的数据，表示模型正在实时推理并输出正弦波预测值。

风险提示：如果烧录失败，优先检查：1) 板卡是否处于 DFU 模式（nRF52 需按复位键两次进入 DFU）；2) J-Link 驱动版本是否与 Zephyr SDK 兼容；3) 是否设置了 ZEPHYR_TOOLCHAIN_VARIANT 环境变量。对于 STM32，若使用 ST-Link，需在 west flash 后加 --runner stlink。

3.4 常见误区与工程化建议

在指导学员过程中，以下问题出现频率最高，直接影响 TinyML 项目的开发效率。

误区	后果	正确做法
直接修改 `zephyr/` 内核源码	升级时冲突，无法维护	所有应用代码放在 `app/` 目录，通过 CMakeLists.txt 引用
忽略设备树，硬编码 GPIO	板级移植困难，代码不可复用	在 DTS 中定义外设节点，使用 `DEVICE_DT_GET` 获取设备
使用系统 GCC 而非 Zephyr SDK	链接错误、ABI 不兼容	始终设置 `ZEPHYR_TOOLCHAIN_VARIANT=zephyr`
不清理构建目录	配置残留导致诡异问题	使用 `west build -p always` 或手动删除 `build/`
忽略 `prj.conf` 中的堆栈大小	TFLM 推理时栈溢出	为推理线程分配至少 8KB 栈，并启用 `CONFIG_MAIN_STACK_SIZE=8192`

3.4.1 案例复盘：一次典型的“编译通过但烧录后无输出”排障

背景：学员使用 STM32F746G-Discovery 板卡，编译 hello_world 成功，但烧录后串口无任何输出。

排查过程：

检查 west flash 输出，确认烧录地址正确（0x08000000）。
使用 ST-Link Utility 读取 Flash 内容，发现前 16 字节全为 0xFF，说明烧录未生效。
检查 west flash --runner stlink 的日志，发现 OpenOCD 无法识别芯片 ID。
最终定位：板卡上的 ST-Link 固件版本过旧，无法与 OpenOCD 0.12 通信。

解决方案：升级 ST-Link 固件至最新版（通过 STM32CubeProgrammer），重新执行 west flash，串口正常输出。

复盘经验：烧录问题 80% 与调试器固件或驱动有关，而非 Zephyr 配置。建议在项目开始前，先使用官方烧录工具（如 STM32CubeProgrammer）验证裸机 LED 闪烁程序，确保硬件链路通畅。

3.5 构建系统的深度理解：CMake 与 Kconfig 的协作

Zephyr 的构建系统是 CMake 的超集，它通过 zephyr/CMakeLists.txt 引入所有必要的模块。理解这一层，有助于你自定义 TinyML 工程的编译选项。

3.5.1 关键构建变量

CONFIG_*：来自 Kconfig，控制内核功能开关（如 CONFIG_TFLITE_MICRO）。
DTS_*：来自设备树，控制硬件配置（如 DTS_NODE_SENSOR_BMI270_BUS_I2C）。
EXTRA_CFLAGS：通过 west build -- -DEXTRA_CFLAGS="-O2" 传递额外编译参数。

# 在应用 CMakeLists.txt 中引入 TFLM 模块
find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
project(my_tiny_ml_app)

target_sources(app PRIVATE src/main.c src/model.cc)
target_include_directories(app PRIVATE include)

# 启用 TFLM 支持
add_subdirectory($ENV{ZEPHYR_BASE}/modules/tflite-micro ${CMAKE_CURRENT_BINARY_DIR}/tflm)
target_link_libraries(app PRIVATE tflite-micro)

  实战建议：在 TinyML 项目中，建议将模型文件（.tflite）转换为 C 数组（如 model_data.cc），并通过 xxd -i 生成。这样可避免文件系统依赖，且便于链接到 Flash 的只读区域。

3.6 多板卡支持与条件编译

Zephyr 的 boards/ 目录下每个板卡都有独立的 defconfig 和 .dts 文件。当你的 TinyML 应用需要同时支持 nRF52840 和 STM32L4 时，可以通过 CONFIG_BOARD 宏进行条件编译。

#ifdef CONFIG_BOARD_NRF52840DK_NRF52840
  #define SENSOR_I2C_ADDR 0x68
#elif defined(CONFIG_BOARD_STM32L4R9I_DISCO)
  #define SENSOR_I2C_ADDR 0x69
#endif

这种设计使得同一套推理代码可以无缝迁移到不同硬件平台，只需在编译时指定 -b 参数。对于产品化开发，建议使用 boards/arm/ 下的自定义板卡目录，将传感器配置、时钟树等硬件差异全部封装在 DTS 中。

3.7 性能优化与调试技巧

在 TinyML 场景下，编译优化级别直接影响推理速度。Zephyr 默认使用 -Os（优化体积），但你可以通过 Kconfig 调整：

# prj.conf 中设置
CONFIG_COMPILER_OPT="-O2"
CONFIG_DEBUG_OPTIMIZATIONS=n

此外，使用 CONFIG_THREAD_ANALYZER=y 可以监控线程栈使用率，避免推理线程栈溢出。对于性能分析，CONFIG_TRACING=y 配合 Orbit 工具可以可视化线程调度和中断延迟。

调试利器：Zephyr 内置 shell 子系统（CONFIG_SHELL=y），通过 UART 提供命令行接口。你可以动态查看传感器数据、调用推理函数，甚至在线调整模型参数，极大加速 TinyML 原型验证。

3.8 本章总结与工程基线

完成本章学习后，你应该能够独立完成以下任务：

使用 west init/update 搭建 Zephyr 开发环境。
理解 zephyr/、boards/、dts/ 的核心作用。
通过 west build 编译任意官方示例或自定义工程。
使用 west flash 烧录固件，并通过串口验证输出。
根据硬件差异修改 DTS 和 defconfig，实现多板卡适配。

建议将以下内容作为你的 工程基线：

工作区目录：~/zephyrproject（包含 zephyr、modules、tools 等）。
应用目录：~/zephyrproject/app，独立于 Zephyr 源码树。
版本管理：使用 west manifest 锁定 Zephyr 和 TFLM 版本，确保可复现构建。
自动化脚本：编写 build.sh 封装环境变量设置和编译命令。

在下一阶段，你将进入 TinyML 的核心环节——模型转换与部署。届时，本章搭建的环境将作为所有实验的基础平台。请务必确保 hello_world 示例能够在你手头的板卡上稳定运行，这是后续所有复杂应用的“最小可行验证”。