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

2、开发环境搭建：安装nRF Connect SDK、Zephyr RTOS、工具链，以及配置VS Code或命令行环境

nRF52840作为Nordic Semiconductor推出的低功耗蓝牙SoC，其开发环境搭建与传统MCU（如STM32）有显著差异。它并非简单地安装一个IDE即可，而是需要构建一套基于Zephyr RTOS的完整软件生态链。本章将系统讲解从零开始搭建nRF52840 TinyML开发环境的核心流程，涵盖nRF Connect SDK（nRF Connect SDK，简称NCS）的获取、Zephyr RTOS的集成、交叉编译工具链的安装，以及VS Code与命令行两种工作流的配置。这套环境不仅是后续传感器数据采集和BLE通信的基础，更是实现低功耗模型推理与数据同步的工程前提。

上图展示了nRF52840 TinyML开发环境的整体架构。从底层的主机操作系统，到中间的交叉编译工具链、构建系统，再到上层的VS Code或命令行开发环境，每一层都有其特定的职责。理解这个分层结构，有助于在后续遇到编译错误或链接问题时，快速定位是工具链版本不匹配、SDK配置错误，还是构建系统参数问题。下面我们将按照实际安装顺序，逐步深入每个环节。

2.1 核心原理：理解NCS与Zephyr的层级关系

在动手安装之前，必须先厘清nRF Connect SDK（NCS）与Zephyr RTOS之间的关系。NCS并非一个独立的RTOS，而是Nordic在Zephyr RTOS基础之上，添加了自家芯片的硬件抽象层（HAL）、BLE协议栈（SoftDevice Controller）、以及一系列专有驱动和库（如nRF Security、nRF IEEE 802.15.4）之后形成的发行版。从工程角度看，NCS是一个包含Zephyr内核源码、Nordic扩展包、第三方库（如TensorFlow Lite Micro）和构建脚本的超级代码仓库。

这种设计带来的直接好处是：开发者既能使用Zephyr标准的设备树（Device Tree）和Kconfig配置系统，又能直接调用Nordic的硬件加速模块（如AES加密引擎、温度传感器、PPI可编程外设互联）。对于TinyML场景，这意味着你可以利用Zephyr的线程调度器管理推理任务，同时通过Nordic的SPI驱动高速读取传感器数据，而无需自己编写底层寄存器操作。

  关键认知：NCS v2.x版本基于Zephyr LTS（长期支持）分支，例如NCS v2.5.0对应Zephyr v3.5.0。版本匹配至关重要——如果混用不同版本的NCS和Zephyr，会导致设备树定义不兼容、API函数签名变化等严重问题。因此，务必使用west工具来管理整个SDK的版本依赖，而不是手动下载ZIP包。

此外，Zephyr的构建系统采用模块化设计。每个应用（Application）通过CMakeLists.txt声明依赖的库和源文件，而prj.conf文件则通过Kconfig机制配置内核选项（如线程栈大小、堆内存、BLE功能开关）。设备树文件（.dts和.overlay）则描述了硬件连接关系，例如哪个GPIO连接了传感器中断引脚、SPI外设的时钟频率是多少。这种"配置与代码分离"的思想，使得同一套代码可以轻松适配不同传感器或不同板卡。

2.2 操作流程：从零到可编译的最小系统

以下安装流程以Ubuntu 22.04 LTS为例（Windows用户强烈建议使用WSL2），分为四个阶段。每个阶段都配有验证命令，确保每一步都正确无误。

阶段一：安装系统依赖与基础工具

# 更新系统包索引
sudo apt update
sudo apt upgrade -y

# 安装基础依赖
sudo apt install -y 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 工具（Zephyr的元工具）
pip3 install --user west

# 将用户级bin目录加入PATH（若未自动添加）
echo 'export PATH=~/.local/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# 验证west安装
west --version

