Kablosuz konumu: RTT ile aralık

Yakındaki RTT özellikli kablosuz erişim noktalarına ve Kablosuz Aware cihazlara olan mesafeyi ölçmek için Kablosuz RTT (Round-Trip-Time) 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 konum belirleme algoritması kullanabilirsiniz. Sonuç genellikle 1-2 metre içinde doğru olur.

Bu doğruluk sayesinde, ayrıntılı konuma dayalı hizmetler geliştirebilirsiniz. Örneğin, kapalı alanlarda gezinme, netleştirilmiş sesle kontrol (ör. "Bu ışığı aç") ve konuma dayalı bilgiler (ör. "Bu ürün için özel teklifler var mı?") gibi hizmetler sunabilirsiniz.

İstekte bulunan cihazın, kablosuz RTT ile mesafeyi ölçmek için erişim noktalarına bağlanması gerekmez. Gizliliği korumak için erişim noktasına olan mesafeyi yalnızca istekte bulunan cihaz belirleyebilir. Erişim noktalarında bu bilgi bulunmaz. Ön plandaki uygulamalar için Wi-Fi RTT işlemleri sınırsızdır ancak arka plandaki uygulamalar için sınırlıdır.

Wi-Fi RTT ve ilgili Fine-Time-Measurement (FTM) özellikleri IEEE 802.11-2016 standardında belirtilmiştir. Wi-Fi RTT, iki cihaz arasındaki mesafeyi hesaplamak için FTM tarafından sağlanan hassas zaman ölçümünü gerektirir. Bu hesaplama, bir paketin cihazlar arasında gidiş dönüş yapması için geçen sürenin ölçülmesi ve bu sürenin ışık hızıyla çarpılmasıyla yapılır.

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

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

Wi-Fi RTT, Android 9'da (API düzeyi 28) kullanıma sunulmuştur. Android 9 çalıştıran cihazlarla çoklu konum belirleme kullanarak bir cihazın konumunu belirlemek için bu protokolü kullanırken uygulamanızda önceden belirlenmiş erişim noktası (AP) konumları verilerine erişmeniz gerekir. Bu verileri nasıl depolayacağınıza ve alacağınıza siz karar verirsiniz.

Android 10 (API düzeyi 29) ve sonraki sürümlerin yüklü olduğu cihazlarda AP konum verileri, enlem, boylam ve yüksekliği içeren ResponderLocation nesneleri olarak gösterilebilir. Konum Yapılandırma Bilgileri/Konum Kamu Raporu'nu (LCI/LCR verileri) destekleyen Wi-Fi RTT AP'leri için protokol, mesafe ölçme işlemi sırasında bir ResponderLocation nesnesi döndürür.

Bu özellik, uygulamaların önceden bu bilgileri depolamasına gerek kalmadan doğrudan konumlarını istemek için AP'lere sorgu göndermesine olanak tanır. Bu sayede uygulamanız, daha önce bilinmeyen AP'leri (ör. kullanıcı yeni bir binaya girdiğinde) bulabilir ve konumlarını belirleyebilir.

IEEE 802.11az NTB aralığı desteği, Android 15 (API düzeyi 35) ve sonraki sürümlerin yüklü olduğu cihazlarda kullanılabilir. Bu, cihaz IEEE 802.11az NTB başlatıcı modunu destekliyorsa (WifiRttManager.CHARACTERISTICS_KEY_BOOLEAN_NTB_INITIATOR ile gösterilir) uygulamanız tek bir aralık isteğiyle hem IEEE 802.11mc hem de IEEE 802.11az özellikli AP'leri bulabileceği anlamına gelir. RangingResult API, aralıklı ölçümler arasındaki aralık için kullanılabilecek minimum ve maksimum değer hakkında bilgi sağlamak üzere 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çme 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 mesafe ölçümü, Android 15 (API düzeyi 35) ve sonraki sürümlerin yüklü olduğu cihazlarda etkinleştirilir.
• Mesafe ölçme isteğinde bulunan cihazda konum hizmetleri etkinleştirilmiş ve kablosuz ağ taraması açık 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. Android'in daha eski bir sürümünü hedefleyen bu tür uygulamalarda bunun yerine ACCESS_FINE_LOCATION izni olmalıdır.
• Uygulama, görünür durumdayken veya ön plan hizmetindeyken erişim noktalarının aralığını sorgulamalıdır. Uygulama, arka plandaki 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 kullanacak şekilde ayarlamak için aşağıdaki adımları uygulayın.

1. İzin isteğinde bulunma

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 yapmak istediğinde çalışma zamanında bu izinleri istemeniz gerekir. İzin daha önce verilmediyse uygulamanızın kullanıcıdan izin istemesi gerekir. Çalışma zamanı izinleri hakkında daha fazla bilgi için Uygulama İzinleri İsteme başlıklı makaleyi inceleyin.

2. Cihazın Wi-Fi RTT'yi destekleyip desteklemediğini kontrol edin.

