Comunicação de banda ultralarga (UWB)

A comunicação de banda ultralarga é uma tecnologia de rádio focada no alcance preciso (medir a localização com uma precisão de 10 cm) entre dispositivos. Essa tecnologia de rádio pode usar uma densidade de baixa energia para medições de curto alcance e realizar sinalização de alta largura de banda em uma grande parte do espectro do rádio. A largura de banda da UWB é maior que 500 MHz (ou superior a 20% da largura de banda fracionária).

Controlador/Iniciador x Controle/Respondente

A comunicação UWB ocorre entre dois dispositivos, em que um é um Controlador e o outro é um Controle. O controlador determina o canal complexo (UwbComplexChannel) que os dois dispositivos vão compartilhar e é o iniciador, enquanto o Controle é o responsável.

Um Controlador pode lidar com vários controles, mas ele só pode se inscrever em um único controlador. Ambas as configurações são compatíveis.

Intervalo de parâmetros

O Controlador e o Controle precisam se identificar e comunicar os parâmetros para começar a alcance. Essa troca é deixada para os aplicativos implementarem usando um mecanismo fora de banda (OOB) seguro de sua escolha, como o Bluetooth de baixa energia (BLE).

Os parâmetros de alcance incluem endereço local, canal complexo e chave de sessão, entre outros. Esses parâmetros podem alternar ou mudar após o término da sessão de alcance e precisam ser recomunicados para reiniciar o alcance.

Alcance do plano de fundo

Um app executado em segundo plano poderá iniciar uma sessão de alcance de UWB se o dispositivo tiver suporte a ela. Para conferir os recursos do dispositivo, consulte RangingCapabilities.

O app não recebe relatórios de alcance quando executado em segundo plano, mas recebe relatórios de alcance quando é movido para o primeiro plano.

Configurações de STS

O app ou serviço provisiona uma chave de sessão para cada sessão usando uma sequência de carimbo de data/hora embaralhada (STS, na sigla em inglês). O STS provisionado é mais seguro que uma configuração de STS estática. O STS provisionado tem suporte em todos os dispositivos ativados para UWB que executam o Android 14 ou versões mais recentes.

Categoria da ameaça STS estático STS projetado
Air: observador passivo Atenuado Atenuado
Ar: amplificação de sinal Atenuado Atenuado
Air: ataque de repetição/retransmissão Suscetível Atenuado

Para STS provisionado:

  1. Use o uwbConfigType no RangingParameters que oferece suporte ao STS provisionado.

  2. Forneça a chave de 16 bytes no campo sessionKeyInfo.

Para STS estático:

  1. Use o uwbConfigType no RangingParameters (link em inglês) que oferece suporte ao STS estático.

  2. Forneça a chave de 8 bytes no campo sessionKeyInfo.

Etapas

Para usar a API UWB, siga estas etapas:

  1. Verifique se os dispositivos estão executando o Android 12 ou mais recente e se oferecem suporte a UWB usando PackageManager#hasSystemFeature("android.hardware.uwb").
  2. Se estiver usando dispositivos IoT, verifique se eles estão em conformidade com o FiRa MAC 1.3.
  3. Descubra dispositivos de peering compatíveis com UWB usando o mecanismo OOB de sua escolha, como BluetoothLeScanner.
  4. Troque os parâmetros de alcance usando um mecanismo OOB seguro de sua escolha, como BluetoothGatt.
  5. Se o usuário quiser interromper a sessão, cancele o escopo dela.

Restrições de uso

As restrições a seguir se aplicam ao uso da API UWB:

  1. O app que inicia novas sessões de alcance da UWB precisa ser um app ou serviço em primeiro plano, a menos que o alcance em segundo plano tenha suporte, conforme ilustrado anteriormente.
  2. Quando o app passa para o segundo plano (enquanto a sessão está em andamento), ele pode deixar de receber relatórios de alcance. No entanto, a sessão da UWB vai continuar a ser mantida nas camadas inferiores. Quando o app voltar para o primeiro plano, os relatórios de alcance serão retomados.

Exemplos de código

App de exemplo

Para conferir um exemplo completo de como usar a biblioteca UWB Jetpack, consulte nosso aplicativo de exemplo no GitHub (link em inglês). Este app de exemplo aborda a validação da compatibilidade com UWB em um dispositivo Android, permitindo o processo de descoberta usando um mecanismo de OOB e configurando a UWB entre dois dispositivos compatíveis com UWB. O exemplo também aborda casos de uso de controle de dispositivos e compartilhamento de mídia.

Intervalo de UWB

Este exemplo de código inicia e encerra o UWB que vai para um Controle:

// 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()
    }
}

Suporte ao RxJava3

A compatibilidade com Rxjava3 agora está disponível para ajudar a alcançar a interoperabilidade com clientes Java. Essa biblioteca oferece uma maneira de receber resultados de alcance como um fluxo observável ou Flowable e recuperar o UwbClientSessionScope como um objeto único.

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();

Suporte ao ecossistema

Estes são os dispositivos de parceiros e SDKs de terceiros compatíveis.

Dispositivos móveis compatíveis com UWB

Desde março de 2024, estes dispositivos oferecem suporte à biblioteca Android UWB Jetpack:

Fornecedor Modelo do dispositivo
Google Pixel 6 Pro, 7 Pro, 8 Pro, Fold e tablet
Samsung Galaxy Note 20, S21+, S22+, S23+, S24+ Z Fold 2, 3, 4, 5

SDKs de terceiros

Desde abril de 2023, essas soluções de parceiros são compatíveis com a biblioteca atual do Jetpack.

Problema conhecido: ordem de bytes revertida para os campos de endereço MAC e ID de fornecedor STS estático

No Android 13 e versões anteriores, a pilha UWB do Android inverte incorretamente a ordem de bytes dos campos abaixo:

  • Endereço MAC do dispositivo
  • Endereço MAC de destino
  • ID do fornecedor STS estático

A inversão da ordem de bytes ocorre porque a pilha do Android trata esses campos como valores, não matrizes. Estamos trabalhando com a FiRa para atualizar a especificação UCI (CR-1112) para declarar explicitamente que esses campos precisam ser tratados como matrizes.

Esse problema será corrigido com a atualização do GMS Core na versão 2320XXXX. A partir desse momento, para estar em conformidade com os dispositivos Android, os fornecedores de IoT precisam modificar sua implementação para evitar a reversão da ordem de bytes desses campos.