Matter Linux Fabric Bridge 示例:基于动态端点的 Fabric Synchronization 实现详解
Matter Linux Fabric Bridge 示例:基于动态端点的 Fabric Synchronization 实现详解
本指南基于 connectedhomeip 仓库中 examples/fabric-bridge-app/linux/README.md,系统讲解 Matter Linux Fabric Bridge 示例应用的设计与实战:它如何通过动态端点(Dynamic Endpoints)实现 Aggregator 设备类型,并在满足 Fabric Synchronization 条件的前提下,把来自一个 Fabric 的终端设备"桥接"到另一个 Fabric,无需对每台设备逐一人工配网。读完本文,你将掌握动态端点的三组声明宏、外部存储属性的读写回调机制、BridgedDeviceManager 的端点生命周期管理,以及该示例在 Ubuntu 与 Raspberry Pi 4 上的完整构建与运行流程。
Fabric Bridge 示例是什么
Matter Fabric Bridge 是一个 Aggregator(聚合器)设备类型示例应用。它演示的是 Matter 的 Fabric Synchronization(Fabric 同步) 特性——该特性允许终端设备从一个 Fabric 免人工干预地迁移/同步到另一个 Fabric,多个生态系统/控制器之间通过定义的机制相互通信,从而简化用户的使用体验。
在本仓库中,该应用的代码分为两部分:
- fabric-bridge-common(examples/fabric-bridge-app/fabric-bridge-common):与平台无关的公共实现,包括动态端点定义、桥接设备管理、属性访问接口等;
- linux(examples/fabric-bridge-app/linux):Linux 平台入口,含
main.cpp、RPC 客户端/服务端以及构建脚本。
官方文档声明该示例在 Ubuntu 22.04 LTS (aarch64) 上验证通过,本文命令以此环境为准。
工作原理:动态端点(Dynamic Endpoints)
为什么需要动态端点
SDK 对动态端点的支持目前是有限的:通常,端点及其包含的集群、属性都在 .zap 文件中静态定义,代码生成器据此产出静态的端点结构与存储。而桥接场景下,桥接设备(Bridged Device)的数量、类型和状态是运行时动态变化的,无法全部预埋在 .zap 中。
为此,ZCL 属性存储机制额外预留了 NUM_DYNAMIC_ENDPOINTS 个端点的属性空间。这些额外的端点结构必须由应用自身定义,并且可以在运行时被增删和修改。在本示例中,该数量由配置宏控制(见下文"关键配置")。
三组声明宏
为便于应用定义这些端点结构,SDK 提供三组宏(详细定义可查阅 src/app/util/ 下属性存储相关头文件,本文以示例代码中的实际用法为准)。
属性列表宏
DECLARE_DYNAMIC_ATTRIBUTE_LIST_BEGIN(attrListName)
DECLARE_DYNAMIC_ATTRIBUTE(attId, attType, attSizeBytes, attrMask)
DECLARE_DYNAMIC_ATTRIBUTE_LIST_END(clusterRevision)
DECLARE_DYNAMIC_ATTRIBUTE_LIST_BEGIN(attrListName):开启一个属性列表声明,attrListName即最终分配得到的属性结构名;DECLARE_DYNAMIC_ATTRIBUTE(attId, attType, attSizeBytes, attrMask):逐个添加属性。attId是集群内属性 ID,attType是 ZCL 数据类型(如BOOLEAN、INT16U、CHAR_STRING、ARRAY、BITMAP32等),attSizeBytes为该属性存储所需字节数(字符串/数组要预留足够长度),attrMask为属性掩码(一般为 0,也可叠加ZAP_ATTRIBUTE_MASK类标志);DECLARE_DYNAMIC_ATTRIBUTE_LIST_END(clusterRevision):收尾,参数为集群版本号(Cluster Revision)。
集群列表宏
DECLARE_DYNAMIC_CLUSTER_LIST_BEGIN(clusterListName)
DECLARE_DYNAMIC_CLUSTER(clusterId, clusterAttrs, role, incomingCommands, outgoingCommands)
DECLARE_DYNAMIC_CLUSTER_LIST_END
DECLARE_DYNAMIC_CLUSTER_LIST_BEGIN(clusterListName):开启集群列表,clusterListName为结构名;DECLARE_DYNAMIC_CLUSTER(clusterId, clusterAttrs, role, incomingCommands, outgoingCommands):添加集群。clusterId为集群 ID(如Descriptor::Id);clusterAttrs引用前面用属性宏定义的属性列表名;role通常为ZAP_CLUSTER_MASK(SERVER);incomingCommands/outgoingCommands是指向命令 ID 数组的指针,数组必须以kInvalidCommandId结尾,若没有命令则传nullptr;DECLARE_DYNAMIC_CLUSTER_LIST_END:收尾,不加分号。
端点声明宏
DECLARE_DYNAMIC_ENDPOINT(endpointName, clusterList)
- 声明一个端点及其关联的集群列表,
clusterList必须事先由DECLARE_DYNAMIC_CLUSTER...宏定义。
外部存储属性与读写回调
所有通过上述属性宏声明的动态属性,都会被配置为 ZCL 数据库中的 MATTER_ATTRIBUTE_FLAG_EXTERNAL_STORAGE——即 SDK 不为它们分配固有存储,存储由应用自己维护。相应地,对这些属性的读/写必须在应用内通过以下两个回调处理:
emberAfExternalAttributeWriteCallbackemberAfExternalAttributeReadCallback
文档明确指出,可参考本桥接应用的 main.cpp(Linux 端)以及公共实现中的属性访问接口来理解这套回调的实际写法。
源码中的真实定义
在 BridgedDeviceManager.cpp 中可以看到这套宏的完整落地。例如 Descriptor 集群的动态属性列表:
DECLARE_DYNAMIC_ATTRIBUTE_LIST_BEGIN(descriptorAttrs)
DECLARE_DYNAMIC_ATTRIBUTE(Descriptor::Attributes::DeviceTypeList::Id, ARRAY, kDescriptorAttributeArraySize, 0),
DECLARE_DYNAMIC_ATTRIBUTE(Descriptor::Attributes::ServerList::Id, ARRAY, kDescriptorAttributeArraySize, 0),
DECLARE_DYNAMIC_ATTRIBUTE(Descriptor::Attributes::ClientList::Id, ARRAY, kDescriptorAttributeArraySize, 0),
DECLARE_DYNAMIC_ATTRIBUTE(Descriptor::Attributes::PartsList::Id, ARRAY, kDescriptorAttributeArraySize, 0),
DECLARE_DYNAMIC_ATTRIBUTE_LIST_END();
其中 kDescriptorAttributeArraySize = 254(注释说明这是当前 ZCL Struct 实现中 max-size 数组的上限,见 BridgedDeviceManager.cpp)。
Bridged Device Basic Information 集群则声明了必选属性 Reachable、UniqueID、FeatureMap,以及可选但常见的 VendorName、VendorID、ProductName、ProductID、NodeLabel、HardwareVersion(String)、SoftwareVersion(String) 等,字段尺寸分别由 kNodeLabelSize、kUniqueIdSize 等常量控制(BridgedDeviceManager.cpp)。
随后是集群列表与端点声明(BridgedDeviceManager.cpp):
DECLARE_DYNAMIC_CLUSTER_LIST_BEGIN(bridgedNodeClusters)
DECLARE_DYNAMIC_CLUSTER(Descriptor::Id, descriptorAttrs, ZAP_CLUSTER_MASK(SERVER), nullptr, nullptr),
DECLARE_DYNAMIC_CLUSTER(BridgedDeviceBasicInformation::Id, bridgedDeviceBasicAttrs, ZAP_CLUSTER_MASK(SERVER), nullptr, nullptr),
DECLARE_DYNAMIC_CLUSTER(EcosystemInformation::Id, ecosystemInformationBasicAttrs, ZAP_CLUSTER_MASK(SERVER), nullptr, nullptr),
DECLARE_DYNAMIC_CLUSTER(AdministratorCommissioning::Id, AdministratorCommissioningAttrs, ZAP_CLUSTER_MASK(SERVER),
administratorCommissioningCommands, nullptr)
DECLARE_DYNAMIC_CLUSTER_LIST_END;
DECLARE_DYNAMIC_ENDPOINT(sBridgedNodeEndpoint, bridgedNodeClusters);
DECLARE_DYNAMIC_ENDPOINT(sIcdBridgedNodeEndpoint, icdBridgedNodeClusters);
注意:代码里定义了两套动态端点模板——普通桥接节点 sBridgedNodeEndpoint 与支持 ICD(间歇性连接设备)的 sIcdBridgedNodeEndpoint。两者差异在集群集合上:ICD 模板额外携带 BridgedDeviceBasicInformation 的 KeepActive 命令列表(bridgedDeviceBasicInformationCommands,以 kInvalidCommandId 结尾,见 BridgedDeviceManager.cpp)。应用在运行时根据被桥接设备是否为 ICD 来选择使用哪套模板。
BridgedDeviceManager:动态端点生命周期管理
bridgedDeviceManager.h 中的 BridgedDeviceManager 是一个单例(BridgedDeviceManager::Instance()),负责全部桥接设备的注册与生命周期管理,核心接口如下:
| 接口 | 作用 |
|---|---|
Init() |
计算首个动态端点 ID:取最后一个固定端点索引 +1,并重置当前端点游标 |
AddDeviceEndpoint(dev, parentEndpointId) |
为设备分配动态端点;若设备未设置 uniqueId 则自动生成;已存在相同 uniqueId 时拒绝添加;返回端点索引(失败返回 std::nullopt) |
RemoveDeviceEndpoint(dev) / RemoveDeviceByScopedNodeId(scopedNodeId) |
清除设备对应的动态端点并回收槽位 |
GetDevice(endpointId) / GetDeviceByScopedNodeId(...) / GetDeviceByUniqueId(...) |
按端点、ScopedNodeId 或唯一 ID 查找设备 |
其实现细节(BridgedDeviceManager.cpp)值得关注:
AddDeviceEndpoint循环查找空槽位(上限为CHIP_DEVICE_CONFIG_DYNAMIC_ENDPOINT_COUNT),并调用底层emberAfSetDynamicEndpoint(index, endpointId, ep, dataVersionStorage, deviceTypeList, parentEndpointId)完成注册;若返回CHIP_ERROR_ENDPOINT_EXISTS则自增端点 ID 并重试(最多kMaxRetries = 10次),且 ID 回绕时重置回首个动态端点;- 设备类型列表固定为
{ DEVICE_TYPE_BRIDGED_NODE (0x0013), DEVICE_VERSION_DEFAULT (1) },即 Matter 规范中的 Bridged Node 设备类型(BridgedDeviceManager.cpp 与 BridgedDeviceManager.cpp); GenerateUniqueId会生成以"GEN-"前缀开头的随机唯一 ID,并保证不与现有设备冲突(BridgedDeviceManager.cpp)。
桥接设备实体本身由 BridgedDevice.h 中的 BridgedDevice 描述,它持有 ScopedNodeId(目标设备在源 Fabric 中的节点标识)、动态端点 ID、父端点 ID、可达性(mReachable)、是否 ICD(mIsIcd)以及一组 BridgedAttributes(厂商名/ID、产品名/ID、硬件/软件版本等)。当可达性或活跃状态变化时,ReachableChanged() / LogActiveChangeEvent() 会通过 MatterReportingAttributeChangeCallback 触发属性上报,并写入 ReachableChanged、ActiveChanged 事件日志(BridgedDevice.cpp)。
桥接设备的属性与命令如何被外部访问
由于动态端点属性是外部存储,SDK 的默认属性访问路径需要被接管。示例采用 AttributeAccessInterface 与 CommandHandlerInterface 两种机制:
- BridgedDeviceBasicInformationImpl:继承
AttributeAccessInterface,在Read()中按属性 ID 从BridgedDeviceManager查找到对应设备,再编码其Reachable、NodeLabel、FeatureMap(ICD 支持位随IsIcd()动态置位)以及厂商/产品/版本字段;Write()中若设备不可达则返回CHIP_ERROR_NOT_CONNECTED(BridgedDeviceBasicInformationImpl.cpp); - BridgedAdministratorCommissioning:同样是
AttributeAccessInterface,为每个被桥接设备暴露 Administrator Commissioning 集群的WindowStatus、AdminFabricIndex、AdminVendorId三个属性(后两者以 nullable 编码,见 BridgedAdministratorCommissioning.cpp); - main.cpp 中的命令处理器:
AdministratorCommissioningCommandHandler拦截对动态端点的OpenCommissioningWindow命令,将其转发为对目标设备的免用户干预配网窗口操作;BridgedDeviceInformationCommandHandler处理 ICD 的KeepActive命令,并校验超时在 30 秒~60 分钟区间(main.cpp)。
ApplicationInit() 中完成这些注册:调用 MatterEcosystemInformationPluginServerInitCallback()(因为 Ecosystem Information 集群只存在于动态端点,需应用自行初始化)、注册命令处理器与属性访问接口、初始化 BridgedDeviceManager 与 Commissioner Control 服务器(main.cpp)。
Fabric Synchronization 的 RPC 通道
Linux 版桥接应用通过 Pigweed RPC 与运行 Fabric Admin 的控制器通信。bridge_enable_pw_rpc 构建开关(见 linux/BUILD.gn)启用 PW_RPC_FABRIC_BRIDGE_SERVICE 后,RpcServer.cpp 中的 FabricBridge RPC 服务会提供五个方法,构成 Fabric 同步的数据面:
AddSynchronizedDevice:携带目标设备的 node_id、fabric_index 及可选属性,创建BridgedDevice并调用BridgedDeviceManager::AddDeviceEndpoint注册到动态端点(父端点固定为端点 1),随后把 Ecosystem Information 集群附加到该端点;RemoveSynchronizedDevice:按 ScopedNodeId 移除设备与端点;ActiveChanged:记录 ICD 设备承诺的活跃时长并写ActiveChanged事件;AdminCommissioningAttributeChanged:同步管理员配网窗口状态、开启者 Fabric 索引与 Vendor ID(并做取值范围校验);DeviceReachableChanged:更新设备可达性并触发属性上报与事件。
RPC 服务器监听端口由 InitRpcServer(gLocalServerPort) 启动于独立线程(RpcServer.cpp)。
构建 Fabric Bridge 示例
1. 安装工具链
在 Ubuntu 上安装构建依赖:
sudo apt-get install git gcc g++ python pkg-config libssl-dev libdbus-1-dev libglib2.0-dev ninja-build python3-venv python3-dev unzip
2. Linux 主机(x64)构建
source scripts/activate.sh
./scripts/build/build_examples.py --target linux-x64-fabric-bridge-rpc-no-ble build
说明:
source scripts/activate.sh激活 SDK 构建环境(含 Python 虚拟环境);- 目标名中的
fabric-bridge即本示例,rpc表示启用 Pigweed RPC,no-ble关闭蓝牙,linux-x64为主机架构。完整的目标名与参数可由./scripts/build/build_examples.py --help查看。
3. Raspberry Pi 4(aarch64)交叉构建
拉取官方交叉编译 Docker 镜像:
docker pull ghcr.io/project-chip/chip-build-crosscompile:211
运行 Docker(将本地 SDK 目录挂载进容器):
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-bridge-no-ble-clang-rpc \
build"
要点:
--target linux-arm64-fabric-bridge-no-ble-clang-rpc针对 64 位 ARM(Raspberry Pi 4)使用 Clang 工具链,且同样启用 RPC;- 需要先执行
git config --global --add safe.directory /var/connectedhomeip以消除容器内目录所有权导致的 Git 安全校验报错。
4. 传输二进制到树莓派
构建完成后,把 fabric-bridge-app 可执行文件用 scp 拷贝到目标设备:
scp ./fabric-bridge-app ubuntu@xxx.xxx.xxx.xxx:/home/ubuntu
在 Ubuntu 上运行完整示例
1. 构建
按上文"构建"章节完成构建。
2. 运行 Linux Fabric Bridge 示例应用
cd ~/connectedhomeip/examples/fabric-bridge-app/linux
sudo out/debug/fabric-bridge-app
运行参数说明(见 main.cpp,默认值可从 --help 查看):
--fabric-admin-server-port <port>:Fabric Admin RPC 服务器端口,默认33001,桥接应用作为 RPC 客户端连接它;--local-server-port <port>:本地 RPC 服务器端口,默认33002。
应用启动后(PW_RPC_FABRIC_BRIDGE_SERVICE 启用时)会先尝试连接 Fabric Admin,失败则每隔 3 秒重试(main.cpp)。
3. 使用 Fabric Admin 测试设备
文档要求最后在笔记本电脑/工作站上用 Fabric Admin(即 examples/fabric-admin 控制器)对桥接应用进行配网与功能验证,例如:
- 将 bridge 应用本身以 Aggregator 身份配网到 Fabric Admin;
- 通过 Fabric Admin 的 RPC 通道调用
AddSynchronizedDevice把源 Fabric 中的设备"同步"过来,使其出现在 bridge 的动态端点上; - 验证新 Fabric 中的控制器无需对每个终端设备单独配网即可访问被桥接设备。
提示:完整的端到端演示依赖 Fabric Admin 与 Fabric Bridge 之间的 Pigweed RPC 服务,相关 proto 服务定义位于 examples/common/pigweed(
fabric_admin_service与fabric_bridge_service)。
关键配置速查
| 配置项 | 位置 | 说明 |
|---|---|---|
CHIP_DEVICE_CONFIG_DYNAMIC_ENDPOINT_COUNT 16 |
fabric-bridge-common/include/CHIPProjectAppConfig.h | 可动态创建的最大端点数量,覆盖 SDK 默认值 |
CHIP_DEVICE_ENABLE_PORT_PARAMS 1 |
同上 | 允许应用启动时通过命令行配置端口 |
bridge_enable_pw_rpc |
linux/BUILD.gn 与 linux/with_pw_rpc.gni | 是否启用 Pigweed RPC(PW_RPC_FABRIC_ADMIN_SERVICE / PW_RPC_FABRIC_BRIDGE_SERVICE) |
chip_device_project_config_include |
linux/args.gni | 指向本示例的项目级配置头文件 |
fabric-bridge-app.matter / .zap |
fabric-bridge-common | 静态端点(如根端点、固定端点)的数据模型定义,动态端点不在此定义 |
小结
Matter Linux Fabric Bridge 示例完整展示了三条关键技术路径:一是用 DECLARE_DYNAMIC_ATTRIBUTE/CLUSTER/ENDPOINT 系列宏在运行时构建端点,二是通过 AttributeAccessInterface 与外部存储属性回调接管动态端点的属性读写,三是借由 Pigweed RPC 在 Fabric Admin 与桥接应用之间同步设备,从而把"免逐台配网的跨 Fabric 设备迁移"落到可运行的端到端演示上。对于想要在自己产品中实现 Aggregator 设备类型或 Fabric Synchronization 的开发者,本示例的 fabric-bridge-common 是实现层面最直接的参考起点。