Android 16 (nivel de API 36) presenta el módulo de medición de distancia, que proporciona una interfaz unificada y estandarizada para medir la distancia entre dispositivos con precisión. Puedes usar esta superficie de la API para medir la distancia y la posición de los dispositivos de intercambio de tráfico sin necesidad de controlar cada tecnología de medición de distancia de forma individual.
El módulo de medición de distancia admite las siguientes tecnologías:
- Banda ultraancha
- Sondeo de canales de Bluetooth
- RTT de NAN de Wi-Fi
- Rango de RSSI de Bluetooth
- Detección de proximidad de Wi-Fi en Android 17 (nivel de API 37) y versiones posteriores
Capacidades de medición de distancia y disponibilidad
La clase RangingManager proporciona a las apps información sobre las tecnologías de medición de distancia que admite el dispositivo local, así como la disponibilidad y las capacidades de cada tecnología. Las apps pueden registrar una interfaz RangingCapabilitiesCallback para recibir actualizaciones sobre cualquier cambio en la disponibilidad o las capacidades de las tecnologías compatibles.
Roles de los dispositivos
Un dispositivo que participa en una sesión de medición de distancia debe ser un iniciador, un respondedor o una etiqueta de TDoA de enlace descendente (DT-Tag) para las sesiones de TDoA de enlace descendente de UWB en Android 17 (nivel de API 37) y versiones posteriores. El dispositivo iniciador comienza la sesión de medición de distancia con uno o más dispositivos de respuesta. Un dispositivo de respuesta responde a las solicitudes de medición de distancia de un solo iniciador a la vez. En una sesión de diferencia de tiempo de llegada de enlace descendente (DL-TDoA) de UWB, el dispositivo usa el rol DEVICE_ROLE_DT_TAG para recibir señales de varias anclas de UWB.
Puedes especificar el rol de un dispositivo determinado en una sesión de medición de distancia con la clase RangingPreference.
Tipos de sesiones de medición de distancia
Cuando se inicia una sesión de medición de distancia entre dispositivos, suele ser necesario establecer un transporte de datos fuera de banda (OOB) para intercambiar parámetros de la sesión.
El módulo de medición de distancia puede controlar las negociaciones de OOB por ti, pero también admite implementaciones de OOB personalizadas.
Implementación predeterminada de OOB
En este tipo de sesión (RANGING_SESSION_OOB), el módulo de medición de distancia controla las negociaciones de OOB para iniciar una sesión de medición de distancia. Selecciona los parámetros adecuados según las preferencias de medición de distancia que proporciona la app y usa las tecnologías adecuadas según lo que admiten ambos dispositivos. Este tipo de sesión
usa una especificación de OOB estandarizada. En Android 16 QPR2 (nivel de API 36.1)
y versiones posteriores, los iniciadores pueden restringir las tecnologías que se negocian
llamando a setRangingTechnologyFilter en
OobInitiatorRangingConfig.Builder.
El módulo de medición de distancia solo define el formato de datos y la secuencia de OOB que se usarán para interactuar con un dispositivo de par. No controla el descubrimiento de dispositivos de pares ni el establecimiento de conexiones.
Implementación personalizada de OOB
En este tipo de sesión (RANGING_SESSION_RAW), la app omite el flujo de OOB del módulo de medición de distancia y controla su propia negociación y parámetros de OOB. Esto significa que la app debe determinar qué tecnologías admite el dispositivo de par, negociar los parámetros de medición de distancia y comenzar la sesión de medición de distancia.
Preferencias de medición de distancia
Usa un objeto RangingPreference para especificar los parámetros seleccionados de una sesión de medición de distancia. Estas son algunas de ellas:
- Rol del dispositivo. Indica si el dispositivo es el iniciador, el respondedor o una DT-Tag en Android 17 (nivel de API 37) y versiones posteriores.
- Configuración de la medición de distancia. Un objeto
RangingConfigespecifica el tipo de sesión de medición de distancia y otros parámetros necesarios para iniciar una sesión de medición de distancia. - Configuración de la sesión. Un objeto
SessionConfigespecifica los parámetros que se aplicarán en la sesión de medición de distancia, como el límite de medición, la fusión de sensores, la configuración de geovalla y mucho más. En Android 17 (nivel de API 37) y versiones posteriores, también puedes configurar el modo de antena (ANTENNA_MODE_DIRECTIONALoANTENNA_MODE_OMNI) consetAntennaModeenSessionConfig.Builderdespués de verificar los modos compatibles congetSupportedAntennaModesenUwbRangingCapabilities.
Permiso de medición de distancia
El módulo de medición de distancia usa un permiso unificado (android.permission.RANGING) para las tecnologías de medición de distancia de par a par. Este permiso se encuentra en la lista
NEARBY_DEVICES_PERMISSIONS.
<uses-permission android:name="android.permission.RANGING" />
Restricciones y limitaciones
El módulo de medición de distancia puede restringir la medición por varios motivos, incluidos los siguientes:
- Las apps de terceros solo pueden realizar mediciones de distancia en segundo plano con banda ultraancha y solo en dispositivos compatibles. No se permite la medición de distancia en segundo plano con otras tecnologías.
- No se permite la medición de distancia cuando se alcanza la cantidad máxima de sesiones de medición de distancia simultáneas por dispositivo.
- Es posible que la medición de distancia esté restringida debido a problemas de estado del sistema, como la batería, el rendimiento o la memoria.
El módulo de medición de distancia también tiene las siguientes limitaciones conocidas:
- El módulo de medición de distancia solo admite la entrega de datos de medición de distancia a dispositivos de par para banda ultraancha. Para otras tecnologías, el módulo de medición de distancia solo entrega datos de medición de distancia al dispositivo iniciador.
- El módulo de medición de distancia solo admite la adición dinámica de dispositivos en el modo de medición de distancia sin procesar y solo para la banda ultraancha.
- El módulo de medición de distancia no admite sesiones de banda ultraancha de uno a varios para las implementaciones de OOB predeterminadas. Si pasas varios controladores de dispositivos, el módulo crea una sesión individual para cada dispositivo de par que admita la banda ultraancha.
Cómo realizar una sesión de medición de distancia
Para realizar una sesión de medición de distancia con el módulo de medición de distancia, sigue estos pasos:
- Verifica que todos los dispositivos ejecuten Android 16 (nivel de API 36) y versiones posteriores.
- Solicita el permiso
android.permission.RANGINGen el manifiesto de la app. - Evalúa las capacidades y la disponibilidad de las tecnologías de medición de distancia.
- Descubre un dispositivo de par para las operaciones de medición de distancia.
- Establece una conexión para un intercambio fuera de banda con cualquiera de los tipos de sesión que se describen en Tipos de sesiones de medición de distancia.
- Inicia la medición de distancia y adquiere datos de medición de distancia de forma continua.
- Finaliza la sesión de medición de distancia.
En la siguiente muestra de código, se indican estos pasos para el rol de iniciador y el de respondedor.
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() } }
Cómo controlar los resultados de la medición de distancia y el movimiento de los pares
Cuando una sesión está activa, RangingSession.Callback entrega mediciones de distancia y ángulo de llegada en objetos RangingData a través de onResults:
- Incertidumbre de la distancia. En Android 16 QPR2 (nivel de API 36.1) y versiones posteriores, llama a
hasDistanceStandardDeviationygetDistanceStandardDeviationMetersenRangingDatapara inspeccionar la desviación estándar de las mediciones de distancia cuando estén disponibles. - Extras específicos de la tecnología. En Android 17 (nivel de API 37) y versiones posteriores,
llama a
getRangingDataExtrasenRangingDatapara recuperar un objetoRangingDataExtrasque contenga metadatos específicos de la tecnología, comoBleSpecificData,UwbSpecificDataoWifiRttSpecificData. - Estado de movimiento del par. En Android 17 (nivel de API 37) y versiones posteriores, anula
onMotionReceivedenRangingSession.Callbackpara recibir actualizaciones deMotionState(MOTION_NOT_DETECTED,MOTION_SLIGHT,MOTION_MODERATEoMOTION_LARGE) cuando cambie el movimiento de un dispositivo de par.
Interoperabilidad de UWB con dispositivos iOS
El módulo de medición de distancia admite la interoperabilidad con dispositivos iOS que usan la banda ultraancha (UWB). Para medir la distancia con un dispositivo iOS, debes usar una implementación de OOB personalizada y configurar la sesión de medición de distancia con parámetros específicos que coincidan con el protocolo de accesorios de interacción cercana de Apple. Para ver un ejemplo, consulta la app de ejemplo.
Cuando crees el RangingPreference, usa RawRangingDevice y
UwbRangingParams para especificar la configuración. Los siguientes parámetros son
cruciales para la interoperabilidad con iOS:
- ID de configuración. Usa
UwbRangingParams.CONFIG_UNICAST_DS_TWR. - Información de la clave de sesión. Proporciona un array de bytes que contenga el ID del proveedor y el IV de STS estático.
- Canal complejo Establece el número de canal y el índice de preámbulo para que coincidan con la configuración del dispositivo iOS.
En el siguiente fragmento de código, se muestra cómo crear un RangingPreference para un dispositivo iniciador que realiza una medición de distancia con un dispositivo de respuesta de iOS:
// 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()
API de TDoA de enlace descendente de UWB
En Android 17 (nivel de API 37) y versiones posteriores, la medición de distancia de diferencia de tiempo de llegada de enlace descendente (DL-TDoA) permite que un dispositivo determine su posición en relación con varias anclas de UWB midiendo los tiempos de llegada relativos de las señales.
En el siguiente fragmento, se muestra cómo usar RangingManager para verificar la compatibilidad con DL-TDoA, configurar DlTdoaRangingParams y RawDtTagRangingConfig para iniciar una sesión y recibir resultados de 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) { // ... } }
Parámetros de configuración fuera de banda (OOB)
En el siguiente fragmento, se proporciona un ejemplo de datos de configuración de OOB de DL-TDoA para Wi-Fi y BLE:
// 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) )
Si no puedes usar una configuración de OOB porque falta o si necesitas
cambiar los valores predeterminados que no están en la configuración de OOB, puedes compilar
parámetros con DlTdoaRangingParams.Builder en lugar de llamar a
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()
App de ejemplo
Para ver un ejemplo de extremo a extremo de cómo usar el módulo de medición de distancia, consulta la app de ejemplo en el AOSP. Esta app de ejemplo abarca todas las tecnologías de medición de distancia que admite el módulo de medición de distancia y, además, incluye flujos para ambos tipos de sesiones compatibles.
Interoperabilidad de UWB con dispositivos iOS
La app de ejemplo para Android admite el inicio de una sesión de medición de distancia de UWB con la app de ejemplo para iOS.