超宽带 (UWB) 通信

超宽带通信是一种专注于精确测距的无线电技术 (测量位置的精确度为 10 厘米)。 这种无线电技术可以使用低能量密度进行短距离测量 以及在很大一部分无线电频谱上执行高带宽信号传输 UWB 的带宽大于 500 MHz(或超过 20% 的小数) 带宽)。

控制方/发起者与被控制者/响应者

UWB 通信在两台设备之间进行,其中一个是控制器,而 另一个是受控对象。控制器会根据 (UwbComplexChannel) 两台设备将共享内容,并且是发起者,而受控对象是发起者 。

一个控制器可以处理多个被控制者,但一个被控制者只能订阅 一个控制器控制器/发起者和被控制者/响应者 配置。

范围参数

控制方和被控制者需要相互识别并传达 测距参数以开始测距。此交换留给应用 使用自己选择的安全带外 (OOB) 机制来实现,例如 蓝牙低功耗 (BLE)。

ranging 参数 包括本地地址、复杂渠道和会话密钥等。注意事项 在测距会话结束后,这些参数可能会旋转或以其他方式更改 结束并且需要重新通信以重新开始测距。

背景测距

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

应用在后台运行时不会收到测距报告;应用 并可在应用移至前台时收到测距报告。

STS 配置

应用或服务使用 Scrambled 时间戳序列 (STS)。预配的 STS 比静态 STS 更安全 配置。运行中、已启用 UWB 的所有设备均支持已配置的 STS Android 14 或更高版本。

威胁类别 静态 STS 提议的 STS
空中:被动观察器 已缓解 已缓解
空气:信号放大 已缓解 已缓解
空中:重放/接力攻击 易危 已缓解

对于预配的 STS:

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

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

对于静态 STS:

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

  2. sessionKeyInfo 字段中提供 8 字节密钥。

步骤

如需使用 UWB API,请按以下步骤操作:

  1. 确保 Android 设备搭载的是 Android 12 或更高版本,并且 支持 UWB PackageManager#hasSystemFeature("android.hardware.uwb")
  2. 如果测距范围是 IoT 设备,请确保这些设备是 FiRa MAC 1.3 合规性。
  3. 使用您选择的 OOB 机制发现支持 UWB 的对等设备, 例如 BluetoothLeScanner
  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 的互操作性 客户。此库提供了一种方法,能够以可观察对象或 流动数据流,以及将 UwbClientSessionScope 检索为单个对象。

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 的移动设备

自 2024 年 3 月起,这些设备将支持 Android UWB Jetpack 库:

供应商 设备型号
Google Pixel 6 Pro、7 Pro、8 Pro、Pold、平板电脑
三星 Galaxy Note 20、S21+、S22+、S23+、S24+ Z Fold 2、3、4、5

第三方 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 供应商需要修改 您的实现以避免颠倒这些字段的字节排序。