Matter Fabric Synchronization 实战指南：基于 connectedhomeip 的跨 Fabric 设备同步-港品优选

Matter Fabric Synchronization 实战指南：基于 connectedhomeip 的跨 Fabric 设备同步

【免费下载链接】connectedhomeipMatter (formerly Project CHIP) creates more connections between more objects, simplifying development for manufacturers and increasing compatibility for consumers, guided by the Connectivity Standards Alliance.项目地址: https://gitcode.com/GitHub_Trending/co/connectedhomeip

Fabric Synchronization（织物同步）是 Matter 协议中让不同生态系统（Ecosystem）之间无需逐一人工配网即可共享设备的能力。本文以 connectedhomeip 仓库中的 fabric_synchronization_guide 为核心，结合 fabric-sync 示例应用的源码与构建脚本，完整讲解 Fabric-Admin / Fabric-Bridge 示例的构建、双机部署、反向配网、设备同步与移除的端到端流程，帮助你快速搭建并验证跨 Fabric 的设备同步演示环境。

图为两个 Fabric Synchronizing Administrator（E1 / E2）分别运行 Fabric-Admin 与 Fabric-Bridge-App，通过同步流程共享开关与灯光等终端设备的架构示意（来源：docs/guides/images/matter_fabric_synchronization.png）。

Fabric Synchronization 核心概念

Fabric Synchronization 定义了一套机制，让多个生态系统/控制器之间相互通信，从而简化终端设备从一条 Fabric 到另一条 Fabric 的配网过程——用户无需对每一台终端设备重复执行配网操作。

在 connectedhomeip 中，该特性的示例应用位于 examples/fabric-sync，其中包含两个核心角色：

Fabric-Admin（管理员）：实现 Fabric Administrator 角色，负责与对端的 Fabric-Bridge 通信，推动 Fabric Synchronization 流程。其实现位于 examples/fabric-sync/admin，内部包含FabricAdmin、PairingManager、DeviceManager、DeviceSynchronization、BridgeSubscription、CommissionerControl、FabricSyncGetter、IcdManager、StayActiveSender、UniqueIdGetter等组件模块。
Fabric-Bridge（桥接器）：实现 Aggregator（聚合器）设备类型，满足 Fabric Synchronization 条件，通过**动态端点（Dynamic Endpoints）**演示端到端的设备同步。其实现位于 examples/fabric-sync/bridge，包括Bridge、FabricBridge、CommissionerControlDelegate等。

关键约束与特性：

Fabric-Admin 与 Fabric-Bridge-App 必须运行在同一台物理设备上，两者通过 RPC 方式互相通信。
Fabric Synchronization 可以从任意一侧发起：发起方（共享自身设备的一方）担任Commissioner角色；接收方（接收被共享设备的一方）担任Commissionee角色。这种双向灵活性使得同步过程顺畅高效。

构建示例应用

构建 Linux 主机版

在当前仓库根目录执行（要求 Linux 主机环境，官方文档注明已在 Ubuntu 22.04 LTS (aarch64) 上测试）：

source scripts/activate.sh ./scripts/build/build_examples.py --target linux-x64-fabric-sync-no-ble build

构建产物fabric-sync即为集成了 Fabric-Admin 与 Fabric-Bridge 的单一可执行文件。

构建 Raspberry Pi 4（RP4）版

RP4 为 aarch64 架构，官方推荐在 Docker 交叉编译环境中构建。先拉取交叉编译镜像并进入容器：

docker pull ghcr.io/project-chip/chip-build-crosscompile:211 docker run -it -v ~/connectedhomeip:/var/connectedhomeip ghcr.io/project-chip/chip-build-crosscompile:211 /bin/bash

进入容器后，在挂载的源码目录内执行：

cd /var/connectedhomeip git config --global --add safe.directory /var/connectedhomeip ./scripts/run_in_build_env.sh \ "./scripts/build/build_examples.py \ --target linux-arm64-fabric-sync-no-ble-clang \ build"

构建完成后，将二进制传输到 RP4 设备上：

scp ./fabric-sync ubuntu@xxx.xxx.xxx.xxx:/home/ubuntu

说明：原指南中引用的./examples/fabric-admin/scripts/run_fabric_sync.sh与examples/fabric-admin、examples/fabric-bridge-app目录在当前仓库快照中并不存在，Fabric Sync 示例已统一收敛为 examples/fabric-sync 目录下的单一fabric-sync可执行文件，可直接运行，无需额外脚本包装。

引导 Fabric Sync 演示环境

在 Linux 上引导（两个生态系统）

演示需要两台 Linux 机器分别代表Ecosystem 1（E1）与Ecosystem 2（E2）。在两台机器上分别启动fabric-sync：

