设备之间的范围

Android 16(API 级别 36)引入了测距模块,该模块提供了一个统一且标准化的接口,用于在设备之间进行精确测距。您可以使用此 API Surface 测量对等设备的距离和位置,而无需单独处理每种测距技术。

测距模块支持以下技术:

测距功能和可用性

RangingManager 类可为应用提供有关本地设备支持的测距技术以及每种技术的可用性和功能的信息。应用可以注册 RangingCapabilitiesCallback 接口,以便在任何受支持技术的可用性或功能发生任何变化时接收更新。

设备角色

在 Android 17(API 级别 37)及更高版本上,参与测距会话的设备必须是发起方、响应方或下行链路 TDoA 标签 (DT-Tag),以便进行 UWB 下行链路 TDoA 会话。发起方设备会与一个或多个响应方设备启动测距会话。响应方设备一次只能响应一个发起方的测距请求。在 UWB 下行链路到达时间差 (DL-TDoA) 会话中,设备使用 DEVICE_ROLE_DT_TAG 角色接收来自多个 UWB 锚点的信号。您可以使用 RangingPreference 类在测距会话中为给定设备指定角色。

测距会话类型

在设备之间启动测距会话时,通常需要建立带外 (OOB) 数据传输,以便为会话交换参数。

测距模块可以为您处理 OOB 协商,但也支持自定义 OOB 实现。

图 1. 会话类型的 OOB 流程。

默认 OOB 实现

在此会话类型 (RANGING_SESSION_OOB) 中,测距模块会处理 OOB 协商,以启动测距会话。它会根据应用提供的测距偏好设置选择合适的参数,并根据两台设备支持的技术使用适当的技术。此会话类型使用标准化的 OOB 规范。在 Android 16 QPR2(API 级别 36.1)及更高版本中,发起方可以通过对 OobInitiatorRangingConfig.Builder 调用 setRangingTechnologyFilter 来限制协商的技术。

测距模块仅定义用于与对等设备交互的 OOB 数据格式和序列。它不负责处理对等设备发现或连接建立。

自定义 OOB 实现

在此会话类型 (RANGING_SESSION_RAW) 中,应用会绕过测距模块的 OOB 流程,自行处理 OOB 协商和参数。这意味着,应用必须确定对等设备支持哪些技术、协商测距参数并开始测距会话。

测距偏好设置

使用 RangingPreference 对象为测距会话指定所选参数。您可以执行以下操作:

  • 设备角色。这表示设备是发起方、响应方还是 DT-Tag(在 Android 17 [API 级别 37] 及更高版本中)。
  • 测距配置。RangingConfig 对象指定测距会话类型以及启动测距会话所需的其他参数。
  • 会话配置。SessionConfig 对象指定要在测距会话中强制执行的参数,例如测量限制、传感器融合、地理围栏配置等。在 Android 17(API 级别 37)及更高版本中,您还可以使用 UwbRangingCapabilities 上的 getSupportedAntennaModes 检查支持的模式,然后使用 SessionConfig.Builder 上的 setAntennaMode 配置天线模式(ANTENNA_MODE_DIRECTIONAL 或 ANTENNA_MODE_OMNI)。

测距权限

测距模块针对点对点测距技术使用统一权限 (android.permission.RANGING)。此权限位于 NEARBY_DEVICES_PERMISSIONS 列表中。

<uses-permission android:name="android.permission.RANGING" />

限制和局限

测距模块可能会出于多种原因限制测距,包括:

  • 第三方应用只能在受支持的设备上使用超宽带执行后台测距。不允许使用其他技术在后台测距。
  • 当设备已达到并发测距会话数上限时,不允许测距。
  • 由于电池、性能或内存等系统运行状况问题,测距可能会受到限制。

测距模块还具有以下已知限制:

  • 测距模块仅支持向对等设备提供超宽带测距数据。对于其他技术,测距模块仅向发起方设备提供测距数据。
  • 测距模块仅支持在原始测距模式下动态添加设备,并且仅支持超宽带。
  • 测距模块不支持默认 OOB 实现的一对多超宽带会话。如果您传入多个设备句柄,该模块会为每个支持超宽带的对等设备创建一个一对一会话。

执行测距会话

