Matter 动态端点桥接实战:基于 Linux Bridge 示例理解并构建可热插拔的桥接设备

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

Matter 动态端点桥接实战:基于 Linux Bridge 示例理解并构建可热插拔的桥接设备

导读

本文围绕 Matter Linux Bridge Example 官方文档 展开,深入讲解 Matter SDK 中"动态端点(Dynamic Endpoints)"机制的原理与工程实现。文中以 chip-bridge-app(一个可动态增删多个子灯的桥接设备)为主线,完整覆盖动态端点的声明宏、外部属性存储回调、桥接实现示例,以及 Linux/Raspberry Pi 上的构建与运行方法。读完本文,你将掌握如何基于 Matter SDK 自己编写一个能够运行时添加/移除子设备的桥接应用,并理解 OnOff、Descriptor、BridgedDeviceBasicInformation、FixedLabel 等集群在动态端点场景下的组织方式。

适用前提:本文步骤在 Ubuntu for Raspberry Pi Server 20.04 LTS(aarch64) 与 Ubuntu for Raspberry Pi Desktop 20.10(aarch64) 上验证通过(文档说明)。其他 Linux 发行版需自行保证工具链与依赖兼容。


一、工作原理(Theory of Operation)

1.1 什么是动态端点

Matter 设备的数据模型由"端点(Endpoint)"构成,每个端点承载若干集群(Cluster)与属性(Attribute)。在常规开发流程中,端点及其集群、属性是在 .zap 文件中静态定义的,由 ZAP 工具生成代码与静态结构。SDK 目前对动态端点的支持是有前提的:代码生成依赖于 .zap 中声明的静态端点,因此动态端点并未完全脱离 ZAP 的约束。

为了支持不在 .zap 中静态定义的端点,ZCL 属性存储机制会为额外的 NUM_DYNAMIC_ENDPOINTS(即 CHIP_DEVICE_CONFIG_DYNAMIC_ENDPOINT_COUNT,桥接示例中设为 16)个端点保留附加的端点信息。这些附加的端点结构必须由应用程序自身定义,并且可以在运行时改变。

1.2 动态端点的四层宏体系

要动态创建一个端点,通常需要自下而上依次声明:属性列表 → 集群列表 → 端点。相关宏定义集中在 src/app/util/attribute-storage.h。

第一层:属性列表声明宏

宏 作用
DECLARE_DYNAMIC_ATTRIBUTE_LIST_BEGIN(attrListName) 开始声明属性列表,定义属性结构体数组名
DECLARE_DYNAMIC_ATTRIBUTE(attId, attType, attSizeBytes, attrMask) 声明一个无默认值的属性
DECLARE_DYNAMIC_ATTRIBUTE_WITH_SCALAR_DEFAULT(attId, attType, attSizeBytes, attrMask, defaultVal) 声明一个带内联标量默认值(≤4 字节:int/uint/bool/enum/bitmap)的属性
DECLARE_DYNAMIC_ATTRIBUTE_WITH_STRING_DEFAULT(attId, attType, attSizeBytes, attrMask, defaultBytesPtr) 声明一个带字符串默认值(Pascal 长度前缀字节)的属性
DECLARE_DYNAMIC_ATTRIBUTE_WITH_MIN_MAX_DEFAULT(attId, attType, attSizeBytes, attrMask, minMaxPtr) 声明一个带最小/最大默认值(指向 min/max 结构)的属性
DECLARE_DYNAMIC_ATTRIBUTE_LIST_END() 结束属性列表,自动追加 ClusterRevision(0xFFFD,INT16U,默认 0)
DECLARE_DYNAMIC_ATTRIBUTE_LIST_END_WITH_REVISION(clusterRevision) 结束属性列表,追加指定 clusterRevision 的 ClusterRevision 属性

其中 _WITH_STRING_DEFAULT 的默认值以 Pascal 格式(长度前缀)保存字节,元数据只存指针而非副本,因此字节缓冲区必须存活到端点注销之后、且注册期间不得改变——桥接应用可借此为每个子设备提供独立的字符串(如序列号、URL),见 attribute-storage.h 的注释说明。

关键语义:所有这些宏声明的属性,都会被配置为 ZCL 数据库中的 MATTER_ATTRIBUTE_FLAG_EXTERNAL_STORAGE(外部存储)属性,即 SDK 不为其维护内部存储,读写必须由应用侧实现:

  • 读取/写入分发入口是 emberAfExternalAttributeReadCallback / emberAfExternalAttributeWriteCallback;
  • 也可以使用 AttributeAccessInterface(如示例中针对 PowerSource 集群注册的 BridgedPowerSourceAttrAccess);
  • 通过 _WITH_*_DEFAULT 提供的默认值存储在 flash 元数据中,可通过 emberAfGetAttributeDefaultValue 访问。

