📚 课程目录第3章开发环境搭建与首个BLE配网工程

3. 开发环境搭建与首个BLE配网工程

Matter 设备在量产前必须完成一次“入网”动作，而 BLE 配网是当前最主流的 commissioning 通道：手机 App 通过 BLE 把 Wi-Fi 凭据、Thread 数据集和操作证书传给设备，设备再切换到目标网络。要跑通这条链路，第一步不是写业务代码，而是把 SDK、工具链、烧录与抓包环境搭起来。本节以“能编译、能烧录、能广播、能抓包”为验收目标，给出可复现的搭建路径。

一、SDK 选型：先定芯片，再定 SDK

Matter SDK（connectedhomeip）本身是“协议栈 + 示例应用”的集合，它并不直接提供芯片外设驱动，而是通过平台适配层对接各家 SDK。因此选型顺序是：先确定目标芯片/模组，再选择其官方 SDK 作为构建底座。常见组合如下：

目标平台	构建底座	典型芯片	适用场景
Nordic	nRF Connect SDK（基于 Zephyr）	nRF52840、nRF5340	Thread + BLE 双模，低功耗传感器
Espressif	ESP-IDF	ESP32-C3、ESP32-S3	Wi-Fi 配网，成本敏感型照明/插座
Silicon Labs	Gecko SDK + Matter 扩展	EFR32MG24	Thread 边界路由器、多协议网关
通用验证	Zephyr 原生 + Matter 模块	nRF52 / EFR32 开发板	学习协议栈、做最小化移植

如果目标是“最快看到 BLE 广播”，推荐 Nordic nRF52840 DK + nRF Connect SDK；如果目标是“最快连上 Wi-Fi”，推荐 ESP32-C3 + ESP-IDF。两者都能在 Linux/macOS 上完成构建，Windows 建议使用 WSL2。

二、工具链与依赖安装

Matter 构建依赖 Python 3.10+、Git、Ninja、GN 以及各平台自己的工具链。以 Ubuntu 22.04 为例，先装系统依赖：

sudo apt update
sudo apt install -y git python3 python3-pip python3-venv ninja-build \
  gcc g++ cmake libssl-dev libdbus-1-dev libglib2.0-dev \
  libavahi-client-dev pkg-config unzip

# 获取 Matter SDK（含子模块）
git clone --depth 1 --recursive https://github.com/project-chip/connectedhomeip.git
cd connectedhomeip
./scripts/checkout_submodules.py --shallow --platform linux

# 激活 Matter 环境（会安装 pigweed、zap 等工具）
source scripts/activate.sh

若使用 nRF Connect SDK，还需安装 west 并初始化：

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

ESP-IDF 则通过官方安装脚本完成：

git clone -b v5.1.2 --recursive https://github.com/espressif/esp-idf.git
cd esp-idf && ./install.sh esp32c3
. ./export.sh

建议把 source scripts/activate.sh 或 . ./export.sh 写入 shell 启动脚本，否则每次新开终端都要重新激活，容易出现“命令找不到”的假故障。

三、编译与烧录首个 BLE 配网示例

Matter 仓库自带 examples/lighting-app，它默认开启 BLE 配网。以 nRF52840 DK 为例，构建命令如下：

cd connectedhomeip
./scripts/examples/gn_build_example.sh \
  examples/lighting-app/nrfconnect \
  out/lighting-app-nrf \
  nrfconnect

编译成功后，产物位于 out/lighting-app-nrf/，其中 lighting-app.hex 是烧录文件。使用 west 烧录：

west flash --hex-file out/lighting-app-nrf/lighting-app.hex

ESP32-C3 的构建方式不同，使用 idf.py：

cd examples/lighting-app/esp32
idf.py set-target esp32c3
idf.py build
idf.py -p /dev/ttyUSB0 flash monitor

烧录后设备复位，若 BLE 配网已启用，串口会打印类似 BLE advertising started 的日志，并给出设备判别名（Discriminator）和配对码（Passcode）。这两个参数是手机 App 发现并连接设备的关键。

四、BLE 广播抓包验证

“能烧录”不等于“广播正确”。必须用抓包确认广播包中确实携带了 Matter 的配网服务 UUID 和厂商数据。推荐使用 nRF Sniffer + Wireshark：把 Sniffer 固件烧到第二块 nRF52840 Dongle，Wireshark 选择 nRF Sniffer for Bluetooth LE 接口，过滤 btle.advertising_address 或直接看 ADV_IND。

Matter 设备广播中应能看到：Flags、Complete Local Name（如 MATTER-1234）、16-bit Service UUID（0xFFF6，Matter 配网服务）以及 Service Data（包含 Discriminator、Vendor ID、Product ID）。如果只看到名字没有 Service Data，说明配网广播未正确初始化，需检查 CHIP_DEVICE_CONFIG_ENABLE_BLE 是否打开。

五、常见问题与判断依据

搭建过程中最容易卡住的不是代码，而是环境与广播状态。下面给出几个典型现象和对应判断：

编译报 “gn: command not found”：没有执行 source scripts/activate.sh，或 Python 虚拟环境未激活。
west flash 找不到板子：检查 USB 线是否支持数据、ls /dev/ttyACM* 是否存在，必要时安装 udev 规则。
串口有日志但手机搜不到设备：确认广播是否真的启动，用 Sniffer 看空口；若空口无包，多半是 BLE 初始化失败或天线未接。
抓包看到广播但没有 Service Data：Matter 配网广播未填充，检查 CHIP_DEVICE_CONFIG_ENABLE_BLE 与 CHIP_DEVICE_CONFIG_USE_TEST_SETUP_PIN_CODE 配置。

不要用“手机能搜到蓝牙名字”作为配网成功的唯一依据。普通 BLE 广播和 Matter 配网广播的区别在于是否携带 0xFFF6 服务数据，必须抓包确认。

完成以上步骤后，你应当得到一个可编译、可烧录、可被 Sniffer 捕获到 Matter 配网广播的工程。此时再打开手机上的 Matter 调试 App（如 chip-tool 或厂商 App），就能进入真正的配网流程：扫描二维码、建立 BLE 连接、下发 Wi-Fi 凭据、设备切换网络并上报完成。环境搭建的价值正在于此——它把“协议能不能跑”变成“空口上能不能看到”，让后续每一步调试都有据可查。