通过 RTT 确定 WLAN 位置信息

您可以利用 Wi-Fi RTT（往返时间）API 提供的 Wi-Fi 位置功能测量距附近支持 RTT 的 Wi-Fi 接入点和 Wi-Fi 感知对等设备的距离。

如果您测量与三个或更多接入点的距离，可以使用多点定位算法来预估与这些测量值最相符的设备位置。结果通常可以精确到 1 至 2 米。

凭借这种精准度，您可以开发基于精确位置的服务，例如室内导航、无歧义语音控制（例如，“打开这盏灯”）以及基于位置的信息（例如，“此产品是否有特别优惠？”）。

请求发出设备无需连接到接入点即可通过 Wi-Fi RTT 测量距离。为维护隐私，只有发出请求的设备能够确定距接入点的距离，接入点没有此信息。前台应用执行 Wi-Fi RTT 操作不受限制，但后台应用执行此类操作时会受限。

WLAN RTT 和相关的精确时间测量 (FTM) 功能 符合 IEEE 802.11-2016 标准。Wi-Fi RTT 需要 FTM 提供的精确时间测量，因为前者通过测量数据包在设备之间往返所需的时间，并将该时间乘以光速来计算两个设备之间的距离。

Android 15（API 级别 35）引入了对 IEEE 802.11az 非基于触发器的支持 (NTB) 范围。

实现差异因 Android 版本而异

Wi-Fi RTT 在 Android 9（API 级别 28）中引入。使用此协议在搭载 Android 9 的设备中使用多点定位来确定设备的位置时，您需要有权访问应用中预先确定的接入点 (AP) 位置数据。存储和检索此类数据的方式由您决定。

在搭载 Android 10（API 级别 29）及更高版本的设备上，AP 位置数据可以表示为 ResponderLocation 对象，其中包括纬度、经度和海拔高度。对于支持位置配置信息/位置城市报告（LCI/LCR 数据）的 Wi-Fi RTT AP，协议会在测距过程中返回 ResponderLocation 对象。

此功能支持应用查询 AP，以直接询问 AP 的位置，而无需提前存储此类信息。因此，即使之前不知道 AP（例如用户进入新建筑物时），您的应用也可以找到 AP 并确定其位置。

IEEE 802.11az NTB 范围支持在搭载 Android 15 的设备上提供 （API 级别 35）及更高版本。也就是说，如果设备支持 IEEE 802.11az NTB 发起者模式（由 WifiRttManager.CHARACTERISTICS_KEY_BOOLEAN_NTB_INITIATOR 表示），您的应用可以通过单个测距请求找到支持 IEEE 802.11mc 和 IEEE 802.11az 的 AP。RangingResult API 已扩展，可提供有关可用于测量范围间隔的最小值和最大值的信息，从而让应用可以控制确切间隔。

要求

• 测距请求发出设备的硬件必须实现 802.11-2016 FTM 标准或 802.11az 标准（非基于触发器的测距）。
• 发出测距请求的设备必须搭载 Android 9（API 级别 28）或更高版本的操作系统。在搭载 Android 15（API 级别 35）及更高版本的设备上，启用了基于非触发器的 IEEE 802.11az 测距。
• 测距请求发出设备必须启用位置信息服务并打开 WLAN 扫描（位于设置 > 位置信息下）。
• 如果发出测距请求的应用以 Android 13（API 级别 33）或更高版本为目标平台，则必须具有 NEARBY_WIFI_DEVICES 权限。如果此类应用以较低版本的 Android 为目标平台，则必须 拥有 ACCESS_FINE_LOCATION 权限。
• 当应用可见或在前台服务中时，应用必须查询接入点的范围。应用无法在后台访问位置信息。
• 接入点必须实现 IEEE 802.11-2016 FTM 标准或 IEEE 802.11az 标准（基于非触发器的测距）。

设置

如需将应用设置为使用 Wi-Fi RTT，请执行以下步骤。

1.请求权限

在应用的清单中请求以下权限：

<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.CHANGE_WIFI_STATE" />
<!-- If your app targets Android 13 (API level 33)
     or higher, you must declare the NEARBY_WIFI_DEVICES permission. -->
<uses-permission android:name="android.permission.NEARBY_WIFI_DEVICES"
                 <!-- If your app derives location information from Wi-Fi APIs,
                      don't include the "usesPermissionFlags" attribute. -->
                 android:usesPermissionFlags="neverForLocation" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"
                 <!-- If any feature in your app relies on precise location
                      information, don't include the "maxSdkVersion"
                      attribute. -->
                 android:maxSdkVersion="32" />

