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

3、开发环境搭建：nRF Connect SDK、Zephyr RTOS、工具链安装、工程模板创建与调试配置

nRF低功耗AI实战课程的核心，是让开发者能够在nRF52840或nRF5340等硬件平台上，高效地完成从传感器数据采集、TinyML模型推理到BLE通信与DFU升级的全链路开发。这一切的起点，便是搭建一个稳定、可复现且易于调试的开发环境。本章节将深入剖析nRF Connect SDK（nCS）与Zephyr RTOS的关系，详细讲解工具链的安装步骤、工程模板的创建逻辑以及调试配置的核心要点，帮助你避开环境搭建阶段的常见陷阱，为后续的实战项目打下坚实基础。

上图展示了从主机开发环境到目标硬件之间的完整工具链与数据流。理解这张图是掌握后续所有操作的前提：nRF Connect SDK 并非一个独立的SDK，而是基于 Zephyr RTOS 的 Nordic 定制发行版。这意味着，你编写的应用程序实际上是运行在 Zephyr 内核之上的，而 nCS 提供了 Nordic 特有的驱动、BLE协议栈、DFU服务和硬件抽象层。因此，环境搭建的核心，就是让主机上的 west 工具能够正确管理 nCS 与 Zephyr 的版本依赖，并通过 CMake/Ninja 完成交叉编译。

3.1 核心原理：nCS、Zephyr 与工具链的层级关系

要避免环境混乱，首先必须厘清三个关键概念：nRF Connect SDK (nCS)、Zephyr RTOS 以及 Arm 交叉编译工具链。nCS 是一个包含 Zephyr 内核、Nordic 专有驱动（如 BLE SoftDevice Controller、nrfx 外设驱动）、协议栈（如 Matter、Thread）、以及大量示例工程的“大礼包”。Zephyr 本身是一个开源 RTOS，nCS 会锁定一个经过 Nordic 验证的 Zephyr 版本，以确保兼容性。工具链则负责将 C/C++ 源码编译成可在 Cortex-M 内核上运行的机器码。

版本管理核心机制：nCS 使用 west 工具（Zephyr's meta-tool）进行多仓库管理。根目录下的 west.yml 文件定义了所有依赖仓库的 Git 提交哈希值。这意味着，即使 Zephyr 上游更新了代码，只要 nCS 的 manifest 文件不变，你的开发环境就是完全可复现的。这是企业级项目开发中极其重要的特性。

工具链的选择上，Nordic 官方推荐使用 nRF Connect for Desktop 中的 Toolchain Manager 来安装。它会自动安装匹配的 GNU Arm Embedded Toolchain、CMake、Ninja、Python 依赖以及 nrfjprog 命令行工具。这种方式的优势在于，所有组件版本都经过 Nordic 测试，避免了手动安装时因版本不匹配导致的诡异编译错误。

3.2 操作流程：从零搭建 nCS 开发环境

以下流程以 Windows 10/11 和 Ubuntu 20.04/22.04 为例，macOS 操作类似但驱动略有差异。整个过程分为四个阶段：安装基础工具、获取 SDK、安装工具链、验证环境。

阶段一：安装基础依赖

Git： 用于版本控制，需确保 git 命令可在终端中运行。
Python 3.8+： 建议安装 64 位版本，并勾选“Add Python to PATH”。
nRF Command Line Tools： 包含 nrfjprog、J-Link 驱动等，是烧录和调试的基础。

阶段二：获取 nRF Connect SDK

推荐使用 nrfutil 命令行工具进行 SDK 安装，它比手动 git clone 更简洁。首先安装 nrfutil：

# Windows (PowerShell)
pip install nrfutil

# Linux / macOS
pip3 install nrfutil

然后，使用 nrfutil 安装 SDK 并创建开发目录：

# 创建一个工作目录，例如 C:\ncs 或 ~/ncs
mkdir ncs
cd ncs

# 安装 SDK 版本 v2.6.0 (或你需要的版本)
nrfutil install ncs-toolchain v2.6.0

# 初始化 west 工作区
nrfutil toolchain-manager launch -- ncs-toolchain v2.6.0 -- west init -m https://github.com/nrfconnect/sdk-nrf --mr v2.6.0

上述命令中，nrfutil toolchain-manager launch 会进入一个虚拟环境，确保所有命令都在正确的 Python 和工具链环境中执行。初始化完成后，进入 nrf 目录并更新子模块：

cd nrf
west update

west update 会根据 west.yml 拉取 Zephyr、mcuboot、nrfxlib 等所有依赖仓库，这个过程可能需要 10-30 分钟，取决于网络状况。

阶段三：安装工具链与 IDE 插件

