Rentang antar-perangkat

Android 16 (level API 36) memperkenalkan modul Pengukuran Jarak, yang menyediakan antarmuka terpadu dan standar untuk pengukuran jarak yang akurat antarperangkat. 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 pengukuran jarak

Class RangingManager memberi aplikasi informasi tentang teknologi rentang yang didukung oleh perangkat lokal, serta ketersediaan dan kemampuan setiap teknologi. Aplikasi dapat mendaftarkan antarmuka RangingCapabilitiesCallback 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 inisiator, responder, atau Tag Downlink-TDoA (DT-Tag) untuk sesi Downlink-TDoA UWB di Android 17 (API level 37) dan yang lebih tinggi. Perangkat inisiator memulai sesi pengukuran jarak dengan satu atau beberapa perangkat responder. Perangkat responder merespons permintaan pengukuran jarak hanya dari satu inisiator dalam satu waktu. Dalam sesi Downlink Time Difference of Arrival (DL-TDoA) UWB, perangkat menggunakan peran DEVICE_ROLE_DT_TAG untuk menerima sinyal dari beberapa anchor UWB. Anda dapat menentukan peran untuk perangkat tertentu dalam sesi pengukuran jarak dengan class RangingPreference.

Jenis sesi pengukuran jarak

Saat memulai sesi pengukuran jarak antarperangkat, sering kali diperlukan transportasi data out-of-band (OOB) untuk bertukar parameter untuk sesi tersebut.

Modul Pengukuran Jarak 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. API 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 spesifikasi OOB standar. Di Android 16 QPR2 (level API 36.1) dan yang lebih tinggi, inisiator dapat membatasi teknologi yang dinegosiasikan dengan memanggil setRangingTechnologyFilter di OobInitiatorRangingConfig.Builder.

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 pembentukan koneksi.

Implementasi OOB kustom

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

Preferensi rentang

Gunakan objek RangingPreference untuk menentukan parameter yang dipilih untuk sesi pengukuran jarak. Ini mencakup hal-hal berikut:

  • Peran perangkat. Ini menunjukkan apakah perangkat adalah inisiator, responder, atau DT-Tag di Android 17 (level API 37) dan yang lebih tinggi.
  • Konfigurasi pengukuran jarak. Objek RangingConfig menentukan jenis sesi rentang dan parameter lain yang diperlukan untuk memulai sesi rentang.
  • Konfigurasi sesi. Objek SessionConfig menentukan parameter yang akan diterapkan pada sesi pengukuran jarak seperti batas pengukuran, fusi sensor, konfigurasi pembatasan wilayah, dan lainnya. Di Android 17 (level API 37) dan yang lebih tinggi, Anda juga dapat mengonfigurasi mode antena (ANTENNA_MODE_DIRECTIONAL atau ANTENNA_MODE_OMNI) dengan setAntennaMode di SessionConfig.Builder setelah memeriksa mode yang didukung dengan getSupportedAntennaModes di UwbRangingCapabilities.

Izin pengukuran jarak

Modul Pengukuran Jarak menggunakan izin terpadu (android.permission.RANGING) untuk teknologi pengukuran jarak peer-to-peer. Izin ini ada dalam daftar NEARBY_DEVICES_PERMISSIONS.

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

Batas dan pembatasan

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

  • Aplikasi pihak ketiga hanya diizinkan untuk melakukan pengukuran jarak di latar belakang dengan ultra-wideband, dan hanya di perangkat yang didukung. Pengukuran jarak di latar belakang dengan teknologi lain tidak diizinkan.
  • Pengukuran jarak tidak diizinkan jika jumlah maksimum sesi pengukuran jarak serentak menurut perangkat telah tercapai.
  • Pengukuran jarak mungkin dibatasi karena masalah kondisi 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 handle perangkat, modul akan membuat sesi satu per satu untuk setiap perangkat peer yang mendukung ultra-wideband.