Cihazın Wi-Fi 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 Wi-Fi RTT olabilir ancak kullanıcı Wi-Fi'yi devre dışı bıraktığı için kullanılamayabilir. Bazı cihazlar, donanım ve yazılım özellikleri nedeniyle SoftAP veya tethering kullanılıyorsa Wi-Fi RTT'yi desteklemeyebilir. Wi-Fi RTT'nin kullanılabilir olup olmadığını kontrol etmek için isAvailable()'ı arayın.

Kablosuz RTT'nin kullanılabilirliği herhangi bir zamanda değişebilir. Uygulamanız, kullanılabilirlik değiştiğinde gönderilen ACTION_WIFI_RTT_STATE_CHANGED mesajını almak için BroadcastReceiver kaydetmelidir. Uygulamanız yayın intent'ini aldığında, müsaitlik 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 başlıklı makaleyi inceleyin.

Mesafe ölçme isteği oluşturma

Bir aralık isteği (RangingRequest), aralık istenen AP'lerin 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 istekte mesafenin ölçüleceği bir erişim noktasını belirtmek için addAccessPoint() yöntemi kullanılabilir:

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 mesafe ölçümü (is80211azNtbResponder()) destekli AP'leri içerebilir. IEEE 802.11az NTB aralığını destekleyen cihazlar, AP'nin özelliğine bağlı olarak 802.11mc veya 802.11az aralığını kullanır. AP her ikisini de desteklediğinde varsayılan olarak 802.11az aralığı kullanılır. IEEE 802.11az'yi desteklemeyen cihazlar, IEEE 802.11mc protokolünü kullanarak tüm aralıkları ölçer.

Benzer şekilde, bir aralık isteği, sırasıyla addWifiAwarePeer(MacAddress peer) ve addWifiAwarePeer(PeerHandle peer) yöntemlerini kullanarak MAC adresini veya PeerHandle'sini 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 belgelerine bakın.

İstek aralığı

Bir uygulama, WifiRttManager.startRanging() yöntemini kullanarak ve aşağıdakileri sağlayarak bir aralık 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 belirleme işlemi eşzamansız olarak gerçekleştirilir ve mesafe belirleme sonuçları RangingResultCallback geri çağırmalarından birinde döndürülür:

• Tüm mesafe ölçme işlemi başarısız olursa onRangingFailure geri çağırma işlevi, RangingResultCallback bölümünde açıklanan bir durum koduyla tetiklenir. Bu tür bir hata, hizmet o sırada mesafe ölçme işlemi gerçekleştiremediğinde (ör. Wi-Fi devre dışı olduğunda, uygulama çok fazla mesafe ölçme işlemi istediği için sınırlandırıldığında veya izin sorunu nedeniyle) oluşabilir.
• Aralık belirleme işlemi tamamlandığında, istek listesiyle eşleşen sonuçların listesiyle birlikte onRangingResults geri çağırma işlemi tetiklenir. Her istek için bir sonuç döndürülür. Sonuçların sırası, isteklerin sırasıyla her zaman eşleşmez. Aralık belirleme işleminin tamamlanabileceğini ancak her sonucun yine de söz konusu ölçümün başarısız olduğunu gösterebileceğini unutmayın.

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

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

1. İsteği belirleyin

İsteği, RangingRequest oluşturulurken sağlanan bilgilere göre tanımlayın: Çoğu zaman ScanResult içinde sağlanan bir MAC adresi, erişim noktasını tanımlar. MAC adresi, getMacAddress() yöntemi kullanılarak aralık belirleme sonucundan elde edilebilir.

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 kullanmanız gerekir.

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 herhangi bir değer başarısızlığı gösterir. Başarısızlık, bu sonucun diğer tüm alanlarının (yukarıdaki istek tanımlaması hariç) geçersiz olduğu ve ilgili get* yönteminin IllegalStateException istisnasıyla başarısız olacağı anlamına gelir.

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

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

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

  getDistanceMm()

  getDistanceStdDevMm()

• Ölçümler için kullanılan paketlerin RSSI'si:

  getRssi()

• Ölçümün yapıldığı milisaniye cinsinden süre (başlatmadan bu yana geçen süreyi gösterir):

  getRangingTimestampMillis()

• Yapılmaya çalışılan ölçümlerin sayısı ve başarılı olan ölçümlerin sayısı (mesafe ölçümleri bu ölçümlere göre yapılır):

  getNumAttemptedMeasurements()

  getNumSuccessfulMeasurements()

• Bir istemci 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. Minimum süre geçmeden sonraki mesafe ölçümü istenirse API, önbelleğe alınmış mesafe ölçümü 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 görüşme yapar. Mesafe ölçümü süresine ek yük getirdiğinden yeni bir mesafe ölçümü oturumu istemekten kaçınmalısınız. 802.11az tetikleyici tabanlı olmayan aralık verimliliğinden tam olarak yararlanmak için önceki RangingResult ölçümünde belirtilen minimum ve maksimum ölçüm süresi arasında bir sonraki aralık isteğini tetikleyin.

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

  get80211azResponderTxLtfRepetitionsCount()

  get80211azInitiatorTxLtfRepetitionsCount()

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

  get80211azNumberOfTxSpatialStreams()

  get80211azNumberOfRxSpatialStreams()

WiFi-RTT'yi destekleyen Android cihazlar

Aşağıdaki tablolarda, WiFi-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ı