NEARBY_WIFI_DEVICES 和 ACCESS_FINE_LOCATION 权限很危险 因此，每当用户想要授予某些权限时，您都需要在运行时 执行 RTT 扫描操作。如果尚未获得授权，应用需要向用户请求该权限。更多信息 有关运行时权限的信息，请参阅 请求应用权限。

注意：如果用户在测距操作期间撤消必要权限，系统将会取消操作并报告失败。

2. 检查设备是否支持 Wi-Fi RTT

如需检查设备是否支持 Wi-Fi RTT，请使用 PackageManager API：

Kotlin

context.packageManager.hasSystemFeature(PackageManager.FEATURE_WIFI_RTT)

Java

context.getPackageManager().hasSystemFeature(PackageManager.FEATURE_WIFI_RTT);

3. 检查 Wi-Fi RTT 是否可用

设备上可能存在 Wi-Fi RTT，但可能无法使用 Wi-Fi RTT，因为用户 已停用 Wi-Fi。根据其硬件和固件功能， 如果正在使用 SoftAP 或网络共享，则设备可能不支持 Wi-Fi RTT。检查 是否提供 Wi-Fi RTT、呼叫 isAvailable()。

Wi-Fi RTT 的可用性随时都可能发生变化。您的应用应注册 BroadcastReceiver 才能收到当可用性发生变化时发送的 ACTION_WIFI_RTT_STATE_CHANGED。应用收到该广播 intent 后，应检查可用性的当前状态并相应地调整其行为。

例如：

Kotlin

val filter = IntentFilter(WifiRttManager.ACTION_WIFI_RTT_STATE_CHANGED)
val myReceiver = object: BroadcastReceiver() {

    override fun onReceive(context: Context, intent: Intent) {
        if (wifiRttManager.isAvailable) {
            …
        } else {
            …
        }
    }
}
context.registerReceiver(myReceiver, filter)

Java

IntentFilter filter =
    new IntentFilter(WifiRttManager.ACTION_WIFI_RTT_STATE_CHANGED);
BroadcastReceiver myReceiver = new BroadcastReceiver() {
    @Override
    public void onReceive(Context context, Intent intent) {
        if (wifiRttManager.isAvailable()) {
            …
        } else {
            …
        }
    }
};
context.registerReceiver(myReceiver, filter);

注意：确保您在检查可用性之前注册广播接收器。否则，在一段时间内，应用可能会认为 Wi-Fi RTT 可用，但在可用性发生变化时不会收到通知。

如需了解详情，请参阅广播。

创建测距请求

测距请求 (RangingRequest) 已创建 以列表形式指定某一范围内的 AP 或 Wi-Fi 感知对等设备， 请求。您可以在单个测距请求中指定多个接入点或 Wi-Fi 感知对等设备，然后测量并返回与所有设备的距离。

例如，请求可以使用 addAccessPoint() 方法指定要测量距离的接入点：

Kotlin

val req: RangingRequest = RangingRequest.Builder().run {
    addAccessPoint(ap1ScanResult)
    addAccessPoint(ap2ScanResult)
    build()
}

Java

RangingRequest.Builder builder = new RangingRequest.Builder();
builder.addAccessPoint(ap1ScanResult);
builder.addAccessPoint(ap2ScanResult);

RangingRequest req = builder.build();

接入点由 ScanResult 对象，该对象可以是 通过调用 WifiManager.getScanResults()。 您可以使用 addAccessPoints(List<ScanResult>) 来批量添加多个接入点

ScanResult 对象可以同时包含支持 IEEE 802.11mc (is80211mcResponder()) 和 IEEE 802.11az 非触发器测距 (is80211azNtbResponder()) 的 AP。支持 IEEE 802.11az NTB 测距的设备会执行 802.11mc 或 802.11az 测距，具体取决于 AP 的功能，如果 AP 同时支持这两种测距，则默认使用 802.11az。不支持 IEEE 802.11az 的设备在执行全部操作时 使用 IEEE 802.11mc 协议测距。

同样，测距请求可以使用其 MAC 添加 WLAN 感知对等设备 地址或其 PeerHandle，使用 该 addWifiAwarePeer(MacAddress peer) 和addWifiAwarePeer(PeerHandle peer) 方法。如需详细了解如何发现 Wi-Fi 感知对等设备， 请参阅 Wi-Fi 感知文档。

请求测距