如需使用测距模块进行测距会话,请按以下步骤操作:

  1. 验证所有设备是否都搭载 Android 16(API 级别 36)及更高版本。
  2. 在应用清单中请求 android.permission.RANGING 权限。
  3. 评估测距技术的功能和可用性。
  4. 发现用于测距操作的对等设备。
  5. 使用测距会话类型中所述的任一会话类型,建立带外交换连接。
  6. 启动测距并持续获取测距数据。
  7. 终止测距会话。

以下代码示例演示了发起方角色和响应方角色的这些步骤。

class RangingApp {

    // Starts a ranging session on the initiator side.
    fun startRangingInitiator(
        context: Context,
        deviceHandle: DeviceHandle,
        executor: Executor,
        callback: RangingSession.Callback
    ): RangingSession? {

        // Get the RangingManager which is the entry point for ranging module.
        val manager = context.getSystemService(RangingManager::class.java)

        // Create a new RangingSession using the provided executor and callback.
        val session = manager.createRangingSession(executor, callback) ?: return null

        // Create an OobInitiatorRangingConfig, which specifies the ranging parameters for
        // the initiator role.
        val config = OobInitiatorRangingConfig.Builder()
            .setFastestRangingInterval(Duration.ofMillis(100))
            .setSlowestRangingInterval(Duration.ofMillis(5000))
            .setRangingMode(RANGING_MODE_AUTO)
            .setSecurityLevel(SECURITY_LEVEL_BASIC)
            .addDeviceHandle(deviceHandle)
            .build()

        // Create a RangingPreference, which specifies the role (initiator) and
        // configuration for the ranging session.
        val preference =
            RangingPreference.Builder(DEVICE_ROLE_INITIATOR, config).build()

        // Start ranging session. Ranging data is delivered asynchronously through
        // callback.onResults; call stopRanging(session) when ranging is no longer needed.
        session.start(preference)
        return session
    }

    // Starts a ranging session on the responder side.
    fun startRangingResponder(
        context: Context,
        deviceHandle: DeviceHandle,
        executor: Executor,
        callback: RangingSession.Callback
    ): RangingSession? {

        // Get the RangingManager which is the entry point for ranging module.
        val manager = context.getSystemService(RangingManager::class.java)

        // Create a new RangingSession using the provided executor and callback.
        val session = manager.createRangingSession(executor, callback) ?: return null

        // Create an OobResponderRangingConfig, which specifies the ranging parameters for
        // the responder role.
        val config = OobResponderRangingConfig.Builder(deviceHandle).build()

        // Create a RangingPreference, which specifies the role (responder) and
        // configuration for the ranging session.
        val preference =
            RangingPreference.Builder(DEVICE_ROLE_RESPONDER, config).build()

        // Start the ranging session. Call stopRanging(session) when finished.
        session.start(preference)
        return session
    }

    // Stops an active ranging session.
    fun stopRanging(session: RangingSession) {
        session.stop()
    }
}

处理测距结果和对等设备移动

当会话处于活动状态时,RangingSession.Callback 会通过 onResults 在 RangingData 对象中提供距离和到达角测量结果:

  • 距离不确定性。在 Android 16 QPR2(API 级别 36.1)及更高版本中,对 RangingData 调用 hasDistanceStandardDeviation 和 getDistanceStandardDeviationMeters,以检查距离测量的标准差(如果可用)。
  • 技术专属额外福利。在 Android 17(API 级别 37)及更高版本中,对 RangingData 调用 getRangingDataExtras,以检索包含特定技术元数据的 RangingDataExtras 对象,例如 BleSpecificData、UwbSpecificData 或 WifiRttSpecificData。
  • 对等运动状态。在 Android 17(API 级别 37)及更高版本中,在 RangingSession.Callback 中替换 onMotionReceived,以便在对等设备的移动发生变化时接收 MotionState 更新(MOTION_NOT_DETECTED、MOTION_SLIGHT、MOTION_MODERATE 或 MOTION_LARGE)。

UWB 与 iOS 设备的互操作性

测距模块支持与使用超宽带 (UWB) 的 iOS 设备进行互操作。如需与 iOS 设备进行测距,您必须使用自定义 OOB 实现,并使用与 Apple Nearby Interaction Accessory Protocol 匹配的特定参数配置测距会话。如需查看示例,请参阅示例应用。