Melakukan sesi pengukuran jarak

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

  1. Pastikan semua perangkat menjalankan Android 16 (level API 36) dan 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 pengukuran jarak.
  6. Memulai pengukuran jarak dan terus memperoleh data pengukuran jarak.
  7. Menghentikan sesi pengukuran jarak.

Contoh kode berikut menunjukkan langkah-langkah ini untuk peran inisiator dan peran responder.

class RangingApp {

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

        // 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) ?: return null

        // 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. Ranging data is delivered asynchronously through
        // callback.onResults; call stopRanging(session) when ranging is no longer needed.
        session.start(preference)
        return session
    }

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

        // 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) ?: return null

        // 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. Call stopRanging(session) when finished.
        session.start(preference)
        return session
    }

    // Stops an active ranging session.
    fun stopRanging(session: RangingSession) {
        session.stop()
    }
}

Menangani hasil pengukuran jarak dan gerakan peer

Saat sesi aktif, RangingSession.Callback akan memberikan pengukuran jarak dan sudut kedatangan dalam objek RangingData melalui onResults:

  • Ketidakpastian jarak. Di Android 16 QPR2 (level API 36.1) dan yang lebih tinggi, panggil hasDistanceStandardDeviation dan getDistanceStandardDeviationMeters di RangingData untuk memeriksa simpangan baku pengukuran jarak jika tersedia.
  • Tambahan khusus teknologi. Di Android 17 (API level 37) dan yang lebih tinggi, panggil getRangingDataExtras di RangingData untuk mengambil objek RangingDataExtras yang berisi metadata khusus teknologi, seperti BleSpecificData, UwbSpecificData, atau WifiRttSpecificData.
  • Status gerakan pembanding. Di Android 17 (level API 37) dan yang lebih tinggi, ganti onMotionReceived di RangingSession.Callback untuk menerima update MotionState (MOTION_NOT_DETECTED, MOTION_SLIGHT, MOTION_MODERATE, atau MOTION_LARGE) saat gerakan perangkat peer berubah.

Interoperabilitas UWB dengan perangkat iOS

Modul Pengukuran Jarak mendukung interoperabilitas dengan perangkat iOS menggunakan ultra-wideband (UWB). Untuk mengukur jarak dengan perangkat iOS, Anda harus menggunakan implementasi OOB kustom dan mengonfigurasi sesi pengukuran jarak dengan parameter tertentu yang cocok dengan Apple Nearby Interaction Accessory Protocol. Untuk mengetahui contohnya, lihat aplikasi contoh.

Saat membuat RangingPreference, gunakan RawRangingDevice dan UwbRangingParams untuk menentukan konfigurasi. Parameter berikut sangat penting untuk interoperabilitas iOS:

  • ID Konfigurasi. Gunakan UwbRangingParams.CONFIG_UNICAST_DS_TWR.
  • Info Kunci Sesi. Berikan array byte yang berisi ID Vendor dan IV STS Statis.
  • Saluran Kompleks. Tetapkan nomor saluran dan indeks preamble agar sesuai dengan konfigurasi perangkat iOS.

Cuplikan kode berikut menunjukkan cara membuat RangingPreference untuk perangkat inisiator yang mengukur jarak dengan responder iOS:

// Create UwbRangingParams with iOS-specific configuration.
val uwbRangingParams = UwbRangingParams.Builder(
    sessionId,
    UwbRangingParams.CONFIG_UNICAST_DS_TWR,
    sourceAddress,
    destinationAddress
)
    .setComplexChannel(
        UwbComplexChannel.Builder()
            .setChannel(channelNumber)
            .setPreambleIndex(preambleIndex)
            .build()
    )
    .setRangingUpdateRate(updateRate)
    .setSessionKeyInfo(sessionKeyInfo) // Vendor ID + STS IV
    .setSlotDuration(slotDuration)
    .build()

