Matter ESP32 Bridge App 示例深入解析:基于 Dynamic Endpoints 的运行时桥接设备管理
Matter ESP32 Bridge App 示例深入解析:基于 Dynamic Endpoints 的运行时桥接设备管理
本指南以 examples/bridge-app/esp32/README.md 为骨架,结合 connectedhomeip 仓库中的实际源码,完整讲解 Matter ESP32 Bridge App 示例的构建、配网、Shell 命令操作,以及其核心机制——Dynamic Endpoints(动态端点)的宏定义、属性外部存储与读写回调实现。读完本文,你将能够编译烧录该桥接示例、通过 Shell 命令在运行时增删桥接灯设备,并用 chip-tool 等 Matter 控制器远程控制这些动态端点,同时理解在静态 ZAP 数据模型之外自定义运行时端点的完整方法。
示例概览:什么是 Matter Bridge
Matter Bridge(桥接器)是一种特殊的 Matter 设备,它把非 Matter 设备(例如 Zigbee、私有协议或纯软件模拟的设备)抽象为 Matter 端点,从而让这些设备可以被标准 Matter 控制器发现与控制。
examples/bridge-app/esp32 是一个原型应用(prototype application),用于演示 Matter bridge 与动态端点管理:桥接器允许你通过 Shell 命令在运行时添加和移除桥接设备,每个桥接设备对 Matter 控制器而言呈现为一个 On/Off Light(开关灯)。这意味着设备表不再是在编译期由 .zap 文件固定写死的,而是可以在运行期自由伸缩。
该示例的完整工程位于 examples/bridge-app/esp32,主要源码包括:
- main/main.cpp:动态端点数据结构声明、Shell 子命令注册、端点添加/移除逻辑、外部属性读写回调;
- main/include/Device.h 与 main/Device.cpp:桥接设备的抽象模型(名称、位置、开关状态、可达性);
- main/include/DeviceCallbacks.h 与 main/DeviceCallbacks.cpp:设备管理器回调;
- CMakeLists.txt、sdkconfig.defaults、partitions.csv:ESP-IDF 构建配置。
环境准备与构建烧录
原 README 将环境搭建指引指向 ESP32 平台的通用指南,对应的仓库路径为:
- 环境与工具链安装:docs/platforms/esp32/setup_idf_chip.md
- 构建与配网完整流程:docs/platforms/esp32/build_app_and_commission.md
核心步骤可归纳为:先 source esp-idf/export.sh 激活 ESP-IDF 环境,再在 connectedhomeip 仓库根目录执行 source scripts/activate.sh 激活 Matter 环境,然后进入示例目录构建:
# 激活 ESP-IDF
$ cd path/to/esp-idf
$ source export.sh
# 激活 Matter 环境
$ cd path/to/connectedhomeip
$ source scripts/activate.sh
# 进入 bridge-app 示例目录并构建
$ cd examples/bridge-app/esp32
$ idf.py set-target esp32 # 也可选择 esp32c3 / esp32s3 / esp32c6
$ idf.py build
烧录与串口监控(替换 (PORT) 为实际串口,如 /dev/ttyUSB0):
$ idf.py -p (PORT) erase_flash
$ idf.py -p (PORT) flash monitor
flash monitor 会同时完成烧录并打开串口日志监控,按 Ctrl+] 退出监控。
关键构建配置:动态端点容量
examples/bridge-app/esp32/CMakeLists.txt 在编译选项中显式定义了动态端点数量:
-DCHIP_DEVICE_CONFIG_DYNAMIC_ENDPOINT_COUNT=16
该宏在 src/include/platform/CHIPDeviceConfig.h 中定义,默认值为 0,即默认情况下 SDK 不预留任何动态端点;桥接示例通过编译选项将其提升为 16,对应 bridge max 命令输出的端点上限。同时 src/app/util/attribute-storage.h 中的 MAX_ENDPOINT_COUNT 被定义为 FIXED_ENDPOINT_COUNT + CHIP_DEVICE_CONFIG_DYNAMIC_ENDPOINT_COUNT,说明总端点容量是固定端点与动态端点之和。
此外 sdkconfig.defaults 启用了调试 Shell(CONFIG_ENABLE_CHIP_SHELL=y),这是后续使用 bridge 命令的前提;同时配置了 BLE(CONFIG_BT_ENABLED=y、CONFIG_BT_NIMBLE_ENABLED=y)用于 BLE 配网、IPv6 自动配置(CONFIG_LWIP_IPV6_AUTOCONFIG=y)以及自定义分区表(CONFIG_PARTITION_TABLE_CUSTOM=y)。
Shell 命令:运行时管理桥接设备
烧录并完成配网(commissioning)后,即可通过 ESP32 串口 Shell 执行 bridge 子命令管理桥接设备。完整的命令列表如下(与 README 一致,并补充了各命令的实际行为与源码依据):
| 命令 | 说明 |
|---|---|
bridge add [name] [location] |
添加一个新的桥接灯设备,可选名称与位置 |
bridge remove <endpoint> |
按端点 ID 移除设备 |
bridge list |
列出所有桥接设备 |
bridge toggle [endpoint] |
切换指定端点(或全部设备)的开关状态 |
bridge max |
显示端点容量限制 |
bridge remove_all |
移除全部桥接设备 |
这些子命令在 main.cpp 的 RegisterBridgeCommands() 中注册到 Matter Shell 引擎,通过 bridge <subcommand> 分发执行。
添加设备(bridge add)
bridge add # 添加默认设备 "Light 1",位置 "Room"
bridge add "Kitchen Light" # 自定义名称
bridge add "Lamp" "Bedroom" # 同时指定名称与位置
从 BridgeAddHandler 的实现可以看到:
- 名称默认为
"Light <N>"(N 为当前设备数加 1),位置默认为"Room"; - 参数超过 2 个会报错并提示用法;
- 若已达到
kMaxBridgedDevices(即CHIP_DEVICE_CONFIG_DYNAMIC_ENDPOINT_COUNT = 16)上限,返回CHIP_ERROR_NO_MEMORY; - 每个新设备被设置为可达(
SetReachable(true)),并注册状态变更回调HandleDeviceStatusChanged; - 每个设备还会分配独立的
DataVersion数组(用于 Matter 数据版本跟踪,数组大小与集群列表bridgedLightClusters的元素数一致),随后调用AddDeviceEndpoint()分配端点。
端点 ID 自动分配:AddDeviceEndpoint()(main.cpp)从 gFirstDynamicEndpointId 开始逐个尝试分配端点 ID,通过 emberAfSetDynamicEndpoint() 注册;若返回 CHIP_ERROR_ENDPOINT_EXISTS 则递增端点 ID 重试(并处理回绕),直到成功或遍历完所有槽位。端点 ID 的起始值在 InitServer() 中计算:取最后一个固定端点的下一个连续 ID(main.cpp)。
移除设备(bridge remove)
bridge remove 3
BridgeRemoveHandler 会校验参数必须为 0~65535 的整数端点 ID,通过 FindDeviceByEndpoint() 反查设备索引,调用 RemoveDeviceEndpoint() 执行 emberAfClearDynamicEndpoint() 注销端点,随后释放 Device 对象与 DataVersion 数组内存并更新设备计数。
列出设备(bridge list)
bridge list
输出示例(来自 README,格式与实际日志一致):
Bridged devices (2/16):
"Kitchen Light" @ Kitchen (endpoint 3, ON)
"Bedroom Lamp" @ Bedroom (endpoint 4, OFF)
对应 BridgeListHandler 的实现:依次遍历 gDevices 数组,输出名称、位置、端点 ID 与开关状态;若没有设备则打印 (none)。
切换开关(bridge toggle)
bridge toggle 3 # 切换端点 3 的设备
bridge toggle # 切换所有设备
BridgeToggleHandler 在带参时先按端点 ID 查找设备再取反其开关状态;无参时遍历全部设备逐一取反。该操作直接修改 Device 内部状态,并通过回调触发 Matter 属性上报(见下文"属性变更上报")。
查看容量(bridge max)与清空(bridge remove_all)
bridge max
输出 Max bridged devices(16)、Current devices 与 Available slots 三项信息。
bridge remove_all
遍历并注销全部设备、释放内存,最后打印移除数量。
从 Matter 控制器控制桥接设备
配网完成后,每个桥接灯都作为独立端点暴露给 Matter 控制器。README 给出了使用 chip-tool 控制端点 3 的命令:
# 打开端点 3 的灯
chip-tool onoff on <node-id> 3
# 关闭端点 3 的灯
chip-tool onoff off <node-id> 3
# 切换端点 3 的灯
chip-tool onoff toggle <node-id> 3
其中 <node-id> 是配网时指定的节点 ID(例如 docs/platforms/esp32/build_app_and_commission.md 中示例配网命令 chip-tool pairing ble-wifi 12345 MY_SSID MY_PASSWORD 20202021 3840 使用的 12345),3 是桥接设备的动态端点 ID。
从底层看,这些命令最终会命中 main.cpp 中的 emberAfExternalAttributeWriteCallback:控制器向端点 3 的 On/Off 集群写入 OnOff 属性时,桥接应用校验设备可达性后将写入值映射到 Device::SetOnOff(),从而驱动被桥接设备的真实开关逻辑。
深入 Dynamic Endpoints 机制
为什么需要动态端点
Matter 端点在常规开发中是通过 .zap 文件定义的:.zap 中声明端点及其包含的集群与属性,再由代码生成器产出静态的端点结构和代码。这种静态方案无法在运行时增减设备。README 明确指出,当前 SDK 对动态端点的支持有限,正因如此,桥接场景需要一套运行时可变的端点机制。
预留端点存储:NUM_DYNAMIC_ENDPOINTS 与 CHIP_DEVICE_CONFIG_DYNAMIC_ENDPOINT_COUNT
为支持未静态定义的端点,ZCL 属性存储机制会为 NUM_DYNAMIC_ENDPOINTS 个额外端点预留属性存储空间。这些额外端点的结构必须由应用自定义,并可在运行时修改。在桥接示例中,这个数量通过 CHIP_DEVICE_CONFIG_DYNAMIC_ENDPOINT_COUNT 编译宏设置为 16(见 CMakeLists.txt),且 MAX_ENDPOINT_COUNT = FIXED_ENDPOINT_COUNT + CHIP_DEVICE_CONFIG_DYNAMIC_ENDPOINT_COUNT(src/app/util/attribute-storage.h)。
动态端点宏定义族
为了便于应用构造这些端点结构,SDK 在 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)、DECLARE_DYNAMIC_ATTRIBUTE_WITH_STRING_DEFAULT(attId, attType, attSizeBytes, attrMask, defaultBytesPtr)、DECLARE_DYNAMIC_ATTRIBUTE_WITH_MIN_MAX_DEFAULT(attId, attType, attSizeBytes, attrMask, minMaxPtr)、DECLARE_DYNAMIC_ATTRIBUTE_LIST_END()、DECLARE_DYNAMIC_ATTRIBUTE_LIST_END_WITH_REVISION(clusterRevision)
- 声明必须以
DECLARE_DYNAMIC_ATTRIBUTE_LIST_BEGIN开始,其展开为EmberAfAttributeMetadata attrListName[] = {,即定义一个属性元数据数组; - 每个属性由
DECLARE_DYNAMIC_ATTRIBUTE或带_WITH_*_DEFAULT变体加入; - 末尾必须用
DECLARE_DYNAMIC_ATTRIBUTE_LIST_END(或带指定 cluster revision 的DECLARE_DYNAMIC_ATTRIBUTE_LIST_END_WITH_REVISION)闭合,两者都会自动追加一个0xFFFD(cluster revision)属性(attribute-storage.h); - 属性类型
attType使用 ZCL 类型名(如BOOLEAN、CHAR_STRING、ARRAY、INT16U),attSizeBytes为属性存储字节数,attrMask可携带MATTER_ATTRIBUTE_FLAG_WRITABLE、MATTER_ATTRIBUTE_FLAG_NULLABLE、MATTER_ATTRIBUTE_FLAG_MUST_USE_TIMED_WRITE等标志位(attribute-storage.h); - 默认值变体的差异:
_WITH_SCALAR_DEFAULT内联一个不超过 4 字节的标量默认值;_WITH_STRING_DEFAULT存储一个 Pascal 格式(长度前缀)字符串指针,要求字节在端点注册期间保持存活且不变;_WITH_MIN_MAX_DEFAULT额外携带EmberAfAttributeMinMaxValue最小/最大值元数据,并自动加上MIN_MAX掩码(attribute-storage.h)。
外部存储标志:所有通过上述宏定义的属性都会被自动标记为 MATTER_ATTRIBUTE_FLAG_EXTERNAL_STORAGE(对应 ZAP_ATTRIBUTE_MASK(EXTERNAL_STORAGE)),意味着 ZCL 数据库只保存属性元数据,实际值存储由应用负责维护。带 _WITH_*_DEFAULT 宏提供的默认值存放在 flash 元数据中,可通过 emberAfGetAttributeDefaultValue 访问(README 原话)。因此,对这些属性的读写必须在应用内通过 emberAfExternalAttributeWriteCallback 与 emberAfExternalAttributeReadCallback(或 AttributeAccessInterface)处理。
集群列表宏
DECLARE_DYNAMIC_CLUSTER_LIST_BEGIN(clusterListName)、DECLARE_DYNAMIC_CLUSTER(clusterId, clusterAttrs, role, incomingCommands, outgoingCommands)、DECLARE_DYNAMIC_CLUSTER_LIST_END
- 以
DECLARE_DYNAMIC_CLUSTER_LIST_BEGIN开头(展开为EmberAfCluster clusterListName[] = {); - 每个集群由
DECLARE_DYNAMIC_CLUSTER添加,其clusterAttrs参数引用前面用属性宏定义的属性列表,role用ZAP_CLUSTER_MASK(SERVER)或ZAP_CLUSTER_MASK(CLIENT)指定服务器/客户端角色; incomingCommands/outgoingCommands为命令 ID 数组,以kInvalidCommandId结尾;若无命令则传nullptr(宏内部会用MATTER_ARRAY_SIZE计算数量,nullptr表示空列表);- 以
DECLARE_DYNAMIC_CLUSTER_LIST_END闭合(attribute-storage.h)。
端点宏
DECLARE_DYNAMIC_ENDPOINT(endpointName, clusterList)
- 展开为
EmberAfEndpointType endpointName = { clusterList, MATTER_ARRAY_SIZE(clusterList), 0 },即定义一个端点类型结构,clusterList必须是前面用集群宏定义的集群列表(attribute-storage.h)。
桥接示例中的实际用法
main.cpp 完整展示了这套宏的用法。桥接灯的端点由三个集群组成:
// On/Off 集群:一个 BOOLEAN 类型的 OnOff 属性
DECLARE_DYNAMIC_ATTRIBUTE_LIST_BEGIN(onOffAttrs)
DECLARE_DYNAMIC_ATTRIBUTE(OnOff::Attributes::OnOff::Id, BOOLEAN, 1, 0), /* on/off */
DECLARE_DYNAMIC_ATTRIBUTE_LIST_END();
// Descriptor 集群:DeviceTypeList / ServerList / ClientList / PartsList 四个 ARRAY 属性
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();
// Bridged Device Basic Information 集群:NodeLabel(字符串)与 Reachable(布尔)
DECLARE_DYNAMIC_ATTRIBUTE_LIST_BEGIN(bridgedDeviceBasicAttrs)
DECLARE_DYNAMIC_ATTRIBUTE(BridgedDeviceBasicInformation::Attributes::NodeLabel::Id, CHAR_STRING, kNodeLabelSize, 0),
DECLARE_DYNAMIC_ATTRIBUTE(BridgedDeviceBasicInformation::Attributes::Reachable::Id, BOOLEAN, 1, 0),
DECLARE_DYNAMIC_ATTRIBUTE_LIST_END();
其中 kNodeLabelSize = 32、kDescriptorAttributeArraySize = 254(ZCL Struct 实现使用 254 字节的最大数组),见 main.cpp。随后将这些属性列表组装为集群列表:
// On/Off 集群支持的入站命令
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(BridgedDeviceBasicInformation::Id, bridgedDeviceBasicAttrs, ZAP_CLUSTER_MASK(SERVER), nullptr,
nullptr) DECLARE_DYNAMIC_CLUSTER_LIST_END;
// 端点 = 集群列表
DECLARE_DYNAMIC_ENDPOINT(bridgedLightEndpoint, bridgedLightClusters);
这里三个集群均作为 Server 角色,On/Off 集群声明了入站命令列表,其余两个集群无命令(nullptr)。
桥接设备的属性读写:外部存储回调
由于动态属性使用外部存储,桥接应用必须实现读写回调。README 指出可参考 main.cpp 的实现,仓库中的完整链路如下:
读回调 emberAfExternalAttributeReadCallback(main.cpp):
- 通过
emberAfGetDynamicIndexFromEndpoint(endpoint)把端点 ID 换算为动态索引,再映射到gDevices[]中的Device对象; - 对 BridgedDeviceBasicInformation 集群,由
HandleReadBridgedDeviceBasicAttribute处理(main.cpp):Reachable返回dev->IsReachable()、NodeLabel通过MakeZclCharString写出设备名、ClusterRevision返回ZCL_BRIDGED_DEVICE_BASIC_INFORMATION_CLUSTER_REVISION (2u); - 对 On/Off 集群,由
HandleReadOnOffAttribute处理(main.cpp):OnOff返回dev->IsOn(),ClusterRevision返回ZCL_ON_OFF_CLUSTER_REVISION (4u); - 其余属性返回
Status::Failure。
写回调 emberAfExternalAttributeWriteCallback(main.cpp):
- 同样先换算动态索引并取得
Device; - 校验设备可达且集群为 On/Off 后,调用
HandleWriteOnOffAttribute(main.cpp),将*buffer == 1映射为dev->SetOnOff(...),从而更新设备开关状态。
Device 类的状态维护见 Device.h 与 Device.cpp:它保存名称(32 字节)、位置(32 字节)、开关状态(kState_On/kState_Off)、可达性、端点 ID,并在状态变化时通过 SetChangeCallback 注册的回调通知上层(如 SetOnOff 变化时触发 kChanged_State,SetReachable 触发 kChanged_Reachable)。
属性变更上报
当桥接设备状态变化时,桥接应用需要主动向 Matter 控制器发起订阅/属性变更通知。HandleDeviceStatusChanged(main.cpp)根据变更掩码将变化映射为具体属性的上报:
kChanged_Reachable→Reachable属性;kChanged_State→ On/Off 集群的OnOff属性;kChanged_Name→NodeLabel属性。
上报通过 ScheduleReportingCallback(main.cpp)构造 ConcreteAttributePath,投递到 Matter 平台事件循环后调用 MatterReportingAttributeChangeCallback(见 CallReportingCallback,main.cpp),最终走 Matter 的 reporting 机制(对应 #include <app/reporting/reporting.h>)。
底层注册 API 与端点生命周期
动态端点的注册/注销由 src/app/util/attribute-storage.cpp 实现:
emberAfSetDynamicEndpoint(index, id, ep, dataVersionStorage, deviceTypeList, parentEndpointId)(attribute-storage.cpp):按索引注册动态端点。实现中会检查realIndex是否超过MAX_ENDPOINT_COUNT、端点 ID 是否有效、dataVersionStorage容量是否不小于 Server 集群数,并检测端点 ID 冲突(返回CHIP_ERROR_ENDPOINT_EXISTS),这与AddDeviceEndpoint()中的重试逻辑对应;emberAfClearDynamicEndpoint(index, ...)(attribute-storage.cpp):注销动态端点,桥接示例的RemoveDeviceEndpoint()(main.cpp)调用它并释放设备内存;emberAfGetDynamicIndexFromEndpoint(id)(attribute-storage.cpp):将端点 ID 转换为相对固定端点区的动态索引,供读写回调使用。
在 InitServer()(main.cpp)中还做了几件与端点生命周期相关的事:
- 计算动态端点起始 ID:
gFirstDynamicEndpointId = 最后一个固定端点 ID + 1; - 禁用最后一个固定端点:该端点是 ZAP 生成的"占位端点",用于确保所需集群代码被生成,运行时被
emberAfEndpointEnableDisable(..., false)关闭; - 为端点 0 设置 Root Node 设备类型(
DEVICE_TYPE_ROOT_NODE 0x0016)、端点 1 设置 Bridge(聚合节点)设备类型(DEVICE_TYPE_BRIDGE 0x000e),见 main.cpp; - 每个动态端点注册时携带设备类型列表
gBridgedOnOffDeviceTypes,包含DEVICE_TYPE_LO_ON_OFF_LIGHT (0x0100)与DEVICE_TYPE_BRIDGED_NODE (0x0013),父端点 ID 为 1(bridge 端点),见 main.cpp。
桥接设备的数据模型与状态跟踪
桥接示例在应用层维护自己的设备数据库 gDevices<a href="https://link.gitcode.com/i/782e5fc880cf7336bd738814ad5a01f7" target="_blank">] 与 gBridgedDataVersions[](大小均为 CHIP_DEVICE_CONFIG_DYNAMIC_ENDPOINT_COUNT,见 [main.cpp)。每次 bridge add 都会:
- 分配新的
Device与DataVersion[](按集群列表元素数分配,清零初始化); - 设置可达并注册变更回调;
- 调用
AddDeviceEndpoint()注册动态端点; - 记录到数组槽位并递增
gBridgedDeviceCount。
bridge remove / bridge remove_all 则执行对称的注销与内存释放,并递减计数。DataVersion 用于 Matter 数据版本跟踪,配合 emberAfSetDynamicEndpoint 的 dataVersionStorage 参数,是动态端点在订阅/属性变更协议中保持一致性的关键。
Cluster 控制:chip-tool 命令行用法
README 的 "Cluster control" 一节说明:要使用 Client 发送 Matter 命令,运行已构建的可执行文件并传入目标集群名、目标命令名与端点 ID。以 On/Off 集群为例:
$ ./out/debug/chip-tool onoff on <NODE ID> <ENDPOINT>
该命令发送单个命令包后即退出。结合前述 docs/platforms/esp32/build_app_and_commission.md 的配网说明,完整的交互流程为:
- 构建 chip-tool:
scripts/examples/gn_build_example.sh examples/chip-tool out/debug; - 配网(BLE + Wi-Fi):
out/debug/chip-tool pairing ble-wifi 12345 MY_SSID MY_PASSWORD 20202021 3840(节点 ID12345、测试 discriminator3840、测试 pin code20202021); - 控制桥接灯:
out/debug/chip-tool onoff on 12345 3、off、toggle同理。
通过 bridge list 查看的端点 ID 就是 chip-tool 命令中 <ENDPOINT> 参数,二者一一对应。
小结
Matter ESP32 Bridge App 示例完整展示了动态端点在桥接场景的落地方式:Shell 命令提供运维入口,DECLARE_DYNAMIC_* 宏族负责描述运行时可变的端点结构,emberAfExternalAttributeRead/WriteCallback 承担外部存储属性的读写,emberAfSetDynamicEndpoint/emberAfClearDynamicEndpoint 管理端点生命周期,属性上报机制则保证控制器侧状态实时同步。这套模式不仅适用于 ESP32,也为其他平台编写桥接类 Matter 应用提供了可复用的参考范式。
如需继续深入,可阅读:
- 动态端点宏与底层存储:src/app/util/attribute-storage.h、src/app/util/attribute-storage.cpp
- 端点配置辅助 API:src/app/util/endpoint-config-api.h
- 动态端点数量配置:src/include/platform/CHIPDeviceConfig.h
- ESP32 平台完整构建与配网指南:docs/platforms/esp32/build_app_and_commission.md、docs/platforms/esp32/setup_idf_chip.md
- 其他平台的桥接示例(Linux 版本包含更丰富的桥接演示):examples/bridge-app/linux