androidx.core.uwb源码解析——数据类型

包：androidx.core.uwb 最新版本：1.0.0-alpha05，更新时间：2023年4月5日。

更新说明：

Version 1.0.0-alpha05
发布版本：androidx.core.uwb:uwb:1.0.0-alpha05和androidx.core.uwb:uwb-rxjava3:1.0.0-alpha05。

API更改：

重新命名RangingParameters#CONFIG_ID_1为CONFIG_UNICAST_DS_TWR。
添加新的配置ID，RangingParameters#CONFIG_MULTICAST_DS_TWR。

修复用户无法并行启动多个测距会话的bug，支持启动多个测距会话。

class RangingParameters

需要传递给底层的一组参数，开启测距。

参数	参数说明
uwbConfigType	UWB配置类型，预定义的一组参数，CONFIG_UNICAST_DS_TWR、CONFIG_MULTICAST_DS_TWR，当前一共支持7种模式。
sessionId	测距会话ID，如果该值为SESSION_ID_UNSET(0)，则它将根据控制器地址和复杂通道值的hash创建。对于测距两端的节点应该使用相同的会话ID。
subSessionId	测距子会话ID。当使用Provisioned STS，个别应答模式使用，如果使用其他配置，则应保持为SUB_SESSION_UNSET（0）。
sessionKeyInfo	用于测距的会话秘钥信息。如果配置文件使用静态STS，则此数组为8字节长，前两个字节为Vendor ID，后六个直接为STATIC_STS_IV。如果配置文件使用PROVISIONED_STS，则此直接数组为16或32直接长，表示会话秘钥。测距两端需要使用相同的会话秘钥。
subSessionKeyInfo	用于测距的子会话秘钥信息。当配置文件使用PROVISIONED_STS个别应答情况时，此字节数组为16或32字节长。如果使用其他STS，则此字段应保持为空。
complexChannel	可选，如果设备类型为ROLE_CONTROLEE，则应设置复杂通道。数据类型UwbComplexChannel
peerDevices	测距的配对设备。如果为单播，则长度为1.
updateRateType	测距数据的更新速率类型，当前支持三种。

关于UwbConfigType类型

当前在android的代码中支持以下7种配置，相应的相关测距周期、时隙周期、时隙数都已经被限定。相关定义，目前来看均参考FiRa相关标准实现。

CONFIG_UNICAST_DS_TWR=1，单播，DS-TWR模式，默认模式，测距周期240ms，时隙周期2400 RSTU（1200 RSTU = 1ms），每个测距轮时隙数为6；所有其他MAC参数均使用FiRa/UCI默认值。
CONFIG_MULLTICAST_DS_TWR=2，一对多，测距周期200ms，时隙周期为2400 RSTU，每个测距轮时隙数为20，其余MAC参数均为FiRa/UCI默认值
CONFIG_UNICAST_DS_TWR_NO_AOA=3，与CONFIG_ID_1相同，但未报告AOA。
CONFIG_PROVISIONED_UNICAST_DS_TWR=4，除启用P-STS安全模式外，与CONFIG_ID_1相同。
CONFIG_PROVISIONED_MULTICAST_DS_TWR = 5，除启用P-STS安全模式外，与CONFIG_ID_2相同。
CONFIG_PROVISIONED_UNICAST_DS_TWR_NO_AOA = 6，除启用P-STS安全模式外，与CONFIG_ID_3相同。
CONFIG_PROVISIONED_INDIVIDUAL_MULTICAST_DS_TWR = 7，除了启用P-STS单独controlee key mode外，与CONFIG_ID_2相同。

updateRateType

RANGING_UPDATE_RATE_AUTOMATIC = 1，屏幕激活，报告间隔为数百毫秒；屏幕关闭，报告周期为几秒。
RANGING_UPDATE_RATE_INFREQUENT = 2，报告间隔与自动模式下屏幕关闭情况的报告间隔相同（几秒）。在测距报告之间通过关闭射频来实现功耗的优化。该实现依赖于硬件和软件，且在不同版本之间会有所差异。（模式下默认报告间隔为4秒）
RANGING_UPDATE_RATE_FREQUENT = 3，AUTOMATIC模式下屏幕激活报告间隔相同（数百毫秒）。实际报告间隔与UwbConfigId相关。不同的配置可能使用不同的配置。

关于部分参数的定义，可以看到在com.google.android.gms.nearby.uwb中有类似参数的定义，在实际应用开发中，除标准的uwb库外，gms.nearby库也有非常紧密的联系：

/* 使用com.google.android.gms相关包 */
import com.google.android.gms.common.ConnectionResult
import com.google.android.gms.common.GoogleApiAvailability
import com.google.android.gms.common.api.ApiException
import com.google.android.gms.nearby.Nearby

val updateRate = when (parameters.updateRateType) {
            RangingParameters.RANGING_UPDATE_RATE_AUTOMATIC ->
                com.google.android.gms.nearby.uwb.RangingParameters.RangingUpdateRate.AUTOMATIC
            RangingParameters.RANGING_UPDATE_RATE_FREQUENT ->
                com.google.android.gms.nearby.uwb.RangingParameters.RangingUpdateRate.FREQUENT
            RangingParameters.RANGING_UPDATE_RATE_INFREQUENT ->
                com.google.android.gms.nearby.uwb.RangingParameters.RangingUpdateRate.INFREQUENT
            else ->
                throw IllegalArgumentException("The selected ranging update rate is not a valid" + " update rate.")
        }

UwbComplexChannel定义

关于UwbComplexChannel的定义，当前UWB设备工作的信道，包含物理信道以及对应的前导码index，对于前导码编码可以理解为UWB中的码分通道，所以与物理信道一起合并定义为复杂信道。如通道5，前导码为9，则UwbComplexChannel(5,9），其定义如下：

class UwbComplexChannel(val channel: Int, val preambleIndex: Int) {

    /** Returns the string format of [UwbComplexChannel]. */
    override fun toString(): String {
        return "UwbComplexChannel(channel=$channel, preambleIndex=$preambleIndex)"
    }
}

UwbComplexChannel为AIDL接口传输自定义类型在包：androidx.core.uwb.backend中进行定义UwbComplexChannel.aidl

package androidx.core.uwb.backend;
parcelable UwbComplexChannel {
  int channel;
  int preambleIndex;
}

在Android中，AIDL相关自定义数据类型均定义为parcelable，以便实现进程间通信。其实现在androidx.core.uwb.backend.impl.internal相关源码实现。

package androidx.core.uwb.backend.impl.internal;

/** Complex channel used by UWB ranging. */
public class UwbComplexChannel {

    @FiraParams.UwbChannel private final int mChannel;
    /* BPRF模式下，仅支持9-12 */
    @FiraParams.UwbPreambleCodeIndex private final int mPreambleIndex;
}

Exceptions类

异常	说明
UwbApiException	Uwb服务错误的异常类
UwbHardwareNotAvailableException	设备上不支持UWB硬件
UwbServiceNotAvailableException	设备上暂不支持UWB服务
UwbSystemCallbackException	UWB系统回调中发生了异常失败，如停止测距或移除已知的controlee失败

Android UWB——androidx.core.uwb数据类型