创建 RangingPreference 时,请使用 RawRangingDevice 和 UwbRangingParams 指定配置。以下参数对于 iOS 互操作性至关重要:

  • 配置 ID。请使用 UwbRangingParams.CONFIG_UNICAST_DS_TWR。
  • 会话密钥信息。提供包含供应商 ID 和静态 STS IV 的字节数组。
  • 复杂渠道。设置信道编号和预置指令索引,使其与 iOS 设备的配置相匹配。

以下代码段演示了如何为与 iOS 响应器测距的发起方设备创建 RangingPreference:

// Create UwbRangingParams with iOS-specific configuration.
val uwbRangingParams = UwbRangingParams.Builder(
    sessionId,
    UwbRangingParams.CONFIG_UNICAST_DS_TWR,
    sourceAddress,
    destinationAddress
)
    .setComplexChannel(
        UwbComplexChannel.Builder()
            .setChannel(channelNumber)
            .setPreambleIndex(preambleIndex)
            .build()
    )
    .setRangingUpdateRate(updateRate)
    .setSessionKeyInfo(sessionKeyInfo) // Vendor ID + STS IV
    .setSlotDuration(slotDuration)
    .build()

// Create RawRangingDevice.
val rawRangingDevice = RawRangingDevice.Builder()
    .setRangingDevice(RangingDevice.Builder().build())
    .setUwbRangingParams(uwbRangingParams)
    .build()

// Create SessionConfig.
val sessionConfig = SessionConfig.Builder()
    .setAngleOfArrivalNeeded(true)
    .setDataNotificationConfig(
        DataNotificationConfig.Builder()
            .setNotificationConfigType(DataNotificationConfig.NOTIFICATION_CONFIG_ENABLE)
            .build()
    )
    .build()

// Create RangingPreference for the initiator.
val preference = RangingPreference.Builder(
    RangingPreference.DEVICE_ROLE_INITIATOR,
    RawInitiatorRangingConfig.Builder()
        .addRawRangingDevice(rawRangingDevice)
        .build()
)
    .setSessionConfig(sessionConfig)
    .build()

UWB Downlink-TDoA API

在 Android 17(API 级别 37)及更高版本中,下行链路到达时间差 (DL-TDoA) 测距功能可让设备通过测量信号的相对到达时间来确定其相对于多个 UWB 锚点的位置。

以下代码段演示了如何使用 RangingManager 验证 DL-TDoA 支持,配置 DlTdoaRangingParams 和 RawDtTagRangingConfig 以启动会话,以及接收 DlTdoaMeasurement 结果:

class RangingApp {

    fun initDlTdoa(context: Context) {
        // Initialize the Ranging Manager.
        val rangingManager = context.getSystemService(RangingManager::class.java)

        // Register for device capabilities.
        val capabilitiesCallback = object : RangingManager.RangingCapabilitiesCallback {
            override fun onRangingCapabilities(capabilities: RangingCapabilities) {
                // Make sure DL-TDoA is supported before starting the session.
                if (capabilities.uwbCapabilities?.isDlTdoaSupported == true) {
                    startDlTDoASession(context)
                }
            }
        }
        rangingManager.registerCapabilitiesCallback(Executors.newSingleThreadExecutor(), capabilitiesCallback)
    }

    fun startDlTDoASession(context: Context) {
        // Initialize the Ranging Manager.
        val rangingManager = context.getSystemService(RangingManager::class.java)

        // Create session and configure parameters.
        val executor = Executors.newSingleThreadExecutor()
        val rangingSession = rangingManager.createRangingSession(executor, RangingSessionCallback())
        val rangingRoundIndexes = byteArrayOf(0)
        val config: ByteArray = byteArrayOf() // OOB config data
        val params = DlTdoaRangingParams.createFromFiraConfigPacket(config, rangingRoundIndexes)

        val rangingDevice = RangingDevice.Builder().build()
        val rawTagDevice = RawRangingDevice.Builder()
            .setRangingDevice(rangingDevice)
            .setDlTdoaRangingParams(params)
            .build()

        val dtTagConfig = RawDtTagRangingConfig.Builder(rawTagDevice).build()

        val preference = RangingPreference.Builder(DEVICE_ROLE_DT_TAG, dtTagConfig)
            .setSessionConfig(SessionConfig.Builder().build())
            .build()

        // Start the ranging session.
        rangingSession?.start(preference)
    }
}

private class RangingSessionCallback : RangingSession.Callback {
    override fun onDlTdoaResults(peer: RangingDevice, measurement: DlTdoaMeasurement) {
        // Process measurement results here.
    }

