Matter Proximity Ranging 集群服务器0x0433架构解析与 RangingAdapter 开发指南【免费下载链接】connectedhomeipMatter (formerly Project CHIP) creates more connections between more objects, simplifying development for manufacturers and increasing compatibility for consumers, guided by the Connectivity Standards Alliance.项目地址: https://gitcode.com/GitHub_Trending/co/connectedhomeip本指南基于 connectedhomeip 仓库中 src/app/clusters/proximity-ranging-server/README.md 及其配套源码系统讲解 Matter Proximity Ranging 集群服务端的代码驱动code-driven实现从集群职责划分、Feature 配置、Codegen 集成到RangingAdapter接口契约、ProximityRangingDriver的会话调度与测量过滤再到命令处理、事件上报与多端点部署。读完本文你将掌握如何在应用侧实现一个面向 BLE Beacon RSSI、Bluetooth Channel Sounding、Wi-Fi USD 或 UWB 的测距适配器并正确地把 Proximity Ranging 集群挂载到 Matter 设备端点上。集群定位与职责划分Proximity Ranging 集群cluster ID0x0433用于配置 proximity ranging 会话并在 Matter 设备之间上报测距数据。它支持多种测距技术BLE Beacon RSSI、Bluetooth Channel SoundingBLTCS、Wi-Fi USD含 Round Trip Time / Next Generation 两种子技术以及 UWB。该目录下是一个代码驱动的 C 服务端实现遵循DefaultServerCluster模式使用Config Builder 风格的 API 做功能配置并通过CodegenIntegration支持基于 ZAP 的部署。整个运行时被明确地划分为三个层次各司其职层次负责内容ProximityRangingClusterSDK每端点一个实例Matter 协议交互属性读取、命令分发、Feature 位图所有权构造时经 Config 固化、StartRangingRequest的规格预校验spec early validation、测距结果与会话状态事件发射、来自驱动的属性变更通知ProximityRangingDriverSDK具体类会话 ID 分配与会话簿记session→adapter 映射、把StartRangingRequest/StopRangingRequest路由到持有对应技术/会话的 adapter、跨已注册 adapter 聚合RangingCapabilities与 Feature 位、把异步 adapter 回调测量数据、会话停止、属性变更转发给集群Application应用每种受支持的测距技术实现一个RangingAdapter把 adapter 以SpanRangingAdapter * const形式传给驱动构造函数adapter 集合在驱动生命周期内固定持久化每个 adapter 的设备身份值例如 BLE Device ID分层边界在 ProximityRangingCluster.h 与 ProximityRangingDriver.h 中体现得非常清楚集群类继承DefaultServerCluster并实现ProximityRangingDriver::CallbackOnMeasurementData、OnSessionStopped、OnAttributeChanged而驱动类继承RangingAdapter::Callback把 adapter 侧的三类异步事件翻译成集群侧的回调。架构总览README 中给出的分层架构图完整呈现了从集群到驱动的调用链┌─────────────────────────────────────────────────────────────┐ │ ProximityRangingCluster (SDK, per-endpoint) │ │ - ReadAttribute, InvokeCommand, Events │ │ - Config { ProximityRangingDriver driver } │ └──────────────────────────┬──────────────────────────────────┘ │ ProximityRangingDriver::Callback ┌──────────────────────────▼──────────────────────────────────┐ │ ProximityRangingDriver (SDK, concrete) │ │ - Session ID allocation session→adapter table │ │ - Routes Start/Stop to the adapter owning the technology │ │ - Aggregates capabilities / supported features │ └──────────────────────────┬──────────────────────────────────┘ │ RangingAdapter interface ┌──────────────────────────▼──────────────────────────────────┐ │ Application-supplied RangingAdapters (one per technology) │ └─────────────────────────────────────────────────────────────┘结合源码可以补充几个关键事实集群实例通过Config持有一份TimerDelegate 它是驱动内部墙钟调度会话StartTime/EndTime/RangingInstanceInterval的计时源必须比集群存活更久。见 ProximityRangingCluster.h 中Config结构体TimerDelegate是强制输入WithFeatures()与WithAdapters()是可选 builder。每个集群实例在构造时内部独占一个ProximityRangingDrivermDriver私有成员不存在跨端点共享的驱动因此多端点部署语义清晰每个端点拥有独立的会话池、独立的回调接线、独立互斥的 adapter 集合。每个RangingAdapter只能被注册给恰好一个驱动实例adapter 排他性这是应用侧必须遵守的约束。Feature 配置与属性可见性集群支持四个可选 Feature全部在构造期通过Config::WithFeatures()固化Feature 位图在构造后不可变Feature枚举值使能的测距能力关联的强制可选属性Wi-Fi USD Proximity DetectionFeature::kWiFiUsdProximityDetection基于 Wi-Fi USD 的测距WiFiDevIKBluetooth Channel SoundingFeature::kBluetoothChannelSounding基于 Bluetooth Channel Sounding 的测距BLTDevIK、BLTCSSecurityLevel、BLTCSModeCapabilityBLE Beacon RSSIFeature::kBleBeaconRssi基于 BLE Beacon RSSI 的测距BLEDeviceIdUWB RangingFeature::kUwbRanging基于 UWB 的测距—WithFeatures()在设置 Feature 位的同时会把对应的强制关联属性标记为存在present。至少必须启用一个 Feature。README 特别强调应用在构造点显式声明Feature 掩码使集群的规格契约在调用点可见而不是在运行时从已注册 adapter 集合推断——保持两者同步是配置责任驱动不会自动推导。这一按 Feature 决定属性可见性的行为在 ProximityRangingCluster.cpp 的Attributes()中得到印证featureAttributes数组把WiFiDevIK、BLEDeviceID、BLTDevIK、BLTCSSecurityLevel、BLTCSModeCapability分别与对应的 Feature 位绑定Feature 未启用时该属性不出现在属性列表中。而ReadAttribute侧同文件#L64-L130在读取这些属性时会先向驱动查询对应配置拿不到就返回Status::UnsupportedAttribute。Codegen 集成为什么自动生成回调是 no-opProximityRangingCluster在构造时必须拿到驱动引用README 描述为ProximityRangingDriver 当前仓库实际实现为TimerDelegate adapter 集合见下文。该引用归应用所有因此自动生成的MatterProximityRangingClusterInitCallback无法自行构造集群——它触发时应用还没来得及提供驱动。为此Codegen 集成是有意的 no-op 桩CodegenIntegration.cpp 中MatterProximityRangingClusterInitCallback、MatterProximityRangingClusterShutdownCallback、以及两个 PluginServer 回调全部为空实现。Codegen 消费者改用ProximityRangingServer它内部持有一个绑定到指定端点的ProximityRangingCluster通过LazyRegisteredServerCluster延迟构造并负责把集群注册到 Codegen 数据模型提供者的 registry 中。注册动作必须由应用在Server::Init()之后的钩子里显式触发。当前仓库 CodegenIntegration.h 中ProximityRangingServer的构造函数签名为ProximityRangingServer(EndpointId endpointId, TimerDelegate timerDelegate, SpanRangingAdapter * const adapters);其中endpointId必须与.zap配置一致Init(BitMaskFeature features)负责真正构造集群并注册未调用Init前集群不注册避免 IM 事件循环处理到未就绪的集群Deinit()反注册并销毁对未Init或已 deinit 的情况安全可重复调用CodegenIntegration.cpp。以当前仓库 API 为准一个典型的 ZAP 部署用法如下示意#include app/clusters/proximity-ranging-server/CodegenIntegration.h #include app/clusters/proximity-ranging-server/RangingAdapter.h namespace { constexpr EndpointId kRangingEndpoint 2; MyBleAdapter sBleAdapter; MyWiFiAdapter sWiFiAdapter; MyBltcsAdapter sBltcsAdapter; RangingAdapter * sAdapters[] { sBleAdapter, sWiFiAdapter, sBltcsAdapter }; // 需要一个应用持有的 TimerDelegate例如基于 SystemLayer 的实现 extern TimerDelegate GetRangingTimerDelegate(); ProximityRanging::ProximityRangingServer sServer( kRangingEndpoint, GetRangingTimerDelegate(), SpanProximityRanging::RangingAdapter * const(sAdapters)); } // namespace void ApplicationInit() { constexpr BitMaskProximityRanging::Feature kFeatures{ ProximityRanging::Feature::kBleBeaconRssi, ProximityRanging::Feature::kWiFiUsdProximityDetection, ProximityRanging::Feature::kBluetoothChannelSounding, }; if (CHIP_ERROR err sServer.Init(kFeatures); err ! CHIP_NO_ERROR) { ChipLogError(AppServer, Proximity Ranging init failed: % CHIP_ERROR_FORMAT, err.Format()); } } void ApplicationShutdown() { sServer.Deinit(); }注意README 中的示例以直接传入 driver的方式构造ProximityRangingServer而当前仓库的实际构造函数以TimerDelegate adapter 集合替代了 driver 参数集群内部自建驱动。若你的应用基于当前仓库构建请以上述实际签名为准。对于代码驱动非 ZAP应用无需这个包装类直接通过ProximityRangingCluster::Config(timerDelegate).WithFeatures(...).WithAdapters(...)构造集群并显式搭建集群注册树即可。RangingAdapter 接口契约每种测距技术实现为一个RangingAdapter。应用为每种技术构造一个 adapter并在驱动构造时以Span形式提供。接口方法如下方法说明GetTechnology()返回该 adapter 实现的RangingTechEnumGetCapabilities()返回该 adapter 的RangingCapabilitiesStructStartSession()启动一次测距会话同步StopSession()停止一个测距会话同步StopAllSessions()停止所有活动会话驱动 shutdown 时调用GetActiveSessionIds()把该 adapter 的活动会话 ID 追加到调用者提供的 SpanGetDeviceId()可选每设备 64 位 ID仅 BLERBC adapterGetWiFiUsdConfig()可选WiFiUsdConfig仅 Wi-Fi USD adapterGetBltcsConfig()可选BltcsConfig仅 BLTCS adapteradapter 通过RangingAdapter::Callback向驱动异步上报结果回调触发时机OnMeasurementData()每个会话有测量数据可用时OnRangingSessionStopped()会话结束超时、请求停止、硬件故障OnAttributeChanged()adapter 持有的属性值发生变化驱动实现该 Callback并把会话 ID 翻译进集群的会话事件汇session-event sink后转发每个事件。单次测量single-shot会话模型从 RangingAdapter.h 源码结构看每个测距会话分两步建立从而把StartTime/EndTime/RangingInstanceInterval的调度集中到驱动避免在每个 adapter 中重复实现PrepareSession(sessionId, params)同步——adapter 校验无线电能否满足请求对端兼容性、安全模式、资源可用性等并暂存按会话所需的簿记。返回ClusterStatusCode成功即承诺接收该会话集群专属失败StatusCodeEnum值会在集群向客户端暴露会话 ID 之前拒绝请求。一旦接受并占用了资源后续必须通过StopSession释放见停止语义。StartSession(sessionId)同步——触发恰好一次测距实例。驱动在StartTime延迟后首次调用StartTime 0时立即调用周期性测距时每个rangingInstanceIntervaltick 再次调用。adapter 使用PrepareSession暂存的参数完成一次测距测量每次被接受的StartSession调用恰好发出一次OnMeasurementData然后等待下一次StartSession或终态StopSession。会话记录在多次StartSession之间不释放只有StopSession会释放它。StartSession返回语义CHIP_NO_ERROR表示无线电已启动若 adapter 正忙于完成上一次测距无线电暂无法承接新请求可返回CHIP_ERROR_BUSY驱动继续维持周期调度、在下个 tick 重试异步无线电故障必须通过OnRangingSessionStopped(kHardwareError)上报。会话 ID 是驱动分配的 1 字节值原样传入两个调用adapter 需要自行跟踪哪些 ID 处于在途状态并对每个经PrepareSession接受的会话上报终止。停止语义与线程模型StopSession(sessionId)必须对会话的任何内部状态统一生效——已 prepare 未 start、正在测量、或 tick 间空闲——三种情况下 adapter 都要释放每会话资源、执行与当前状态对应的无线电拆除、并恰好发出一次OnRangingSessionStopped。adapter 严禁在PrepareSession内部同步发出OnRangingSessionStopped若启动在准备期已知失败应从PrepareSession返回集群专属失败状态码终止回调只有在PrepareSession返回成功后才合法。线程方面接口方法全部由Matter 主线程调用Callback是线程安全的adapter可以从任意线程调用它。可选的GetDeviceId/GetWiFiUsdConfig/GetBltcsConfig默认返回std::nullopt只有实现了对应技术的 adapter 才需要覆写——覆写后集群才会在读取相应属性时给出值否则返回UnsupportedAttribute见 ProximityRangingCluster.cpp。Adapter 集合的静态约束Adapter 集合在驱动构造时固定——它反映设备物理无线电配置运行时不会变化// Backing array must outlive the driver. RangingAdapter * sAdapters[] { sBleAdapter, sWiFiAdapter, sBltcsAdapter }; ProximityRangingDriver sDriver{ SpanRangingAdapter * const(sAdapters) };两个硬性约束在 ProximityRangingDriver.cpp 的构造函数中用VerifyOrDie强制执行因为静态组合错误属于配置 bug每个指针必须非空集合内每个 adapter 的GetTechnology()必须唯一禁止同一技术注册多个 adapter。构造时驱动还会对每个 adapter 调用SetCallback(this)把自身注册为其回调接收方。并发会话上限由宏CHIP_CLUSTER_PROXIMITY_RANGING_MAX_CONCURRENT_SESSIONS控制默认16ProximityRangingDriver.h它决定驱动内部ObjectPoolSession, kMaxConcurrentSessions会话池的容量。内存预算更紧或会话需求更高的平台可在构建配置中例如-D或CHIPProjectConfig覆写该宏。当 adapter 接受了请求但池中已无空位时驱动会立即对 adapter 调用StopSession回滚其预留并向集群上报集群专属失败StatusCodeEnum::kBusySessionCapacityReached。StartRangingRequest 的规格预校验HandleStartRangingRequest在触碰驱动之前先执行规格派生的校验ProximityRangingCluster.cpp 的ValidateStartRangingRequest。校验失败返回集群专属状态码满足任一条件即拒绝kRejectedInfeasibleRanging请求本身不可行请求技术对应的 Feature 位未在FeatureMap中置位匹配的DeviceRoleConfigOptional 缺失或存在一个不匹配的角色配置不一致例如同时携带多个技术的 role config角色枚举不属于请求技术所属的角色家族例如对kBLEBeaconRSSIRanging请求kBLTInitiatorRoleReportingCondition.MinDistanceCondition 0或MaxDistanceCondition 0附加校验源码级补充minDistanceCondition maxDistanceCondition同样被判为不可行。kRejectedInfeasibleRangingTriggers触发配置非法Trigger.EndTime Trigger.StartTimeTrigger.RangingInstanceInterval 0当该字段存在时。各技术的角色家族在源码中逐一枚举BLTCS 只接受kBLTInitiatorRole/kBLTReflectorRoleWi-Fi USDkWiFiRoundTripTimeRanging/kWiFiNextGenerationRanging只接受kWiFiSubscriberRole/kWiFiPublisherRoleBLE Beacon RSSI 只接受kBLEScanningRole/kBLEBeaconRole未知技术一律判不可行。adapter 可以信赖这些预校验因此只需处理技术专属限制例如硬件不支持所请求的频段。命令流程与响应语义StartRangingRequest与StopRangingRequest均同步处理。README 给出的时序如下Client Cluster Driver Adapter │ │ │ │ ├─ StartRangingRequest ──►│ │ │ │ ├─ HandleStartRanging ───►│ │ │ │ ├─ FindAdapter(tech) │ │ │ ├─ allocate session │ │ │ ├─ PrepareSession ───►│ │ │ │◄─ ClusterStatusCode ┤ │ │◄─ ClusterStatusCode ────┤ │ │◄─ StartRangingResponse ─┤ │ │ │ │ ├─ StartSession ─────►│成功路径下集群发送携带分配好SessionID的StartRangingResponse。拒绝路径下驱动/adapter 返回集群专属失败ClusterStatusCodeStatusCodeEnum值如RejectedInfeasibleRanging或BusySessionCapacityReached集群直接以该状态码作为命令的响应不发送StartRangingResponse——这一行为在 ProximityRangingCluster.cpp 中有明确注释StartRangingResponse只在请求成功时发送。驱动侧的三阶段处理ProximityRangingDriver.cpp阶段一PrepareSession——向匹配技术的 adapter 请求校验并暂存会话成功后才提交会话记录阶段二启动EndTime截止定时器——trigger.endTime因预校验保证endTime startTime始终严格为正驱动endTimer阶段三触发首次测量——startTime 0时同步调用IssueStartSession否则以startTime为延迟启动nextTrigger定时器定时器触发时再发起。另外会话 ID 从接受时刻起就可见于SessionIDList属性即使StartTime延迟尚未结束驱动会立即把该属性标记为 dirty因为客户端收到kAccepted后有权看到该 ID。StopRangingRequest的语义ProximityRangingCluster.cpp 中若SessionID不匹配任何活动会话服务端按规格返回状态码INVALID_IN_STATE。驱动在HandleStopRanging中先取消会话的待处理定时器再调用 adapter 的StopSession。事件上报集群发射两个事件RangingResult测量数据可用时发射。路径为 adapter 的Callback::OnMeasurementData()→ 驱动转发为ProximityRangingDriver::Callback::OnMeasurementData()→ 集群在 ProximityRangingCluster.cpp 中构造Events::RangingResult::Type携带sessionID与rangingResultData并经eventsGenerator发射。RangingSessionStatus会话异步结束时发射。路径为 adapter 侧Callback::OnRangingSessionStopped()、集群侧Callback::OnSessionStopped()事件携带sessionID与status同文件#L231-L239。注意RangingSessionStatus的事件源有区分由驱动/集群在处理过程中主动停止的会话也会经 adapter 的OnRangingSessionStopped回调回流并触发该事件。属性变更通知链路当 adapter 持有的属性值变化例如 BLE Device ID 轮换时adapter 调用RangingAdapter::Callback::OnAttributeChanged()驱动经ProximityRangingDriver::Callback::OnAttributeChanged()转发给集群集群调用NotifyAttributeChanged(attributeId)把属性标记为 dirty订阅者即可观察到新值ProximityRangingCluster.cpp。驱动内部还会自发地把SessionIDList标记 dirty——会话接受HandleStartRanging与回收RetireSession时各一次。驱动内部墙钟调度、报告过滤与状态重映射这一节的内容主要来自 ProximityRangingDriver.cpp 的实现是 README 之上最有价值的源码深化点。墙钟归属Wall-clock ownership驱动独占全部墙钟调度StartTime延迟、EndTime截止、RangingInstanceInterval周期 tick 均由驱动内的NextTriggerTimer/EndTimer每个会话各一个TimerContext管理。adapter 永远不会看到startTime/endTime/rangingInstanceInterval字段也看不到ReportingCondition——BuildStartParams同文件#L43-L68只把technology、各技术的 role config、frequencyBand、bandwidth传给 adapter。adapter 对节奏完全无状态每次StartSession只执行单次测距。周期测距的节拍锚定在发出StartSession的时刻每次调用后驱动以now interval重挂nextTrigger因此 tick 间距严格等于interval与OnMeasurementData到达时间无关IssueStartSession#L479-L503。若StartSession返回CHIP_ERROR_BUSY驱动记日志并按既有节奏继续。ReportingCondition 过滤每个会话记录reporting条件与interval周期毫秒nullopt表示单次瞬时测距。驱动在OnMeasurementData中自行执行SatisfiesReporting#L395-L424distance非空时低于minDistanceCondition或高于maxDistanceCondition的测量被丢弃distance为空而存在任一距离条件时按规格距离为 null 时除非被 ReportingCondition 禁止否则仍应发射 RangingResult的语义有距离条件时抑制该测量存在errorMarginCondition且测量errorMargin大于该条件时丢弃。对单次瞬时测距rangingInstanceInterval nullopt被过滤的测量就是无线电的唯一一次机会——驱动不会重新发起StartSession会话悬挂至EndTime触发再由下方所述的状态重映射给出规格正确的结局。周期测距中被过滤的测量则不影响节奏。kPeerNotFound 状态重映射与被动响应方驱动会把 adapter 上报的kSessionEndTimeReached终态重映射为kPeerNotFound前提是该会话在整个生命周期内从未有测量通过报告过滤peerFound false。但被动响应方会话kBLEBeaconRole/kWiFiPublisherRole/kBLTReflectorRole抑制该重映射OnRangingSessionStopped#L322-L356真实无线电在这些角色下本就不产生测量没有测量是预期结果而非找不到对端。会话记录中的isPassiveResponder标志在HandleStartRanging时按请求角色设置。瞬时测距的提前终止瞬时测距在首个通过报告过滤的测量到达时立即提前终止驱动取消两个定时器并调用 adapter 的StopSession随后OnRangingSessionStopped回调回收会话并发射RangingSessionStatus(SessionEndTimeReached)事件OnMeasurementData#L358-L393。多端点支持每个端点构造自己的ProximityRangingCluster拥有自己的 Feature 位图。当前ProximityRangingDriver同一时刻只保留一个集群回调因此一个驱动实例在Init()/Shutdown()生命周期内绑定单个集群实例。在多个端点暴露 proximity ranging 的应用应当为每个端点构造一个驱动及各自的 adapter 集合。从源码看这一约束已被进一步收紧每个集群在构造时即内部拥有独立的驱动与独占的 adapter 集合端点间互不共享会话池与回调。测试与构建佐证该目录配套的单元测试可以验证本文描述的多数行为是深入理解实现的最佳入口TestProximityRangingDriver.cpp直接面向驱动、不经过集群的单元测试覆盖ReportingCondition过滤min/max 距离、errorMargin、kSessionEndTimeReached → kPeerNotFound重映射、以及驱动拥有的PrepareSession → StartSession → StopSession调度。测试使用MockRangingAdapter记录每次PrepareSession/StartSession/StopSession调用并直接驱动Callback还以mStartError CHIP_ERROR_BUSY模拟上一次测量仍在进行。TestProximityRangingCluster.cpp 与 TestBleRssiRangingHelpers.cpp分别覆盖集群侧行为与 BLE RSSI 辅助函数。构建层面BUILD.gn 提供两个 targetproximity-ranging-server集群 驱动 adapter 接口依赖zzz_generated/app-common/clusters/ProximityRanging的生成代码与可选的ble-rssi-helpers仅实现 BLE Beacon RSSI 技术的平台才依赖避免无关平台被拉入src/ble头文件。附BLE Beacon RSSI 辅助工具对实现 BLE Beacon RSSI adapter 的平台BleRssiRangingHelpers.h 提供了一套开箱即用的工具HmacObfuscateBleDeviceId按规格用HMAC-SHA256(sessionKey, BLEDeviceID (big-endian) || messageCounter (big-endian))生成ObfuscatedBLEDeviceIdPlaintextObfuscateBleDeviceId明文大端BLEDeviceId忽略 sessionKey会空中泄露设备标识仅用于测试EncodeBeaconPayload/DecodeBeaconPayload把 64 位BLEDeviceID编码进广播负载OpCode、消息计数器、发射功率、混淆 ID或在扫描角色下校验收到的广播是否来自候选BLEDeviceID常量时间比较GenerateBleDeviceId/RetrieveGenerateBleDeviceId用平台 CSPRNG 生成非零随机 ID后者读取DefaultStorageKeyAllocator::ProximityRangingBleDeviceId()持久化键首次使用时生成并写回存储保证跨重启的 ID 稳定性——规格要求BLEDeviceID稳定以便对端跨时间关联信标。注意规格保留kInvalidBleDeviceId 0为哨兵值生成的 ID 不得等于它。小结Proximity Ranging 集群0x0433在 connectedhomeip 中是一个典型的SDK 框架 应用注入技术实现结构集群负责 Matter 协议面与规格预校验驱动负责会话簿记、墙钟调度与测量过滤应用只需按RangingAdapter契约实现每种技术的无线电适配并静态注入。掌握Config::WithFeatures()的 Feature 契约、adapter 的 single-shot 会话模型与回调义务每个被接受的会话必须恰好一次OnRangingSessionStopped、以及驱动对ReportingCondition与kPeerNotFound重映射的语义即可在任意支持的平台上正确接入该集群。【免费下载链接】connectedhomeipMatter (formerly Project CHIP) creates more connections between more objects, simplifying development for manufacturers and increasing compatibility for consumers, guided by the Connectivity Standards Alliance.项目地址: https://gitcode.com/GitHub_Trending/co/connectedhomeip创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考