Komunikasi ultra-wideband (UWB)

Komunikasi ultra-wideband adalah teknologi radio yang berfokus pada rentang yang tepat (mengukur lokasi dengan akurasi 10 cm) antarperangkat. Teknologi radio ini dapat menggunakan kepadatan energi rendah untuk pengukuran jarak pendek dan melakukan sinyal bandwidth tinggi di sebagian besar spektrum radio. Bandwidth UWB lebih besar dari 500 MHz (atau melebihi 20% bandwidth fraksional).

Pengontrol/Inisiator vs. Kontrol/Respons

Komunikasi UWB terjadi antara dua perangkat, dengan satu perangkat adalah Pengontrol, dan perangkat lainnya adalah Kontrol. Pengontrol menentukan saluran kompleks (UwbComplexChannel) yang akan dibagikan oleh kedua perangkat dan merupakan inisiator, sedangkan Kontrol adalah responder.

Pengontrol dapat menangani beberapa Kontrol, tetapi Kontrol hanya dapat berlangganan ke satu Pengontrol. Konfigurasi Pengontrol/Pemrakarsa dan Kontrol/Penjawab didukung.

Parameter rentang

Pengontrol dan Kontrol harus saling mengidentifikasi dan berkomunikasi parameter rentang untuk memulai rentang. Pertukaran ini diserahkan kepada aplikasi untuk diimplementasikan menggunakan mekanisme out-of-band (OOB) aman pilihan mereka, seperti Bluetooth Hemat Energi (BLE).

Parameter rentang mencakup alamat lokal, saluran kompleks, dan kunci sesi, di antara yang lainnya. Perhatikan bahwa parameter ini dapat berputar atau berubah setelah sesi pengukuran jarak berakhir dan perlu dikomunikasikan ulang untuk memulai ulang pengukuran jarak.

Rentang latar belakang

Aplikasi yang berjalan di latar belakang dapat memulai sesi pengukuran jarak UWB jika perangkat mendukungnya. Untuk memeriksa kemampuan perangkat, lihat RangingCapabilities.

Aplikasi tidak menerima laporan rentang saat berjalan di latar belakang; aplikasi menerima laporan rentang saat berpindah ke latar depan.

Konfigurasi STS

Aplikasi atau layanan menyediakan kunci sesi untuk setiap sesi menggunakan Urutan Stempel Waktu yang Diacak (STS). STS yang disediakan lebih aman daripada konfigurasi STS statis. STS yang disediakan didukung di semua perangkat yang kompatibel dengan UWB yang menjalankan Android 14 atau yang lebih tinggi.

Untuk STS yang disediakan:

1. Gunakan uwbConfigType di RangingParameters yang mendukung STS yang disediakan.

2. Berikan kunci 16 byte di kolom sessionKeyInfo.

Untuk STS statis:

1. Gunakan uwbConfigType di RangingParameters yang mendukung STS statis.

2. Berikan kunci 8 byte di kolom sessionKeyInfo.

Langkah

Untuk menggunakan UWB API, ikuti langkah-langkah berikut:

1. Pastikan perangkat Android berjalan di Android 12 atau yang lebih baru dan mendukung UWB menggunakan PackageManager#hasSystemFeature("android.hardware.uwb").
2. Jika melakukan pengukuran terhadap perangkat IoT, pastikan perangkat tersebut mematuhi FiRa MAC 1.3.
3. Temukan perangkat peer yang kompatibel dengan UWB menggunakan mekanisme OOB pilihan Anda, seperti BluetoothLeScanner.
4. Bertukar parameter rentang menggunakan mekanisme OOB aman pilihan Anda, seperti BluetoothGatt.
5. Jika pengguna ingin menghentikan sesi, batalkan cakupan sesi.

Batasan penggunaan

Batasan berikut berlaku untuk penggunaan UWB API:

1. Aplikasi yang memulai sesi pengukuran jarak UWB baru harus berupa aplikasi atau layanan latar depan, kecuali jika pengukuran jarak latar belakang didukung seperti yang diilustrasikan sebelumnya.
2. Saat aplikasi berpindah ke latar belakang (saat sesi sedang berlangsung), aplikasi mungkin tidak lagi menerima laporan rentang. Namun, sesi UWB akan terus dipertahankan di lapisan yang lebih rendah. Saat aplikasi kembali ke latar depan, laporan rentang akan dilanjutkan.

Contoh kode

Aplikasi contoh

Untuk contoh menyeluruh tentang cara menggunakan library Jetpack UWB, lihat aplikasi contoh di GitHub. Aplikasi contoh ini mencakup validasi kompatibilitas UWB di perangkat Android, mengaktifkan proses penemuan menggunakan mekanisme OOB, dan menyiapkan UWB yang berkisar antara dua perangkat yang kompatibel dengan UWB. Contoh ini juga mencakup kasus penggunaan kontrol perangkat dan berbagi media.

Pengukuran Jarak UWB

Contoh kode ini memulai dan menghentikan pengukuran rentang UWB untuk Kontrol:

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

Dukungan RxJava3

Dukungan Rxjava3 kini tersedia untuk membantu mencapai interoperabilitas dengan klien Java. Library ini menyediakan cara untuk mendapatkan hasil rentang sebagai streaming Observable atau Flowable, dan untuk mengambil UwbClientSessionScope sebagai objek Tunggal.

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

Dukungan ekosistem

Berikut adalah perangkat partner dan SDK pihak ketiga yang didukung.

Perangkat seluler yang mendukung UWB

Mulai Januari 2025, perangkat berikut mendukung library Jetpack UWB Android:

Catatan: Pengukuran jarak UWB latar belakang didukung di semua perangkat kecuali untuk hal berikut:

• Pixel 6 Pro dan Pixel 7 Pro.
• Ponsel Samsung dengan Android 13 atau yang lebih lama.
• Ponsel Samsung China dengan Android 14 atau yang lebih lama.

SDK pihak ketiga

Mulai April 2023, solusi partner ini kompatibel dengan library Jetpack saat ini.

• UWB Development Kit Estimote.
• Mobile Knowledge MK UWB Kit Mobile Edition 2.0.

Masalah umum: urutan byte dibalik untuk alamat MAC dan kolom ID vendor STS statis

Di Android 13 dan yang lebih lama, stack UWB Android salah membalikkan urutan byte untuk kolom berikut:

• Alamat MAC perangkat
• Alamat MAC tujuan
• ID vendor STS statis

Pembalikan urutan byte terjadi karena stack Android memperlakukan kolom ini sebagai nilai, bukan array. Kami sedang bekerja sama dengan FiRa untuk memperbarui spesifikasi UCI (CR-1112) untuk secara eksplisit menyatakan bahwa kolom ini harus diperlakukan sebagai array.

Masalah ini akan diperbaiki melalui update GMS Core dalam rilis 2320XXXX. Agar mematuhi perangkat Android mulai saat itu, vendor IOT perlu mengubah implementasi Anda untuk menghindari pembalikan urutan byte kolom ini.