第二层:集群列表声明宏

宏 作用
DECLARE_DYNAMIC_CLUSTER_LIST_BEGIN(clusterListName) 开始声明集群列表
DECLARE_DYNAMIC_CLUSTER(clusterId, clusterAttrs, role, incomingCommands, outgoingCommands) 声明一个集群,引用此前定义的属性列表与命令列表
DECLARE_DYNAMIC_CLUSTER_LIST_END 结束集群列表

其中 role 决定集群作为 Server 还是 Client,可取 ZAP_CLUSTER_MASK(SERVER) 或 ZAP_CLUSTER_MASK(CLUSTER)(见 attribute-storage.h);命令列表必须以 kInvalidCommandId 结尾,若无命令则传 nullptr。

第三层:端点声明宏

宏 作用
DECLARE_DYNAMIC_ENDPOINT(endpointName, clusterList) 声明一个动态端点及其关联的集群列表

其展开形式为 EmberAfEndpointType endpointName = { clusterList, MATTER_ARRAY_SIZE(clusterList), 0 }。

第四层:运行时注册/注销 API(位于 src/app/util/attribute-storage.h,实现在 src/app/util/attribute-storage.cpp):

  • emberAfSetDynamicEndpoint(index, id, ep, dataVersionStorage, deviceTypeList, parentEndpointId):将端点注册到动态槽位,内部会校验索引上限(index + FIXED_ENDPOINT_COUNT < MAX_ENDPOINT_COUNT)、端点 ID 是否与已有端点冲突(冲突返回 CHIP_ERROR_ENDPOINT_EXISTS)、dataVersionStorage 是否足够容纳 Server 集群数;
  • emberAfSetDynamicEndpointWithEpUniqueId(...):支持为端点设置全局唯一 ID(CHIP_CONFIG_USE_ENDPOINT_UNIQUE_ID 开启时使用);
  • emberAfClearDynamicEndpoint(index):注销动态端点。

二、Limitations:为什么 .zap 里必须有一个"哑端点"

由于代码生成依赖 .zap 中静态声明的集群与属性,必须在 .zap 中包含一个定义了全部可能被动态端点使用的集群的固定端点,否则代码生成阶段不会产出对应集群的处理代码。桥接示例的做法是:

  • Endpoint 0:在 .zap 中定义,包含桥本身的 Basic、配置集群与根 Descriptor 集群;
  • Endpoint 1:在 .zap 中定义,作为"哑端点(dummy)",囊括所有可能用于动态端点的集群,运行时被禁用。

对应的 bridge-app.zap 与 bridge-app.matter 位于 examples/bridge-app/bridge-common/。运行时禁用的逻辑见 main.cpp:

// Disable last fixed endpoint, which is used as a placeholder for all of the
// supported clusters so that ZAP will generated the requisite code.
emberAfEndpointEnableDisable(emberAfEndpointFromIndex(static_cast<uint16_t>(emberAfFixedEndpointCount() - 1)), false);

动态端点的起始 ID 取"最后一个固定端点 + 1",见 main.cpp。


三、桥接实现示例(Bridge Implementation Example)

3.1 端点的声明

示例首先通过宏声明了一个 bridgedLightEndpoint 结构,用于一盏灯端点,包含 OnOff、Descriptor、BridgedDeviceBasicInformation、FixedLabel 集群(FixedLabel 与 BridgedDeviceBasicInformation 通过 DeviceOnOff 类的注册逻辑挂载,见 Device.cpp)。核心声明代码位于 main.cpp:

// Declare On/Off cluster attributes
DECLARE_DYNAMIC_ATTRIBUTE_LIST_BEGIN(onOffAttrs)
DECLARE_DYNAMIC_ATTRIBUTE(OnOff::Attributes::OnOff::Id, BOOLEAN, 1, 0), /* on/off */
    DECLARE_DYNAMIC_ATTRIBUTE_LIST_END();

// Declare Descriptor cluster attributes
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();

constexpr CommandId onOffIncomingCommands[] = {
    app::Clusters::OnOff::Commands::Off::Id,
    app::Clusters::OnOff::Commands::On::Id,
    app::Clusters::OnOff::Commands::Toggle::Id,
    app::Clusters::OnOff::Commands::OffWithEffect::Id,
    app::Clusters::OnOff::Commands::OnWithRecallGlobalScene::Id,
    app::Clusters::OnOff::Commands::OnWithTimedOff::Id,
    kInvalidCommandId,
};

