Matter 灯（接入 Apple Home）

仓库地址:https://gitcode.com/hinearlink/samples（本样例位于 ws63/matter_light）

概述

• 标准协议接入：WS63 运行 Matter 协议栈（connectedhomeip），作为标准的「灯」设备（On/Off Light）接入 Apple Home，iPhone「家庭」App 扫码即配、直接控制。
• BLE 配网，免预置凭证：手机通过蓝牙完成安全配对（PASE），Wi-Fi 凭据与设备操作证书都在配网过程中下发——固件里不写死 Wi-Fi 密码，代码可以放心开源。
• 无云本地直连：配网完成后，开关指令走局域网（IPv6 / UDP，CASE 加密会话），不经过任何厂商云。
• 全流程教程：SDK 与子模块获取 → 样例集成 → 关键修改 → 编译 → 烧录 → 测试证书烧写 → iPhone 配网 → 控制闭环，附完整串口日志与 FAQ。

为什么选 Matter：Matter 是连接标准联盟（CSA）主导的智能家居统一应用层协议，Apple、Google、Amazon 等生态共同支持。对开发者来说，一份符合标准的固件可以被不同生态的 App 直接添加，不用为每个云平台单独适配；对用户来说，配网与控制都发生在本地，隐私和响应速度都更有保障。WS63 自带 2.4 GHz Wi-Fi + BLE，恰好满足 Matter over Wi-Fi 设备的硬件要求——BLE 负责配网、Wi-Fi 负责日常控制，本案例把这套组合从编译到控制闭环完整跑通。

演示视频（约 5 秒）：iPhone「家庭」App 里连续点按开关，板载 LED 同步亮 / 灭。

▶ 完整演示视频：videos/demo.mp4

项目结构

ws63/matter_light/
├── README.md                        # 本文
├── images/                          # 教程配图（00~09、12、13 + demo.gif）
├── src/                             # 样例入口（复制进 SDK 的 application/samples/matter/）
│   ├── Kconfig                      # samples/matter 组菜单：Sample 单选框
│   ├── CMakeLists.txt               # samples/matter 组构建入口
│   └── matter_light/                # 样例本体（Kconfig + CMakeLists）
└── videos/
    └── demo.mp4                     # 演示视频完整版

Matter Light 的应用逻辑（lighting-app）位于 SDK 的 connectedhomeip 子模块 examples/lighting-app/hisilicon/，由 libMatter.mk 驱动 GN/Ninja 编译成 libMatterApp.a 整体链接进固件；本样例负责把它接入 application/samples/ 的样例体系，并在下文给出真机跑通所需的关键修改。

开发环境准备

一次性安装构建依赖（同官方 Matter 用户指南）：

sudo apt-get update
sudo apt-get install -y git cmake 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 default-jre

硬件准备

同款开发板购买（WS63-01S）：

• 商品链接：https://www.jlc-yx.com/products/detail/622649373851631617
• 扫码直达：

ESP-01S 烧录器（把 WS63-01S 插在底板上用，本例的烧录与供电都走它）：

• 商品链接：https://e.tb.cn/h.jaQLfzdfKpTSadp?tk=z2YOTrU0LYD

⚠️ 引脚提醒：官方参考设计里灯接在 GPIO_02，而 WS63-01S 板载 LED 接在 GPIO_14。不按第一部分步骤 4 修改，配网和控制都会「成功」，但灯不会亮。

第一部分：编译 Matter 固件

步骤 1：获取 SDK 与子模块

git clone https://gitcode.com/HiSpark/fbb_ws63.git
cd fbb_ws63
git submodule update --init --remote --force

git clone 拉下来的就是完整 SDK 主体（src/application、src/middleware、src/tools 等）；需要单独拉取的只有 Matter 协议栈——它是 src/middleware/services/matter/connectedhomeip 处的 Git 子模块，由上面最后一条命令拉到与 SDK 匹配的固定版本。网络不稳时重复执行即可，已完成的会跳过。

步骤 2：拉取 Matter 协议栈的第三方依赖

cd src/middleware/services/matter/connectedhomeip
./scripts/checkout_submodules.py --shallow --platform hisilicon

⚠️ 这是全流程最大的网络坑：这一步要从 GitHub 拉取 pigweed、mbedtls、lwip、boringssl 等 11 个仓库，直连基本必挂，失败形式是 gnutls_handshake() failed 或 unexpected disconnect。请先配置好代理，例如：

