O Android 16 (nível 36 da API) apresenta o módulo de alcance, que oferece uma interface unificada e padronizada para alcance preciso entre dispositivos. Você pode usar essa superfície de API para medir a distância e a posição de dispositivos de peering sem precisar processar cada tecnologia de medição individualmente.
O módulo de medição de distância oferece suporte às seguintes tecnologias:
- Banda ultralarga
- Sondagem de canal Bluetooth
- Wi-Fi NAN RTT
- Alcance do RSSI do Bluetooth
- Detecção de proximidade por Wi-Fi no Android 17 (nível 37 da API) e versões mais recentes
Recursos e disponibilidade de alcance
A classe RangingManager fornece aos apps informações sobre as tecnologias de medição de distância
com suporte do dispositivo local, bem como a disponibilidade e
os recursos de cada tecnologia. Os apps podem registrar uma interface
RangingCapabilitiesCallback para receber atualizações sobre mudanças
na disponibilidade ou nos recursos de qualquer tecnologia compatível.
Papéis do dispositivo
Um dispositivo que participa de uma sessão de medição de distância precisa ser um iniciador, um respondente
ou uma tag de downlink-TDoA (DT-Tag) para sessões de downlink-TDoA de UWB no
Android 17 (nível 37 da API) e versões mais recentes. O dispositivo iniciador inicia a sessão de medição
com um ou mais dispositivos de resposta. Um dispositivo de resposta responde a
solicitações de medição de um iniciador por vez. Em uma sessão de diferença de tempo de chegada de downlink (DL-TDoA, na sigla em inglês) de UWB, o dispositivo usa a função
DEVICE_ROLE_DT_TAG para receber sinais de várias âncoras de UWB.
É possível especificar o papel de um determinado dispositivo em uma sessão de medição com a
classe RangingPreference.
Tipos de sessão de medição de distância
Ao iniciar uma sessão de medição entre dispositivos, geralmente é necessário estabelecer um transporte de dados fora de banda (OOB, na sigla em inglês) para trocar parâmetros da sessão.
O módulo de alcance pode processar negociações OOB para você, mas também oferece suporte a implementações OOB personalizadas.
Implementação padrão de OOB
Nesse tipo de sessão (RANGING_SESSION_OOB), o módulo de medição de alcance processa
as negociações OOB para iniciar uma sessão de medição de alcance. Ele seleciona parâmetros adequados
com base nas preferências de medição fornecidas pelo app e usa as
tecnologias adequadas com base no que os dois dispositivos aceitam. Esse tipo de sessão
usa uma especificação OOB padronizada. No Android 16 QPR2 (nível 36.1 da API)
e versões mais recentes, os iniciadores podem restringir quais tecnologias são negociadas chamando
setRangingTechnologyFilter em
OobInitiatorRangingConfig.Builder.
O módulo de medição de distância define apenas o formato de dados e a sequência OOB a serem usados para interagir com um dispositivo de peering. Ela não lida com a descoberta de dispositivos de peering ou o estabelecimento de conexão.
Implementação personalizada de OOB
Nesse tipo de sessão (RANGING_SESSION_RAW), o app ignora o fluxo OOB do módulo
de medição de distância e processa a própria negociação e os parâmetros OOB. Isso significa
que o app precisa determinar quais tecnologias o dispositivo de peering aceita, negociar
parâmetros de medição e iniciar a sessão de medição.
Preferências de alcance
Use um objeto RangingPreference para especificar os parâmetros selecionados para uma
sessão de medição de distância. Isso inclui o seguinte:
- Papel do dispositivo. Indica se o dispositivo é o iniciador, o respondente ou uma DT-Tag no Android 17 (nível 37 da API) e versões mais recentes.
- Configuração de alcance. Um objeto
RangingConfigespecifica o tipo de sessão de medição e outros parâmetros necessários para iniciar uma sessão de medição. - Configuração da sessão. Um objeto
SessionConfigespecifica parâmetros a serem aplicados na sessão de medição, como limite de medição, fusão de sensores, configuração de fronteira geográfica virtual e muito mais. No Android 17 (nível 37 da API) e versões mais recentes, também é possível configurar o modo de antena (ANTENNA_MODE_DIRECTIONALouANTENNA_MODE_OMNI) comsetAntennaModeemSessionConfig.Builderdepois de verificar os modos compatíveis comgetSupportedAntennaModesemUwbRangingCapabilities.
Permissão de alcance
O módulo de medição usa uma permissão unificada (android.permission.RANGING) para
tecnologias de medição ponto a ponto. Essa permissão está na lista
NEARBY_DEVICES_PERMISSIONS.
<uses-permission android:name="android.permission.RANGING" />
Restrições e limitações
O módulo de medição pode restringir a medição por vários motivos, incluindo os seguintes:
- Os apps de terceiros só podem realizar medições em segundo plano com banda ultralarga e apenas em dispositivos compatíveis. Não é permitido usar o alcance em segundo plano com outras tecnologias.
- A medição de distância não é permitida quando o número máximo de sessões simultâneas por dispositivo é atingido.
- A medição pode ser restrita devido a problemas de integridade do sistema, como bateria, desempenho ou memória.
O módulo de medição também tem as seguintes limitações conhecidas:
- O módulo de alcance só oferece suporte ao envio de dados de alcance para dispositivos de peering para banda ultralarga. Para outras tecnologias, o módulo de medição de distância só fornece dados de medição de distância ao dispositivo iniciador.
- O módulo de medição só oferece suporte à adição dinâmica de dispositivos no modo de medição bruta e apenas para banda ultralarga.
- O módulo de medição não oferece suporte a sessões de banda ultralarga de um para muitos para implementações OOB padrão. Se você transmitir vários identificadores de dispositivo, o módulo vai criar uma sessão individual para cada dispositivo de peering que oferece suporte à banda ultralarga.
Realizar uma sessão de medição de distância
Para realizar uma sessão de medição de distância usando o módulo de medição de distância, siga estas etapas:
- Verifique se todos os dispositivos usam o Android 16 (nível 36 da API) ou uma versão mais recente.
- Solicite a permissão
android.permission.RANGINGno manifesto do app. - Avalie os recursos e a disponibilidade de tecnologias de medição de distância.
- Descubra um dispositivo de peering para operações de medição.
- Estabeleça uma conexão para uma troca fora de banda usando um dos tipos de sessão descritos em Tipos de sessão de medição.
- Inicie a medição e adquira continuamente dados de medição.
- Encerre a sessão de medição.
O exemplo de código a seguir demonstra essas etapas para os papéis de iniciador e de respondente.
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() } }
Processar resultados de medição de distância e movimento de pares
Quando uma sessão está ativa, o RangingSession.Callback fornece medições de distância e
ângulo de chegada em objetos RangingData usando
onResults:
- Incerteza de distância. No Android 16 QPR2 (nível 36.1 da API) e versões mais recentes,
chame
hasDistanceStandardDeviationegetDistanceStandardDeviationMetersemRangingDatapara inspecionar o desvio padrão das medições de distância, quando disponível. - Extras específicos de tecnologia. No Android 17 (nível 37 da API) e versões mais recentes,
chame
getRangingDataExtrasemRangingDatapara recuperar um objetoRangingDataExtrasque contém metadados específicos da tecnologia, comoBleSpecificData,UwbSpecificDataouWifiRttSpecificData. - Estado de movimento do app semelhante. No Android 17 (nível 37 da API) e versões mais recentes, substitua
onMotionReceivedemRangingSession.Callbackpara receber atualizações deMotionState(MOTION_NOT_DETECTED,MOTION_SLIGHT,MOTION_MODERATEouMOTION_LARGE) quando o movimento de um dispositivo de peering mudar.
Interoperabilidade de UWB com dispositivos iOS
O módulo de alcance é compatível com dispositivos iOS que usam banda ultralarga (UWB). Para fazer a medição com um dispositivo iOS, use uma implementação personalizada de OOB e configure a sessão de medição com parâmetros específicos que correspondam ao Protocolo de acessório de interação por proximidade da Apple. Para ver um exemplo, consulte o app de exemplo.
Ao criar o RangingPreference, use RawRangingDevice e
UwbRangingParams para especificar a configuração. Os parâmetros a seguir são
cruciais para a interoperabilidade do iOS:
- ID de configuração. Use
UwbRangingParams.CONFIG_UNICAST_DS_TWR. - Informações da chave de sessão: forneça uma matriz de bytes que contenha o ID do fornecedor e o IV estático do STS.
- Canal complexo. Defina o número do canal e o índice do preâmbulo para corresponder à configuração do dispositivo iOS.
O snippet de código a seguir demonstra como criar um RangingPreference para
um dispositivo iniciador que varia com um respondente do 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 Downlink-TDoA de UWB
No Android 17 (nível 37 da API) e versões mais recentes, a medição de alcance por diferença de tempo de chegada de downlink (DL-TDoA, na sigla em inglês) permite que um dispositivo determine a própria posição em relação a várias âncoras de UWB medindo os tempos de chegada relativos dos sinais.
O snippet a seguir demonstra como usar RangingManager para verificar
a compatibilidade com DL-TDoA, configurar DlTdoaRangingParams e
RawDtTagRangingConfig para iniciar uma sessão e receber
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) { // ... } }
Configurações fora de banda (OOB)
O snippet a seguir mostra um exemplo de dados de configuração OOB de DL-TDoA para Wi-Fi e 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) )
Se não for possível usar uma configuração OOB porque ela está ausente ou se você precisar
mudar os valores padrão que não estão na configuração OOB, crie
parâmetros com DlTdoaRangingParams.Builder em vez de chamar
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 exemplo
Para um exemplo completo de como usar o módulo de medição, consulte o app de exemplo no AOSP. Esse app de exemplo abrange todas as tecnologias de medição de distância compatíveis com o módulo de medição de distância e inclui fluxos para os dois tipos de sessão compatíveis.
Interoperabilidade de UWB com dispositivos iOS
O app de exemplo para Android permite iniciar uma sessão de medição de distância por UWB com o app de exemplo para iOS.