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

3、开发环境搭建：nRF Connect SDK、Zephyr RTOS、工具链安装与项目创建

nRF5340 作为一款双核 SoC，其开发环境搭建的复杂度远高于传统单核 MCU。开发者不仅要管理应用核（Application Core，负责高层应用与 AI 推理）和网络核（Network Core，负责 BLE/802.15.4 等无线协议栈）两套固件的编译与烧录，还要处理 Zephyr RTOS 的版本兼容、Nordic 专有工具链的配置以及多工程依赖关系。本章将系统讲解从零搭建 nRF5340 双核开发环境的完整流程，涵盖 nRF Connect SDK（nRF Connect SDK，简称 NCS）的获取、Zephyr RTOS 的集成机制、工具链的安装验证，以及如何通过命令行和 VS Code 两种方式创建并编译双核项目。我们将以 nRF5340 DK 开发板为硬件基准，确保每一步操作均可复现。

上图展示了 nRF5340 开发环境的整体架构。左侧是主机侧必须安装的软件组件，中间是 NCS 仓库的核心内容，右侧是目标板上的资源分布。整个构建链路的核心在于 west 工具——它是 Zephyr 项目的多仓库管理工具，负责拉取 NCS 及其依赖的 Zephyr、模块和第三方库。理解这张图有助于后续排障时快速定位问题层级：是主机工具链缺失，还是 NCS 仓库损坏，或是目标板连接异常。

3.1 核心原理：NCS 与 Zephyr 的版本绑定关系

nRF Connect SDK 并非独立的 RTOS，而是 Nordic 在 Zephyr RTOS 之上构建的一套发行版。NCS 通过 west manifest 文件（west.yml）精确锁定 Zephyr 的 commit 版本，以及 Nordic 自研的 nrf 仓库、mcuboot、TF-M 等组件的版本。这种绑定机制确保了双核通信库（如 IPC Service）、BLE 协议栈（SoftDevice Controller）与 Zephyr 内核 API 之间的兼容性。

以 NCS v2.6.0 为例，其对应的 Zephyr 版本为 v3.5.0。如果开发者直接使用上游 Zephyr 主线代码，往往会因为 API 变更导致编译失败。因此，必须通过 west 命令拉取 NCS 官方 manifest，而不是手动 git clone 各个仓库。west 会依据 west.yml 中的 revision 字段自动 checkout 到正确的 commit。

NCS 版本	Zephyr 版本	GNU ARM 工具链	备注
v2.5.0	v3.4.0	12.2.rel1	较稳定，适合量产
v2.6.0	v3.5.0	12.3.rel1	支持 nRF5340 双核 AI 示例
v2.7.0	v3.6.0	12.3.rel1	最新，API 有调整

版本陷阱：不要混用不同版本的 NCS 和 Zephyr SDK。例如，使用 NCS v2.6.0 但手动安装 Zephyr SDK 0.16.8，会导致链接器脚本不匹配。务必使用 west config 检查当前工程的 manifest 路径。

3.2 操作流程：从零安装到双核工程编译

以下步骤以 Ubuntu 22.04 LTS 为例，Windows 用户建议使用 WSL2 或直接安装 nRF Connect for Desktop（内含命令行工具）。整个流程约需 30-60 分钟，取决于网络速度。

步骤 1：安装基础依赖

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 \
  xz-utils file make gcc gcc-multilib g++-multilib libsdl2-dev

步骤 2：安装 west 并获取 NCS 源码

pip3 install --user west
echo 'export PATH=~/.local/bin:"$PATH"' >> ~/.bashrc
source ~/.bashrc
mkdir ~/ncs && cd ~/ncs
west init -m https://github.com/nrfconnect/sdk-nrf --mr v2.6.0 ncs
cd ncs
west update

west update 会拉取约 2GB 的代码，包括 Zephyr、nrf、mcuboot、TF-M、mbedtls 等。如果网络不稳定，可以配置 west config 使用镜像仓库。

步骤 3：安装 ARM 工具链

cd ~/ncs
wget https://developer.arm.com/-/media/Files/downloads/gnu/12.3.rel1/binrel/arm-gnu-toolchain-12.3.rel1-x86_64-arm-none-eabi.tar.xz
tar xf arm-gnu-toolchain-12.3.rel1-x86_64-arm-none-eabi.tar.xz
export ZEPHYR_TOOLCHAIN_VARIANT=gnuarmemb
export GNUARMEMB_TOOLCHAIN_PATH=~/ncs/arm-gnu-toolchain-12.3.rel1-x86_64-arm-none-eabi

将上述 export 写入 ~/.bashrc 以便持久化。注意：Zephyr SDK 与 GNU ARM 工具链是两种不同的选择，NCS 官方推荐使用 GNU ARM 工具链，因为它体积小且与 Nordic 的 nrfjprog 配合更好。

