Android 16 引入了测距模块。此协议和载荷规范定义了带外 (OOB) 通信的消息序列和载荷，用于在进行测距的发起方设备和响应方设备之间交换测距配置，以及启动和停止测距。
本页的主要目的是让非 Android 设备提供商能够实现此规范，以便其设备可以与 Android 设备兼容，从而进行测距。
消息和消息序列
本部分介绍了消息以及消息交换的顺序。
下表显示了 OOB 交换中存在的所有消息：
| 消息 | 消息 ID |
|---|---|
Ranging Capability Request |
0x0 |
Ranging Capability Response |
0x1 |
Ranging Configuration |
0x2 |
Ranging Configuration Response（可选） |
0x3 |
Stop Ranging |
0x6 |
Stop Ranging Response（可选） |
0x7 |
如图 1 和图 2 所示，消息交换的触发方式取决于通信渠道。
对于基于连接的通信渠道（例如 BLE GATT），消息交换从发起方设备向响应方设备发送 Ranging Capability Request 开始。响应方设备通过发送 Ranging
Capability Response 进行回复，如图 1 所示：
图 1. 使用基于连接的通信渠道进行 OOB 消息交换。
对于基于广告的通信渠道，响应方设备首先会广播 Ranging Capability。在这种情况下，不会从发起设备发送 Ranging Capability Request。相反，在检测到广告后，当发起方（初始扫描器）设备准备就绪时，它会通过广播 Ranging Configuration 作为其第一条消息来做出响应，如图 2 所示：
图 2. 使用基于广告的通信进行 OOB 消息交换。
在两种情况下，其余的消息交换过程都是相同的。响应方设备会在收到 Ranging Configuration 消息后立即开始测距。响应方设备在收到或检测到 Stop
Ranging 消息后停止测距。
在基于连接的流程中，响应方设备仅填充 Ranging Capability Request 消息中请求的测距技术的功能，而在广播流程中，响应方设备必须列出其所有功能，因为没有先前的功能请求消息。
发起方设备假定，对于其发送的任何请求消息，只会收到一个响应。响应设备不得做出任何此类假设，以便能够以任意顺序响应任何请求。这样可确保响应方设备能够响应来自发起方设备的多个连续 Ranging Capability Request 消息或任何其他无序消息。
测距技术 ID
下表列出了测距技术的 ID：
| 测距技术 | ID |
|---|---|
| UWB | 0x0 |
| CS | 0x1 |
| Wi-Fi NAN RTT | 0x2 |
| RSSI | 0x3 |
| RFU | 0x4 - 0xFF |
在需要测距技术 ID 的下表中，会使用这些 ID。对于包含测距技术 bitfield 的字段，当相应技术包含在 bitfield 中时，会设置与该技术 ID 的索引对应的位。
例如，RSSI 的 ID 值为 3，但如果 RSSI 包含在测距技术位字段中，则必须开启 ID（3）位置的位（第一个位位于位置 0），这会使位字段的最终值为 0x8。如果同时包含 UWB 和 RSSI，则位字段的值为 0x0A（位 0 和位 3 都处于开启状态）。
邮件格式
每条消息都包含一个标头和一个载荷。
图 3. 消息格式。
标题
大小：2 字节
说明：标头是所有消息共有的部分，也是消息中首先包含的部分。标头包含版本和消息类型 ID。版本字段用于指定消息内容所遵循的本规范的版本。本规范的当前版本为 1。如需详细了解如何在不同版本的设备之间使用版本控制，请参阅版本控制。标头在不同版本之间保持向后兼容，这意味着使用情形始终可以解析它，以确定消息的版本和 ID。
下表总结了标头：
| 八位字节 | 数据类型 | 说明 | 值 |
|---|---|---|---|
| 0 | uint8 | 版本 | 0x1 - 当前版本 |
| 1 | unit8 | 消息 ID |
|
载荷
大小：各不相同（取决于消息类型）
说明：载荷是消息的最后一部分，位于标头之后。载荷取决于消息类型。以下各部分定义了每种消息类型的载荷格式。
测距功能请求消息载荷
大小（不包括标头大小）：2 字节
说明：由发起方设备发送，用于发起消息交换。
当通信渠道基于广告时，此消息是可选的，在这种情况下，响应方设备需要先广播 Ranging
Capability 消息。发起方设备（初始扫描器）读取广播并直接回复 Ranging Capability 消息，从而避免了发送此消息。
下表总结了 Ranging Capability Request 消息载荷：
| 八位字节 | 数据类型 | 说明 | 值 |
|---|---|---|---|
| 0 | uint8*2 | 请求的测距技术位字段 |
|
测距功能响应消息载荷
大小（不包括标头大小）：可变（公共部分 2 字节加上每种包含的测距技术字节的大小）
说明：由回答者发送，作为对 Ranging Capability
Request 消息的回答。此消息载荷由通用部分和测距技术专用部分（BLE CS、Wi-Fi NAN RTT、BLE RSSI）组成，如下表所示。只有在响应方设备支持相应测距技术且 Ranging Capability Request 消息中请求了该测距技术时，才必须添加每个测距技术特定的部分。对于广告通信渠道，必须包含所有受支持的测距技术。
下表总结了常见的 Ranging Capability Response 消息载荷：
| 八位字节 | 数据类型 | 说明 | 值 |
|---|---|---|---|
| 0 | uint8*2 | 支持的测距技术位字段。表示后续载荷中测距技术的功能集。 |
|
| 2 | 字节数组 | 测距技术功能字节。 | 按技术定义的重复结构块。 |
下表总结了 UWB Ranging Capability Response 消息载荷：
| 八位字节 | 数据类型 | 说明 | 值 |
|---|---|---|---|
| 0 | uint8 | 测距技术 ID | 0x0 - UWB |
| 1 | uint8 | 大小 | UWB 功能字节的大小（包括技术 ID 和大小 字段），以字节为单位。 |
| 2 | uint8*2 | UWB 地址 | 2 字节设备 UWB 地址。 |
| 4 | uint8*4 | 支持的渠道位字段 | 支持的渠道的位字段。位设置为 0 表示不支持，设置为 1 表示支持。位 0 对应于通道 0。LSB == channel 0MSB == channel 31 |
| 8 | uint8*4 | 支持的前导序列索引位字段 | 支持的前导序列索引的位字段。位设置为 0 表示不支持，设置为 1 表示支持。位 0 对应于前导序列索引 1。LSB == preamble index 1MSB == preamble index 32 |
| 12 | uint8*4 | 支持的配置 ID 位字段 | 支持的 UWB 配置 ID 的位字段。位设置为 0 表示不支持，设置为 1 表示支持。LSB == config Id 0> MSB == config Id 31 |
| 16 | uint8*2 | 支持的最小测距间隔 | 表示支持的最快测距间隔（以毫秒为单位）。允许的值（以毫秒为单位）：
|
| 18 | uint8 | 支持的最短广告时段时长 | 表示支持的最小时隙时长（以毫秒为单位）。例如，如果设备返回 1 毫秒，则假定它也支持 2 毫秒以上的时段。允许的值（以毫秒为单位）：
|
| 19 | 支持的 UWB 设备角色位字段 | 支持的 UWB 角色的位字段。例如，如果两者都支持，则最终字段值为 0x3。
|
下表总结了 BLE CS Ranging Capability Response 消息载荷：
| 八位字节 | 数据类型 | 说明 | 值 |
|---|---|---|---|
| 0 | uint8 | 测距技术 ID | 0x1 - BLE CS |
| 1 | uint8 | 大小 | BLE CS 功能字节的大小（包括技术 ID 和大小 字段），以字节为单位。 |
| 2 | uint8 | 支持的安全类型位字段 | BLE CS 支持的安全类型的位字段。
|
| 3 | uint8*6 | 设备地址 | 用于 BLE CS 的设备的地址；采用大端序。 |
下表总结了 Wi-Fi NAN RTT Ranging Capability Response 消息载荷：
| 八位字节 | 数据类型 | 说明 | 值 |
|---|---|---|---|
| 0 | uint8 | 测距技术 ID | 0x2 - Wi-Fi NAN RTT |
| 1 | uint8 | 大小 | BLE RSSI 功能字节的大小（包括技术 ID 和大小 字段），以字节为单位。 |
| 2 | uint8 | 支持的功能位字段 | 支持的功能的位字段。
|
| 3 | uint8 | 支持周期性测距 |
|
| 4 | uint8 | 支持的带宽 | 此信息有助于推导使用 Wi-Fi NAN 可实现的测距精度，并可帮助应用确定是使用 UWB、BLE CS、BLE RSSI 还是 Wi-Fi NAN 进行测距。
|
| 5 | uint8 | 支持的接收链数量 | 此信息有助于推导使用 Wi-Fi NAN 可实现的测距精度，并可帮助应用确定是使用 UWB、BLE CS、BLE RSSI 还是 Wi-Fi NAN 进行测距。
|
下表总结了 BLE RSSI Ranging Capability Response 消息载荷：
| 八位字节 | 数据类型 | 说明 | 值 |
|---|---|---|---|
| 0 | uint8 | 测距技术 ID | 0x3 - BLE RSSI |
| 1 | uint8 | 大小 | BLE RSSI 功能字节的大小（包括技术 ID 和大小 字段），以字节为单位 |
| 2 | uint8*6 | 设备地址 | 用于 BLE RSSI 的设备的地址；采用大端字节顺序 |
测距配置消息载荷
大小（不包括标头大小）：各不相同（公共部分为 4 字节，加上每个包含的测距技术字节的大小）。
说明：此消息由发起方发送，其中包含每种测距技术可以开始测距的配置。响应方设备必须在收到此消息后尝试使用每种指示的测距技术开始测距。此消息载荷由通用部分和测距技术专用部分（UWB、BLE CS、Wi-Fi NAN RTT、BLE RSSI）组成，如下表所示。
下表总结了常见的 Ranging Configuration 消息载荷：
| 八位字节 | 数据类型 | 说明 | 值 |
|---|---|---|---|
| 0 | uint8*2 | 测距技术配置集位字段 | 此消息包含配置数据的测距技术的位字段，必须为这些技术设置配置参数。
|
| 2 | uint8*2 | 位字段 | RFU。必须设置为与测距技术配置集位字段相同的值。 |
| 4 | 字节数组 | 测距技术配置字节 | 按技术定义的重复结构块 |
下表总结了 UWB Ranging Configuration 消息载荷：
| 八位字节 | 数据类型 | 说明 | 值 |
|---|---|---|---|
| 0 | uint8 | 测距技术 ID | 0x0 - UWB |
| 1 | uint8 | 大小 | UWB 配置的大小（包括技术 ID 和大小 字段），以字节为单位 |
| 2 | uint8*2 | UWB 地址 | 2 字节设备 UWB 地址 |
| 4 | uint8*4 | 会话 ID | 生成的会话 ID。会话 ID 是手机与外围设备之间测距会话的唯一标识符。 |
| 8 | uint8 | 所选配置 ID | 所选配置 ID 编号（整数）。配置 ID 用于指定 UWB 测距会话必须使用的时序参数和安全类型。 |
| 9 | uint8 | 所选频道 | UWB 测距会话的所选渠道 |
| 10 | uint8 | 所选序言索引 | UWB 测距会话的所选前导序列索引 |
| 11 | uint8*2 | 所选测距间隔 | 所选的测距时间间隔速率（以毫秒为单位）。允许的值（以毫秒为单位）：
|
| 13 | uint8 | 所选空档时长 | 所选时段的持续时间（以毫秒为单位）。允许的值（以毫秒为单位）：
|
| 14 | uint8 | 会话密钥长度 | 会话密钥的长度（以字节为单位） |
| 15 | 字节数组 | 会话密钥 | 会话密钥。如果使用 S-STS，则前两个字节是供应商 ID，接下来的六个字节是静态 STS IV。如果使用 P-STS，则为 16 字节或 32 字节的会话密钥。所用安全性的类型由配置 ID 确定。 |
| 不定 | uint8*2 | 国家/地区代码 | ISO 3166-1 alpha-2 国家/地区代码，以两个 ASCII 字符表示 |
| 不定 | uint8 | 所选设备角色 |
|
| 不定 | uint8 | 所选设备模式 |
|
下表总结了 BLE CS Ranging Configuration 消息载荷：
| 八位字节 | 数据类型 | 说明 | 值 |
|---|---|---|---|
| 0 | uint8 | 测距技术 ID | 0x1 - BLE CS |
| 1 | uint8 | 大小 | BLE CS 配置的大小（包括技术 ID 和大小 字段），以字节为单位 |
| 2 | uint8 | 所选安全类型 | 所选安全类型。允许的值：
|
| 3 | uint8*6 | 设备地址 | 用于 BLE CS 的设备的地址；采用大端序 |
下表总结了 Wi-Fi NAN RTT Ranging Configuration 消息载荷：
| 八位字节 | 数据类型 | 说明 | 值 |
|---|---|---|---|
| 0 | uint8 | 测距技术 ID | 0x2 - Wi-Fi NAN RTT |
| 1 | uint8 | 大小 | Wi-Fi NAN RTT 配置（包括技术 ID 和大小 字段）的大小（以字节为单位） |
| 2 | uint8 | 服务名称长度 | “服务名称”字段的长度（以字节为单位）。请参阅 Wi-Fi 感知规范 v4.0 第 1.3.3 节表 1。定义。 |
| 3 | 字节数组 | 服务名称 | 服务名称。请参阅 Wi-Fi 感知规范 v4.0 第 1.3.3 节表 1。定义。 |
| 不定 | uint8 | 设备角色 |
|
| 不定 | uint8 | 使用周期性测距 |
|
下表总结了 BLE RSSI Ranging Configuration 消息载荷：
| 八位字节 | 数据类型 | 说明 | 值 |
|---|---|---|---|
| 0 | uint8 | 测距技术 ID | 0x3 - BLE RSSI |
| 1 | uint8 | 大小 | BLE RSSI 配置的大小（包括技术 ID 和大小 字段），以字节为单位 |
| 2 | uint8*6 | 设备地址 | 用于 BLE RSSI 的设备的地址；采用大端字节顺序 |
测距配置响应消息载荷
大小（不包括标头大小）：2 字节
说明：此消息由响应者发送，作为对 Ranging Configuration 消息的响应。此消息为可选消息，仅当所用通信渠道要求对每个请求做出明确响应时才需要。
下表总结了 Ranging Configuration Response 消息载荷：
| 八位字节 | 数据类型 | 说明 | 值 |
|---|---|---|---|
| 0 | uint8*2 | 成功设置了测距技术配置位字段 | 已成功设置的测距技术的位字段。如果相应技术已请求并成功设置，则该位域会将相应测距技术位设置为 1，否则设置为 0。
|
停止测距消息载荷
大小（不包括标头大小）：2 字节
说明：当需要停止使用指定的测距技术进行测距时，发起方设备会发送此消息。
下表汇总了 Stop Ranging 消息载荷：
| 八位字节 | 数据类型 | 说明 | 值 |
|---|---|---|---|
| 0 | uint8*2 | 用于停止位字段的测距技术 | 必须停止测距的测距技术的位字段。如果相应位设置为 1，则表示测距技术必须停止测距；如果设置为 0，则表示测距技术要么一开始就未测距，要么必须继续测距（如果已在测距）。对于某些测距技术（例如 CS），这是一种空操作，因为测距仅在发起方一侧启动和停止。
|
停止测距响应消息载荷
大小（不包括标头大小）：2 字节
说明：此消息由响应者发送，作为对 Stop Ranging 消息的响应。此消息是可选的，仅当所用通信渠道要求对每个请求进行明确响应时才需要。
下表总结了 Stop Ranging Response 消息载荷：
| 八位字节 | 数据类型 | 说明 | 值 |
|---|---|---|---|
| 0 | uint8*2 | 测距技术已成功停止位字段 | 成功停止测距的测距技术位字段。如果请求停止相应技术且该技术已成功停止，则该位域会将测距技术位设置为 1，否则设置为 0。
|
版本控制
规范的版本包含在每条消息的标头中。 本部分定义了当其中一个设备（发起方或响应方）的版本比另一个设备旧时，如何进行通信。
情形 1：基于连接的通信渠道
本部分介绍使用基于连接的通信渠道的情况，其中 Ranging Capability Request 是发起方设备发送的第一条消息。
情形 1.a：发起方支持较新版本的规范，响应方支持较旧版本的规范。
发起方设备会发送包含新版本的 Ranging Capability Request 消息。响应方设备仅支持旧版本，因此会使用旧版本进行响应，然后响应方的旧版本会用于其余的消息交换。这意味着 Ranging Capability Request 消息必须向后兼容。
情形 1.b：发起方支持旧版规范，响应方支持新版规范。
响应方设备发现发起方设备无法使用较新版本，因此仅使用发起方设备最初请求的旧版本发送消息。
情形 2：基于广告的通信渠道
本部分介绍了使用基于广告的通信渠道的场景，其中响应方设备直接广播 Ranging Capability Request，而无需初始请求。
情形 2.a：发起方支持较新版本的规范，响应方支持较旧版本的规范。
在 Ranging Capability Response 广告中设置的旧版本将用于其余的通信。
情形 2.b：发起方支持旧版规范，响应方支持新版规范。
新版 Ranging Capability Response 广告必须向后兼容，以便发起方设备即使使用新版本也能读取消息。然后，发起方设备会使用其支持的旧版本发送 Ranging
Configuration 消息。这是用于其余通信的版本。
为确保 Ranging Capability Response 向后兼容，添加到此规范的下一个版本中的任何新字段（在 Ranging
Capability Response 消息载荷中）都必须附加到载荷的末尾，并且不得修改任何现有字段。在解析配置时，如果指示的大小大于预期，则只能理解旧版规范的任何设备都必须忽略额外的字段。
碎片化
此规范与通信渠道无关，因此未定义在单个消息过大而无法放入所用通信渠道的传输数据包中的情况下，如何对消息载荷进行分段。测距模块希望接收完整形式的每条消息。分段的责任在于 OOB 通信渠道的实现者。
测距技术细节
本部分包含与测距技术相关的具体细节。
超宽带 (UWB) 规格
本部分介绍了超宽带的具体细节。
配置 ID
为 UWB 交换的 OOB 配置数据不包含 UWB 启动 UWB 测距会话所需的全套可用可配置参数。这是因为所选配置 ID 会隐式选择某些形参。
每个配置 ID 都是一组预定义的 UWB 配置参数，记录在 UwbRangingParams 中。响应方设备会在功能响应消息中发送其支持的所有配置 ID 的列表，而发起方会选择其中一个受支持的配置 ID 来使用。这样，在 OOB 期间交换的配置参数集会更小。它还限制了可用于 UWB 测距的参数组合数量，从而可以仅测试允许的参数组合。
在每次 UWB 会话结束后请求功能
在停止现有 UWB 会话后和启动新 UWB 会话之前，发起方设备必须请求响应方设备的功能并再次设置配置参数，因为 UWB 地址可能会在当前测距会话结束后立即轮换。
BLE 信道探测 (CS) 规范
本部分介绍了信道探测的具体细节。
设备之间所需的配对
使用信道探测进行测距需要发起方设备和响应方设备之间存在已建立的绑定。此规范未提供在设备之间创建绑定的方法。Ranging API 的用户必须在设备之间建立此绑定。
客服人员需要采取行动
在 UWB 中，两个设备都需要显式调用 UWB 测距启动和停止测距 API。相比之下，对于 CS，只需要发起方设备通过调用蓝牙 (BT) 堆栈来启动 CS 测距。响应方上的其余初始化通过 BT 带内进行。这意味着，在收到 Ranging Configuration 消息或 CS 的 Stop Ranging 消息后，如果 BT 已启用，响应方无需执行任何操作。响应方设备可以使用这些消息作为触发器来更新界面，或者例如闪烁设备 LED。