此阶段的核心是安装west。west是Zephyr项目的官方命令行工具，它负责下载、更新和管理NCS及其所有子模块。与直接使用git clone不同，west会根据manifest文件（west.yml）自动拉取指定版本的Zephyr、Nordic HAL、以及可选的TinyML库，确保版本一致性。

阶段二：获取nRF Connect SDK源码

# 创建nRF workspace目录（建议路径不含中文和空格）
mkdir ~/ncs
cd ~/ncs

# 使用west初始化NCS v2.5.0（可根据需要更换版本号）
west init -m https://github.com/nrfconnect/sdk-nrf --mr v2.5.0

# 拉取所有子模块（耗时较长，约10-20分钟，取决于网络）
cd ~/ncs/nrf
west update

执行west update后，~/ncs目录下会生成zephyr、nrf、modules、bootloader等子目录。其中modules目录内包含hal/nordic、tee/tf-m等关键组件。验证方法：检查~/ncs/zephyr目录是否存在，并查看~/ncs/nrf/west.yml文件中的revision字段是否与预期版本一致。

阶段三：安装ARM交叉编译工具链

# 下载ARM GNU Toolchain（以12.2版本为例）
wget https://developer.arm.com/-/media/Files/downloads/gnu/12.2.rel1/binrel/arm-gnu-toolchain-12.2.rel1-x86_64-arm-none-eabi.tar.xz

# 解压到 /opt 目录
sudo tar -xf arm-gnu-toolchain-12.2.rel1-x86_64-arm-none-eabi.tar.xz -C /opt

# 添加环境变量
echo 'export PATH=/opt/arm-gnu-toolchain-12.2.rel1-x86_64-arm-none-eabi/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# 验证编译器
arm-none-eabi-gcc --version

这里需要特别说明：Zephyr支持GCC和Clang两种编译器，但官方推荐使用ARM的GNU工具链。对于TinyML应用，编译器的优化级别直接影响模型推理速度和代码体积。建议在prj.conf中设置CONFIG_COMPILER_OPT="-Os"（优化体积）或"-O2"（优化速度），具体取舍将在后续章节讨论。

阶段四：配置Python虚拟环境与Zephyr依赖

# 创建并激活Python虚拟环境（强烈推荐）
python3 -m venv ~/ncs/.venv
source ~/ncs/.venv/bin/activate

# 安装Zephyr的Python依赖
pip install --upgrade pip
pip install -r ~/ncs/zephyr/scripts/requirements.txt

# 安装nRF额外的Python依赖（用于TinyML和BLE）
pip install -r ~/ncs/nrf/scripts/requirements.txt

# 设置Zephyr环境变量（每次打开新终端需执行）
export ZEPHYR_BASE=~/ncs/zephyr
export ZEPHYR_TOOLCHAIN_VARIANT=gnuarmemb
export GNUARMEMB_TOOLCHAIN_PATH=/opt/arm-gnu-toolchain-12.2.rel1-x86_64-arm-none-eabi

为了简化每次打开终端的配置，可以将上述export语句写入~/.bashrc。但更推荐的做法是使用west自带的west config命令设置全局参数，或者使用env.sh脚本统一管理。

环境变量	作用	示例值
`ZEPHYR_BASE`	指向Zephyr源码根目录	`~/ncs/zephyr`
`ZEPHYR_TOOLCHAIN_VARIANT`	指定工具链类型	`gnuarmemb`
`GNUARMEMB_TOOLCHAIN_PATH`	ARM GCC工具链安装路径	`/opt/arm-gnu-toolchain-12.2.rel1-x86_64-arm-none-eabi`
`PATH`	包含west和arm-none-eabi-gcc	`~/.local/bin:/opt/.../bin:$PATH`

阶段五：编译并烧录第一个示例程序

# 进入NCS示例目录
cd ~/ncs/nrf/samples/bluetooth/peripheral_hr

