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

2. Zephyr开发环境搭建

Zephyr 的开发环境与“装一个 IDE 就能编译”的传统单片机开发不同，它由三层组成：Zephyr 源码与构建系统、工具链（Zephyr SDK 或 GNU Arm Embedded）、west 元工具与 manifest 仓库。Nordic 的 nRF Connect SDK（NCS）本质上是一个以 Zephyr 为内核、叠加了 Nordic 驱动、协议栈（SoftDevice Controller、Matter、Bluetooth LE 等）和示例的 west manifest 仓库集合。理解这三层关系，是避免“命令敲了但报错找不到工具链”“west build 找不到 board”这类问题的前提。

本节以 Ubuntu 22.04（或 WSL2 下的 Ubuntu）为主环境，Windows 原生环境在命令细节上略有差异，但流程一致。目标是在命令行完成一次完整的 hello world 构建与烧录，再把同一套工程导入 VS Code 使用 nRF Connect 扩展进行图形化构建与调试。

一、依赖安装与 Python 环境

Zephyr 的构建脚本依赖 CMake、Ninja、dtc、Python3 及一系列 pip 包。先安装系统依赖：

sudo apt update
sudo apt install -y git cmake ninja-build gperf ccache dfu-util \
  device-tree-compiler wget python3-dev python3-pip python3-venv \
  python3-tk xz-utils file make gcc-multilib libsdl2-dev libmagic1

建议为 Zephyr 单独创建 Python 虚拟环境，避免污染系统 Python。NCS 官方推荐使用 west 自带的 venv 机制，但手动创建同样可行：

python3 -m venv ~/zephyr-venv
source ~/zephyr-venv/bin/activate
pip install -U pip wheel
pip install west

此时 west --version 应能输出版本号。west 是 Zephyr 的“元构建工具”，它本身不编译代码，而是负责管理多仓库（manifest）、调用 CMake/Ninja、封装 flash/debug 等操作。

二、获取 nRF Connect SDK 源码

NCS 通过 west manifest 拉取。先初始化 manifest 仓库，再执行 west update 拉取 Zephyr、nrfxlib、MCUboot、Matter 等所有子模块。以 NCS v2.6.0 为例：

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

west update 会下载数 GB 内容，耗时取决于网络。完成后目录结构大致为：ncs/nrf（Nordic 层）、ncs/zephyr（Zephyr 内核）、ncs/nrfxlib、ncs/mcuboot、ncs/modules 等。west zephyr-export 会把 Zephyr 的 CMake 包注册到当前 Python 环境，使 find_package(Zephyr) 可用。

三、安装 Zephyr SDK 工具链

Zephyr SDK 提供交叉编译器（arm-zephyr-eabi-gcc）、调试器（GDB）、OpenOCD 等。NCS 对 SDK 版本有要求，v2.6.0 推荐 Zephyr SDK 0.16.5。下载并安装：

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

安装脚本会询问是否注册 CMake 包、是否安装 udev 规则。udev 规则用于让普通用户访问 J-Link 调试器，务必选择安装。安装完成后设置环境变量：

export ZEPHYR_SDK_INSTALL_DIR=~/zephyr-sdk-0.16.5
export ZEPHYR_TOOLCHAIN_VARIANT=zephyr

把这两行写入 ~/.bashrc 可持久生效。若使用 Nordic 官方工具链（nRF Connect for Desktop 附带的 Toolchain Manager），则 ZEPHYR_TOOLCHAIN_VARIANT=nordic，此时不需要单独安装 Zephyr SDK。两种方式二选一，不要混用。

四、命令行构建与烧录 hello world

NCS 自带示例位于 ncs/nrf/samples/hello_world。构建命令：

cd ~/ncs
west build -b nrf52840dk_nrf52840 nrf/samples/hello_world
west flash

-b 指定 board 名称，nrf52840dk_nrf52840 是 nRF52840 DK 的标准 board 标识。首次构建会在 build/ 下生成 CMake 缓存、编译产物 zephyr/zephyr.hex。烧录后通过串口查看输出：

west espressif monitor   # 不适用
# 使用 minicom 或 screen
screen /dev/ttyACM0 115200

正常应看到类似输出：

*** Booting Zephyr OS build v3.5.99-ncs1 ***
Hello World! nrf52840dk_nrf52840

若串口无输出，先确认 board 是否选对、J-Link 是否被识别（lsusb 应看到 SEGGER），再检查 west flash 是否成功。nRF52840 DK 的 VCOM 通常映射为 /dev/ttyACM0，波特率 115200。

五、VS Code 配置

安装 VS Code 后，安装 nRF Connect for VS Code 扩展包（包含 nRF Connect、nRF DeviceTree、nRF Kconfig 等）。在设置中指定 NCS 路径与工具链：

nRF Connect › NCS Install Directory：~/ncs
nRF Connect › Toolchain Manager：选择 Zephyr SDK 或 Nordic Toolchain
nRF Connect › Board：nrf52840dk_nrf52840

打开 ncs/nrf/samples/hello_world 目录，扩展会自动识别为 NCS 工程。左侧 nRF Connect 面板提供 Build、Flash、Debug、Memory 等按钮，底层调用的仍是 west 命令。VS Code 的优势在于 Kconfig 与 Devicetree 可视化编辑、断点调试和 RTT 日志查看。

六、环境验证与常见问题

完成上述步骤后，建议按以下顺序验证：west --version、west topdir、arm-zephyr-eabi-gcc --version、west build -b nrf52840dk_nrf52840 nrf/samples/hello_world、west flash、串口输出。任一环节失败，优先检查环境变量是否在当前 shell 生效。

若 west build 报 “ZEPHYR_BASE not set”，说明未执行 west zephyr-export 或未 source venv。若报 “board not found”，检查 board 名称拼写，nRF52840 DK 的 board 是 nrf52840dk_nrf52840，不是 nrf52840_dk。

上图把环境拆成主机层、工具链层、源码层，并给出从 west build 到 west flash 的链路。实际排障时，按层定位：命令找不到属于主机层，编译报错属于工具链层，board 或驱动缺失属于源码层。把这三层都验证通过，nRF52840 DK 的 hello world 就稳定可复现了。