📚 课程目录第2章开发环境搭建

2、开发环境搭建：安装nRF Connect SDK、配置Zephyr环境、使用west工具管理项目

在开始TinyML模型与nRF Connect SDK（NCS）的集成之前，必须先构建一个可靠、可复现的开发环境。nRF Connect SDK并非一个独立的软件包，而是基于Zephyr RTOS的发行版，它通过west工具将Zephyr内核、Nordic的SoC支持包、板级定义、协议栈以及应用示例组织为一个多仓库的工程结构。本章将围绕NCS的安装、Zephyr环境的配置以及west工具的核心用法展开，帮助您从零搭建一套能够支撑后续模型部署、编译与烧录的完整工具链。

上图展示了NCS开发环境的核心逻辑：主机工具链驱动west，west管理NCS与Zephyr的多仓库结构，最终编译产物烧录至目标硬件。下面我们将分步骤深入每个环节的具体操作与原理。

2.1 核心原理：NCS、Zephyr与west的关系

理解三者的关系是搭建环境的前提。nRF Connect SDK是Nordic Semiconductor基于Zephyr RTOS定制的软件发行版。它并非简单的代码分支，而是通过west清单（manifest）文件将多个Git仓库组合为一个有机整体。Zephyr提供内核、设备驱动模型、设备树（Devicetree）机制以及构建系统；NCS在Zephyr之上增加了Nordic专有的SoC支持（如nRF5340、nRF9160）、低功耗蓝牙协议栈、Wi-Fi、蜂窝网络以及电源管理组件。west是Zephyr项目的官方多仓库管理工具，它负责解析清单文件、拉取指定版本的仓库、管理项目依赖，并封装了构建、烧录、调试等常用命令。

组件	角色	关键目录/文件	版本管理方式
nRF Connect SDK	Nordic 应用层与协议栈	nrf/、nrfxlib/	随west manifest锁定
Zephyr RTOS	内核、HAL、设备树、构建系统	zephyr/	随west manifest锁定
west	多仓库管理、构建、烧录	~/.local/bin/west	pip 安装，独立升级
应用工程	用户代码与模型集成	任意目录下的应用文件夹	用户自建Git仓库

这种分层设计使得开发者可以同时获得Zephyr社区的最新特性与Nordic的硬件优化支持。但这也意味着，环境搭建必须严格遵循版本匹配原则——NCS版本与Zephyr版本、工具链版本、west版本之间存在兼容性矩阵，随意混用会导致编译失败或运行时异常。

2.2 操作流程：从零安装NCS与配置Zephyr环境

以下流程以Ubuntu 22.04 LTS（或WSL2）为参考，适用于NCS v2.6.0及以上版本。整个安装过程约需30-60分钟，取决于网络状况。

步骤一：安装系统依赖与基础工具

首先更新包管理器并安装编译所需的系统库。Zephyr的构建系统依赖CMake、Ninja、Python3、Devicetree编译器（dtc）以及多种开发库。

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

步骤二：安装west与Python依赖

west通过pip安装，建议使用虚拟环境避免污染系统Python。NCS的构建脚本会调用west，因此需要确保west可执行文件在PATH中。

pip3 install --user west
echo 'export PATH=~/.local/bin:"$PATH"' >> ~/.bashrc
source ~/.bashrc
west --version

步骤三：获取NCS源码（west init & west update）

创建一个工作目录（例如 ~/ncs），使用west初始化该目录。初始化时需指定Nordic官方manifest仓库的URL和版本分支。这里以 v2.6.0 标签为例，该版本对应Zephyr 3.6。

mkdir ~/ncs && cd ~/ncs
west init -m https://github.com/nrfconnect/sdk-nrf --mr v2.6.0
west update

west update 会根据manifest文件拉取所有依赖仓库，包括zephyr、mcuboot、nrfxlib、cmsis-nn等。这一步耗时较长，且需要稳定的网络连接。如果网络不稳定，可以配置Git代理或使用Nordic提供的镜像源。

步骤四：安装Zephyr SDK（交叉编译工具链）

Zephyr SDK包含针对ARM、RISC-V等架构的交叉编译器、GDB调试器以及QEMU模拟器。NCS要求使用与Zephyr版本匹配的SDK版本。下载并解压到 ~/zephyr-sdk，然后运行安装脚本。

cd ~
wget https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v0.16.5-1/zephyr-sdk-0.16.5-1_linux-x86_64.tar.xz
tar xf zephyr-sdk-0.16.5-1_linux-x86_64.tar.xz
cd zephyr-sdk-0.16.5-1
./setup.sh -c

安装完成后，需要将SDK路径写入 ~/.zephyrrc 文件，以便west构建时自动识别。

echo 'export ZEPHYR_SDK_INSTALL_DIR=~/zephyr-sdk-0.16.5-1' >> ~/.zephyrrc
echo 'export ZEPHYR_TOOLCHAIN_VARIANT=zephyr' >> ~/.zephyrrc

步骤五：验证环境

