Lokasi Wi-Fi: ranging dengan RTT

Anda dapat menggunakan fungsi lokasi Wi-Fi yang disediakan oleh Wi-Fi RTT (Round-Trip-Time) API untuk mengukur jarak ke titik akses Wi-Fi berkemampuan RTT terdekat dan perangkat Wi-Fi Aware peer.

Jika Anda mengukur jarak ke tiga titik akses atau lebih, Anda dapat menggunakan algoritme multilaterasi untuk memperkirakan posisi perangkat yang paling sesuai dengan pengukuran tersebut. Hasilnya biasanya akurat dalam 1-2 meter.

Dengan keakuratan ini, Anda dapat mengembangkan layanan berdasarkan lokasi yang sangat akurat, seperti navigasi dalam ruangan, kontrol suara yang diperjelas (misalnya, "Nyalakan lampu ini"), dan informasi berdasarkan lokasi (misalnya, "Apakah ada penawaran spesial untuk produk ini?").

Perangkat yang melakukan permintaan tidak perlu terhubung ke titik akses untuk mengukur jarak dengan Wi-Fi RTT. Untuk menjaga privasi, hanya perangkat yang meminta yang dapat menentukan jarak ke titik akses; titik akses tidak memiliki informasi ini. Operasi Wi-Fi RTT tidak terbatas untuk aplikasi latar depan tetapi dibatasi untuk aplikasi latar belakang.

Wi-Fi RTT dan kemampuan terkait Fine-Time-Measurement (FTM) ditentukan oleh standar IEEE 802.11-2016. Wi-Fi RTT memerlukan pengukuran waktu yang tepat yang disediakan oleh FTM karena menghitung jarak antara dua perangkat dengan mengukur waktu yang dibutuhkan paket untuk melakukan perjalanan bolak-balik antara perangkat dan mengalikan waktu itu dengan kecepatan cahaya.

Android 15 (level API 35) memperkenalkan dukungan untuk pengukuran jarak berbasis non-trigger (NTB) IEEE 802.11az.

Perbedaan implementasi berdasarkan versi Android

Wi-Fi RTT diperkenalkan di Android 9 (API level 28). Saat menggunakan protokol ini untuk menentukan posisi perangkat menggunakan multilaterasi dengan perangkat yang menjalankan Android 9, Anda harus memiliki akses ke data lokasi titik akses (AP) yang telah ditentukan sebelumnya di aplikasi. Anda bebas menentukan cara menyimpan dan mengambil data ini.

Pada perangkat yang menjalankan Android 10 (API level 29) dan lebih tinggi, data lokasi AP dapat direpresentasikan sebagai objek ResponderLocation, yang mencakup lintang, bujur, dan ketinggian. Untuk AP Wi-Fi RTT yang mendukung Location Configuration Information/Location Civic Report (data LCI/LCR), protokol akan menampilkan objek ResponderLocation selama proses ranging.

Fitur ini memungkinkan aplikasi meminta AP untuk menanyakan posisi mereka secara langsung tanpa perlu menyimpan informasi ini sebelumnya. Jadi, aplikasi Anda dapat menemukan AP dan menentukan posisi mereka meskipun AP tidak diketahui sebelumnya, seperti ketika pengguna memasuki gedung baru.

Dukungan pengukuran jarak NTB IEEE 802.11az tersedia di perangkat yang menjalankan Android 15 (level API 35) dan yang lebih tinggi. Artinya, jika perangkat mendukung mode inisiator NTB IEEE 802.11az (ditunjukkan oleh WifiRttManager.CHARACTERISTICS_KEY_BOOLEAN_NTB_INITIATOR), aplikasi Anda dapat menemukan AP yang kompatibel dengan IEEE 802.11mc dan IEEE 802.11az dengan satu permintaan rentang. RangingResult API telah diperluas untuk memberikan informasi tentang nilai minimum dan maksimum yang dapat digunakan untuk interval antara pengukuran rentang, sehingga interval yang tepat tetap berada dalam kontrol aplikasi Anda.

Persyaratan

