Comunicação de banda ultralarga (UWB)

Observação: no momento, a UWB só está disponível usando Jetpack.

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

Controlador/Iniciador vs. Controle/Respondente

A comunicação UWB ocorre entre dois dispositivos, em que um é um controlador e o o Controlee. O controlador determina o canal complexo (UwbComplexChannel) que os dois dispositivos compartilham e é o iniciador, enquanto o Controlee é o participante.

Um Controlador pode lidar com vários Controles, mas o Controlee só pode assinar a um único Controlador. Controlador/Iniciador e Controle/Responsável têm suporte.

Parâmetros de variedade

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

Parâmetros de alcance incluem endereço local, canal complexo e chave de sessão, entre outros. Observação que esses parâmetros podem alternar ou alterar após a sessão de alcance termina e precisa ser comunicada novamente para reiniciar o alcance.

Intervalo do plano de fundo

Um app executado em segundo plano pode iniciar uma sessão de alcance UWB se o dispositivo oferece suporte a ele. Para verificar as funcionalidades do dispositivo, consulte RangingCapabilities.

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

Configurações de STS

O app ou serviço provisiona uma chave para cada sessão usando uma Sequência de carimbos de data/hora (STS). O STS provisionado é mais seguro que um STS estático configuração do Terraform. O STS provisionado é compatível com todos os dispositivos com UWB em execução Android 14 ou mais recente.

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

Para o STS provisionado:

1. Use o uwbConfigType no RangingParameters compatível com o STS provisionado.

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

Para o STS estático:

1. Use o uwbConfigType em RangingParameters compatível com STS estático.

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

Etapas

Para usar a API UWB, siga estas etapas:

1. Confira se os dispositivos estão executando o Android 12 ou mais recente e se oferecem suporte à UWB usando PackageManager#hasSystemFeature("android.hardware.uwb"):
2. Caso esteja comparando com dispositivos IoT, verifique se eles são FiRa MAC 1.3 em conformidade.
3. Descubra dispositivos de peering compatíveis com UWB usando o mecanismo OOB de sua escolha como BluetoothLeScanner
4. Troque 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 de UWB precisa estar em primeiro plano app ou serviço, a menos que a faixa de segundo plano seja suportada conforme ilustrado antes.
2. Quando o app passa para o segundo plano (enquanto a sessão está em andamento), o app não poderá mais receber relatórios de alcance. No entanto, a sessão UWB vai continuam a ser mantidas nas camadas inferiores. Quando o app voltar para a versã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, confira 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, a ativação do processo de descoberta usando um mecanismo OOB e a configuração de um intervalo de 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 alcance da UWB em um Controlee:

// 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

O suporte a Rxjava3 agora está disponível para ajudar a ter interoperabilidade com Java clientes. Essa biblioteca oferece uma maneira de coletar resultados como um objeto Observable ou Flowable e para 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 compatíveis e os SDKs de terceiros.

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, 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.

• Estimar o Kit de desenvolvimento de UWB.
• Mobile Knowledge MK UWB Kit Mobile Edition 2.0.

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

No Android 13 e versões anteriores, a pilha UWB do Android inverte o byte incorretamente para os seguintes campos:

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

A reversão da ordem dos bytes ocorre porque a pilha do Android trata esses campos. como valores, e não matrizes. Estamos trabalhando com a FiRa para atualizar a especificação da 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 implementação para evitar reverter a ordem de bytes desses campos.