步骤 4：安装 nRF Command Line Tools

# 从 Nordic 官网下载 nRF-Command-Line-Tools_10_24_0_Linux64.deb
sudo dpkg -i nRF-Command-Line-Tools_10_24_0_Linux64.deb
# 验证安装
nrfjprog --version
JLinkExe --version

步骤 5：创建双核项目并编译

cd ~/ncs/ncs
west build -b nrf5340dk_nrf5340_cpuapp \
  -d build/app \
  nrf/applications/hello_world
west build -b nrf5340dk_nrf5340_cpuapp \
  -d build/net \
  nrf/applications/hello_world -- -DOVERLAY_CONFIG=overlay-net_core.conf

上述命令分别编译应用核和网络核的 hello_world。实际开发中，更推荐使用 nrf/applications/nrf5340_audio 或 hci_rpmsg 等官方双核示例，它们已经配置好了 IPC 通信。

  关键参数说明：
  -b nrf5340dk_nrf5340_cpuapp：指定目标板为 nRF5340 DK 的应用核。
-d build/app：指定构建目录，避免双核产物混淆。
-- -DOVERLAY_CONFIG=...：为网络核添加额外的 Kconfig 配置。

3.3 案例拆解：双核 AI 推理项目的环境配置实战

假设我们要在 nRF5340 上部署一个手势识别 AI 模型，应用核运行 TensorFlow Lite Micro 推理，网络核负责通过 BLE 传输结果。这个场景对环境配置提出了额外要求：需要启用 FPU（浮点单元）、配置共享内存（IPC）、以及确保网络核固件包含 BLE 协议栈。

初始现象：直接编译官方 hello_world 双核示例成功，但加入 TFLite Micro 后，应用核编译报错 undefined reference to arm_softmax_qsym_f32。

分析过程：该错误通常是因为 CMSIS-NN 库未正确链接。TFLite Micro 在 Cortex-M33 上依赖 CMSIS-NN 进行算子优化，而 CMSIS-NN 需要 FPU 支持。检查 prj.conf 发现未启用 CONFIG_CPU_HAS_FPU=y。

解决步骤：

在应用核的 prj.conf 中添加：

CONFIG_CPU_HAS_FPU=y
CONFIG_FPU=y
CONFIG_TFLITE_MICRO=y
CONFIG_CMSIS_NN=y

在 CMakeLists.txt 中链接 CMSIS-NN：

target_link_libraries(app PRIVATE
  TensorFlowLiteMicro
  cmsis-nn
)

重新编译：west build -d build/app -b nrf5340dk_nrf5340_cpuapp .

结果对比：编译通过，生成的 merged.hex 大小从 180KB 增加到 420KB，但仍小于应用核的 1MB Flash 限制。烧录后，应用核通过 IPC 将推理结果发送给网络核，网络核通过 BLE 通知手机 App。

风险与代价：启用 FPU 后，CPU 功耗略有上升（约 0.5mA），但推理速度提升 3 倍。如果产品对功耗极其敏感，可以考虑使用定点模型并关闭 FPU。

排障经验：当遇到链接错误时，优先检查 build/app/zephyr/.config 文件，确认 Kconfig 选项是否真正生效。有时因为缓存，修改 prj.conf 后需要执行 west build -t clean 强制重新配置。

3.4 常见误区与总结复盘

在培训数百名工程师的过程中，我们发现以下四个误区最容易导致环境搭建失败：

误区	现象	正确做法
使用 pip 安装的 west 版本过旧	west init 报 manifest 解析错误	升级 west：`pip3 install --user west -U`
未设置 ZEPHYR_TOOLCHAIN_VARIANT	编译时找不到 arm-none-eabi-gcc	在 ~/.bashrc 中 export 该变量
直接 git clone Zephyr 主线	API 与 NCS 不兼容	始终使用 west 拉取 NCS 官方 manifest
烧录时只烧 app 核	网络核无固件，BLE 无法工作	使用 `nrfjprog --program merged.hex` 烧录合并镜像

总结复盘：搭建 nRF5340 双核开发环境的核心要点可以归纳为三点：版本锁定（NCS 与 Zephyr 严格对应）、工具链分离（GNU ARM 工具链与 Zephyr SDK 二选一）、双核构建分离（应用核与网络核使用不同的构建目录）。建议初学者先使用 nrf5340dk_nrf5340_cpuapp 目标编译官方 hci_rpmsg 示例，确认双核通信正常后，再逐步加入 AI 推理代码。最后，务必掌握 west build -t menuconfig 和 west build -t flash 这两个高频命令，它们能显著提升开发效率。