Kablosuz konumu: RTT ile aralık

Yakındaki RTT özellikli kablosuz ağ erişim noktalarına ve eş Wi-Fi Aware cihazlara olan mesafeyi ölçmek için Wi-Fi RTT (Gidiş Dönüş Süresi) API tarafından sağlanan kablosuz konum işlevini kullanabilirsiniz.

Üç veya daha fazla erişim noktasına olan mesafeyi ölçerseniz bu ölçümlere en uygun cihaz konumunu tahmin etmek için çoklu nirengi algoritması kullanabilirsiniz. Sonuç genellikle 1-2 metre içinde doğrudur.

Bu doğruluk sayesinde, bina içi navigasyon, anlam belirsizliği giderilmiş ses kontrolü (ör. "Bu ışığı aç") ve konuma dayalı bilgiler (ör. "Bu ürün için özel teklifler var mı?") gibi ayrıntılı konuma dayalı hizmetler geliştirebilirsiniz.

İstekte bulunan cihazın, kablosuz RTT ile mesafeyi ölçmek için erişim noktalarına bağlanması gerekmez. Gizliliği korumak için yalnızca istekte bulunan cihaz erişim noktasına olan mesafeyi belirleyebilir. Erişim noktaları bu bilgiye sahip değildir. Kablosuz RTT işlemleri, ön planda çalışan uygulamalar için sınırsızdır ancak arka planda çalışan uygulamalar için kısıtlanır.

Kablosuz RTT ve ilgili Fine-Time-Measurement (FTM) özellikleri, IEEE 802.11-2016 standardı tarafından belirtilir. Wi-Fi RTT, FTM tarafından sağlanan hassas zaman ölçümünü gerektirir. Çünkü iki cihaz arasındaki mesafeyi, bir paketin cihazlar arasında gidiş dönüş süresini ölçüp bu süreyi ışık hızıyla çarparak hesaplar.

Android 15 (API düzeyi 35), IEEE 802.11az tetikleyici tabanlı olmayan (NTB) ölçüm desteğini kullanıma sundu.

Android sürümüne göre uygulama farklılıkları

Kablosuz RTT, Android 9'da (API düzeyi 28) kullanıma sunulmuştur. Android 9 çalıştıran cihazlarla çoklu nirengi kullanarak bir cihazın konumunu belirlemek için bu protokolü kullanırken uygulamanızda önceden belirlenmiş erişim noktası (AP) konum verilerine erişmeniz gerekir. Bu verilerin nasıl depolanıp alınacağına karar vermek size bağlıdır.

Android 10 (API düzeyi 29) ve sonraki sürümlerin yüklü olduğu cihazlarda AP konum verileri; enlem, boylam ve rakım bilgilerini içeren ResponderLocation nesneleri olarak gösterilebilir. Konum Yapılandırma Bilgileri'ni veya Konum Sivil Raporu'nu (LCI veya LCR verileri) destekleyen kablosuz RTT erişim noktaları için protokol, mesafe ölçümü işlemi sırasında bir ResponderLocation nesnesi döndürür.

Uygulamalar, erişim noktalarının konumunu önceden depolamak yerine doğrudan sorgulayabilir. Uygulamanız, daha önce bilinmeyen erişim noktalarını bulabilir ve konumlarını belirleyebilir (ör. kullanıcı yeni bir binaya girdiğinde).

IEEE 802.11az NTB mesafe ölçümü desteği, Android 15 (API düzeyi 35) ve sonraki sürümleri çalıştıran cihazlarda kullanılabilir. Yani cihaz, IEEE 802.11az NTB başlatıcı modunu destekliyorsa (WifiRttManager.CHARACTERISTICS_KEY_BOOLEAN_NTB_INITIATOR ile gösterilir) uygulamanız tek bir menzil isteğiyle hem IEEE 802.11mc hem de IEEE 802.11az özellikli erişim noktalarını bulabilir. RangingResult API, mesafe ölçümleri arasındaki aralık için kullanılabilecek minimum ve maksimum değer hakkında bilgi sağlayacak şekilde genişletildi. Böylece tam aralık, uygulamanızın kontrolünde kalır.