DECLARE_DYNAMIC_CLUSTER_LIST_BEGIN(bridgedLightClusters)
DECLARE_DYNAMIC_CLUSTER(OnOff::Id, onOffAttrs, ZAP_CLUSTER_MASK(SERVER), onOffIncomingCommands, nullptr),
    DECLARE_DYNAMIC_CLUSTER(Descriptor::Id, descriptorAttrs, ZAP_CLUSTER_MASK(SERVER), nullptr, nullptr),
    DECLARE_DYNAMIC_CLUSTER_LIST_END;

// Declare Bridged Light endpoint
DECLARE_DYNAMIC_ENDPOINT(bridgedLightEndpoint, bridgedLightClusters);

值得注意的实现细节:

  • kDescriptorAttributeArraySize = 254,这是因为当前 ZCL 对 Struct 的实现使用 254 字节的最大数组(main.cpp);
  • OnOff 集群声明了 6 条 incoming 命令(Off/On/Toggle/OffWithEffect/OnWithRecallGlobalScene/OnWithTimedOff),以 kInvalidCommandId 收尾;
  • 每个动态端点还需配套 DataVersion 数组(如 gLight1DataVersions),数量与集群数一致,用于 Data Version 跟踪。

除了灯端点,示例还声明了温度传感器端点(Temperature measurement + Descriptor + Bridged Device Basic Information)与组合设备端点(Descriptor + Power Source),展示了多种设备类型的动态注册方式,见 main.cpp。

3.2 运行时增删端点的完整流程

示例演示了"运行时添加与移除端点"这一核心概念。按文档描述(并结合当前版本源码)的典型流程为:

  1. 声明 bridgedLightEndpoint 结构;
  2. 动态添加三盏灯,占据端点 2、3、4(分别对应 Light 1、Light 2、Light 3);
  3. 移除端点 3,模拟删除 Light 2;
  4. 添加第四盏灯 Light 4,占据端点 5;
  5. 重新添加 Light 2,占据端点 6。

说明:不同版本示例会随测试计划(如 TC-BR-2)演进端点编号细节,例如当前源码在 ApplicationInit() 中先添加 Light1、两个温度传感器、组合设备及 4 个 Action 灯,再通过键盘命令热插拔。编号以当前仓库源码为准(见 main.cpp)。

所有端点都会填充 Bridged Device Basic Information 与 Fixed Label 集群:

  • BridgedDeviceBasicInformation 集群中模拟了 reachable 属性(应用通过 SetReachable() 控制,设备不可达时写操作会被拒绝);
  • FixedLabel 集群中模拟 LabelList 属性,值为 "room" / [灯名] 的键值对。

端点增删的底层实现封装在 AddDeviceEndpoint / RemoveDeviceEndpoint 中(main.cpp):

  • AddDeviceEndpoint 在 gDevices 数组中寻找空闲槽位,循环调用 emberAfSetDynamicEndpoint;若返回 CHIP_ERROR_ENDPOINT_EXISTS 则递增 gCurrentEndpointId 重试(处理端点 ID 回绕),成功后通过 CodegenDataModelProvider::Instance().Registry().Register(...) 注册桥接设备信息(reachable、nodeLabel、uniqueId);
  • RemoveDeviceEndpoint 调用 gDevices[index]->Unregister() 与 emberAfClearDynamicEndpoint(index) 完成注销。

3.3 外部属性读写回调的实现

由于动态属性均为外部存储,应用的读写处理集中在两个回调中(main.cpp):

Protocols::InteractionModel::Status emberAfExternalAttributeReadCallback(EndpointId endpoint, ClusterId clusterId,
                                                                         const EmberAfAttributeMetadata * attributeMetadata,
                                                                         uint8_t * buffer, uint16_t maxReadLength)
{
    uint16_t endpointIndex = emberAfGetDynamicIndexFromEndpoint(endpoint);
    // ... 按 clusterId 分发到 HandleReadOnOffAttribute / HandleReadTempMeasurementAttribute
}

Protocols::InteractionModel::Status emberAfExternalAttributeWriteCallback(EndpointId endpoint, ClusterId clusterId,
                                                                          const EmberAfAttributeMetadata * attributeMetadata,
                                                                          uint8_t * buffer)
{
    // ... 校验 endpointIndex 有效、设备可达后分发到 HandleWriteOnOffAttribute
}

以 HandleReadOnOffAttribute 为例(main.cpp),它依据 attributeId 与 maxReadLength 分发:读 OnOff 属性(长度 1)返回 dev->IsOn() ? 1 : 0,读 ClusterRevision(长度 2)返回 ZCL_ON_OFF_CLUSTER_REVISION;而 HandleWriteOnOffAttribute(main.cpp)在设备可达时把写入的布尔值透传给 dev->SetOnOff(...)——这正是"桥自身维护子设备状态数据库"的典型模式。