应用使用 WifiRttManager.startRanging() 方法发出测距请求，并提供以下内容：用于指定操作的 RangingRequest、用于指定回调上下文的 Executor，以及用于接收结果的 RangingResultCallback。

例如：

Kotlin

val mgr = context.getSystemService(Context.WIFI_RTT_RANGING_SERVICE) as WifiRttManager
val request: RangingRequest = myRequest
mgr.startRanging(request, executor, object : RangingResultCallback() {

    override fun onRangingResults(results: List<RangingResult>) { … }

    override fun onRangingFailure(code: Int) { … }
})

Java

WifiRttManager mgr =
      (WifiRttManager) Context.getSystemService(Context.WIFI_RTT_RANGING_SERVICE);

RangingRequest request ...;
mgr.startRanging(request, executor, new RangingResultCallback() {

  @Override
  public void onRangingFailure(int code) { … }

  @Override
  public void onRangingResults(List<RangingResult> results) { … }
});

测距操作以异步方式执行；测距结果在 RangingResultCallback 的某个回调中返回：

• 如果整个测距操作失败，将会触发 onRangingFailure 回调，并返回 RangingResultCallback 中描述的状态代码。如果该服务当时出于某些原因（例如 WLAN 已停用、应用请求的测距操作过多并受到限制，或者存在权限问题）无法执行测距操作，可能会发生此类失败。
• 测距操作完成后， onRangingResults 回调函数，系统会返回与 个请求 - 每个请求一个结果。结果的顺序不一定与请求的顺序一致。请注意，测距操作可能已经完成，但每个结果仍有可能提示该特定测量失败。

解读测距结果

返回的每个结果由 onRangingResults 回调由 RangingResult 指定 对象。请对每个请求执行以下操作。

1. 识别请求

根据在创建 RangingRequest： 通常是 ScanResult 中提供的 MAC 地址，用于标识访问权限 。您可以使用 getMacAddress() 方法从测距结果中获取 MAC 地址。

测距结果列表的顺序可能与测距请求中指定的对等设备（接入点）的顺序不同，因此您应使用 MAC 地址而非结果的顺序来识别对等设备。

2. 确定每个测量是否成功

如需确定测量是否成功，请使用 getStatus() 方法。除以下项之外的任何值： STATUS_SUCCESS 表示失败。失败意味着此结果的所有其他字段 （上述请求标识除外）无效，而相应的 get* 方法将失败，并显示 IllegalStateException 异常。

3. 获取每个成功测量的结果

对于每个成功的测量 (RangingResult)，您可以使用相应的 get 方法检索结果值：

• 距离（单位为毫米）和测量的标准偏差：

  getDistanceMm()

  getDistanceStdDevMm()

• 用于测量的数据包的 RSSI：

  getRssi()

• 测量所用时间（以毫秒为单位；表示自启动以来的时间）：

  getRangingTimestampMillis()

• 尝试的测量次数和成功的测量次数（以及距离测量的依据）：

  getNumAttemptedMeasurements()

  getNumSuccessfulMeasurements()

• 客户端设备必须在 11az NTB 之间等待的最短和最长时间 测量：

  getMinTimeBetweenNtbMeasurementsMicros() 和 getMaxTimeBetweenNtbMeasurementsMicros() 会返回最短时间和最长时间。如果下一次测距是 则 API 会返回 缓存的测距结果。如果在请求下一次测距之后， 超过时间上限后，API 会终止非触发器 并且与进行响应的 。您应该避免请求新的测距会话，因为这会增加 给测距造成的影响。为了充分利用 802.11az 基于非触发器的测距效率，触发下一个测距请求 前一个测量值中指定的最短和最长测量时间之间 “RangingResult”的测量结果。

• 响应器和发起器在 IEEE 802.11az NTB 结果的预文中使用的长训练字段 (LTF) 重复次数：

  get80211azResponderTxLtfRepetitionsCount()

  get80211azInitiatorTxLtfRepetitionsCount()

• 发起端台用于 IEEE 802.11az NTB 结果的发射和接收空间时间流 (STS) 的数量：

  get80211azNumberOfTxSpatialStreams()

  get80211azNumberOfRxSpatialStreams()

注意： LTF 重复以及时空传输和接收次数 (STS) 可用于估算 IEEE 802.11az NTB 结果的准确性。

支持 Wi-Fi RTT 的 Android 设备

下表列出了部分手机、接入点以及零售、仓储和配送中心设备 支持 WiFi-RTT。这些远远不够全面。建议您与我们联系，以便在此列出您提供的支持 RTT 的产品。

