超宽带 (UWB) 通信

注意 ：UWB 目前仅支持 Jetpack。

超宽带通信是一种专注于精确测距的无线电技术 （测量位置的精确度为 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 库。

• Estimote UWB 开发套件。
• Mobile Knowledge MK UWB Kit Mobile Edition 2.0。

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

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

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

之所以发生字节顺序颠倒，是因为 Android 堆栈将这些字段 作为值，而不是数组。我们正在与 FiRa 合作，更新 UCI 规范 （CR-1112） 来明确说明应将这些字段视为数组。

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