此外,PowerSource 集群使用 AttributeAccessInterface(BridgedPowerSourceAttrAccess)而非回调方式处理读写,并在 ApplicationInit 中注册到 AttributeAccessInterfaceRegistry(main.cpp、main.cpp)。

3.4 运行时调试与测试命令

chip-bridge-app 支持从 stdin 输入字符触发设备状态变化,便于配合 Matter 桥接测试计划(TC-BR-、TC-ACT-、TC-BRBINFO-*)验证,命令分发逻辑在 handle_char_input 中(main.cpp),例如:

按键 行为
2 添加 Light 2(TC-BR-2 step 2)
4 移除 Light 1(TC-BR-2 step 4)
5 重新添加 Light 1(TC-BR-2 step 5)
b 重命名灯光(TC-BR-3)
c 切换灯光开关状态(TC-BR-3)
t 温度传感器测量值 +1 度(TC-BR-4)
u / v 设置 TempSensor1 不可达 / 可达(TC-BRBINFO-2.2)
w 增加 Light1 的 configurationVersion(TC-BRBINFO-3.2)
r / f / i / l Actions 集群的 Room/Zone 相关操作(TC-ACT-2.2)
m / n / o Actions 集群的 Action 增删改名(TC-ACT-2.2)

按键输入由 bridge_polling_thread 轮询捕获,并通过 DeviceLayer::SystemLayer().ScheduleLambda 调度到 chip 线程上执行(main.cpp)。该示例同时支持通过命名管道(--pipe 参数,见 LinuxDeviceOptions::app_pipe)接收控制命令(main.cpp)。


四、构建(Building)

4.1 安装工具链

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

4.2 构建示例应用

cd ~/connectedhomeip/examples/bridge-app/linux
git submodule update --init
source third_party/connectedhomeip/scripts/activate.sh
gn gen out/debug
ninja -C out/debug

构建系统说明:

  • 示例通过 BUILD.gn 生成可执行目标 chip-bridge-app,其源文件包括 main.cpp、Device.cpp、bridged-actions-stub.cpp(Actions 集群存根,全局 gRooms/gActions 变量定义在 main.cpp)以及桥接公共代码;
  • scripts/activate.sh 是 SDK 的环境激活脚本(位于仓库根目录 scripts/activate.sh),用于准备 Python 虚拟环境与构建依赖;
  • 动态端点数量由 CHIPProjectAppConfig.h 中的 CHIP_DEVICE_CONFIG_DYNAMIC_ENDPOINT_COUNT 16 决定(Linux/ASR/ESP32 等平台一致,ESP32 通过 CMake 宏 -DCHIP_DEVICE_CONFIG_DYNAMIC_ENDPOINT_COUNT=16 传入,见 esp32/CMakeLists.txt)。

4.3 清理构建产物

cd ~/connectedhomeip/examples/bridge-app/linux
rm -rf out/

说明:本文为只读讲解,不修改仓库内容;以上清理命令仅针对本地生成的 out/ 构建目录。


五、在 Raspberry Pi 4 上运行完整示例

5.1 前置条件

  1. 一块 Raspberry Pi 4 开发板;
  2. 一个 USB 蓝牙适配器:Ubuntu Desktop 会自行发送蓝牙广播,从而阻塞 CHIP 通过 BLE 连接设备;若使用 Ubuntu Server,需要通过 APT 安装 pi-bluetooth;
  3. Ubuntu 20.04 或更新版本的 ARM64 镜像。

5.2 构建

按上文 构建(Building) 一节完成构建。

5.3 运行

(可选)插入 USB 蓝牙适配器

插入后,按照 Linux BLE 设置指南 找到对应的蓝牙控制器编号(例如 hci1)。

运行桥接示例应用

cd ~/connectedhomeip/examples/bridge-app/linux
sudo out/debug/chip-bridge-app --ble-controller [bluetooth controller number]
# 本例中使用的设备为 hci1:
sudo out/debug/chip-bridge-app --ble-controller 1

使用 ChipDeviceController 测试设备

在笔记本/工作站等主机上使用 ChipDeviceController(或后续版本的 chip-tool / Matter 控制器,仓库中的 examples/chip-tool)对桥设备进行发现、配网(commissioning)与集群读写测试。桥设备配网后,即可在控制器侧看到桥下动态注册的各个子设备端点,并可执行开灯、关灯、切换等 OnOff 操作以及读取桥接设备基本信息。


六、总结与扩展阅读

登录后查看全文
connectedhomeip