Rentang antar-perangkat

Android 16 memperkenalkan modul Rentang, yang menyediakan antarmuka terpadu dan standar untuk pengukuran jarak yang akurat antar-perangkat. Anda dapat menggunakan platform API ini untuk mengukur jarak dan posisi perangkat peer tanpa perlu menangani setiap teknologi pengukuran jarak satu per satu.

Modul Pengukuran Jarak mendukung teknologi berikut:

Kemampuan dan ketersediaan rentang

Class RangingManager memberi aplikasi informasi tentang teknologi rentang yang didukung oleh perangkat lokal, serta ketersediaan dan kemampuan setiap teknologi. Aplikasi dapat mendaftar ke Callback untuk menerima update tentang perubahan apa pun pada ketersediaan atau kemampuan teknologi yang didukung.

Peran perangkat

Perangkat yang berpartisipasi dalam sesi pengukuran jarak harus berupa pemicu atau perespons. Perangkat inisiator memulai sesi pengukuran jarak dengan satu atau beberapa perangkat responden. Perangkat responden merespons permintaan rentang dari hanya satu pemicu dalam satu waktu. Anda dapat menentukan peran untuk perangkat tertentu dalam sesi pengukuran jarak dengan class RangingPreference.

Jenis sesi rentang

Saat memulai sesi pengukuran jarak antara perangkat, sering kali perlu membangun transpor data out-of-band (OOB) untuk bertukar parameter untuk sesi.

Modul Rentang dapat menangani negosiasi OOB untuk Anda, tetapi juga mendukung implementasi OOB kustom.

Gambar 1. Alur OOB untuk jenis sesi.

Implementasi OOB default

Dalam jenis sesi ini (RANGING_SESSION_OOB), modul Pengukuran jarak menangani negosiasi OOB untuk memulai sesi pengukuran jarak. Fitur ini memilih parameter yang sesuai berdasarkan preferensi rentang yang disediakan oleh aplikasi, dan menggunakan teknologi yang sesuai berdasarkan dukungan kedua perangkat. Jenis sesi ini menggunakan OOB specification standar.

Modul Pengukuran Jarak hanya menentukan format dan urutan data OOB yang akan digunakan untuk berinteraksi dengan perangkat peer. API ini tidak menangani penemuan perangkat peer atau pembuatan koneksi.

Implementasi OOB kustom

Dalam jenis sesi ini (RANGING_SESSION_RAW), aplikasi mengabaikan alur OOB modul Pengukuran Jarak dan menangani negosiasi serta parameter OOB-nya sendiri. Artinya, aplikasi harus menentukan teknologi yang didukung perangkat peer, melakukan negosiasi parameter pengukuran jarak, dan memulai sesi pengukuran jarak.

Preferensi rentang

Gunakan objek RangingPreference untuk menentukan parameter yang diinginkan untuk sesi pengukuran rentang. Hal tersebut meliputi:

  • Peran perangkat. Ini menunjukkan apakah perangkat akan menjadi inisiator atau responder.
  • Konfigurasi rentang. Objek RangingConfig menentukan jenis sesi pengukuran jarak dan parameter lain yang diperlukan untuk memulai sesi pengukuran jarak.
  • Konfigurasi sesi. Objek SessionConfig menentukan parameter yang akan diterapkan pada sesi pengukuran seperti batas pengukuran, fusi sensor, konfigurasi pembatasan wilayah, dan lainnya.

Izin rentang

Modul Pengukuran Jarak memerlukan izin terpadu baru (android.permission.RANGING) untuk mengakses semua teknologi pengukuran jarak saat ini dan mendatang. Izin ini ada dalam daftar NEARBY_DEVICES_PERMISSIONS.

<uses-permission android:name="android.permission.RANGING" />

Larangan dan batasan

Modul Pengukuran Jarak mungkin membatasi pengukuran jarak karena beberapa alasan, termasuk hal berikut:

  • Aplikasi pihak ketiga hanya diizinkan untuk melakukan pengukuran latar belakang dengan ultra-wideband, dan hanya di perangkat yang didukung. Pengukuran rentang di latar belakang dengan teknologi lain tidak diizinkan.
  • Pengukuran rentang tidak diizinkan jika jumlah maksimum sesi pengukuran rentang serentak per perangkat telah tercapai.
  • Pengukuran rentang mungkin dibatasi karena masalah kesehatan sistem seperti baterai, performa, atau memori.

Modul Pengukuran Jarak juga memiliki batasan umum berikut:

  • Modul Pengukuran Jarak hanya mendukung pengiriman data pengukuran jarak ke perangkat peer untuk ultra-wideband. Untuk teknologi lain, modul Pengukuran Jarak hanya mengirimkan data pengukuran jarak ke perangkat inisiator.
  • Modul Pengukuran Jarak hanya mendukung penambahan perangkat secara dinamis dalam mode pengukuran jarak mentah, dan hanya untuk ultra-wideband.
  • Modul Pengukuran Jarak tidak mendukung sesi ultra-wideband one-to-many untuk implementasi OOB default. Jika Anda meneruskan beberapa nama sebutan perangkat, modul akan membuat sesi satu lawan satu untuk setiap perangkat peer yang mendukung ultra-wideband.

Melakukan sesi pengukuran rentang