Şartlar

• Mesafe ölçümü isteğinde bulunan cihazın donanımı, 802.11-2016 FTM standardını veya 802.11az standardını (tetikleyici tabanlı olmayan mesafe ölçümü) uygulamalıdır.
• Mesafe ölçümü isteğinde bulunan cihazda Android 9 (API düzeyi 28) veya sonraki bir sürüm yüklü olmalıdır. IEEE 802.11az tetikleyici tabanlı olmayan menzil belirleme, Android 15 (API düzeyi 35) ve sonraki sürümleri çalıştıran cihazlarda etkinleştirilir.
• Mesafe ölçme isteğinde bulunan cihazda konum hizmetleri ve kablosuz tarama etkinleştirilmiş olmalıdır (Ayarlar > Konum bölümünde).
• Mesafe ölçme isteğinde bulunan uygulama Android 13 (API düzeyi 33) veya sonraki sürümleri hedefliyorsa NEARBY_WIFI_DEVICES iznine sahip olmalıdır. Bu tür bir uygulama Android'in daha eski bir sürümünü hedefliyorsa bunun yerine ACCESS_FINE_LOCATION iznine sahip olmalıdır.
• Uygulama, görünür durumdayken veya ön plan hizmetindeyken erişim noktası aralığını sorgulamalıdır. Uygulama, arka planda konum bilgilerine erişemez.
• Erişim noktası, IEEE 802.11-2016 FTM standardını veya IEEE 802.11az standardını (tetikleyici tabanlı olmayan mesafe ölçümü) uygulamalıdır.

Kurulum

Uygulamanızı Wi-Fi RTT'yi kullanacak şekilde ayarlamak için aşağıdaki adımları uygulayın.

1. İzin iste

Uygulamanızın manifest dosyasında aşağıdaki izinleri isteyin:

<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" />

NEARBY_WIFI_DEVICES ve ACCESS_FINE_LOCATION izinleri tehlikeli izinler olduğundan, kullanıcı her RTT tarama işlemi gerçekleştirmek istediğinde bu izinleri çalışma zamanında istemeniz gerekir. Uygulamanızın, daha önce verilmemişse kullanıcıdan izin istemesi gerekir. Çalışma zamanında istenen izinler hakkında daha fazla bilgi için Uygulama İzinleri İsteme başlıklı makaleyi inceleyin.

2. Cihazın kablosuz RTT'yi destekleyip desteklemediğini kontrol etme

Cihazın kablosuz RTT'yi destekleyip desteklemediğini kontrol etmek için PackageManager API'sini kullanın:

context.packageManager.hasSystemFeature(PackageManager.FEATURE_WIFI_RTT)

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

3. Kablosuz RTT'nin kullanılabilir olup olmadığını kontrol etme

Cihazda kablosuz RTT olabilir ancak kullanıcı kablosuz bağlantıyı devre dışı bıraktığı için kullanılamayabilir. Donanım ve donanım yazılımı özelliklerine bağlı olarak bazı cihazlar, SoftAP veya tethering kullanılıyorsa kablosuz RTT'yi desteklemeyebilir. Kablosuz RTT'nin kullanılabilir olup olmadığını kontrol etmek için isAvailable() yöntemini çağırın.

Kablosuz RTT'nin kullanılabilirlik durumu herhangi bir zamanda değişebilir. Uygulamanız, kullanılabilirlik durumu değiştiğinde gönderilen ACTION_WIFI_RTT_STATE_CHANGED öğesini almak için bir BroadcastReceiver kaydetmelidir. Uygulamanız yayın amacını aldığında, mevcut kullanılabilirlik durumunu kontrol etmeli ve davranışını buna göre ayarlamalıdır.

Örneğin:

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);

Daha fazla bilgi için Yayınlar bölümüne bakın.

