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:
- Ultra-wideband
- Suara saluran Bluetooth
- RTT NAN Wi-Fi
- Rentang RSSI Bluetooth
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.

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:
- Pastikan semua perangkat beroperasi di Android 16 atau yang lebih baru.
- Minta izin
android.permission.RANGING
dalam manifes aplikasi. - Menilai kemampuan dan ketersediaan teknologi pengukuran jarak.
- Menemukan perangkat peer untuk operasi rentang.
- Buat koneksi untuk pertukaran out-of-band, menggunakan salah satu jenis sesi yang dijelaskan dalam Jenis sesi rentang.
- Memulai pengukuran jarak dan terus memperoleh data pengukuran jarak.
- 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.