export HTTPS_PROXY=http://127.0.0.1:7890   # 换成你自己的代理地址

失败后直接重跑同一条命令即可，已经拉好的仓库会自动跳过。

步骤 3：复制样例并注册（SDK 侧两处修改）

把本仓库的样例复制进 SDK（在 fbb_ws63 根目录执行）：

mkdir -p src/application/samples/matter
cp -r <本仓库路径>/ws63/matter_light/src/. src/application/samples/matter/

修改 1：src/application/samples/CMakeLists.txt，在 NFC 样例的 endif() 之后（约第 35 行）加上：

if(DEFINED CONFIG_ENABLE_MATTER_SAMPLE)
    add_subdirectory_if_exist(matter)
endif()

修改 2：src/application/samples/Kconfig，在文件末尾追加：

config ENABLE_MATTER_SAMPLE
    bool
    prompt "Enable the Sample of MATTER."
    default n
    depends on SAMPLE_ENABLE
    help
        This option means enable the sample of MATTER.
        需配合 ws63-liteos-matter 目标使用(Matter 栈位于 connectedhomeip 子模块,
        本样例提供构建入口、板级适配与使用说明)。

if ENABLE_MATTER_SAMPLE
osource "application/samples/matter/Kconfig"
endif

这两处就是把新样例接入 SDK 样例体系的标准做法，与 bt / wifi_test 等既有组的注册方式完全一致。

步骤 4：一处关键修改（板载 LED 引脚）

整个样例在 Matter 应用子模块（src/middleware/services/matter/connectedhomeip/）内只需要改这一处。

板载 LED 引脚 —— examples/lighting-app/hisilicon/main/LightingManager.cpp

找到（约第 23 行）：

#define MATTER_LIGHT_PIN GPIO_02

改为：

#define MATTER_LIGHT_PIN GPIO_14

为什么：官方参考设计按 GPIO_02 接灯，WS63-01S 板载 LED 是 GPIO_14。不改的话配网、控制全流程正常（串口照样打印 LightingManager Action ON），只有灯不亮。

步骤 5：menuconfig 勾选样例

cd src
python3 build.py -c ws63-liteos-matter menuconfig

勾选：

• Enable Sample → Enable the Sample of MATTER.
• Sample → Support Matter Light Sample

保存退出。不想用图形界面的话，等价的命令行写法：

python3 build/script/usr_config.py --command setconfig --chip ws63 --core acore \
    --target ws63-liteos-matter ENABLE_MATTER_SAMPLE=y SAMPLE_SUPPORT_MATTER_LIGHT=y

步骤 6：激活构建环境并编译

# 在 fbb_ws63/src/middleware/services/matter/connectedhomeip 下：
source scripts/activate.sh          # 准备 Matter 构建所需的 Python 环境（首次会下载工具，需联网）

# 然后切回 fbb_ws63/src：
cd <fbb_ws63 根目录>/src
python3 -u build.py -c ws63-liteos-matter

首次全量编译约需数十分钟。产物在：

src/output/ws63/fwpkg/ws63-liteos-matter/ws63-liteos-matter_all.fwpkg

⚠️ 首次编译的坑：若第一次编译在 CHIP_CORE 阶段报 /bin/sh: -M: invalid option（表现为每条编译命令开头缺少编译器路径），直接再执行一次 python3 -u build.py -c ws63-liteos-matter 即可——首次运行时输出目录里还没有 args.gn，gn 只拿到空编译器等默认参数；第二次运行 args.gn 已就位，构建正常。全新克隆（2026-10）上实测第一次必现、第二次通过，原因详见 FAQ 7。

第二部分：烧录、证书与配网

步骤 1：烧录固件

开发板插在 ESP-01S 烧录器底板上，通过底板连接电脑（首次使用需安装串口驱动，如 CH340），把 ws63-liteos-matter_all.fwpkg 烧进开发板。使用 near-link 工具仓库（https://gitee.com/hihope_iot/near-link）里的 BurnTool：选择芯片 ws63、对应串口和 fwpkg 固件，勾选 Auto Burn，点击连接后按一下底板上的 RST 键开始烧录（命令行版 BurnToolCmd 随 HiSpark Studio 一起提供，用法见官方 docs/zh-CN/tools/HiSparkStudioforVSCodeUserGuide/ 指南）。