    override fun onOpened() {
        // ...
    }

    override fun onOpenFailed(reason: Int) {
        // ...
    }

    override fun onStarted(peer: RangingDevice, technology: Int) {
        // ...
    }

    override fun onStopped(peer: RangingDevice, technology: Int) {
        // ...
    }

    override fun onResults(peer: RangingDevice, data: RangingData) {
        // ...
    }

    override fun onClosed(reason: Int) {
        // ...
    }
}

带外 (OOB) 配置

以下代码段提供了 Wi-Fi 和 BLE 的 DL-TDoA OOB 配置数据示例:

// Wi-Fi Configuration (Vendor-Specific IE, FiRa CID 0x5A18FF, Config 0)
val wifiConfig = byteArrayOf(
    0xDD.toByte(), 0x30, 0x5A, 0x18, 0xFF.toByte(), // Wi-Fi VSE Header
    0x5F, 0x1C, // UWB Configuration Sub-Element
    0x02, 0x00, // Profile ID (Untracked Navigation), Config ID 0
    0x06, 0x02, 0x20, 0x08, // Device MAC Address
    0x14, 0x01, 0x0A, // Preamble Code Index (10)
    0x27, 0x02, 0x08, 0x07, // Vendor ID
    0x28, 0x06, 0xA1.toByte(), 0xB2.toByte(), 0xC3.toByte(), 0xD4.toByte(), 0xE5.toByte(), 0xF6.toByte(), // Static STS IV
    0x08, 0x02, 0x60, 0x09, // Slot Duration (2400 RSTU = 2 ms)
    0x1B, 0x01, 0x0A, // Slots per Ranging Round (10)
    0x09, 0x04, 0xFA.toByte(), 0x00, 0x00, 0x00, // Ranging Duration (250 ms)
    0x52, 0x01, 0x00, // Initiator DT-Anchor Round Index (0)
    0x9F.toByte(), 0x04, 0xAA.toByte(), 0xBB.toByte(), 0xCC.toByte(), 0xDD.toByte() // Session ID (0xDDCCBBAA)
)

// BLE Configuration (ADV_NONCONN_IND Service Data UUID 0xFFF3, Config 0)
val bleConfig = byteArrayOf(
    0x1E, 0x16, 0xF3.toByte(), 0xFF.toByte(), // BLE Service Data Header
    0xF0.toByte(), // Fragment Indication Sub-Element (unfragmented)
    0x5F, 0x09, // UWB Configuration Sub-Element
    0x02, 0x00, // Profile ID (Untracked Navigation), Config ID 0
    0x06, 0x02, 0x20, 0x08, // Device MAC Address
    0x27, 0x02, 0x08, 0x07, // Vendor ID
    0x28, 0x06, 0xA1.toByte(), 0xB2.toByte(), 0xC3.toByte(), 0xD4.toByte(), 0xE5.toByte(), 0xF6.toByte(), // Static STS IV
    0x9F.toByte(), 0x04, 0xAA.toByte(), 0xBB.toByte(), 0xCC.toByte(), 0xDD.toByte() // Session ID (0xDDCCBBAA)
)

如果您因缺少 OOB 配置而无法使用该配置,或者需要更改 OOB 配置中没有的默认值,则可以使用 DlTdoaRangingParams.Builder 构建参数,而不是调用 DlTdoaRangingParams.createFromFiraConfigPacket:

val dlTdoaParams = DlTdoaRangingParams.Builder(1)
    .setComplexChannel(
        UwbComplexChannel.Builder()
            .setChannel(9).setPreambleIndex(10).build()
    )
    .setDeviceAddress(deviceAddress)
    .setSessionKeyInfo(byteArrayOf(0x01, 0x02, 0x03, 0x04))
    .setRangingIntervalMillis(240)
    .setSlotDuration(UwbRangingParams.DURATION_2_MS)
    .setSlotsPerRangingRound(20)
    .setRangingRoundIndexes(byteArrayOf(0x01, 0x05))
    .build()

示例应用

如需查看有关如何使用测距模块的端到端示例,请参阅 AOSP 中的示例应用。此示例应用涵盖了测距模块支持的所有测距技术,并包含两种受支持会话类型的流程。

UWB 与 iOS 设备的互操作性

Android 示例应用支持与 iOS 示例应用启动 UWB 测距会话。

图 2. Android 和 iOS UWB 使用情况。