超宽带 (UWB) 通信

超宽带通信是一种无线电技术，专注于在设备之间实现精确测距（测量位置的精确度为 10 厘米）。这种无线技术可以使用低能量密度进行短距离测量，并在很大一部分射频频谱内执行高带宽信号传输。UWB 的带宽大于 500 MHz（或超过 20% 的部分带宽）。

控制器/发起者与受控方/响应方

UWB 通信发生在两部设备之间，其中一部设备是控制器，另一部设备是受控设备。控制器确定这两部设备将共享的复杂通道 (UwbComplexChannel)，并充当发起方，而受控设备充当响应方。

控制器可以处理多个控制器，但控制器只能订阅单个控制器。支持控制器/发起方和受控方/响应方配置。

测距参数

控制器和受控设备需要相互识别，并传达测距参数以开始测距。此交换由应用使用其选择的安全外带 (OOB) 机制（例如蓝牙低功耗 [BLE]）来实现。

范围参数包括本地地址、复杂渠道和会话密钥等。请注意，这些参数可能会在测距会话结束后轮替或以其他方式更改，并且需要重新通信才能重新开始测距。

后台测距

如果设备支持，在后台运行的应用可以启动 UWB 测距会话。如需查看设备功能，请参阅 RangingCapabilities。

应用在后台运行时不会收到测距报告；当应用移至前台时，会收到测距报告。

STS 配置

应用或服务使用经过扰码的时间戳序列 (STS) 为每个会话预配会话密钥。预配的 STS 比静态 STS 配置更安全。搭载 Android 14 或更高版本的所有支持 UWB 的设备都支持预配的 STS。

威胁类别 静态 STS 预配的 STS
Air：被动观察器 已缓解 已缓解
Air：信号放大 已缓解 已缓解
空中：重放/中继攻击 易受感染 已缓解

对于预配的 STS：

  1. 在支持预配 STS 的 RangingParameters 中使用 uwbConfigType。

  2. 在 sessionKeyInfo 字段中提供 16 字节的密钥。

对于静态 STS：

  1. 使用支持静态 STS 的 RangingParameters 中的 uwbConfigType。

  2. 在 sessionKeyInfo 字段中提供 8 字节的键。

步骤

如需使用 UWB API，请按以下步骤操作：

  1. 确保 Android 设备搭载 Android 12 或更高版本，并且支持使用 PackageManager#hasSystemFeature("android.hardware.uwb") 的 UWB。
  2. 如果要与 IoT 设备进行测距，请确保这些设备符合 FiRa MAC 1.3 标准。
  3. 使用您选择的 OOB 机制（例如 BluetoothLeScanner）发现支持 UWB 的对等设备。
  4. 使用您选择的安全 OOB 机制（例如 BluetoothGatt）交换测距参数。
  5. 如果用户想停止会话，请取消会话的范围。

使用限制

使用 UWB API 时，需要遵循以下限制：

  1. 发起新的 UWB 测距会话的应用必须是前台应用或服务，除非支持后台测距（如前所述）。
  2. 当应用移至后台（会话仍在进行时）时，应用可能无法再接收测距报告。不过，UWB 会话将继续在较低层级维护。当应用返回前台时，测距报告将会恢复。

代码示例

示例应用

如需查看有关如何使用 UWB Jetpack 库的端到端示例，请参阅 GitHub 上的示例应用。此示例应用涵盖了在 Android 设备上验证 UWB 兼容性、使用 OOB 机制启用发现流程，以及在两部支持 UWB 的设备之间设置 UWB 测距。该示例还涵盖了设备控制和媒体共享用例。

UWB 测距

以下代码示例会为受控设备启动和终止 UWB 测距：

// The coroutineScope responsible for handling uwb ranging.
// This will be initialized when startRanging is called.
var job: Job?

// A code snippet that initiates uwb ranging for a Controlee.
suspend fun startRanging() {

    // Get the ranging parameter of a partnering Controller using an OOB mechanism of choice.
    val partnerAddress : Pair<UwbAddress, UwbComplexChannel> = listenForPartnersAddress()

    // Create the ranging parameters.
    val partnerParameters = RangingParameters(
        uwbConfigType = UwbRangingParameters.UWB_CONFIG_ID_1,
        // SessionKeyInfo is used to encrypt the ranging session.
        sessionKeyInfo = null,
        complexChannel = partnerAddress.second,
        peerDevices = listOf(UwbDevice.createForAddress(partnerAddress.first)),
        updateRateType = UwbRangingParameters.RANGING_UPDATE_RATE_AUTOMATIC
    )

    // Initiate a session that will be valid for a single ranging session.
    val clientSession = uwbManager.clientSessionScope()

    // Share the localAddress of the current session to the partner device.
    broadcastMyParameters(clientSession.localAddress)

    val sessionFlow = clientSession.prepareSession(partnerParameters)

    // Start a coroutine scope that initiates ranging.
    CoroutineScope(Dispatchers.Main.immediate).launch {
        sessionFlow.collect {
            when(it) {
                is RangingResultPosition -> doSomethingWithPosition(it.position)
                is RangingResultPeerDisconnected -> peerDisconnected(it)
            }
        }
    }
}

