本文不再重复 ESP-IDF、ESP-Matter、WSL 和基础 Matter 环境的搭建。相关内容可以先参考：
本文主要关注 OTA 本身，以及 Fabric、Node ID、控制器凭证不匹配时的排查方法。
一、Matter OTA 中有哪些角色
一次完整的 Matter OTA 至少涉及三个角色：
本文实测环境：
项目 | 参数 |
待升级设备 | WS6GW Zigbee-Matter Bridge |
DUT Node ID | 0x12344321 |
DUT Endpoint | 0 |
当前 Matter 版本 | 65536 / 1.0.0 |
目标 Matter 版本 | 65537 / 1.0.1 |
当前 ZC 版本 | 46 |
目标 ZC 版本 | 47 |
Provider Node ID | 0xDEADBEEF |
Provider Discriminator | 22 |
Provider Passcode | 20202021 |
控制器 Node ID | 112233 / 0x1B669 |
二、编译 chip-tool 和 OTA Provider
进入 connectedhomeip：
1. 编译 chip-tool
生成文件：
检查：
2. 编译 Linux OTA Provider
生成文件：
检查：
OTA Provider 的
--filepath、ACL 和 QueryImage 行为可以参考 connectedhomeip 的官方 OTA Provider README。三、准备 Matter OTA 文件
本次使用的 OTA 文件：
虽然文件扩展名是
.bin，但它并不是普通 ESP-IDF 应用固件，而是带有 Matter OTA Header 的升级镜像。可以使用官方工具查看 Header：
本次镜像的关键信息：
计算文件摘要：
本次文件：
注意：
- OTA Header 中的版本必须高于设备当前版本。
- Provider 提供的是完整 Matter OTA 镜像，不是普通 app.bin。
- 本项目的 Matter OTA 镜像内部还携带 ZC 47 固件。
- 网关升级到 Matter 1.0.1 并重启后，会继续自动执行 ZC 46 → 47。
四、确认 chip-tool 使用了正确的 Fabric
这是整个流程中最容易踩坑的地方。
Matter Node ID 只在特定 Fabric 中有效。只知道 Node ID，但使用了另一套控制器凭证，设备仍然无法访问。
例如，错误控制器查找的是：
而设备实际发布的是：
即使 Node ID 都是 0x12344321，由于 Compressed Fabric ID 不同，也无法建立 CASE 会话。
本次控制器凭证的位置
此前认证自测使用的是 Python Matter 测试控制器，凭证保存在：
而默认运行 chip-tool 时，加载的是另一套
/tmp/chip_tool_* 凭证。因此，本次将正确控制器凭证转换到单独目录：
转换示例：
这些文件包含 Fabric 私钥，不能提交到 Git，也不要上传到博客或公开网盘。
验证 DUT 是否可访问
本次实测成功日志：
只有这一步成功后，才继续测试 OTA。
五、启动 OTA Provider
打开终端一：
这里真正指定 OTA 文件的是
--filepath "$OTA_IMAGE"。Provider 启动后，需要保持该终端运行。后续 QueryImage、BDX 下载和 ApplyUpdate 都可以在这里观察。
六、将 OTA Provider 加入同一个 Fabric
OTA Provider 本身也是一个 Matter Node，因此必须加入和 DUT 相同的 Fabric。
打开终端二：
首次配网 Provider：
这条命令走的是 On-Network Commissioning：
- 电脑和 Provider 已经处于同一局域网。
- 不配置 Wi-Fi。
- 不通过 BLE 传输网络凭证。
- 0xDEADBEEF 是本次分配给 Provider 的 Node ID。
成功标志：
只要
/tmp/ws6gw-ota-provider-kvs 保留，后续重启 Provider 不需要再次配网。七、配置 OTA Provider 的 ACL
OTA Requestor 会主动向 Provider 发送 QueryImage。如果 Provider 没有授权 DUT 访问 OTA Provider Cluster，就可能出现 UnsupportedAccess。
先读取 Provider 当前 ACL：
对于刚刚首次配网的 Provider，可以写入：
两条 ACL 的含义：
- 允许默认控制器 Node ID 112233 管理 Provider。
- 允许 Fabric 内节点以 Operate 权限访问 OTA Provider Cluster，也就是 Cluster 41/0x0029。
ACL 属性是一个列表。写入时会替换整个列表，因此不能只写新增项，必须保留原来的管理员条目。connectedhomeip 的官方 Provider 文档也特别说明了这一点。
测试环境可以允许 Fabric 内全部节点访问；产品环境建议把第二条 ACL 的 subjects 收紧到指定 OTA Requestor。
八、触发 OTA
确认以下条件：
- DUT 可以被正确的控制器读取。
- Provider 仍在运行。
- Provider 已加入 DUT 所在 Fabric。
- ACL 已配置。
- OTA 文件 Header 版本高于 DUT 当前版本。
然后发送 AnnounceOTAProvider：
参数依次为：
本次参数：
参数 | 值 |
ProviderNodeID | 0xDEADBEEF |
VendorID | 0 |
AnnouncementReason | 0，Simple Announcement |
ProviderEndpoint | 0 |
DUTNodeID | 0x12344321 |
DUTEndpoint | 0 |
AnnounceOTAProvider 成功只代表 DUT 收到了 Provider 信息，不等于整个 OTA 已成功。
九、观察 OTA 过程
在 Provider 终端中，正常流程大致为：
DUT 侧通常会经历：
完整 OTA 的判断链应该是：
不能只看到 chip-tool 的 Invoke Success 就判定 OTA 成功。
十、升级结果验证
等待 DUT 重启并重新发布 operational mDNS 后，读取软件版本：
读取版本字符串：
Matter OTA 成功后的期望结果：
检查内嵌 ZC 固件
本项目的新 Matter 固件启动约 12 秒后，会检测 HMBN Bundle，并自动执行 ZC 46 → 47。
通过 USB 串口输入：
最终期望：
至此可以确认：
十一、常见问题
1. Timeout waiting for mDNS resolution
典型日志：
先查看设备启动日志中的：
如果设备发布的是：
而 chip-tool 查找的是：
说明控制器凭证不匹配。此时修改 Node ID 没有意义，需要换回正确的
--storage-directory。2. Node ID 很长，是不是错误
不是。Matter Node ID 是 Commissioner 配网时分配的 64 位标识：
和：
都可以成为合法 Node ID。
关键不在长短，而在于它是否属于当前 Fabric。
3. Provider 启动了，但没有发送文件
检查启动命令是否带有
--filepath /path/to/matter-ota-image。announce-otaprovider 不负责指定文件。OTA 文件是在启动 Provider 时通过 --filepath 选定的。4. Provider 返回 UnsupportedAccess
优先检查 Provider ACL，确保 OTA Requestor 有权限访问 Cluster 0x0029。
5. QueryImage 返回 UpdateNotAvailable
检查：
- OTA Header 中的 Version 是否高于当前版本。
- Vendor ID、Product ID 是否符合 Requestor 的筛选逻辑。
- 文件是否为 Matter OTA 镜像，而不是普通应用固件。
ota_image_tool.py show能否正确解析。
6. 找错串口设备
多台开发板同时连接时，不能只按“最新日志”判断目标设备。
例如本次环境：
日志第一行通常会记录实际串口：
同时还应核对：
- Wi-Fi SSID
- Matter Fabric ID
- Node ID
- 网关 MAC/设备标识
- 子设备数量
- reboot-count
十二、后续重复测试的最短流程
只要下面两份存储仍在：
后续不需要再次配网 Provider，也不需要重复写 ACL。
终端一启动 Provider：
终端二触发 OTA：
升级后读回版本：
总结
Matter OTA 表面上只是“给设备发一个升级包”，但真正决定成败的是四个条件：
- OTA 文件必须带有效的 Matter OTA Header。
- OTA Provider 和 Requestor 必须处于同一个 Fabric。
- Provider ACL 必须允许 Requestor 查询和下载镜像。
- 最终必须通过版本读回和设备运行日志确认升级结果。
其中最容易忽略的是控制器凭证。Node ID 相同不代表设备可访问，必须同时保证 Compressed Fabric ID 一致。把
--storage-directory 固定下来，并在正式 OTA 前先读取一次 SoftwareVersion，可以省掉大量无效排查。- 作者:L_Z_J
- 链接:https://www.mcoi.top/article/Post-matter-ota-chip-tool-provider-bdx
- 声明:本文采用 CC BY-NC-SA 4.0 许可协议，转载请注明出处。
