Google 致力于为黑人社区推动种族平等。查看具体举措

通过 RTT 确定 Wi-Fi 位置信息

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

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

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

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

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

实现差异因 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 并确定其位置。

要求

  • 测距请求发出设备的硬件必须实现 802.11mc FTM 标准。
  • 测距请求发出设备必须搭载 Android 9(API 级别 28)或更高版本的操作系统。
  • 测距请求发出设备必须启用位置信息服务并打开 WLAN 扫描(位于设置 > 位置信息下)。
  • 测距请求发出设备必须拥有 ACCESS_FINE_LOCATION 权限。
  • 当应用可见或在前台服务中时,应用必须查询接入点的范围。应用无法在后台访问位置信息
  • 接入点必须实现 IEEE 802.11mc FTM 标准。

设置

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

1.请求权限

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

<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.CHANGE_WIFI_STATE" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

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,但由于用户已停用 WLAN,该功能目前或不可用。如果 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);

如需了解详情,请参阅广播

创建测距请求

通过指定请求范围的 AP 或 Wi-Fi 感知对等设备的列表,即可创建测距请求 (RangingRequest)。您可以在单个测距请求中指定多个接入点或 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) 批量添加多个接入点。

同样,测距请求可以通过以下两种途径添加 Wi-Fi 感知对等设备:使用 addWifiAwarePeer(MacAddress peer) 方法利用相应设备的 MAC 地址,或者使用 addWifiAwarePeer(PeerHandle peer) 方法利用相应设备的 PeerHandle。如需详细了解如何发现 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. 获取每个成功测量的结果

对于每个成功的测量,您可以使用相应的 get 方法检索结果值:

支持 Wi-Fi RTT 的 Android 设备

以下表格列出了支持 Wi-Fi RTT 的一些手机接入点。这些远远不够全面。建议您与我们联系,以便在此列出您提供的支持 RTT 的产品。

手机

制造商和型号 Android 版本
Xiaomi Redmi Note 5 Pro 9.0 及更高版本
LG V30 9.0 及更高版本
Samsung Note 10+ 9.0 及更高版本
Samsung A9 Pro 9.0 及更高版本
Google Pixel 4 9.0 及更高版本
Google Pixel 3 9.0 及更高版本
Google Pixel 2 9.0 及更高版本
Google Pixel 1 9.0 及更高版本

接入点

制造商和型号 支持日期
Compulab WILD AP 支持
Google Wi-Fi 支持
Google Nest Wi-Fi 路由器 2020 年 5 月
Google Nest Wi-Fi 盒子 2020 年 5 月