• Hardware perangkat yang membuat permintaan pengukuran jarak harus menerapkan standar FTM 802.11-2016 atau standar 802.11az (pengukuran jarak berbasis non-pemicu).
• Perangkat yang membuat permintaan ranging harus menjalankan Android 9 (API level 28) atau yang lebih baru. Pengukuran berbasis non-pemicu IEEE 802.11az diaktifkan di perangkat yang menjalankan Android 15 (level API 35) dan yang lebih tinggi.
• Perangkat yang membuat permintaan ranging harus mengaktifkan layanan lokasi dan pemindaian Wi-Fi (dalam Setelan > Lokasi).
• Jika aplikasi yang membuat permintaan pengukuran jarak menargetkan Android 13 (level API 33) atau yang lebih tinggi, aplikasi tersebut harus memiliki izin NEARBY_WIFI_DEVICES. Jika aplikasi tersebut menargetkan Android versi yang lebih lama, aplikasi tersebut harus memiliki izin ACCESS_FINE_LOCATION sebagai gantinya.
• Aplikasi harus meminta rentang titik akses saat aplikasi terlihat atau ada di layanan latar depan. Aplikasi tidak dapat mengakses informasi lokasi dari latar belakang.
• Titik akses harus menerapkan standar FTM IEEE 802.11-2016 atau standar IEEE 802.11az (ranging berbasis non-pemicu).

Penyiapan

Untuk menyiapkan aplikasi Anda menggunakan Wi-Fi RTT, lakukan langkah-langkah berikut.

1. Minta izin

Minta izin berikut dalam manifes aplikasi Anda:

<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.CHANGE_WIFI_STATE" />
<!-- If your app targets Android 13 (API level 33)
     or higher, you must declare the NEARBY_WIFI_DEVICES permission. -->
<uses-permission android:name="android.permission.NEARBY_WIFI_DEVICES"
                 <!-- If your app derives location information from Wi-Fi APIs,
                      don't include the "usesPermissionFlags" attribute. -->
                 android:usesPermissionFlags="neverForLocation" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"
                 <!-- If any feature in your app relies on precise location
                      information, don't include the "maxSdkVersion"
                      attribute. -->
                 android:maxSdkVersion="32" />

Izin NEARBY_WIFI_DEVICES dan ACCESS_FINE_LOCATION adalah izin berbahaya, jadi Anda harus memintanya saat waktu proses setiap kali pengguna ingin melakukan operasi pemindaian RTT. Aplikasi Anda perlu meminta izin pengguna jika izin belum diberikan. Untuk mengetahui informasi selengkapnya tentang izin runtime, lihat Meminta Izin Aplikasi.

2. Periksa apakah perangkat mendukung Wi-Fi RTT

Untuk memeriksa apakah perangkat mendukung Wi-Fi RTT, gunakan PackageManager API:

context.packageManager.hasSystemFeature(PackageManager.FEATURE_WIFI_RTT)

context.getPackageManager().hasSystemFeature(PackageManager.FEATURE_WIFI_RTT);

3. Periksa apakah Wi-Fi RTT tersedia

Wi-Fi RTT mungkin ada di perangkat, tetapi mungkin tidak tersedia karena pengguna telah menonaktifkan Wi-Fi. Bergantung pada kemampuan hardware dan firmware, beberapa perangkat mungkin tidak mendukung Wi-Fi RTT jika SoftAP atau tethering sedang digunakan. Untuk memeriksa apakah Wi-Fi RTT tersedia, panggil isAvailable().

Ketersediaan Wi-Fi RTT dapat berubah kapan saja. Aplikasi Anda harus mendaftarkan BroadcastReceiver untuk menerima ACTION_WIFI_RTT_STATE_CHANGED, yang dikirim saat ketersediaan berubah. Ketika aplikasi Anda menerima intent siaran, aplikasi harus memeriksa kondisi ketersediaan saat ini dan menyesuaikan perilakunya dengan sesuai.

Contoh:

val filter = IntentFilter(WifiRttManager.ACTION_WIFI_RTT_STATE_CHANGED)
val myReceiver = object: BroadcastReceiver() {

    override fun onReceive(context: Context, intent: Intent) {
        if (wifiRttManager.isAvailable) {
            …
        } else {
            …
        }
    }
}
context.registerReceiver(myReceiver, filter)

IntentFilter filter =
    new IntentFilter(WifiRttManager.ACTION_WIFI_RTT_STATE_CHANGED);
