Komunikacja ultraszerokopasmowa (UWB)

Komunikacja ultraszerokopasmowa to technologia radiowa skoncentrowana na precyzyjnym określaniu (pomiar lokalizacji z dokładnością do 10 cm) między urządzeniami. Ta technologia radiowa może wykorzystywać gęstość przy niskiej energii do pomiarów w krótkim zasięgu i wykorzystywać sygnał o dużej przepustowości w dużej części pasma radiowego. Przepustowość UWB przekracza 500 MHz (lub ponad 20% wartości ułamkowej przepustowość).

Kontroler/Inicjator kontra użytkownik sterujący/respondent

Komunikacja UWB odbywa się między 2 urządzeniami, z których jedno to kontroler, jest podmiotem kontrolowanym. Kontroler określa złożony kanał (UwbComplexChannel), który oba urządzenia będą współużytkowane i będą inicjatorem, a Osoba sterująca będzie użytkownika.

Kontroler może obsługiwać wielu kont nadzorowanych, ale ten podmiot może subskrybować tylko z jednym kontrolerem. zarówno administrator/inicjator, jak i osoba sterująca/podmiot odpowiadający są obsługiwane.

Parametry rangi

Administrator i Osoba kontrolująca muszą zidentyfikować się nawzajem i komunikować parametry, aby rozpocząć zakres. Ta wymiana jest pozostawiana aplikacjom implementują za pomocą wybranego przez siebie bezpiecznego mechanizmu zewnętrznego, takiego jak Bluetooth Low Energy (BLE).

Parametry zakresu obejmują m.in. adres lokalny, kanał złożony i klucz sesji. Notatka że te parametry mogą ulec rotacji lub w inny sposób ulec zmianie po sesji określania zakresu i konieczne jest ponowne przesłanie informacji, aby ponownie uruchomić zakres.

Zakres tła

Aplikacja działająca w tle może rozpocząć sesję UWB, jeśli urządzenie który ją obsługuje. Aby sprawdzić możliwości urządzenia, zobacz RangingCapabilities.

Aplikacja nie otrzymuje raportów dotyczących zakresu, gdy działa w tle. aplikacja otrzymuje raporty o zakresie po przejściu na pierwszy plan.

Konfiguracje STS

Aplikacja lub usługa udostępnia klucz sesji dla każdej sesji za pomocą metody zaszyfrowanej Sekwencja sygnatury czasowej (STS). Udostępniona usługa STS jest bezpieczniejsza niż statyczna usługa STS konfiguracji. Obsługiwany mechanizm STS jest obsługiwany na wszystkich urządzeniach obsługujących UWB Androida w wersji 14 lub nowszej.

Kategoria zagrożenia Statyczny mechanizm STS Prognozowany STS
Powietrze: bierny obserwator Wyeliminowano Wyeliminowano
Powietrze: wzmocnienie sygnału Wyeliminowano Wyeliminowano
Powietrze: powtórka/atak typu przekaźnika Wrażliwa Wyeliminowano

W przypadku obsługiwanego mechanizmu STS:

  1. W usłudze RangingParameters użyj zasady uwbConfigType, która obsługuje Obsługiwany mechanizm STS.

  2. W polu sessionKeyInfo wpisz 16-bajtowy klucz.

W przypadku statycznego mechanizmu STS:

  1. W RangingParameters używaj zasady uwbConfigType, która obsługuje statyczny mechanizm STS.

  2. W polu sessionKeyInfo wpisz klucz 8-bajtowy.

Kroki

Aby użyć interfejsu UWB API, wykonaj te czynności:

  1. Sprawdź, czy na urządzeniach z Androidem jest zainstalowany Android 12 lub nowszy. obsługuje UWB przy użyciu PackageManager#hasSystemFeature("android.hardware.uwb")
  2. W przypadku urządzeń IoT upewnij się, że są to FiRa MAC 1.3 pod kątem zgodności z przepisami.
  3. wykrywanie urządzeń równorzędnych zgodnych z UWB przy użyciu wybranego mechanizmu OOB; na przykład BluetoothLeScanner
  4. Wymienianie parametrów określania zakresu za pomocą wybranego przez Ciebie bezpiecznego mechanizmu OOB. na przykład BluetoothGatt.
  5. Jeśli użytkownik chce zatrzymać sesję, anuluj jej zakres.

Ograniczenia w zakresie użytkowania

Korzystanie z interfejsu UWB API podlega tym ograniczeniom:

  1. Aplikacja inicjująca nowe sesje ustalania zakresu UWB musi być na pierwszym planie aplikacji lub usługi, chyba że zakres tła jest obsługiwany, jak pokazano na ilustracji wcześniej.
  2. Gdy aplikacja przechodzi w tle (w trakcie trwania sesji), może nie otrzymywać raportów dotyczących zakresu. Sesja UWB zostanie jednak i utrzymują się na niższych warstwach. Gdy aplikacja wróci do na pierwszym planie, raporty dotyczące określania zakresu zostaną wznowione.

Przykładowe fragmenty kodu

Przykładowa aplikacja

Pełny przykład korzystania z biblioteki UWB Jetpack znajdziesz w naszej przykładowej aplikacji na GitHubie. Ta przykładowa aplikacja obejmuje weryfikowanie zgodności UWB na urządzeniach z Androidem, włączanie procesu wykrywania za pomocą mechanizmu OOB oraz konfigurowanie UWB z różnych 2 urządzeń obsługujących UWB. W przykładzie omawiamy też przypadki użycia sterowania urządzeniami i udostępniania multimediów.

Poziomy UWB

Ten przykładowy kod inicjuje i kończy zakres UWB dla podmiotu sterowanego:

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

Obsługa RxJava3

Udostępniliśmy obsługę języka Rxjava3, która ułatwia współdziałanie z Javą klientów. Ta biblioteka umożliwia uzyskanie wyników z zakresu jako dostrzegalnego lub Strumień ciągły oraz pobieranie UwbClientSessionScope jako pojedynczego obiektu.

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

Wspieranie ekosystemu

Oto obsługiwane urządzenia partnerów i pakiety SDK innych firm.

Urządzenia mobilne z obsługą UWB

Od marca 2024 r. bibliotekę UWB Jetpack na Androida obsługują te urządzenia:

Dostawca Model urządzenia
Google Pixel 6 Pro, 7 Pro, 8 Pro, Fold, tablet
Samsung Galaxy Note 20, S21+, S22+, S23+, S24+ Z Fold 2, 3, 4, 5

Pakiety SDK innych firm

Od kwietnia 2023 r. te rozwiązania partnerskie są zgodne z bieżącą bibliotekę Jetpack.

Znany problem: odwrócona kolejność bajtów w polach adresu MAC i statycznego identyfikatora dostawcy STS

Na Androidzie 13 i starszych wersjach stos UWB Androida nieprawidłowo odwraca bajt. w następujących polach:

  • Adres MAC urządzenia
  • Docelowy adres MAC
  • Statyczny identyfikator dostawcy STS

Zmiana kolejności bajtów ma miejsce, ponieważ stos Androida traktuje te pola jako wartości, a nie tablice. Współpracujemy z FiRa nad aktualizacją specyfikacji UCI (CR-1112) wyraźnie określić, że te pola powinny być traktowane jako tablice.

Ten problem zostanie rozwiązany w ramach aktualizacji GMS Core w wersji 2320XXXX. Aby zachować zgodność z urządzeniami z Androidem, dostawcy IOT muszą wprowadzić w implementacji, aby uniknąć odwrócenia kolejności bajtów w tych polach.