⚠️ _all.fwpkg 是整包固件：烧录会擦除 NV 存储，Matter 测试证书、已配网信息全部丢失。每次整包重烧后，都要重新执行「步骤 2」并重新配网。

步骤 2：烧写 Matter 测试证书

出厂状态没有 Matter 证书，直接配网会在证书这一步失败。上电后打开串口工具（115200 8N1），发送：

AT+MATTERPROVISION

等待约 30 秒，串口打印 ProvisionMatterCertificates success!!! 即成功；随后重启设备（按 RST 键或重新上电）。

烧进去的是官方测试证书（仅供开发调试，不支持商用认证）：

相关的 AT 命令：

这些证书从哪来？

• 开发调试（本样例）：直接用 connectedhomeip 仓库自带的 CSA 官方测试证书，不需要申请。证书本体在子模块的 credentials/test/attestation/（DAC、PAI，如 Chip-Test-DAC-FFF2-8001-0008）与 credentials/test/certification-declaration/（CD）；SDK 已把这组证书硬编码在 src/platform/hisilicon/MatterAtCmd.cpp（sTestCD / sTestDAC / sTestPAI / sTestDACKey / kDacPublicKey 五个字节数组），AT+MATTERPROVISION 做的就是把它们加密写进 NV——所以开发阶段「获取证书」就是执行这条 AT 命令，不需要你另外准备证书文件。想换一组证书：替换这五个数组后重新编译（或改成从产线数据读取）；官方 credentials/development/attestation/ 目录另有一套自签开发证书可选。
• 量产产品：测试证书在配网时 iOS 会提示「未认证配件」。正式产品要走 CSA 认证流程：加入 CSA 取得 Vendor ID → 通过 CSA 认可的服务商申请 PAI 证书 → 用 PAI 为每台设备签发 DAC；CD 在 CSA 系统完成产品注册后生成，最后随产线数据写入每台设备。

步骤 3：iPhone「家庭」App 配网

1. 板子重新上电后，串口会打印配网二维码与配对码：

chip[SVR] SetupQRCode: [MT:-24J042C00KA0648G00]
chip[SVR] Copy/paste the below URL in a browser to see the QR Code:
chip[SVR] https://project-chip.github.io/connectedhomeip/qrcode.html?data=MT%3A-24J042C00KA0648G00
chip[SVR] Manual pairing code: [34970112332]

把第二行 URL 在电脑浏览器里打开就能看到本机的配网二维码（也可以用手边的二维码工具把 MT: 开头的字符串生成二维码）。

二维码 / 配对码从哪来？ 它们不是从哪个平台下载的，而是设备根据自身参数在开机时生成的 onboarding payload（内容是鉴别码 discriminator、PIN、厂商/产品 ID 与配网方式），上电时自动打印在串口——上面的 payload、手动配对码与渲染链接就是全部信息。

• 参数当前取值是测试默认值：PIN 20202021、鉴别码 3840（0xF00，BLE 广播名 HISI-MATTER-3840 里的数字即鉴别码），定义在子模块 src/platform/hisilicon/CHIPDevicePlatformConfig.h；设备 NV 里写有 factory data 时以 NV 为准。
• 也可以用工具离线生成同样的 payload（比如想在其它电脑上出图）：

chip-tool payload generate-qrcode --discriminator 3840 --passcode 20202021 \
    --vendor-id 0xFFF1 --product-id 0x8001 --commissioning-flow 0

• 量产：产线为每台设备生成唯一的鉴别码与 PIN（写入设备 NV），并生成对应二维码印刷在设备标签上。

1. 打开 iPhone「家庭」App，点右上角「+」，选择「添加配件」。

1. 扫描步骤 1 生成的二维码，出现钥匙串提示后点「设置」。

1. 出现「未认证配件」提示是正常现象——用的是官方测试证书，点「仍然添加」。

1. 手机与板子建立蓝牙连接，自动把 Wi-Fi 凭据下发给板子，等待设备入网（1~2 分钟内完成都属正常）。

1. 添加完成。首页出现设备卡片（默认名「Matter Accessory」，可在 App 内重命名），点卡片即可控制。

步骤 4：控制闭环

点开关，板载蓝灯同步亮 / 灭，串口同步打印：

chip[ZCL] Toggle ep1 on/off from state 0 to 1
chip[-] LightingManager Action ON, ret:0x0
chip[ZCL] Toggle ep1 on/off from state 1 to 0
chip[-] LightingManager Action OFF ret:0x0