BroadcastReceiver myReceiver = new BroadcastReceiver() {
    @Override
    public void onReceive(Context context, Intent intent) {
        if (wifiRttManager.isAvailable()) {
            …
        } else {
            …
        }
    }
};
context.registerReceiver(myReceiver, filter);

Untuk informasi selengkapnya, lihat Siaran.

Membuat permintaan ranging

Permintaan pengukuran jarak (RangingRequest) dibuat dengan menentukan daftar AP atau perangkat Wi-Fi Aware yang dimintai pengukuran jarak. Beberapa titik akses atau peer Wi-Fi Aware dapat ditentukan dalam satu permintaan ranging; jarak ke semua perangkat diukur dan dikembalikan.

Misalnya, permintaan dapat menggunakan metode addAccessPoint() untuk menentukan titik akses guna mengukur jarak:

val req: RangingRequest = RangingRequest.Builder().run {
    addAccessPoint(ap1ScanResult)
    addAccessPoint(ap2ScanResult)
    build()
}

RangingRequest.Builder builder = new RangingRequest.Builder();
builder.addAccessPoint(ap1ScanResult);
builder.addAccessPoint(ap2ScanResult);

RangingRequest req = builder.build();

Titik akses diidentifikasi oleh objek ScanResult, yang dapat diperoleh dengan memanggil WifiManager.getScanResults(). Anda dapat menggunakan addAccessPoints(List<ScanResult>) untuk menambahkan beberapa titik akses dalam batch.

Objek ScanResult dapat berisi titik akses yang mendukung IEEE 802.11mc (is80211mcResponder()) dan IEEE 802.11az non-trigger based ranging (is80211azNtbResponder()). Perangkat yang mendukung pengukuran jarak NTB IEEE 802.11az melakukan pengukuran jarak 802.11mc atau 802.11az, bergantung pada kemampuan AP, dengan default ke 802.11az jika AP mendukung keduanya. Perangkat yang tidak mendukung IEEE 802.11az melakukan semua pengukuran jarak menggunakan protokol IEEE 802.11mc.

Demikian pula, permintaan pengukuran jarak dapat menambahkan peer Wi-Fi Aware menggunakan alamat MAC atau PeerHandle, menggunakan metode addWifiAwarePeer(MacAddress peer) dan addWifiAwarePeer(PeerHandle peer), secara berturut-turut. Untuk informasi selengkapnya tentang menemukan peer Wi-Fi Aware, lihat dokumentasi Wi-Fi Aware.

Permintaan ranging

Aplikasi mengeluarkan permintaan pengukuran jarak menggunakan metode WifiRttManager.startRanging() dan menyediakan hal berikut: RangingRequest untuk menentukan operasi, Executor untuk menentukan konteks callback, dan RangingResultCallback untuk menerima hasil.

Contoh:

val mgr = context.getSystemService(Context.WIFI_RTT_RANGING_SERVICE) as WifiRttManager
val request: RangingRequest = myRequest
mgr.startRanging(request, executor, object : RangingResultCallback() {

    override fun onRangingResults(results: List<RangingResult>) { … }

    override fun onRangingFailure(code: Int) { … }
})

WifiRttManager mgr =
      (WifiRttManager) Context.getSystemService(Context.WIFI_RTT_RANGING_SERVICE);

RangingRequest request ...;
mgr.startRanging(request, executor, new RangingResultCallback() {

  @Override
  public void onRangingFailure(int code) { … }

  @Override
  public void onRangingResults(List<RangingResult> results) { … }
});

Operasi pengukuran jarak dilakukan secara asinkron, dan hasil pengukuran jarak dikembalikan dalam salah satu callback dari RangingResultCallback:

• Jika keseluruhan operasi pengukuran jarak gagal, callback onRangingFailure dipicu dengan kode status yang dijelaskan dalam RangingResultCallback. Kegagalan tersebut dapat terjadi jika layanan tidak dapat melakukan operasi ranging pada saat itu. Misalnya, karena Wi-Fi dinonaktifkan, karena aplikasi telah meminta terlalu banyak operasi ranging dan dibatasi, atau karena masalah izin.
• Ketika operasi pengukuran jarak selesai, callback onRangingResults dipicu dengan daftar hasil yang cocok dengan daftar permintaan—satu hasil untuk setiap permintaan. Urutan hasil tidak harus sesuai dengan urutan permintaan. Perhatikan bahwa operasi ranging mungkin selesai tetapi setiap hasil mungkin masih menunjukkan kegagalan pengukuran spesifik tersebut.