Mesafe ölçümü isteği oluşturma

Mesafe ölçümü isteği (RangingRequest), mesafe ölçümü istenen erişim noktalarının veya Wi-Fi Aware eşlerinin listesi belirtilerek oluşturulur. Tek bir mesafe ölçme isteğinde birden fazla erişim noktası veya Wi-Fi Aware eşi belirtilebilir. Tüm cihazlara olan mesafeler ölçülür ve döndürülür.

Örneğin, bir istek, mesafenin ölçüleceği erişim noktasını belirtmek için addAccessPoint() yöntemini kullanabilir:

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();

Erişim noktası, WifiManager.getScanResults() çağrılarak elde edilebilen ScanResult nesnesiyle tanımlanır. Birden fazla erişim noktasını toplu olarak eklemek için addAccessPoints(List<ScanResult>) kullanabilirsiniz.

ScanResult nesneleri hem IEEE 802.11mc (is80211mcResponder()) hem de IEEE 802.11az tetikleyici tabanlı olmayan ölçüm (is80211azNtbResponder()) destekli erişim noktalarını içerebilir. IEEE 802.11az NTB ölçümünü destekleyen cihazlar, AP'nin kapasitesine bağlı olarak 802.11mc veya 802.11az ölçümü gerçekleştirir. AP her ikisini de destekliyorsa varsayılan olarak 802.11az kullanılır. IEEE 802.11az'yi desteklemeyen cihazlar, tüm mesafe ölçümlerini IEEE 802.11mc protokolünü kullanarak gerçekleştirir.

Benzer şekilde, bir mesafe ölçümü isteği, sırasıyla addWifiAwarePeer(MacAddress peer) ve addWifiAwarePeer(PeerHandle peer) yöntemlerini kullanarak MAC adresini veya PeerHandle değerini kullanarak bir Wi-Fi Aware eşi ekleyebilir. Wi-Fi Aware eşlerini keşfetme hakkında daha fazla bilgi için Wi-Fi Aware belgelerini inceleyin.

Mesafe ölçümü isteğinde bulunma

Uygulama, WifiRttManager.startRanging() yöntemini kullanarak ve şunları sağlayarak bir mesafe ölçümü isteği gönderir: işlemi belirtmek için RangingRequest, geri çağırma bağlamını belirtmek için Executor ve sonuçları almak için RangingResultCallback.

Örneğin:

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) { … }
});

Mesafe ölçümü işlemi eşzamansız olarak gerçekleştirilir ve mesafe ölçümü sonuçları RangingResultCallback geri çağırmalarından birinde döndürülür:

• Mesafe ölçme işleminin tamamı başarısız olursa onRangingFailure geri çağırma işlevi, RangingResultCallback bölümünde açıklanan bir durum koduyla tetiklenir. Hizmet, o sırada bir mesafe ölçme işlemi gerçekleştiremiyorsa (ör. kablosuz bağlantı devre dışı bırakıldığı, uygulama çok fazla mesafe ölçme işlemi istediği ve kısıtlandığı veya izin sorunu olduğu için) bu tür bir hata oluşabilir.
• Mesafe ölçme işlemi tamamlandığında onRangingResults geri çağırma işlevi, istek listesiyle eşleşen bir sonuç listesiyle (her istek için bir sonuç) tetiklenir. Sonuçların sırası, isteklerin sırasıyla eşleşmeyebilir. Mesafe ölçme işlemi tamamlanabilir ancak her sonuç, ilgili ölçümün başarısız olduğunu gösterebilir.

Mesafe ölçümü sonuçlarını yorumlama

onRangingResults geri çağırma işlevi tarafından döndürülen sonuçların her biri, bir RangingResult nesnesi tarafından belirtilir. Her istekte aşağıdakileri yapın.

1. İsteği tanımlama