sudo rm -rf /tmp/chip_* # 清理旧的 KVS / 状态文件 cd ~/connectedhomeip/ out/debug/fabric-sync

原指南中在 E1、E2 上分别执行./examples/fabric-admin/scripts/run_fabric_sync.sh来启动同步脚本；在当前仓库中，该脚本已被直接运行fabric-sync可执行文件的方式取代。

应用启动后会初始化两部分：bridge::BridgeInit()初始化桥接端（Aggregator 设备），admin::FabricAdmin::Instance().Init()初始化管理端，并将日志重定向写入/tmp/fabric_sync.log（参见 examples/fabric-sync/main.cpp 中的ApplicationInit()）。

在 RP4 上引导

分别 SSH 登录两台 RP4（代表 E1 与 E2），然后运行之前 scp 过去的二进制：

ssh ubuntu@xxx.xxx.xxx.xxx # Password: <password> ./fabric-sync

两台机器的引导步骤完全一致，区别仅在于它们各自的 IP 与端口参数会在后续命令中作为对端地址使用。

运行 Fabric Sync 演示

第 1 步：Fabric Sync Setup（互相配网）

Fabric Sync Setup 的目标是让两个支持 Fabric Synchronization 的生态系统，把对方的 Fabric Bridge 节点配网进自己私有的 Fabric。

在E1 的 Fabric-Admin 控制台中：

将 E1 的本地桥接器以节点 ID 1 加入本地 Fabric：

fabricsync add-local-bridge 1

将 E2 的桥接器以节点 ID 2 配入 E1（参数依次为 setup PIN 码、E2 Fabric-Bridge 的 IP 与端口）：

fabricsync add-bridge 2 <setup-pin-code> <e2-fabric-bridge-ip> <e2-fabric-bridge-port>

该命令会触发**反向配网（Reverse Commissioning）**流程。数秒后，E1 控制台应看到如下消息，表示 E1 的本地桥接到已在 E2 的 Endpoint 2 上成功配网：

>>> A new device is added on Endpoint 2.

注意：只需将本地桥接器加入对端生态系统即可触发 Fabric Sync Setup。上例中该流程由 E1 发出的add-bridge命令发起；对端（E2）是否把本地桥接器加入 E1 是可选的。

在示例应用的交互 shell 中，对应命令为app add-bridge，完整用法参见 examples/fabric-sync/shell/ShellCommands.cpp：

app add-bridge <node-id> <setup-pin-code> <device-remote-ip> <device-remote-port>

第 2 步：将 Light 示例配到 E2

由于 Fabric-Bridge 本身也是一个 Matter Server，如果它与 Light 示例运行在同一台机器上会发生端口/服务冲突。因此Light 示例必须运行在与 Fabric-Admin / Fabric-Bridge 不同的物理机器上，再通过 Fabric-Admin 在源端将其配网。

规避同机冲突的变通方案：若必须在同一台机器上运行多个 Matter Server，可以为每个应用分配不同的端口与唯一的 Key-Value Store（KVS）路径。示例：以独立 discriminator / passcode、端口与 KVS 启动 Light App：

./out/linux-x64-light-clang/chip-lighting-app --discriminator 3843 --passcode 20202023 --secured-device-port 5543 --unsecured-commissioner-port 5553 --KVS /tmp/chip_kvs_lighting_app

各参数含义：

参数	值（示例）	说明
`--discriminator`	`3843`	设备发现标识符，用于配网时定位目标设备
`--passcode`	`20202023`	配网使用的 Setup PIN 码
`--secured-device-port`	`5543`	设备监听安全消息的 UDP 端口
`--unsecured-commissioner-port`	`5553`	监听未加密 commissioner 消息的 UDP 端口
`--KVS`	`/tmp/chip_kvs_lighting_app`	该应用的持久化 Key-Value Store 路径，必须与其它应用唯一区分

接着在 Fabric-Admin 控制台使用 payload 配 Light 示例为节点 ID 3：

pairing already-discovered 3 20202021 <ip> 5543

设备成功加入后，E2 侧会看到新分配的节点 ID：

>>> New device with Node ID: 0x3 has been successfully added.

同时，当新设备从 E1 被添加到 E2 时，你也会收到通知：

>>> A new device is added on Endpoint 3.

第 3 步：将 Light 示例同步回 E1

Light 示例在 E2 配网成功后，即可使用 E2 上新分配的动态端点 ID将该设备同步到 E1：

fabricsync sync-device <endpointid>

对应 shell 命令为app sync-device <endpointid>（见 examples/fabric-sync/shell/ShellCommands.cpp），其背后由DeviceSynchronization模块驱动，将源端生态系统中已配网的动态端点设备"镜像"到目标生态系统。

