Matter 网关联调怎么验收：从串口通信到 Apple Home 状态同步

开发板接好，手机点一下，灯亮了。做智能家居项目，很容易在这一刻觉得最难的部分已经过去。

接着拔掉灯的电源，手机里可能还显示它开着；重启网关，设备可能又要配一次；用灯上的按键关灯，Apple Home 里的图标却没有变化。

这些问题分别落在命令执行、状态同步和数据恢复上。只做一次开灯演示，很难看出来。

上一篇开发板采购清单解决了验证需要哪些硬件。这一篇接着往下走：板子到手后，第一轮联调应该留下什么证据，满足哪些条件，才能进入下一阶段。

目前，电脑上的 Matter 原型已经接入 Apple Home，Linux 镜像也已经构建完成。芯科 NCP 与泰凌设备的实际互通、真实灯具的状态回传，以及整条链路的故障恢复仍待验证。下面是我给这个项目整理的首轮验收方案，具体结果要等硬件测试后再填。

先缩小到一盏灯，把版本固定下来

我们的链路是 Apple Home 通过局域网连接 Linux 网关，网关通过 UART/BGAPI 调用芯科 Bluetooth Mesh NCP，再由 NCP 控制泰凌 Mesh 设备。灯具的状态还要沿着这条路径返回。

首轮只接一台设备，先验证最简单的开关功能。调光、色温、场景和多路开关都往后放。这个时候增加设备种类，只会让同一个失败出现更多解释。

测试前记录好主机程序提交、NCP 固件与 SDK 版本、设备固件版本，以及串口参数。接线也拍照留底，特别是电平、共地和 RTS/CTS。不要一边升级主机程序，一边换模组固件，最后只记得“改了以后好了”。

先用所选 SDK 配套的主机示例验证 NCP 和设备，再换成自己的 Rust 主机程序。两边使用同一套硬件和固件，才有比较价值。若官方示例也控制不了设备，应先查固件能力和模型配置；若示例能用而自己的程序不能，再检查帧解析和调用顺序。

把“成功”拆成四层

一次开灯，至少需要区分下面四件事。

层次	能说明什么	还不能说明什么
主机写入串口	数据交给了串口接口	NCP 已正确解析
收到 BGAPI 响应	NCP 对这次 API 调用给出了结果	远端灯具已经执行
收到设备状态	远端模型报告了当前或目标状态	Matter 属性和手机界面已同步
Apple Home 显示一致	用户看到的状态与这次验证结果一致	重启或掉线之后仍然可靠

BGAPI 响应的具体含义要看对应命令文档，不能把所有返回成功都解释成灯已打开。异步事件也可能和命令响应交错到达，解析程序不能只按“发一条、读一条”的直觉处理。

主机日志需要能串起一次操作。我会在应用内部给操作分配一个编号，记录目标设备、目标状态、发送时间、API 响应、相关状态事件和最终结果。这个编号由主机自己维护，并不意味着 BGAPI 或每一种 Mesh 消息都会原样带回它。

首轮同一设备只保留一个待完成操作，先降低关联难度。收到状态时还要检查来源地址、元素、模型和时间范围，不能把旁边设备的上报，或者操作前的旧状态，算作本次成功。

配网完成后，还要检查模型配置

“设备加进网络了”值得记录，但距离能控制它还有一段。

需要读取 Composition Data，确认目标功能在哪个元素、支持哪个模型；再按模型和通信方式完成 AppKey 添加、模型绑定，以及必要的发布、订阅配置。不同设备固件即使都标着 Bluetooth Mesh，也可能只在部分标准模型上重合。厂商私有功能还需要单独适配。

首轮先用单播，控制一个明确地址上的开关模型，优先选择有确认响应的操作，再用状态查询交叉核对。这样出现失败时，可以逐项检查地址、密钥绑定、模型能力和状态接收，不必同时排查组地址及多个节点的响应。

这里还要区分两种回程：控制后收到响应，以及设备主动发布状态。前者能通，不代表后者已经配置好。物理按键改变状态后，如果设备固件支持相应状态发布，就检查发布配置和接收路径；如果它不会主动发布，就需要评估轮询补偿及其延迟，不能直接承诺实时同步。

三条操作路径，要分别验收

第一条是从主机控制灯。先不接 Matter，发出开关命令，检查灯的实际变化，再检查返回的状态。若设备支持渐变，还要区分当前值、目标值和剩余过渡时间，避免把“准备变到这个值”当作“已经到了这个值”。

第二条是从灯改变主机状态。用设备自身支持的按键或另一条已知控制路径改变灯，主机不主动发送开关命令，观察能否收到新状态。这一条专门验证回传，不能用“发一次查询就对了”代替主动上报的验收。若采用轮询方案，就单独记录它的更新时间。

第三条才是 Apple Home 控制真实灯具：手机发命令，灯执行，状态进入网关，再由 Matter 属性更新和报告机制传给控制器。随后从灯端改变状态，确认手机也跟着变。