// A code snippet that cancels uwb ranging.
fun cancelRanging() {

    // Canceling the CoroutineScope will stop the ranging.
    job?.let {
        it.cancel()
    }
}

RxJava3 支持

现在，Rxjava3 支持可帮助实现与 Java 客户端的互操作性。此库提供了一种方法，可将测距结果作为 Observable 或 Flowable 流获取，并将 UwbClientSessionScope 检索为 Single 对象。

private final UwbManager uwbManager;

// Retrieve uwbManager.clientSessionScope as a Single object
Single<UwbClientSessionScope> clientSessionScopeSingle =
                UwbManagerRx.clientSessionScopeSingle(uwbManager);
UwbClientSessionScope uwbClientSessionScope = clientSessionScopeSingle.blockingGet();

// Retrieve uwbClientSessionScope.prepareSession Flow as an Observable object
Observable<RangingResult> rangingResultObservable =
                UwbClientSessionScopeRx.rangingResultsObservable(clientSessionScope,
                        rangingParameters);

// Consume ranging results from Observable
rangingResultObservable.subscribe(
   rangingResult -> doSomethingWithRangingResult(result), // onNext
   (error) -> doSomethingWithError(error), // onError
   () -> doSomethingOnResultEventsCompleted(), //onCompleted
);
// Unsubscribe
rangingResultObservable.unsubscribe();
   

// Retrieve uwbClientSessionScope.prepareSession Flow as a Flowable object
Flowable<RangingResult> rangingResultFlowable =
                UwbClientSessionScopeRx.rangingResultsFlowable(clientSessionScope,
                        rangingParameters);

// Consume ranging results from Flowable using Disposable
Disposable disposable = rangingResultFlowable
   .delay(1, TimeUnit.SECONDS)
   .subscribeWith(new DisposableSubscriber<RangingResult> () {
      @Override public void onStart() {
          request(1);
      }
      
      @Override public void onNext(RangingResult rangingResult) {
             doSomethingWithRangingResult(rangingResult);
             request(1);
      }


      @Override public void onError(Throwable t) {
             t.printStackTrace();
      }


         @Override public void onComplete() {
            doSomethingOnEventsCompleted();
         }
   });

// Stop subscription
disposable.dispose();

生态系统支持

下面列出了受支持的合作伙伴设备和第三方 SDK。

支持 UWB 的移动设备

自 2025 年 1 月起，以下设备支持 Android UWB Jetpack 库：

供应商 设备型号
Google Pixel Pro（Pixel 6 Pro 及更新型号）、Pixel Fold、Pixel Tablet
摩托罗拉 Edge 50 Ultra
三星 Galaxy Note 20、Galaxy Plus 和 Ultra（S21 及更新型号）、Galaxy Z Fold（Fold2 及更新型号）

注意：除以下设备外，所有设备都支持后台 UWB 测距：

  • Pixel 6 Pro 和 Pixel 7 Pro。
  • 搭载 Android 13 或更低版本的三星手机。
  • 搭载 Android 14 或更低版本的三星中国大陆手机。

第三方 SDK

自 2023 年 4 月起，这些合作伙伴解决方案与当前的 Jetpack 库兼容。

已知问题：MAC 地址和静态 STS 供应商 ID 字段的字节顺序已反转

在 Android 13 及更低版本中，Android UWB 堆栈会错误地对以下字段的字节顺序进行反转：

  • 设备 MAC 地址
  • 目标 MAC 地址
  • 静态 STS 供应商 ID

出现字节顺序反转是因为 Android 堆栈将这些字段视为值，而不是数组。我们正在与 FiRa 合作更新 UCI 规范 (CR-1112)，以明确说明应将这些字段视为数组。

2320XXXX 版本中的 GMS Core 更新将修复此问题。 从那时起，为了与 Android 设备兼容，IoT 供应商需要修改您的实现，以避免反转这些字段的字节顺序。