Matter Linux Fabric Bridge 示例:基于动态端点的 Fabric Synchronization 实现详解

原创2026-09-18 11:40:271,723 阅读
文章标签:物联网智能家居嵌入式IoT协议通信网络蓝牙密码学认证鉴权

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,多个生态系统/控制器之间通过定义的机制相互通信,从而简化用户的使用体验。

在本仓库中,该应用的代码分为两部分:

官方文档声明该示例在 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 不为它们分配固有存储,存储由应用自己维护。相应地,对这些属性的读/写必须在应用内通过以下两个回调处理:

  • emberAfExternalAttributeWriteCallback
  • emberAfExternalAttributeReadCallback

文档明确指出,可参考本桥接应用的 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 控制器)对桥接应用进行配网与功能验证,例如:

  1. 将 bridge 应用本身以 Aggregator 身份配网到 Fabric Admin;
  2. 通过 Fabric Admin 的 RPC 通道调用 AddSynchronizedDevice 把源 Fabric 中的设备"同步"过来,使其出现在 bridge 的动态端点上;
  3. 验证新 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 是实现层面最直接的参考起点。

登录后查看全文
connectedhomeip