接入点

制造商和型号	支持日期
Nest Wifi Pro (Wi-Fi 6E)	支持
Compulab WILD AP	支持
Google Wi-Fi	支持
Google Nest Wi-Fi 路由器	支持
Google Nest Wi-Fi 盒子	支持
阿鲁巴 AP-635	支持
思科 9130	支持
思科 9136	支持
Cisco 9166	支持
Cisco 9164	支持
Aruba AP-505	支持
Aruba AP-515	支持
阿鲁巴 AP-575	支持
阿鲁巴 AP-518	支持
Aruba AP-505H	支持
阿鲁巴 AP-565	支持
Aruba AP-535	支持

手机

制造商和型号	Android 版本
Pixel 6	9.0 及更高版本
Pixel 6 Pro	9.0 及更高版本
Pixel 5	9.0 及更高版本
Pixel 5a	9.0 及更高版本
Pixel 5a 5G	9.0 及更高版本
小米 Mi 10 Pro	9.0 及更高版本
小米 Mi 10	9.0 及更高版本
小米 Redmi Mi 9T Pro	9.0 及更高版本
小米 Mi 9T	9.0 及更高版本
小米 Mi 9	9.0 及更高版本
小米 Mi Note 10	9.0 及更高版本
小米 Mi Note 10 Lite	9.0 及更高版本
小米 Redmi Note 9S	9.0 及更高版本
小米 Redmi Note 9 Pro	9.0 及更高版本
小米 Redmi Note 8T	9.0 及更高版本
小米红米 NOTE 8	9.0 及更高版本
小米 Redmi K30 Pro	9.0 及更高版本
小米 Redmi K20 Pro	9.0 及更高版本
小米红米 K20	9.0 及更高版本
Xiaomi Redmi Note 5 Pro	9.0 及更高版本
小米 Mi CC9 Pro	9.0 及更高版本
LG G8X ThinQ	9.0 及更高版本
LG V50S ThinQ	9.0 及更高版本
LG V60 ThinQ	9.0 及更高版本
LG V30	9.0 及更高版本
三星 Galaxy Note 10+ 5G	9.0 及更高版本
三星 Galaxy S20+ 5G	9.0 及更高版本
Samsung Galaxy S20+	9.0 及更高版本
Samsung Galaxy S20 5G	9.0 及更高版本
三星 Galaxy S20 Ultra 5G	9.0 及更高版本
Samsung Galaxy S20	9.0 及更高版本
三星 Galaxy Note 10+	9.0 及更高版本
三星 Galaxy Note 10 5G	9.0 及更高版本
三星 Galaxy Note 10	9.0 及更高版本
Samsung A9 Pro	9.0 及更高版本
Google Pixel 4 XL	9.0 及更高版本
Google Pixel 4	9.0 及更高版本
Google Pixel 4a	9.0 及更高版本
Google Pixel 3 XL	9.0 及更高版本
Google Pixel 3	9.0 及更高版本
Google Pixel 3a XL	9.0 及更高版本
Google Pixel 3a	9.0 及更高版本
Google Pixel 2 XL	9.0 及更高版本
Google Pixel 2	9.0 及更高版本
Google Pixel 1 XL	9.0 及更高版本
Google Pixel 1	9.0 及更高版本
《Poco X2》	9.0 及更高版本
夏普 Aquos R3 SH-04L	9.0 及更高版本

零售、仓储和配送中心设备

制造商和型号	Android 版本
Zebra PS20	10.0 及更高版本
斑马 TC52/TC52HC	10.0 及更高版本
Zebra TC57	10.0 及更高版本
斑马 TC72	10.0 及更高版本
Zebra TC77	10.0 及更高版本
斑马 MC93	10.0 及更高版本
斑马 TC8300	10.0 及更高版本
斑马 VC8300	10.0 及更高版本
Zebra EC30	10.0 及更高版本
斑马 ET51	10.0 及更高版本
Zebra ET56	10.0 及更高版本
斑马线 L10	10.0 及更高版本
斑马 CC600/CC6000	10.0 及更高版本
斑马 MC3300x	10.0 及更高版本
Zebra MC330x	10.0 及更高版本
Zebra TC52x	10.0 及更高版本
斑马 TC57x	10.0 及更高版本
Zebra EC50（LAN 和 HC）	10.0 及更高版本
Zebra EC55（WAN）	10.0 及更高版本
Zebra WT6300	10.0 及更高版本
Skorpio X5	10.0 及更高版本