// Create RawRangingDevice.
val rawRangingDevice = RawRangingDevice.Builder()
    .setRangingDevice(RangingDevice.Builder().build())
    .setUwbRangingParams(uwbRangingParams)
    .build()

// Create SessionConfig.
val sessionConfig = SessionConfig.Builder()
    .setAngleOfArrivalNeeded(true)
    .setDataNotificationConfig(
        DataNotificationConfig.Builder()
            .setNotificationConfigType(DataNotificationConfig.NOTIFICATION_CONFIG_ENABLE)
            .build()
    )
    .build()

// Create RangingPreference for the initiator.
val preference = RangingPreference.Builder(
    RangingPreference.DEVICE_ROLE_INITIATOR,
    RawInitiatorRangingConfig.Builder()
        .addRawRangingDevice(rawRangingDevice)
        .build()
)
    .setSessionConfig(sessionConfig)
    .build()

UWB Downlink-TDoA API

Di Android 17 (level API 37) dan yang lebih tinggi, pengukuran jarak Downlink Time Difference of Arrival (DL-TDoA) memungkinkan perangkat menentukan posisinya relatif terhadap beberapa anchor UWB dengan mengukur waktu kedatangan relatif sinyal.

Cuplikan berikut menunjukkan cara menggunakan RangingManager untuk memverifikasi dukungan DL-TDoA, mengonfigurasi DlTdoaRangingParams dan RawDtTagRangingConfig untuk memulai sesi, dan menerima hasil DlTdoaMeasurement:

class RangingApp {

    fun initDlTdoa(context: Context) {
        // Initialize the Ranging Manager.
        val rangingManager = context.getSystemService(RangingManager::class.java)

        // Register for device capabilities.
        val capabilitiesCallback = object : RangingManager.RangingCapabilitiesCallback {
            override fun onRangingCapabilities(capabilities: RangingCapabilities) {
                // Make sure DL-TDoA is supported before starting the session.
                if (capabilities.uwbCapabilities?.isDlTdoaSupported == true) {
                    startDlTDoASession(context)
                }
            }
        }
        rangingManager.registerCapabilitiesCallback(Executors.newSingleThreadExecutor(), capabilitiesCallback)
    }

    fun startDlTDoASession(context: Context) {
        // Initialize the Ranging Manager.
        val rangingManager = context.getSystemService(RangingManager::class.java)

        // Create session and configure parameters.
        val executor = Executors.newSingleThreadExecutor()
        val rangingSession = rangingManager.createRangingSession(executor, RangingSessionCallback())
        val rangingRoundIndexes = byteArrayOf(0)
        val config: ByteArray = byteArrayOf() // OOB config data
        val params = DlTdoaRangingParams.createFromFiraConfigPacket(config, rangingRoundIndexes)

        val rangingDevice = RangingDevice.Builder().build()
        val rawTagDevice = RawRangingDevice.Builder()
            .setRangingDevice(rangingDevice)
            .setDlTdoaRangingParams(params)
            .build()

        val dtTagConfig = RawDtTagRangingConfig.Builder(rawTagDevice).build()

        val preference = RangingPreference.Builder(DEVICE_ROLE_DT_TAG, dtTagConfig)
            .setSessionConfig(SessionConfig.Builder().build())
            .build()

        // Start the ranging session.
        rangingSession?.start(preference)
    }
}

private class RangingSessionCallback : RangingSession.Callback {
    override fun onDlTdoaResults(peer: RangingDevice, measurement: DlTdoaMeasurement) {
        // Process measurement results here.
    }

    override fun onOpened() {
        // ...
    }

    override fun onOpenFailed(reason: Int) {
        // ...
    }

    override fun onStarted(peer: RangingDevice, technology: Int) {
        // ...
    }

    override fun onStopped(peer: RangingDevice, technology: Int) {
        // ...
    }

    override fun onResults(peer: RangingDevice, data: RangingData) {
        // ...
    }

    override fun onClosed(reason: Int) {
        // ...
    }
}