同步完成后，可以在两个生态系统中分别开关灯，验证状态同步：

从 E1 控制（<node-id>为 E1 视角下的节点 ID）：

onoff on <node-id> 1 onoff off <node-id> 1

从 E2 控制（使用 E2 分配的节点 ID）：

onoff on <node-id> 1 onoff off <node-id> 1

第 4 步：从生态系统中移除 Light 示例

解除配网即可将该设备从生态系统中移除：

pairing unpair <node-id>

对应 shell 命令为app remove-device <node-id>。

配接并同步商用 WiFi 开关

除 Light 示例外，还可以演示将 WiFi 商用开关同步到另一个生态系统。

配接开关到 Fabric-Source

在 Fabric-Source 控制台，使用设备的 payload 配网（支持 WiFi 配网模式，参数为节点 ID、SSID、密码与 payload）：

pairing code-wifi <node-id> <ssid> <passwd> <payload>

将开关同步到 E1

开关在 E2 配网成功后，使用 E2 上新分配的动态端点 ID 将其同步到 E1：

fabricsync sync-device <endpointid>

开关控制与 Light 相同，从 E1 / E2 两侧均可执行：

onoff on <node-id> 1 onoff off <node-id> 1

移除开关

pairing unpair <node-id>

底层实现要点

动态端点机制

Fabric Synchronization 依赖动态端点实现"运行时增减设备"。由于 SDK 中端点通常由 .zap 文件静态定义，为支持动态端点，ZCL 属性存储机制需要额外保留NUM_DYNAMIC_ENDPOINTS个端点的空间。仓库提供了一组宏来声明动态属性、动态集群与动态端点（详见 examples/fabric-sync/README.md）：

属性列表：DECLARE_DYNAMIC_ATTRIBUTE_LIST_BEGIN / DECLARE_DYNAMIC_ATTRIBUTE / DECLARE_DYNAMIC_ATTRIBUTE_LIST_END
集群列表：DECLARE_DYNAMIC_CLUSTER_LIST_BEGIN / DECLARE_DYNAMIC_CLUSTER / DECLARE_DYNAMIC_CLUSTER_LIST_END
端点声明：DECLARE_DYNAMIC_ENDPOINT(endpointName, clusterList)

所有动态属性都被标记为MATTER_ATTRIBUTE_FLAG_EXTERNAL_STORAGE，其读写必须由应用通过emberAfExternalAttributeReadCallback/emberAfExternalAttributeWriteCallback回调处理。

管理端组件协作

从源码结构看，examples/fabric-sync/admin 中各模块分工明确：

FabricAdmin：管理员主入口，持有并协调各子管理器；
PairingManager：负责设备配网（add-device/pair-device）与桥接器配网（add-bridge）；
DeviceManager：维护本地已配网设备的节点 ID 与动态端点映射；
DeviceSynchronization：实现sync-device，将设备同步到对端生态系统；
BridgeSubscription/DeviceSubscription：订阅对端桥接器/设备状态变化；
CommissionerControl：利用 Matter Commissioner Control 相关机制完成反向配网；
StayActiveSender/IcdManager：面向 ICD（间歇性连接设备）的保活与同步支持。

Shell 命令注册

所有同步命令通过 examples/fabric-sync/shell 目录下的命令类（AddBridgeCommand、AddDeviceCommand、PairDeviceCommand、RemoveBridgeCommand、RemoveDeviceCommand、SyncDeviceCommand）注册到 CHIP Shell，main中通过Shell::RegisterCommands()挂载（见 examples/fabric-sync/main.cpp）。

常见问题与注意事项

同机冲突：Fabric-Bridge 本身是 Matter Server，与其它 Matter 示例共机运行会产生冲突。要么将终端示例放到独立物理机，要么用不同的端口 + 唯一 KVS 路径规避（如上文 Light 启动命令所示）。
KVS 唯一性：多应用共机时，--KVS路径必须各不相同，否则持久化状态互相覆盖。
脚本路径差异：旧指南中的run_fabric_sync.sh脚本在当前仓库中已不存在，直接运行构建出的fabric-sync可执行文件即可达到同样的引导效果。
动态端点 ID：sync-device必须使用目标生态系统中实际分配的动态端点 ID，配网日志中的 "A new device is added on Endpoint N" 即为该 ID 的来源。

通过上述步骤，你可以在两台 Linux 主机（或 RP4）上完整复现 Matter 跨 Fabric 设备同步：从双向桥接配网、反向配网，到终端设备跨生态系统的共享、控制与移除，并可直接阅读 examples/fabric-sync 与 fabric_synchronization_guide 两个文档交叉验证细节。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析