RangingRequest oluşturulurken sağlanan bilgilere göre isteği tanımlayın. Bu bilgi genellikle erişim noktasını tanımlayan ScanResult içinde sağlanan bir MAC adresidir. MAC adresi, getMacAddress() yöntemi kullanılarak mesafe ölçümü sonucundan alınabilir.

Mesafe ölçümü sonuçlarının listesi, mesafe ölçümü isteğinde belirtilen eşlerden (erişim noktaları) farklı bir sırada olabilir. Bu nedenle, eşi tanımlamak için sonuçların sırasını değil, MAC adresini kullanın.

2. Her ölçümün başarılı olup olmadığını belirleme

Bir ölçümün başarılı olup olmadığını belirlemek için getStatus() yöntemini kullanın. STATUS_SUCCESS dışındaki tüm değerler hata olduğunu gösterir. Başarısızlık, bu sonucun diğer tüm alanlarının (önceki adımda yer alan istek kimliği hariç) geçersiz olduğu ve ilgili get* yönteminin IllegalStateException istisnasıyla başarısız olduğu anlamına gelir.

3. Her başarılı ölçüm için sonuç alma

Her başarılı ölçüm (RangingResult) için ilgili get yöntemleriyle sonuç değerlerini alabilirsiniz:

• Mesafe (mm) ve ölçümün standart sapması:

  getDistanceMm()

  getDistanceStdDevMm()

• Ölçümler için kullanılan paketlerin RSSI değeri:

  getRssi()

• Ölçümün yapıldığı milisaniye cinsinden zaman (başlatmadan sonraki süreyi gösterir):

  getRangingTimestampMillis()

• Ölçüm yapmaya çalışılan ve başarılı olunan ölçümlerin sayısı (ve mesafe ölçümlerinin dayandığı ölçümler):

  getNumAttemptedMeasurements()

  getNumSuccessfulMeasurements()

• İstemci cihazın 11az NTB ölçümleri arasında beklemesi gereken minimum ve maksimum süre:

  getMinTimeBetweenNtbMeasurementsMicros() ve getMaxTimeBetweenNtbMeasurementsMicros(), minimum ve maksimum süreyi döndürür. Bir sonraki mesafe ölçümü minimum süre dolmadan istenirse API, önbelleğe alınmış mesafe sonucunu döndürür. Maksimum süre geçtikten sonra bir sonraki mesafe ölçümü istenirse API, tetikleyici olmayan mesafe ölçümü oturumunu sonlandırır ve yanıt veren istasyonla yeni bir mesafe ölçümü oturumu için anlaşır. Mesafe ölçümü süresine ek yük getirdiği için yeni bir mesafe ölçümü oturumu istemekten kaçının. 802.11az tetikleyici tabanlı olmayan mesafe ölçüm verimliliğinden tam olarak yararlanmak için bir sonraki mesafe ölçüm isteğini, önceki RangingResult ölçümünde belirtilen minimum ve maksimum ölçüm süresi arasında tetikleyin.

• IEEE 802.11az NTB sonucu için yanıtlayan ve başlatan istasyonların ön talimatlarda kullandığı Uzun Eğitim Alanı (LTF) tekrarları:

  get80211azResponderTxLtfRepetitionsCount()

  get80211azInitiatorTxLtfRepetitionsCount()

• Başlatıcı istasyonun IEEE 802.11az NTB sonucu için kullandığı uzamsal zaman akışlarının (STS) iletim ve alım sayısı:

  get80211azNumberOfTxSpatialStreams()

  get80211azNumberOfRxSpatialStreams()

WiFi-RTT'yi destekleyen Android cihazlar

Aşağıdaki tablolarda, Kablosuz RTT'yi destekleyen bazı telefonlar, erişim noktaları ve perakende, depolama ve dağıtım merkezi cihazları listelenmiştir. Bunlar kapsamlı olmaktan uzaktır. RTT özellikli ürünlerinizi burada listelemek için bize ulaşmanızı öneririz.

Erişim noktaları

Telefonlar

Perakende, depolama ve dağıtım merkezi cihazları