# 编译（指定开发板为nrf52840dk_nrf52840）
west build -b nrf52840dk_nrf52840

# 烧录（通过USB连接DK板，使用板载J-Link）
west flash

如果一切顺利，开发板上的LED会开始闪烁，手机使用nRF Connect App可以扫描到名为"Nordic_HR"的蓝牙设备。这个简单的BLE心率服务示例，验证了从工具链到SDK再到硬件烧录的完整链路是否通畅。

2.3 实战场景：配置VS Code与命令行双工作流

在实际TinyML项目开发中，开发者往往需要同时使用VS Code的图形化界面和命令行的高效脚本能力。下面分别介绍两种工作流的配置要点，并给出一个混合使用的案例。

VS Code工作流配置

VS Code通过nRF Connect for VS Code扩展包提供完整的图形化支持。安装步骤如下：

在VS Code扩展市场搜索并安装nrf-connect扩展包（Nordic Semiconductor官方发布）。
安装完成后，按Ctrl+Shift+P打开命令面板，输入nRF Connect: Open Welcome Page。
在欢迎页中点击“Open nRF Connect SDK Project”，选择~/ncs/nrf/samples/bluetooth/peripheral_hr目录。
扩展会自动检测到west和工具链路径。如果未检测到，需要在设置中手动指定nrf-connect.toolchain.path和nrf-connect.topdir。
在左侧的nRF Connect面板中，可以图形化选择开发板（nrf52840dk_nrf52840）、配置Kconfig选项（点击prj.conf文件）、查看设备树可视化。

VS Code的优势在于可视化配置和断点调试。例如，你可以直接在prj.conf的图形界面中勾选CONFIG_BT来启用BLE，而不需要记忆Kconfig宏名称。调试时，按F5即可启动GDB调试会话，查看传感器数据缓冲区的内容。

命令行工作流配置

命令行环境更适合自动化构建和远程开发。推荐使用west build配合ninja的增量编译特性。以下是一个高效的命令行工作流示例：

# 创建构建别名（写入~/.bashrc）
alias build_hr='cd ~/ncs/nrf/samples/bluetooth/peripheral_hr && west build -b nrf52840dk_nrf52840'
alias flash_hr='cd ~/ncs/nrf/samples/bluetooth/peripheral_hr && west flash'

# 使用ccache加速重复编译
west build -b nrf52840dk_nrf52840 -- -DCMAKE_C_COMPILER_LAUNCHER=ccache

# 清理并重新编译（当设备树或Kconfig改动较大时）
west build -b nrf52840dk_nrf52840 -p always

对于TinyML项目，命令行还有一个独特优势：可以方便地集成模型转换脚本。例如，你可以编写一个build.sh脚本，先调用TensorFlow Lite Converter将.tflite模型转换为C数组，再触发west build编译固件，实现"一键构建"。

混合工作流建议：日常开发使用VS Code进行代码编辑和Kconfig配置，利用其智能提示和图形化界面；当需要批量测试不同传感器配置或执行CI/CD流水线时，切换到命令行模式。两种方式共享同一个build目录，不会产生冲突。

2.4 案例拆解：传感器数据采集项目的环境验证

为了验证环境搭建的完整性，我们设计一个简单的实战案例：读取nRF52840 DK板载的温湿度传感器（如SHT40或DHT22，取决于板卡版本），并通过串口打印数据。这个案例虽然简单，但能全面检验GPIO驱动、I2C/SPI总线配置、传感器驱动库和日志系统是否正常工作。

背景与约束：假设我们使用nRF52840 DK开发板，板载传感器通过I2C接口连接（默认地址0x44）。目标是在串口终端上每秒打印一次温度和湿度值。初始现象是：编译通过，但串口无输出。

分析判断过程：