运行现象

一次完整「配网 → 控制」的串口关键日志如下（按阶段归类摘录，行间不一定与原始日志严格相邻；... 处为省略说明）：

chip[DL] BLEManagerImpl:SetAdvertisingData:419 mDeviceName=HISI-MATTER-3840
chip[DL] slow advertising
...（省略：NV 初始化、事件循环等启动日志）
chip[SVR] SetupQRCode: [MT:-24J042C00KA0648G00]
chip[SVR] Manual pairing code: [34970112332]
...（手机扫码、建立 BLE 连接、PASE 安全配对）
chip[EM] >>> [E:34357r S:0 M:185231458] (U) Msg RX from 0:39C93F0E796D36CB [0000] to 0000000000000000 --- Type 0000:22 (SecureChannel:PASE_Pake1) (B:92)
chip[EM] <<< [E:34357r S:0 M:239662479] (U) Msg TX from 0000000000000000 to 0:39C93F0E796D36CB [0000] [BLE] --- Type 0000:23 (SecureChannel:PASE_Pake2) (B:127)
chip[SC] SecureSession[0xa2ada8, LSID:16158]: State change 'kEstablishing' --> 'kActive'
chip[SVR] Commissioning completed session establishment step
...（签发设备操作证书，创建 fabric）
chip[ZCL] OpCreds: Received an AddNOC command
chip[DIS] mDNS service published: _matter._tcp
chip[ZCL] OpCreds: successfully created fabric index 0x1 via AddNOC
...（向板子下发 Wi-Fi 凭据，设备开始入网）
chip[NP] HisiWiFiDriver::NetworkMatch
chip[NP] NetworkCommissioningDelegate: SSID: <你的路由器 SSID>
...（省略：DHCP 过程）
+NOTICE:CONNECTED
chip[NP] wifi_check_dhcp_status::STA DHCP success.
...（配网收尾）
chip[FS] GeneralCommissioning: Received CommissioningComplete
chip[SVR] Commissioning completed successfully
[Disconnected] addr:<手机 BLE 地址>, conn_id:00
...（BLE 断开属于正常收尾：配网完成，设备转入 Wi-Fi 局域网控制）
...（在「家庭」App 里点开关，指令经 Wi-Fi 局域网到达）
chip[ZCL] Toggle ep1 on/off from state 0 to 1
chip[-] LightingManager Action ON, ret:0x0
...（再点一次）
chip[ZCL] Toggle ep1 on/off from state 1 to 0
chip[-] LightingManager Action OFF ret:0x0

说明：串口实际打印的是你配网时选择的真实 Wi-Fi 名称，此处以占位符代替。配网完成后手机会主动断开 BLE 连接（[Disconnected]），设备转入 Wi-Fi 局域网控制，属正常收尾。

常见问题（FAQ）

1. 配网时手机连上就断（蓝牙调试 App 报 "Peer removed pairing information"）

现象：设备广播正常、手机能扫到 HISI-MATTER-3840，但一配对就断，反复重试都配不上；用蓝牙调试 App 手动连接，会直接弹出 Peer removed pairing information。

原因：iOS 13.4+ 的陈旧 BLE 配对信息（bond）死锁。iPhone 里还留着这块板子上一次配对时保存的密钥，而重烧固件后板子侧的密钥没了，两边对不上；iOS 会拒绝对话并拒绝重新配对，而 CoreBluetooth 没有公开 API 能清除手机侧的记录（这类纯 BLE 设备在手机蓝牙设置里也不显示）。

解法：在手机侧清掉旧记录，让 iPhone 把板子当成一台全新设备，按顺序做：

1. 「家庭」App 里移除旧配件：点开配件 → 设置 → 移除配件；
2. 设置 → 蓝牙，列表里如果有 HISI-MATTER-3840，点「忽略此设备」；
3. 蓝牙关一下再开；如果仍然复现，重启一次手机。

清理完重新配网即可。首次在全新手机上配网一般不会遇到这个问题。

2. 配网失败 / 中断一次之后，手机搜不到设备

现象：第一次配网中途取消或失败后，短时间内手机扫不到设备。

处理：按一下板子上的 RST（或重新上电），等串口重新出现 chip[DL] CHIPoBLE advertising started 后重新配网即可。

3. 配网最后提示「配件已添加到其他家庭」