在 nRF Connect for Desktop 中，打开 Toolchain Manager，选择已安装的 SDK 版本，点击“打开 VS Code”。VS Code 会自动加载 Nordic 的扩展包，包括 nRF Connect for VS Code 扩展。该扩展提供了工程创建、构建、烧录、调试的图形化界面，但底层依然调用 west 命令。

经验提醒：不要直接在系统全局安装 GNU Arm Embedded Toolchain。nrfutil 管理的工具链是隔离的，这避免了不同项目间工具链版本的冲突。在 VS Code 中，务必通过 nRF Connect: Select Toolchain 命令选择正确的工具链。

阶段四：验证环境

创建一个最简单的空工程并编译，以验证环境是否正常。在 VS Code 中，按 Ctrl+Shift+P 打开命令面板，输入 nRF Connect: Create New Application，选择 Zephyr 基础模板，板卡选择 nrf52840dk_nrf52840。创建完成后，点击左下角的“Build Configuration”按钮，选择 build 配置，然后点击“Build”图标。如果终端输出 Memory region Used Size Region Size %age Used 且无错误，则环境搭建成功。

3.3 案例拆解：工程模板创建与调试配置实战

本案例将演示如何从零创建一个包含 BLE 广播 和 UART 日志 的最小工程，并配置调试器。这是后续所有传感器和 TinyML 实验的基础骨架。

背景与目标：在 nRF52840 DK 开发板上，创建一个 Zephyr 工程，实现每秒通过 UART 打印一次“Hello Nordic AI”，同时开启 BLE 广播。目标是通过这个案例，掌握工程结构、设备树（Devicetree）配置和调试器连接。

操作步骤：

创建工程：使用 VS Code 的 nRF Connect 扩展创建新应用，选择 Zephyr 模板，命名 hello_ai。
修改 prj.conf：在工程根目录的 prj.conf 文件中，添加以下配置：

# 启用 UART 控制台
CONFIG_CONSOLE=y
CONFIG_UART_CONSOLE=y
CONFIG_SERIAL=y

# 启用 BLE 广播
CONFIG_BT=y
CONFIG_BT_PERIPHERAL=y
CONFIG_BT_DEVICE_NAME="AI_Node"

编写主程序：在 src/main.c 中，初始化 BLE 并循环打印日志。

#include <zephyr/kernel.h>
#include <zephyr/device.h>
#include <zephyr/drivers/uart.h>
#include <zephyr/bluetooth/bluetooth.h>

void main(void)
{
    int err;
    printk("Hello Nordic AI!\n");

    err = bt_enable(NULL);
    if (err) {
        printk("Bluetooth init failed (err %d)\n", err);
        return;
    }
    printk("Bluetooth initialized\n");

    while (1) {
        k_sleep(K_SECONDS(1));
        printk("AI Node alive...\n");
    }
}

构建与烧录：点击 VS Code 底部的 Build 按钮，编译成功后，连接开发板，点击 Flash 按钮。
调试配置：在 .vscode/launch.json 中，nRF Connect 扩展会自动生成调试配置。确保 device 字段为 nrf52840dk_nrf52840，servertype 为 jlink。点击“Start Debugging”即可进入断点调试。

结果与复盘：打开串口监视器（波特率 115200），可以看到每秒打印一次日志。使用手机上的 nRF Connect 应用，可以扫描到名为 “AI_Node” 的广播包。此案例验证了工具链、烧录、调试链路的完整性。常见问题是 CONFIG_BT_DEVICE_NAME 未生效，这通常是因为设备树中 bt_name 属性覆盖了 Kconfig 配置，需在设备树 overlay 中修改。

3.4 常见误区与总结复盘

环境搭建的失败往往源于对版本管理和工具链隔离机制的忽视。以下是三个高频误区：

误区	现象	解决方案
手动安装 GNU Arm 工具链	编译时出现 `arm-none-eabi-gcc: not found` 或版本冲突	使用 nrfutil 管理的工具链，通过 `nrfutil toolchain-manager launch` 进入环境
直接修改 Zephyr 源码	更新 SDK 后修改丢失，或导致依赖仓库哈希不匹配	所有应用代码放在独立工程中，通过 `west build` 引用 SDK，不要改动 `nrf/` 目录下的文件
忽略设备树 (Devicetree) 配置	外设无法工作，如 GPIO 无输出、UART 无日志	学习 `.dts` 和 `.overlay` 文件，使用 `west build -t menuconfig` 检查配置

风险提示：在 Windows 上，如果路径包含中文或空格，CMake 可能会报错。建议将 ncs 工作目录放在纯英文路径下，例如 C:\ncs。另外，J-Link 驱动版本过旧可能导致无法识别 nRF5340 芯片，务必通过 nRF Connect for Desktop 更新到最新版。