首先检查prj.conf是否启用了I2C和传感器驱动：CONFIG_I2C=y、CONFIG_SENSOR=y。
检查设备树overlay文件（boards/nrf52840dk_nrf52840.overlay）是否正确配置了I2C节点和传感器节点。
使用west build -t menuconfig打开图形化配置界面，确认CONFIG_SHT4X（或对应驱动）已勾选。
检查串口配置：CONFIG_SERIAL=y、CONFIG_UART_CONSOLE=y，并确认波特率设置为115200。

实际操作步骤：

# 1. 创建项目目录
mkdir ~/ncs/my_sensor_app && cd ~/ncs/my_sensor_app

# 2. 创建最小项目结构
touch CMakeLists.txt prj.conf
mkdir boards && touch boards/nrf52840dk_nrf52840.overlay

# 3. 编辑CMakeLists.txt
cat > CMakeLists.txt << EOF
cmake_minimum_required(VERSION 3.20.0)
find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
project(sensor_app)
target_sources(app PRIVATE src/main.c)
EOF

# 4. 编辑prj.conf
cat > prj.conf << EOF
CONFIG_I2C=y
CONFIG_SENSOR=y
CONFIG_SHT4X=y
CONFIG_SERIAL=y
CONFIG_UART_CONSOLE=y
CONFIG_LOG=y
EOF

# 5. 编写main.c（核心代码片段）
# 初始化传感器并周期性读取数据

结果对比与复盘：经过排查，发现问题是设备树overlay中I2C的时钟频率设置过高（400kHz），而传感器实际支持的最大频率为100kHz。将clock-frequency = <100000>;修改后，数据正常输出。这个案例说明，环境搭建不仅仅是安装软件，还需要对硬件规格有基本了解。在TinyML项目中，传感器数据采集的稳定性直接影响模型推理的输入质量，因此务必在环境验证阶段就确保传感器驱动工作正常。

风险提示：在配置I2C或SPI总线时，务必查阅传感器数据手册确认最大时钟频率。过高的频率可能导致数据错位或通信失败。此外，nRF52840的GPIO电平为1.8V，如果使用5V传感器，必须添加电平转换电路，否则会损坏芯片。

2.5 常见误区与总结复盘

在搭建环境的过程中，开发者常会遇到以下几类问题，这里逐一剖析并提供解决方案。

误区/问题	典型表现	根因分析	解决方案
版本不匹配	编译报错：undefined reference to `bt_enable'	NCS与Zephyr版本混用，API签名不一致	严格使用`west init -m ... --mr <版本号>`锁定版本
工具链路径错误	CMake错误：`-- Toolchain not found`	`GNUARMEMB_TOOLCHAIN_PATH`未设置或路径错误	使用`echo $GNUARMEMB_TOOLCHAIN_PATH`检查，确保指向bin目录的上一级
Python依赖缺失	west命令报ModuleNotFoundError	未激活虚拟环境或未安装requirements.txt	执行`source ~/ncs/.venv/bin/activate`后重新安装依赖
设备树配置错误	编译通过但外设无响应	overlay文件未正确覆盖默认引脚定义	使用`west build -t devicetree`查看实际生成的设备树
烧录失败	J-Link连接超时	USB驱动未安装或板卡供电不足	安装SEGGER J-Link驱动，检查USB线是否为数据线

总结复盘：一个健壮的nRF52840 TinyML开发环境，应当具备以下特征：版本可追溯（通过west manifest锁定）、构建可重复（使用虚拟环境和固定工具链）、配置可审查（设备树和Kconfig文件纳入版本控制）。建议在项目初期就编写一个setup.sh脚本，将本章所有安装步骤自动化，这样团队成员可以快速复现环境，避免"在我电脑上能编译"的尴尬。

最后，验证环境是否就绪的最快方法，是编译并运行一个最小BLE示例（如bluetooth/peripheral_hr）。如果该示例能成功烧录并广播，说明工具链、SDK、烧录链路均正常。在此基础上，再逐步添加传感器驱动和TinyML推理代码，可以大幅降低排障难度。