Wi-Fi 定位：使用 RTT 测距

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

如果您测量到三个或更多接入点的距离，可以使用多边测量算法来估算最符合这些测量结果的设备位置。结果通常在 1-2 米内准确。

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

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

Wi-Fi 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 并确定其位置，例如当用户进入新建筑时。

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）或更高版本。IEEE 802.11az 非触发式测距在运行 Android 15（API 级别 35）及更高版本的设备上启用。
• 发出测距请求的设备必须启用定位服务并开启 Wi-Fi 扫描（在“设置”>“位置信息”下）。
• 如果发出测距请求的应用以 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

context.packageManager.hasSystemFeature(PackageManager.FEATURE_WIFI_RTT)

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

3. 检查 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，该广播在可用性更改时发送。当您的应用收到此广播意图时，应用应检查当前的可用性状态并相应地调整其行为。

例如

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)

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);

有关更多信息，请参阅广播。

创建测距请求

测距请求 (RangingRequest) 通过指定请求范围的 AP 或 Wi-Fi Aware 对等设备列表来创建。可以在单个测距请求中指定多个接入点或 Wi-Fi Aware 对等设备；所有设备的距离都将测量并返回。

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

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

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 测距的设备根据 AP 的功能执行 802.11mc 或 802.11az 测距，当 AP 同时支持两者时，默认为 802.11az。不支持 IEEE 802.11az 的设备使用 IEEE 802.11mc 协议执行所有测距。

类似地，测距请求可以使用其 MAC 地址或其 PeerHandle 添加 Wi-Fi Aware 对等设备，分别使用 addWifiAwarePeer(MacAddress peer) 和 addWifiAwarePeer(PeerHandle peer) 方法。有关发现 Wi-Fi Aware 对等设备的更多信息，请参阅 Wi-Fi Aware 文档。

请求测距

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

例如

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) { … }
})

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 中描述的状态码。发生此类失败的原因可能是服务当时无法执行测距操作（例如，因为 Wi-Fi 已禁用，或者因为应用请求了过多的测距操作并受到限制，或者因为权限问题）。
• 测距操作完成后，会触发 onRangingResults 回调，其中包含与请求列表匹配的结果列表——每个请求对应一个结果。结果的顺序不一定与请求的顺序匹配。请注意，测距操作可能已完成，但每个结果可能仍指示该特定测量失败。

解释测距结果

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

1. 识别请求

根据创建 RangingRequest 时提供的信息识别请求：最常见的是 ScanResult 中提供的 MAC 地址，用于标识接入点。MAC 地址可以使用 getMacAddress() 方法从测距结果中获取。

测距结果列表的顺序可能与测距请求中指定的对等设备（接入点）的顺序不同，因此您应该使用 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()

支持 WiFi-RTT 的 Android 设备

下表列出了一些支持 WiFi-RTT 的手机、接入点以及零售、仓储和配送中心设备。这些列表远非完整。我们鼓励您联系我们，在此处列出您的支持 RTT 的产品。

接入点

手机

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