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:
Use o
uwbConfigType
noRangingParameters
que oferece suporte ao STS provisionado.Forneça a chave de 16 bytes no campo
sessionKeyInfo
.
Para STS estático:
Use o
uwbConfigType
noRangingParameters
(link em inglês) que oferece suporte ao STS estático.Forneça a chave de 8 bytes no campo
sessionKeyInfo
.
Etapas
Para usar a API UWB, siga estas etapas:
- 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")
. - Se estiver usando dispositivos IoT, verifique se eles estão em conformidade com o FiRa MAC 1.3.
- Descubra dispositivos de peering compatíveis com UWB usando o mecanismo OOB de sua escolha,
como
BluetoothLeScanner
. - Troque os parâmetros de alcance usando um mecanismo OOB seguro de sua escolha,
como
BluetoothGatt
. - 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:
- 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.
- 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 |
---|---|
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.
- Kit de desenvolvimento de UWB do Estimote.
- Conhecimento para dispositivos móveis Kit MK UWB Mobile Edition 2.0.
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.