Konfigurasi out-of-band (OOB)

Cuplikan berikut memberikan contoh data konfigurasi OOB DL-TDoA untuk Wi-Fi dan BLE:

// Wi-Fi Configuration (Vendor-Specific IE, FiRa CID 0x5A18FF, Config 0)
val wifiConfig = byteArrayOf(
    0xDD.toByte(), 0x30, 0x5A, 0x18, 0xFF.toByte(), // Wi-Fi VSE Header
    0x5F, 0x1C, // UWB Configuration Sub-Element
    0x02, 0x00, // Profile ID (Untracked Navigation), Config ID 0
    0x06, 0x02, 0x20, 0x08, // Device MAC Address
    0x14, 0x01, 0x0A, // Preamble Code Index (10)
    0x27, 0x02, 0x08, 0x07, // Vendor ID
    0x28, 0x06, 0xA1.toByte(), 0xB2.toByte(), 0xC3.toByte(), 0xD4.toByte(), 0xE5.toByte(), 0xF6.toByte(), // Static STS IV
    0x08, 0x02, 0x60, 0x09, // Slot Duration (2400 RSTU = 2 ms)
    0x1B, 0x01, 0x0A, // Slots per Ranging Round (10)
    0x09, 0x04, 0xFA.toByte(), 0x00, 0x00, 0x00, // Ranging Duration (250 ms)
    0x52, 0x01, 0x00, // Initiator DT-Anchor Round Index (0)
    0x9F.toByte(), 0x04, 0xAA.toByte(), 0xBB.toByte(), 0xCC.toByte(), 0xDD.toByte() // Session ID (0xDDCCBBAA)
)

// BLE Configuration (ADV_NONCONN_IND Service Data UUID 0xFFF3, Config 0)
val bleConfig = byteArrayOf(
    0x1E, 0x16, 0xF3.toByte(), 0xFF.toByte(), // BLE Service Data Header
    0xF0.toByte(), // Fragment Indication Sub-Element (unfragmented)
    0x5F, 0x09, // UWB Configuration Sub-Element
    0x02, 0x00, // Profile ID (Untracked Navigation), Config ID 0
    0x06, 0x02, 0x20, 0x08, // Device MAC Address
    0x27, 0x02, 0x08, 0x07, // Vendor ID
    0x28, 0x06, 0xA1.toByte(), 0xB2.toByte(), 0xC3.toByte(), 0xD4.toByte(), 0xE5.toByte(), 0xF6.toByte(), // Static STS IV
    0x9F.toByte(), 0x04, 0xAA.toByte(), 0xBB.toByte(), 0xCC.toByte(), 0xDD.toByte() // Session ID (0xDDCCBBAA)
)

Jika Anda tidak dapat menggunakan konfigurasi OOB karena tidak ada, atau jika Anda perlu mengubah nilai default yang tidak ada dalam konfigurasi OOB, Anda dapat membuat parameter dengan DlTdoaRangingParams.Builder, bukan memanggil DlTdoaRangingParams.createFromFiraConfigPacket:

val dlTdoaParams = DlTdoaRangingParams.Builder(1)
    .setComplexChannel(
        UwbComplexChannel.Builder()
            .setChannel(9).setPreambleIndex(10).build()
    )
    .setDeviceAddress(deviceAddress)
    .setSessionKeyInfo(byteArrayOf(0x01, 0x02, 0x03, 0x04))
    .setRangingIntervalMillis(240)
    .setSlotDuration(UwbRangingParams.DURATION_2_MS)
    .setSlotsPerRangingRound(20)
    .setRangingRoundIndexes(byteArrayOf(0x01, 0x05))
    .build()

Aplikasi contoh

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

Interoperabilitas UWB dengan perangkat iOS

Aplikasi contoh Android mendukung memulai sesi pengukuran jarak UWB dengan aplikasi contoh iOS.

Gambar 2. Penggunaan UWB Android dan iOS.