4. 搭建Matter over WiFi开发环境

Matter over WiFi 的开发环境搭建，本质上是把一条“从源码到可运行节点”的链路打通：硬件提供射频与算力，SDK 提供协议栈与示例，工具链负责编译，烧录工具把固件写入芯片，最后通过配网与日志确认节点真正上线。本节以 ESP32 系列为例，给出可复现的搭建路径，并说明每一步的输入、操作与判断依据。

一、硬件选型：先确定“能跑 Matter”的最小系统

Matter over WiFi 节点需要同时具备 WiFi 射频、足够的 Flash 与 RAM、以及可被 SDK 支持的 SoC。常见选择是 ESP32-C3、ESP32-S3 或 ESP32（经典款）。其中 ESP32-C3 为 RISC-V 单核，成本低、WiFi 能力完整，适合做灯、插座等轻量节点；ESP32-S3 双核、带 AI 指令与更多 GPIO，适合带屏或传感器聚合的节点。若使用 ESP32 经典款，需注意其蓝牙与 WiFi 共存时的内存余量。

除主控外，还需要一块开发板（如 ESP32-C3-DevKitM-1）、USB 数据线（必须支持数据传输，而非仅充电）、以及一个 2.4 GHz WiFi 路由器。Matter 目前主要运行在 2.4 GHz 频段，5 GHz SSID 无法用于配网。若要做 Thread 边界路由器实验，可另备一块支持 802.15.4 的板卡，但本节只聚焦 WiFi。

二、SDK 获取：用 esp-matter 而不是裸 ESP-IDF

Matter 协议栈由 connectedhomeip 提供，乐鑫在其上封装了 esp-matter，包含 ESP-IDF 适配层、示例与构建脚本。推荐使用 esp-matter 的 release 分支，避免 master 的频繁变动。获取方式如下：

# 1. 安装依赖（Ubuntu 示例）
sudo apt-get install git gcc g++ pkg-config libssl-dev libdbus-1-dev \
  libglib2.0-dev libavahi-client-dev ninja-build python3-venv python3-dev \
  python3-pip unzip libgirepository1.0-dev libcairo2-dev libreadline-dev

# 2. 获取 esp-idf（esp-matter 要求特定版本）
git clone -b v5.1.2 --recursive https://github.com/espressif/esp-idf.git
cd esp-idf && ./install.sh esp32c3

# 3. 获取 esp-matter
cd ~
git clone -b release/v1.2 --recursive https://github.com/espressif/esp-matter.git
cd esp-matter
./install.sh

安装完成后，每次新开终端都要先激活环境：先执行 . $HOME/esp-idf/export.sh，再执行 . $HOME/esp-matter/export.sh。判断是否成功，可运行 idf.py --version 与 echo $ESP_MATTER_PATH，两者都能输出有效路径即表示环境变量就绪。

三、工具链安装：编译、烧录、监视三件套

ESP-IDF 的工具链包含 xtensa-esp32-elf 或 riscv32-esp-elf 交叉编译器、CMake、Ninja、esptool.py 与 idf.py。安装脚本会自动下载对应芯片的编译器。烧录依赖 esptool，监视依赖 idf.py monitor。若在 Linux 下遇到串口权限问题，需把当前用户加入 dialout 组：

sudo usermod -aG dialout $USER
# 重新登录后生效，插上开发板确认设备节点
ls /dev/ttyUSB*   # 常见为 /dev/ttyUSB0

在 macOS 上设备名通常为 /dev/cu.usbserial-* 或 /dev/cu.wchusbserial*。Windows 则需安装 CP210x 或 CH34x 驱动，设备管理器中会出现 COM 口。工具链是否可用，可用 idf.py --list-targets 验证，能列出 esp32c3 等目标即正常。

四、示例工程编译与烧录：以 light 为例

esp-matter 自带 examples/light，实现一个可被 Matter 控制器点亮的灯节点。进入目录后设置目标芯片并编译：

cd $ESP_MATTER_PATH/examples/light
idf.py set-target esp32c3
idf.py build

编译成功会生成 build/light.bin 等文件。若报错找不到 esp_matter 组件，通常是未执行 export.sh 或 ESP_MATTER_PATH 未设置。烧录与监视：

idf.py -p /dev/ttyUSB0 flash monitor

烧录完成后串口会输出启动日志。关键判断点有三个：一是出现 CHIP:IN: ... DeviceLayer initialized，说明协议栈已初始化；二是出现二维码或手动配对码（如 34970112332），这是配网凭证；三是出现 CHIP:DL: ... WiFi station started，说明 WiFi 已进入待配网状态。若卡在 Failed to initialize，优先检查 Flash 分区表是否与示例匹配。

五、完成第一个可运行节点：配网与验证

用手机安装支持 Matter 的控制器（如 Google Home、Apple Home 或 chip-tool）。以 chip-tool 为例，在 PC 上执行：

# 配网：把节点加入 WiFi
./chip-tool pairing ble-wifi 1 MySSID MyPassword 20202021 3840

# 读取 OnOff 属性，确认节点在线
./chip-tool onoff read on-off 1 1

其中 20202021 是示例默认的 setup passcode，3840 是 discriminator。配网成功后，节点会打印 CHIP:DL: ... Connected to WiFi，并可通过 onoff toggle 控制灯的开闭。若配网失败，常见原因是 SSID 为 5 GHz、密码含特殊字符、或手机与节点不在同一网段。此时可先用串口日志确认节点是否已进入 BLE advertising 状态，再排查路由器设置。

六、可复用的环境检查清单

把上述过程固化为一张检查表，可在换机或换板时快速定位问题。表中“判断依据”一列是实际可观察的输出，而非主观感受。