现象：配网收尾时弹出上图提示（「Matter Accessory 已添加到此家庭。」）。

原因：设备 NV 里残留着更早一次配网留下的 fabric 信息（比如这块板子之前配过网、没有清干净）。

处理：点「好」继续即可完成本次添加；想彻底清掉旧记录，先发送 AT+MATTERRESET 再重新配网。注意 AT+MATTERRESET 会连测试证书一起清掉，重置后要重新执行 AT+MATTERPROVISION。

4. 配网途中弹窗提示「未认证配件」

现象：配网过程中出现「此配件尚未认证可与你的家配合使用……」（见第二部分步骤 3 第 4 步截图）。

原因：烧写的是官方测试证书，不是 CSA 认证的产品证书，iOS 对未认证配件会给出提示。

处理：点「仍然添加」即可，功能不受影响。正式产品必须使用 CSA 认证的 DAC 证书（证书的获取方式见第二部分步骤 2）。

5. 重烧固件后配不上网 / 提示证书相关错误

现象：重新烧录 _all.fwpkg 后，串口配网日志出现证书相关报错，或配网流程走不下去。

原因：整包烧录会擦除 NV，测试证书没了。

处理：重新发送一次 AT+MATTERPROVISION（等约 30 秒出现 success 后重启设备），再重新配网。

6. 配网全部成功、串口也打印 Action ON，但板载 LED 不亮

现象：App 控制正常、日志正常，只有灯没反应。

原因：MATTER_LIGHT_PIN 还是参考设计的 GPIO_02。

处理：见第一部分步骤 4，按自己板子的原理图改成实际引脚（WS63-01S 为 GPIO_14），重新编译烧录。

7. 编译 / 环境疑难

• checkout_submodules.py 与 activate.sh 都需要访问 GitHub，失败先排查网络与代理；checkout_submodules.py 可以反复重跑（已完成的仓库会自动跳过）。
• 必须在 WSL 的 Linux 文件系统内构建（如 ~/fbb_ws63），不要放在 /mnt/c、/mnt/d 下。
• 编译前记得先在 connectedhomeip 目录执行 source scripts/activate.sh（提供 Matter 构建所需的 Python 环境与 gn/ninja 构建工具）；它返回 0 不代表万事大吉——代理不稳时内部的 cipd 下载会报 ssl.SSLEOFError，gn/ninja 实际没装上，编译到 Matter 库这一步才报 gn: command not found。排查方法：which gn ninja 有输出才算成功；失败就删掉 connectedhomeip/.environment 再重跑 source scripts/activate.sh（先确认代理可用）。
• 首次编译在 CHIP_CORE 阶段报 /bin/sh: -M: invalid option：这是输出目录里 args.gn 尚未就位的缘故——它由 libMatter.mk 在 gn gen 之后才拷贝进输出目录，首次运行时 gn 只拿到空编译器等默认参数，生成的 toolchain.ninja 里编译命令没有编译器路径。重跑一次 python3 -u build.py -c ws63-liteos-matter 即可（第二次 args.gn 已就位）；全新克隆（2026-10）上实测第一次必现、第二次通过。自查方法：grep "command = " output/ws63/acore/ws63-liteos-matter/matter_build/out/ws63/toolchain.ninja，正常应能看到 riscv32-linux-musl-g++ 的完整路径。
• 更多官方参考：SDK 仓库 docs/zh-CN/software/Matter用户指南/。

协议速查

注意事项

• 测试证书仅供开发调试：Matter 测试证书不支持商用，正式产品需使用 CSA 认证的证书。
• 整包固件（_all.fwpkg）烧录会擦除 NV：证书与配网信息全部丢失，请按第二部分步骤 2 重灌后配网。
• WS63 仅支持 2.4 GHz Wi-Fi，配网时下发的路由器凭据必须是 2.4 GHz 频段。
• 本文实测覆盖 connectedhomeip 子模块 0b387896 与全新克隆（2026-10 官方 --remote 步骤）拿到的 e52b1acf 两个版本，关键修改（LightingManager.cpp 的 LED 引脚）在两版上逐字一致；若上游后续更新导致行文对不上，以第一节的思路自行定位。
• 板载 LED 引脚随开发板型号不同而不同，请以自己的原理图为准。

作者：GaoXiaolong
邮箱：gaoxiaolon@gmail.com
日期：2026.10.12