Matter 动态端点桥接实战:基于 Linux Bridge 示例理解并构建可热插拔的桥接设备
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 运行时增删端点的完整流程
示例演示了"运行时添加与移除端点"这一核心概念。按文档描述(并结合当前版本源码)的典型流程为:
- 声明
bridgedLightEndpoint结构; - 动态添加三盏灯,占据端点
2、3、4(分别对应Light 1、Light 2、Light 3); - 移除端点
3,模拟删除Light 2; - 添加第四盏灯
Light 4,占据端点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 前置条件
- 一块 Raspberry Pi 4 开发板;
- 一个 USB 蓝牙适配器:Ubuntu Desktop 会自行发送蓝牙广播,从而阻塞 CHIP 通过 BLE 连接设备;若使用 Ubuntu Server,需要通过 APT 安装
pi-bluetooth; - 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 操作以及读取桥接设备基本信息。
六、总结与扩展阅读
- 动态端点机制:
.zap静态声明 + 运行时外部存储 + 应用自维护状态,是 Matter 桥接设备(把一个或多个非 Matter 子设备映射为多个端点)的标准实现路径; - 宏体系:
DECLARE_DYNAMIC_ATTRIBUTE*→DECLARE_DYNAMIC_CLUSTER*→DECLARE_DYNAMIC_ENDPOINT,配合emberAfSetDynamicEndpoint/emberAfClearDynamicEndpoint完成端点的运行时生命周期管理; - 读写回调:
emberAfExternalAttributeReadCallback/emberAfExternalAttributeWriteCallback或AttributeAccessInterface是动态属性数据访问的唯一入口; - 可继续深入的文件:
- 宏定义与注册 API:src/app/util/attribute-storage.h、src/app/util/attribute-storage.cpp
- 桥接示例完整实现:examples/bridge-app/linux/main.cpp、examples/bridge-app/linux/Device.cpp、examples/bridge-app/linux/include/Device.h
- ZAP 配置:examples/bridge-app/bridge-common/bridge-app.zap、examples/bridge-app/bridge-common/bridge-app.matter
- 其他平台移植:examples/bridge-app/asr/、examples/bridge-app/esp32/、examples/bridge-app/telink/