Menginterpretasikan hasil ranging

Setiap hasil yang ditampilkan oleh callback onRangingResults ditentukan oleh objek RangingResult. Pada setiap permintaan, lakukan hal berikut.

1. Identifikasi permintaan

Identifikasi permintaan berdasarkan informasi yang diberikan saat membuat RangingRequest: alamat MAC paling sering tersedia di ScanResult mengidentifikasi titik akses. Alamat MAC dapat diperoleh dari hasil pengukuran jarak menggunakan metode getMacAddress().

Daftar hasil ranging mungkin berada dalam urutan berbeda dari peer (titik akses) yang ditentukan dalam permintaan ranging, jadi Anda harus menggunakan alamat MAC untuk mengidentifikasi peer, bukan urutan hasil.

2. Tentukan apakah setiap pengukuran berhasil

Untuk menentukan apakah suatu pengukuran berhasil, gunakan metode getStatus(). Nilai apa pun selain STATUS_SUCCESS menunjukkan kegagalan. Kegagalan berarti semua kolom lain dari hasil ini (kecuali identifikasi permintaan di atas) tidak valid, dan metode get* yang sesuai akan gagal dengan pengecualian IllegalStateException.

3. Dapatkan hasil untuk setiap pengukuran yang berhasil

Untuk setiap pengukuran yang berhasil (RangingResult), Anda dapat mengambil nilai hasil dengan masing-masing metode get:

• Jarak, dalam mm, dan standar deviasi pengukuran:

  getDistanceMm()

  getDistanceStdDevMm()

• RSSI dari paket yang digunakan untuk pengukuran:

  getRssi()

• Waktu dalam milidetik saat pengukuran dilakukan (menunjukkan waktu sejak booting):

  getRangingTimestampMillis()

• Jumlah pengukuran yang dicoba dan jumlah pengukuran yang berhasil (dan yang menjadi dasar pengukuran jarak):

  getNumAttemptedMeasurements()

  getNumSuccessfulMeasurements()

• Waktu minimum dan maksimum yang harus ditunggu perangkat klien di antara pengukuran NTB 11az:

  getMinTimeBetweenNtbMeasurementsMicros() dan getMaxTimeBetweenNtbMeasurementsMicros() menampilkan waktu minimum dan maksimum. Jika pengukuran rentang berikutnya diminta sebelum waktu minimum berlalu, API akan menampilkan hasil rentang yang di-cache. Jika pengukuran rentang berikutnya diminta setelah waktu maksimum berlalu, API akan menghentikan sesi pengukuran non-pemicu dan melakukan negosiasi sesi pengukuran baru dengan stasiun yang merespons. Anda sebaiknya menghindari permintaan sesi pengukuran jarak baru, karena akan menambah overhead pada waktu pengukuran jarak. Untuk memanfaatkan sepenuhnya efisiensi pengukuran berbasis non-pemicu 802.11az, picu permintaan pengukuran berikutnya antara waktu pengukuran minimum dan maksimum yang ditentukan dalam pengukuran RangingResult sebelumnya.

• Pengulangan Long Training Field (LTF) yang digunakan stasiun responder dan inisiator dalam preamble untuk hasil NTB IEEE 802.11az:

  get80211azResponderTxLtfRepetitionsCount()

  get80211azInitiatorTxLtfRepetitionsCount()

• Jumlah streaming waktu spasial (STS) transmisi dan penerimaan yang digunakan stasiun pemrakarsa untuk hasil NTB IEEE 802.11az:

  get80211azNumberOfTxSpatialStreams()

  get80211azNumberOfRxSpatialStreams()

Perangkat Android yang mendukung Wi-Fi RTT

Tabel berikut mencantumkan beberapa ponsel, titik akses, dan perangkat pusat distribusi, pergudangan, dan retail yang mendukung Wi-Fi RTT. Ini jauh dari komprehensif. Sebaiknya Anda menghubungi kami untuk mencantumkan produk-produk dengan kemampuan RTT di sini.

Titik akses

Ponsel

Perangkat pusat distribusi, pergudangan, dan retail