Android 16 memperkenalkan modul Ranging, yang menyediakan antarmuka terpadu dan standar untuk rentang yang akurat antar-perangkat. Anda dapat menggunakan platform API ini untuk mengukur jarak dan posisi perangkat peer tanpa perlu menangani setiap teknologi rentang secara terpisah.
Modul Ranging mendukung teknologi berikut:
- Ultra-wideband
- Channel sounding Bluetooth
- Wi-Fi NAN RTT
- 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 rentang harus berupa inisiasi atau responden. Perangkat inisiasi memulai sesi rentang dengan satu atau beberapa perangkat responden. Perangkat responden merespons permintaan rentang dari hanya satu inisiasi dalam satu waktu. Anda dapat menentukan peran untuk perangkat tertentu dalam sesi rentang
dengan class RangingPreference.
Jenis sesi rentang
Saat memulai sesi rentang antar-perangkat, sering kali perlu membuat transportasi data di luar band (OOB) untuk bertukar parameter sesi.
Modul Ranging dapat menangani negosiasi OOB untuk Anda, tetapi juga mendukung implementasi OOB kustom.
Implementasi OOB default
Dalam jenis sesi ini (RANGING_SESSION_OOB), modul Ranging menangani
negosiasi OOB untuk memulai sesi rentang. Modul ini memilih parameter yang sesuai berdasarkan preferensi rentang yang diberikan oleh aplikasi, dan menggunakan teknologi yang sesuai berdasarkan apa yang didukung oleh kedua perangkat. Jenis sesi ini
menggunakan OOB specificationstandar.
Modul Ranging hanya menentukan format dan urutan data OOB yang akan digunakan untuk berinteraksi dengan perangkat peer. Modul ini tidak menangani penemuan perangkat peer atau pembuatan koneksi.
Implementasi OOB kustom
Dalam jenis sesi ini (RANGING_SESSION_RAW), aplikasi melewati alur OOB modul Ranging
dan menangani negosiasi serta parameter OOB-nya sendiri. Artinya, aplikasi harus menentukan teknologi mana yang didukung perangkat peer, menegosiasikan parameter rentang, dan memulai sesi rentang.
Preferensi rentang
Gunakan objek RangingPreference untuk menentukan parameter yang dipilih untuk sesi rentang. Hal ini mencakup hal-hal berikut:
- Peran perangkat. Hal ini menunjukkan apakah perangkat akan menjadi inisiasi atau responden.
- Konfigurasi rentang. Objek
RangingConfigmenentukan jenis sesi rentang dan parameter lain yang diperlukan untuk memulai sesi rentang. - Konfigurasi sesi. Objek
SessionConfigmenentukan parameter yang akan diterapkan pada sesi rentang seperti batas pengukuran, fusi sensor, konfigurasi geofence, dan lainnya.
Izin rentang
Modul Ranging memerlukan izin terpadu baru (android.permission.RANGING) untuk mengakses semua teknologi rentang saat ini dan mendatang. Izin ini ada dalam daftar NEARBY_DEVICES_PERMISSIONS.
<uses-permission android:name="android.permission.RANGING" />
Batas dan pembatasan
Modul Ranging mungkin membatasi rentang karena beberapa alasan, termasuk hal berikut:
- Aplikasi pihak ketiga hanya diizinkan untuk melakukan rentang latar belakang dengan ultra-wideband, dan hanya pada perangkat yang didukung. Rentang di latar belakang dengan teknologi lain tidak diizinkan.
- Rentang tidak diizinkan jika jumlah maksimum sesi rentang serentak menurut perangkat telah tercapai.
- Rentang mungkin dibatasi karena masalah kesehatan sistem seperti baterai, performa, atau memori.
Modul Ranging juga memiliki batasan umum berikut:
- Modul Ranging hanya mendukung pengiriman data rentang ke perangkat peer untuk ultra-wideband. Untuk teknologi lain, modul Ranging hanya mengirimkan data rentang ke perangkat inisiasi.
- Modul Ranging hanya mendukung penambahan perangkat dinamis dalam mode rentang mentah, dan hanya untuk ultra-wideband.
- Modul Ranging tidak mendukung sesi ultra-wideband one-to-many untuk implementasi OOB default. Jika Anda meneruskan beberapa pengendali perangkat, modul akan membuat sesi one-to-one untuk setiap perangkat peer yang mendukung ultra-wideband.
Melakukan sesi rentang
Untuk melakukan sesi rentang menggunakan modul Ranging, ikuti langkah-langkah berikut:
- Pastikan semua perangkat beroperasi di Android 16 atau yang lebih tinggi.
- Minta
android.permission.RANGINGizin dalam manifes aplikasi. - Nilai kemampuan dan ketersediaan teknologi rentang.
- Temukan perangkat peer untuk operasi rentang.
- Buat koneksi untuk pertukaran di luar band, menggunakan salah satu dari jenis sesi yang dijelaskan dalam Jenis sesi rentang.
- Mulai rentang dan terus dapatkan data rentang.
- Hentikan sesi rentang.
Contoh kode berikut menunjukkan langkah-langkah ini untuk peran inisiasi 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();
}
}
Interoperabilitas UWB dengan perangkat iOS
Modul Ranging mendukung interoperabilitas dengan perangkat iOS menggunakan ultra-wideband (UWB). Untuk melakukan rentang dengan perangkat iOS, Anda harus menggunakan implementasi OOB kustom dan mengonfigurasi sesi rentang dengan parameter tertentu yang cocok dengan Protokol Aksesori Interaksi Terdekat Apple. Lihat aplikasi contoh untuk referensi.
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 STS IV Statis.
- Saluran Kompleks: Tetapkan nomor saluran dan indeks preamble agar sesuai dengan konfigurasi perangkat iOS.
Cuplikan kode berikut menunjukkan cara membuat RangingPreference untuk perangkat inisiasi yang melakukan rentang dengan responden iOS:
Kotlin
// 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()
Java
// Create UwbRangingParams with iOS-specific configuration
UwbRangingParams uwbRangingParams = new UwbRangingParams.Builder(
sessionId,
UwbRangingParams.CONFIG_UNICAST_DS_TWR,
sourceAddress,
destinationAddress)
.setComplexChannel(new UwbComplexChannel.Builder()
.setChannel(channelNumber)
.setPreambleIndex(preambleIndex)
.build())
.setRangingUpdateRate(updateRate)
.setSessionKeyInfo(sessionKeyInfo) // Vendor ID + STS IV
.setSlotDuration(slotDuration)
.build();
// Create RawRangingDevice
RawRangingDevice rawRangingDevice = new RawRangingDevice.Builder()
.setRangingDevice(new RangingDevice.Builder().build())
.setUwbRangingParams(uwbRangingParams)
.build();
// Create SessionConfig
SessionConfig sessionConfig = new SessionConfig.Builder()
.setAngleOfArrivalNeeded(true)
.setDataNotificationConfig(new DataNotificationConfig.Builder()
.setNotificationConfigType(DataNotificationConfig.NOTIFICATION_CONFIG_ENABLE)
.build())
.build();
// Create RangingPreference for the initiator
RangingPreference preference = new RangingPreference.Builder(
RangingPreference.DEVICE_ROLE_INITIATOR,
new RawInitiatorRangingConfig.Builder()
.addRawRangingDevice(rawRangingDevice)
.build())
.setSessionConfig(sessionConfig)
.build();
UWB Downlink-TDoA API
Untuk UWB DL-TDoA API, lihat fitur baru Android 17.
Aplikasi contoh
Untuk contoh end-to-end cara menggunakan modul Ranging, lihat aplikasi contoh di AOSP. Aplikasi contoh ini mencakup semua teknologi rentang yang didukung oleh modul Ranging dan menyertakan alur untuk kedua jenis sesi yang didukung.
Interoperabilitas UWB dengan perangkat iOS
Aplikasi contoh Android mendukung memulai sesi rentang UWB dengan aplikasi contoh iOS.