进入NCS目录，尝试编译一个简单的示例工程（例如blinky）来验证整个工具链是否正常。

cd ~/ncs/nrf/samples/blinky
west build -b nrf5340dk_nrf5340_cpuapp
west flash

如果编译无错误且烧录后开发板上的LED开始闪烁，则说明环境搭建成功。

2.3 案例拆解：为TinyML应用创建独立工程并管理依赖

在实际的TinyML项目中，我们通常不会直接修改NCS自带的示例，而是创建独立的应用工程。这样做的好处是：应用代码与SDK分离，便于版本控制；可以灵活地选择NCS版本；避免污染SDK目录。下面以一个手势识别应用为例，演示如何创建工程并集成TensorFlow Lite Micro（TFLM）模块。

背景与目标：在nRF5340 DK上部署一个基于加速度计数据的手势分类模型。需要创建一个名为 gesture_app 的独立工程，该工程依赖NCS的传感器驱动和TFLM推理库。

操作步骤：

创建工程目录结构：在 ~/ncs 下创建 gesture_app 文件夹，内部包含 src/main.c、CMakeLists.txt、prj.conf 以及 model/gesture_model.tflite（模型文件）。
编写CMakeLists.txt：该文件是Zephyr构建系统的入口，需要指定应用源码路径、依赖的Zephyr模块以及TFLM库。

cmake_minimum_required(VERSION 3.20.0)
find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
project(gesture_app)

target_sources(app PRIVATE src/main.c)

# 引入TFLM微控制器库
add_subdirectory(${ZEPHYR_BASE}/../modules/lib/tflm-micro)
target_link_libraries(app PRIVATE tflm-micro)

配置prj.conf：启用传感器驱动和必要的内核配置。

CONFIG_GPIO=y
CONFIG_I2C=y
CONFIG_SENSOR=y
CONFIG_BMI270=y
CONFIG_STDOUT_CONSOLE=y
CONFIG_MAIN_STACK_SIZE=4096

构建与烧录：使用west构建，指定板卡为nRF5340 DK的application核心。

cd ~/ncs/gesture_app
west build -b nrf5340dk_nrf5340_cpuapp
west flash

结果与复盘：首次构建时，west会自动检测到 modules/lib/tflm-micro 目录并编译TFLM静态库。整个构建过程约3-5分钟。如果遇到 undefined reference to 'tflite::MicroInterpreter' 之类的链接错误，通常是因为CMakeLists.txt中未正确链接TFLM库或未包含头文件路径。此时应检查 target_link_libraries 是否包含 tflm-micro，并在 main.c 中通过 #include "tensorflow/lite/micro/micro_interpreter.h" 引入头文件。

  工程管理要点：独立应用工程应使用Git进行版本管理，并在仓库中记录NCS版本号（例如通过 west manifest --freeze 生成 west.yml 锁定文件）。这样团队成员或CI服务器可以精确复现相同的构建环境。

2.4 常见误区与总结复盘

在环境搭建过程中，开发者经常遇到以下几类问题，提前了解可以节省大量排障时间。

误区/问题	典型现象	根因分析	解决方案
west命令找不到	执行 `west --version` 提示command not found	pip安装路径未加入PATH	检查 `~/.local/bin` 是否在PATH中，或重新执行 `export PATH=~/.local/bin:$PATH`
NCS与Zephyr版本不匹配	编译时出现 `#error "Zephyr version mismatch"`	manifest拉取的Zephyr版本与NCS要求不一致	删除 `~/ncs` 重新执行 `west init -m ... --mr v2.6.0` 并 `west update`
缺少Python依赖	构建时提示 `ModuleNotFoundError: No module named 'packaging'`	pip依赖未完整安装	执行 `pip3 install --user -r ~/ncs/zephyr/scripts/requirements.txt`
设备树编译错误	报错 `undefined device` 或 `gpio_dt_spec` 相关错误	板级定义与驱动不匹配	检查 `BOARD` 变量是否正确，确认 `prj.conf` 中启用了对应驱动

总结复盘：搭建NCS开发环境的核心是理解west的清单机制。建议遵循以下最佳实践：第一，始终使用 west init 指定明确的NCS版本标签，避免使用 main 分支导致的不稳定；第二，将 west update 生成的 west.yml 文件纳入版本控制，确保团队协作时环境一致；第三，对于TinyML项目，务必确认 modules/ 目录下是否包含 tflm-micro 或 cmsis-nn 等依赖，若缺失可在 west.yml 中手动添加；第四，定期运行 west update 获取安全补丁和驱动更新，但升级前需阅读NCS的Release Notes，确认与当前应用的兼容性。

风险提示：不要使用系统自带的gcc-arm-none-eabi工具链替代Zephyr SDK。Zephyr SDK包含了针对Zephyr RTOS优化的编译器选项和Newlib库，混用可能导致浮点运算异常或链接错误。此外，WSL2用户需注意USB设备映射问题，烧录时可能需要使用 usbipd 工具将nRF5340 DK的USB端口映射到WSL2中。