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 CS、BLE RSSI）组成，如下表所示。只有在响应器设备支持相应测距技术且 Ranging Capability Request 消息中请求了该测距技术时，才必须添加每个特定于测距技术的部分。对于广告通信渠道，必须包含所有受支持的测距技术。
下表总结了常见的 Ranging Capability Response 消息载荷：
| 八位字节 | 数据类型 | 说明 | 值 |
|---|---|---|---|
| 0 | uint8*2 | 支持的测距技术位字段。指示载荷其余部分中随附的一组测距技术功能。 |
|
| 2 | 字节数组 | 测距技术能力字节。 | 按技术定义的重复结构体块。 |
下表总结了 UWB Ranging Capability Response 消息载荷：
| 八位字节 | 数据类型 | 说明 | 值 |
|---|---|---|---|
| 0 | uint8 | 测距技术 ID | 0x0 - UWB |
| 1 | uint8 | 大小 | UWB 功能字节（包括 Technology ID 和 Size 字段）的大小（以字节为单位）。 |
| 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 Request 消息载荷：
| 八位字节 | 数据类型 | 说明 | 值 |
|---|---|---|---|
| 0 | uint8 | 测距技术 ID | 0x1 - BLE CS |
| 1 | uint8 | 大小 | BLE CS 功能字节（包括 Technology ID 和 Size 字段）的大小（以字节为单位）。 |
| 2 | uint8 | 支持的安全类型位字段 | BLE CS 支持的安全类型的位字段。
|
| 3 | uint8*6 | 设备地址 | 用于 BLE CS 的设备的地址；采用大端序。 |
Wi-Fi NAN RTT CS Ranging Capability Request 消息载荷如下表所示：
| 八位字节 | 数据类型 | 说明 | 值 |
|---|---|---|---|
| 0 | uint8 | 测距技术 ID | 0x2 - Wi-Fi NAN RTT |
| 1 | uint8 | 大小 | BLE RSSI 功能字节（包括 Technology ID 和 Size 字段）的大小（以字节为单位）。 |
| 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 Request 消息载荷：
| 八位字节 | 数据类型 | 说明 | 值 |
|---|---|---|---|
| 0 | uint8 | 测距技术 ID | 0x3 - BLE CS |
| 1 | uint8 | 大小 | BLE RSSI 功能字节（包括 Technology ID 和 Size 字段）的大小（以字节为单位） |
| 2 | uint8*6 | 设备地址 | 用于 BLE RSSI 的设备的地址；采用大端序 |
测距配置消息载荷
大小（不包括头文件大小）：不定（公共部分 4 字节，加上每个包含的测距技术字节的大小）。
说明：此消息由发起方发送，其中包含每个测距技术可以开始测距的配置。响应器设备在收到此消息后，必须尝试使用每个指示的测距技术启动测距。此消息载荷由通用部分和测距技术专用部分（UWB、BLE CS、Wi-Fi NAN RTT、BLE RSSI）组成，如下表所示。
下表总结了常见的 Ranging Configuration 消息载荷：
| 八位字节 | 数据类型 | 说明 | 值 |
|---|---|---|---|
| 0 | uint8*2 | 测距技术配置集位字段 | 此消息包含的测距技术的位字段，并且必须为这些技术设置配置参数。
|
| 2 | uint8*2 | 位字段 | RFU。必须设置为与 Ranging technologies configuration set bitfield 字段相同的值。 |
| 4 | 字节数组 | 测距技术配置字节 | 针对每项技术定义的重复结构体块 |
UWB Ranging Configuration 消息载荷汇总如下表所示：
| 八位字节 | 数据类型 | 说明 | 值 |
|---|---|---|---|
| 0 | uint8 | 测距技术 ID | 0x0 - UWB |
| 1 | uint8 | 大小 | UWB 配置的大小（包括 Technology ID 和 Size 字段），以字节为单位 |
| 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 配置（包括 Technology ID 和 Size 字段）的大小（以字节为单位） |
| 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 配置的大小（包括 Technology ID 和 Size 字段），以字节为单位 |
| 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 配置的大小（包括 Technology ID 和 Size 字段），以字节为单位 |
| 2 | uint8*6 | 设备地址 | 用于 BLE RSSI 的设备的地址；采用大端序 |
测距配置响应消息载荷
大小（不包括标头大小）：2 字节
说明：响应方会发送此消息作为对 Ranging Configuration 消息的响应。此消息是可选的，只有在所用的通信渠道要求对每个请求做出明确响应时，才需要此消息。
下表汇总了 Ranging Configuration Response 消息载荷：
| 八位字节 | 数据类型 | 说明 | 值 |
|---|---|---|---|
| 0 | uint8*2 | 已成功设置测距技术配置位字段 | 成功设置的测距技术的位字段。如果成功请求并设置了测距技术，该位字段会将测距技术位设置为 1，否则将其设置为 0。
|
Stop Ranging 消息载荷
大小（不包括标头大小）：2 字节
说明：发起器设备在需要停止使用指定测距技术进行测距时发送此消息。
下表汇总了 Stop Ranging 消息载荷：
| 八位字节 | 数据类型 | 说明 | 值 |
|---|---|---|---|
| 0 | uint8*2 | 用于停止位字段的测距技术 | 必须停止测距的测距技术的位字段。位设置为 1 表示测距技术必须停止测距，而 0 表示测距技术最初未进行测距，或者如果已进行测距，则必须继续测距。对于某些测距技术（例如 CS），这是一个无操作，因为测距仅在发起端启动和停止。
|
停止测距响应消息载荷
大小（不包括标头大小）：2 字节
说明：响应方会发送此消息作为对 Stop Ranging 消息的响应。此消息是可选的，只有在所用的通信渠道要求对每个请求做出明确响应时，才需要此消息。
Stop Ranging Response 消息载荷汇总如下表所示：
| 八位字节 | 数据类型 | 说明 | 值 |
|---|---|---|---|
| 0 | uint8*2 | 已成功停止 ranging 技术位字段 | 成功停止测距的测距技术的位字段。如果系统请求停止某项测距技术且该技术已成功停止，该位字段会将测距技术位设置为 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 的用户必须在设备之间建立此关联。
回复方针对 CS 支持请求需要采取的行动
在 UWB 中，两台设备都需要显式调用 UWB 开始测距和停止测距 API。相比之下，对于 CS，只有发起端设备需要通过调用蓝牙 (BT) 堆栈来启动 CS 测距。响应方端的其余初始化操作会通过 BT 在带内进行。这意味着，如果已启用 BT，则在收到 CS 的 Ranging Configuration 消息或 Stop Ranging 消息后，响应方端无需执行任何操作。响应器设备可以使用这些消息作为触发器来更新界面，或者执行其他操作，例如闪烁设备 LED。