如果主机已经拿到新状态，Apple Home 却没更新，排查范围就能缩到设备映射、属性更新和订阅报告这一段。此时重新配网通常只会打断线索。

我会把“期望状态”和“最近确认的实际状态”分开保存。手机请求开灯时，可以产生一个待确认操作；设备报告开灯后，才更新确认状态。需要乐观显示的话，也必须定义超时和纠正行为。灯断电后，不能仅凭命令成功写进串口，就持续把它记成已打开。

给第一轮设一个明确的通过条件

没有等待时间和重复次数，“偶尔有点慢”很容易变成一个长期搁置的问题。

我的首轮计划是：在固定的近距离、单灯测试环境里，连续做 20 轮开关，每轮等上一次结束再继续；每次分别记录物理变化、设备状态返回和手机显示更新的耗时。先把 5 秒设为本轮端到端等待上限，超时就记失败并留下日志。

20 轮和 5 秒都是这个项目暂定的测试门槛，不是 Matter 或 Bluetooth Mesh 标准要求，也不是已经测出的性能。 它们用于让首轮结果可比较，后面再根据设备能力和使用体验收紧。

通过标准是这批操作没有无法解释的状态错误、没有超时后悄悄遗留的待处理任务，也没有靠重启程序才能继续的情况。某轮失败后重试成功，仍要保留第一次失败，不能只统计最后亮灯的那一次。

状态同步还要检查乱序：旧查询的返回如果晚于新操作到达，不能简单按接收时间覆盖新状态。首轮串行测试降低了这个概率，但正式支持快速连点前，仍需要单独验证命令排队、过期响应和状态收敛策略。

故障一次只制造一个

正常控制通过后，再开始拔电和重启。第一轮先做下面四种场景，每种恢复到稳定状态后，再做下一种。

场景	重点观察	恢复后的验收要求
灯具断电	请求超时后如何处理，何时判为不可达	重新上电后能恢复控制并取得真实状态
NCP 重启	主机是否识别重启，是否清理未完成操作	串口会话和必要初始化恢复，已有设备可继续控制
主机进程重启	设备表、Matter 身份和映射是否保留	不重复生成灯具，不要求用户重新添加网关
网关局域网断开	Matter 控制路径与下行 Mesh 状态分别怎样变化	网络恢复后重新同步，而非一直显示断网前的缓存

一次状态查询超时，不一定足够判定灯已经离线。离线判断应有明确的观察窗口和失败次数，并记录触发原因。具体参数要结合设备供电方式、上报机制和网络表现确定，不能给所有节点套同一个心跳规则。

重启后设备不重复，还依赖稳定的身份和映射。主机不能每次扫描到灯，就随手生成一个新的 Matter 端点编号。设备、元素与桥接端点之间的关系需要持久化，并按协议栈要求恢复。

Mesh 的密钥、地址分配、序列号和重放保护相关状态，也必须按所用协议栈的机制保存与恢复。哪些保存在 NCP、哪些保存在主机，要先查清楚。不能用一个手工增加的序列号偏移，假装解决所有掉电恢复问题。

这里验证的是原设备重启。更换 NCP 是另一件事，涉及原模组内持久状态能否迁移，不能因为重启通过就宣布支持换模组恢复。

失败时先留证据，最后才考虑恢复出厂

联调里最容易丢掉的信息，是恢复出厂之前的状态。灯没响应，删掉重新加，暂时好了，却没有弄清楚究竟是绑定错误、缓存过期，还是密钥与设备记录不一致。

每次失败至少保留当时的版本、操作步骤、目标设备标识和相关日志。公开分享日志时，去掉密钥、配网凭据和其他敏感信息。

记录表可以从下面这个空模板开始：

记录项	本次填写
用例编号与版本组合	待填
操作前的灯具状态、主机状态	待填
操作步骤与期望结果	待填
串口响应、设备状态、手机更新的时间	待填
是否通过及日志位置	待填
失败后做了什么，能否再次复现	待填

还要分清“移除”发生在哪一层：从一个 Matter 平台移除网关，与从 Mesh 网络移除并复位灯具，是不同操作。测试时不能为了清理手机里的配对，就顺手抹掉全部下行设备数据。

做到哪一步，才值得继续加设备

第一轮结束时，我希望拿到一套可重复的过程：指定版本的固件和主机程序，能完成单灯配置、控制、反向状态同步；手机与真实灯具最终一致；灯具、NCP 和主机分别重启后，可以恢复到可解释、可继续操作的状态。

满足这些条件，再加入第二盏灯，验证地址与端点是否串线，然后逐步增加调光、色温和组控制。大规模节点、长时间压力测试、OTA、替换模组和认证测试，还要各自安排，首轮跑通不能替它们盖章。

对于这个网关，我最想先建立的是定位问题的能力。以后灯不亮时，能从记录里判断命令停在哪一层；手机状态不对时，能找到最后一次可信的设备状态。这样的单灯闭环，才适合继续往上加功能。