Untuk melakukan sesi pengukuran jarak menggunakan modul Pengukuran Jarak, ikuti langkah-langkah berikut:

  1. Pastikan semua perangkat beroperasi di Android 16 atau yang lebih baru.
  2. Minta izin android.permission.RANGING dalam manifes aplikasi.
  3. Menilai kemampuan dan ketersediaan teknologi pengukuran jarak.
  4. Menemukan perangkat peer untuk operasi rentang.
  5. Buat koneksi untuk pertukaran out-of-band, menggunakan salah satu jenis sesi yang dijelaskan dalam Jenis sesi rentang.
  6. Memulai pengukuran jarak dan terus memperoleh data pengukuran jarak.
  7. Menghentikan sesi pengukuran rentang.

Contoh kode berikut menunjukkan langkah-langkah ini untuk peran pemicu dan peran responden.

Kotlin

class RangingApp {

    // Starts a ranging session on the initiator side.
    fun startRangingInitiator(
        context: Context,
        deviceHandle: DeviceHandle,
        executor: Executor,
        callback: RangingSessionCallback
    ) {

        // Get the RangingManager which is the entry point for ranging module.
        val manager = context.getSystemService(RangingManager::class.java)

        // Create a new RangingSession using the provided executor and callback.
        val session = manager.createRangingSession(executor, callback)

        // Create an OobInitiatorRangingConfig, which specifies the ranging parameters for
        // the initiator role.
        val config = OobInitiatorRangingConfig.Builder()
            .setFastestRangingInterval(Duration.ofMillis(100))
            .setSlowestRangingInterval(Duration.ofMillis(5000))
            .setRangingMode(RANGING_MODE_AUTO)
            .setSecurityLevel(SECURITY_LEVEL_BASIC)
            .addDeviceHandle(deviceHandle)
            .build()

        // Create a RangingPreference, which specifies the role (initiator) and
        // configuration for the ranging session.
        val preference =
            RangingPreference.Builder(DEVICE_ROLE_INITIATOR, config).build()

        // Start ranging session.
        session.start(preference)

        // If successful, the ranging data will be sent through callback#onResults

        // Stop ranging session
        session.stop()
    }

    // Starts a ranging session on the responder side.
    fun startRangingResponder(
        context: Context,
        deviceHandle: DeviceHandle,
        executor: Executor,
        callback: RangingSessionCallback
    ) {

        // Get the RangingManager which is the entry point for ranging module.
        val manager = context.getSystemService(RangingManager::class.java)

        // Create a new RangingSession using the provided executor and callback.
        val session = manager.createRangingSession(executor, callback)

        // Create an OobResponderRangingConfig, which specifies the ranging parameters for
        // the responder role.
        val config = OobResponderRangingConfig.Builder(deviceHandle).build()

        // Create a RangingPreference, which specifies the role (responder) and
        // configuration for the ranging session.
        val preference =
            RangingPreference.Builder(DEVICE_ROLE_RESPONDER, config).build()

        // Start the ranging session.
        session.start(preference)

        // Stop the ranging session
        session.stop()
    }
}

Java

public class RangingApp {

    // Starts a ranging session on the initiator side.
    void startRangingInitiator(Context context, DeviceHandle deviceHandle, Executor executor, RangingSessionCallback callback) {

        // Get the RangingManager which is the entry point for ranging module.
        RangingManager manager = context.getSystemService(RangingManager.class);

        // Create a new RangingSession using the provided executor and callback.
        RangingSession session = manager.createRangingSession(executor, callback);

        // Create an OobInitiatorRangingConfig, which specifies the ranging parameters for
        // the initiator role.
        OobInitiatorRangingConfig config = new OobInitiatorRangingConfig.Builder()
                .setFastestRangingInterval(Duration.ofMillis(100))
                .setSlowestRangingInterval(Duration.ofMillis(5000))
                .setRangingMode(RANGING_MODE_AUTO)
                .setSecurityLevel(SECURITY_LEVEL_BASIC)
                .addDeviceHandle(deviceHandle)
                .build();

        // Create a RangingPreference, which specifies the role (initiator) and
        // configuration for the ranging session.
        RangingPreference preference =
                new RangingPreference.Builder(DEVICE_ROLE_INITIATOR, config).build();

        // Start ranging session.
        session.start(preference);

        // If successful, the ranging data will be sent through callback#onResults

        // Stop ranging session
        session.stop();

    }

    // Starts a ranging session on the responder side.
    void startRangingResponder(Context context,  DeviceHandle deviceHandle, Executor executor, RangingSessionCallback callback) {

        // Get the RangingManager which is the entry point for ranging module.
        RangingManager manager = context.getSystemService(RangingManager.class);

        // Create a new RangingSession using the provided executor and callback.
        RangingSession session = manager.createRangingSession(executor, callback);

        // Create an OobResponderRangingConfig, which specifies the ranging parameters for
        // the responder role.
        OobResponderRangingConfig config = new OobResponderRangingConfig.Builder(  deviceHandle).build();

        // Create a RangingPreference, which specifies the role (responder) and
        // configuration for the ranging session.
        RangingPreference preference =
                new RangingPreference.Builder(DEVICE_ROLE_RESPONDER, config).build();

        // Start the ranging session.
        session.start(preference);

        // Stop the ranging session
        session.stop();
    }
}

Aplikasi contoh

Untuk contoh menyeluruh tentang cara menggunakan modul Rentang, lihat aplikasi contoh di AOSP. Aplikasi contoh ini mencakup semua teknologi pengukuran jarak yang didukung oleh modul Pengukuran Jarak dan menyertakan alur untuk kedua jenis sesi yang didukung.