Kablosuz konumu: RTT ile aralık

Yakındaki RTT özellikli kablosuz erişim noktalarına ve eş Kablosuz Ağ Farkında cihazlarına olan mesafeyi ölçmek için Kablosuz Ağ RTT (Gidiş Dönüş Süresi) API'si 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 yansıma algoritması kullanabilirsiniz. Sonuç genellikle 1-2 metre içinde doğrudur.

Bu doğruluk sayesinde kapalı mekan navigasyonu, anlam karışıklığını gideren sesli kontrol (ör. "Bu ışığı aç") ve konuma dayalı bilgiler (ör. "Bu ürün için özel teklif 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 istek gönderen cihaz erişim noktasına olan mesafeyi belirleyebilir. Erişim noktalarında bu bilgiler bulunmaz. Kablosuz RTT işlemleri, ön plan uygulamaları için sınırsızdır ancak arka plan uygulamaları için sınırlandırılır.

Kablosuz RTT ve ilgili hassas zaman ölçümü (FTM) özellikleri IEEE 802.11-2016 standardında belirtilmiştir. Wi-Fi RTT, bir paketin cihazlar arasında gidip gelme süresini ölçerek ve bu süreyi ışık hızıyla çarparak iki cihaz arasındaki mesafeyi hesapladığından FTM tarafından sağlanan hassas zaman ölçümünü gerektirir.

Android 15 (API düzeyi 35), IEEE 802.11az tetikleyici tabanlı olmayan (NTB) menzil 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 yansıma kullanarak bir cihazın konumunu belirlemek için bu protokolü kullanırken uygulamanızda önceden belirlenmiş erişim noktası (AP) konumu verilerine erişiminiz olmalıdır. Bu verileri nasıl depolayacağınıza ve alacağınıza siz karar verirsiniz.

Android 10 (API düzeyi 29) ve sonraki sürümleri çalıştıran cihazlarda AP konum verileri, enlem, boylam ve rakımı içeren ResponderLocation nesneleri olarak temsil edilebilir. Konum Yapılandırması Bilgileri/Konum Sivil Raporu'nu (LCI/LCR verileri) destekleyen kablosuz RTT AP'leri için protokol, aracılık işlemi sırasında bir ResponderLocation nesnesi döndürür.

Bu özellik, uygulamaların bu bilgileri önceden depolamak zorunda kalmadan AP'lerden doğrudan konumlarını sormasına olanak tanır. Böylece uygulamanız, daha önce bilinmeyen AP'leri (ör. kullanıcı yeni bir binaya girdiğinde) bulup konumlarını belirleyebilir.

IEEE 802.11az NTB menzil desteği, Android 15 (API düzeyi 35) ve sonraki sürümleri çalıştıran cihazlarda kullanılabilir. Diğer bir deyişle, 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 bulabilir. RangingResult API, tam aralığı uygulamanızın kontrolüne bırakarak, 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.

Şartlar

• Menzil isteği gönderen cihazın donanımı, 802.11-2016 FTM standardını veya 802.11az standardını (tetikleyici tabanlı olmayan menzil) uygulamalıdır.
• Aralık belirleme isteği gönderen cihazda Android 9 (API düzeyi 28) veya sonraki bir sürüm yüklü olmalıdır. Tetikleyici tabanlı olmayan IEEE 802.11az menzil ölçümü, Android 15 (API düzeyi 35) ve sonraki sürümleri çalıştıran cihazlarda etkindir.
• Aralık belirleme isteği gönderen cihazda konum hizmetlerinin ve kablosuz ağ tarama özelliğinin (Ayarlar > Konum bölümünde) etkin olması gerekir.
• Aralık belirleme isteği gönderen 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şemiyor.
• Erişim noktası, IEEE 802.11-2016 FTM standardını veya IEEE 802.11az standardını (tetikleyici tabanlı olmayan menzil belirleme) uygulamalıdır.

Kurulum

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

1. İzin isteme

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 verilmemişse 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 kablosuz RTT'yi destekleyip desteklemediğini kontrol edin

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

context.packageManager.hasSystemFeature(PackageManager.FEATURE_WIFI_RTT)

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

3. Kablosuz RTT'nin kullanılıp kullanılamadığını kontrol etme

Cihazda kablosuz RTT mevcut 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. WiFi RTT'nin kullanılıp kullanılamadığını kontrol etmek için isAvailable() numaralı telefonu arayın.

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

Örnek:

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.

Aralık isteği oluşturma

Bir kapsam isteği (RangingRequest), kapsam istenen AP'lerin veya Wi-Fi Aware eşlerinin listesi belirtilerek oluşturulur. Tek bir menzil isteğiyle birden fazla erişim noktası veya Wi-Fi Aware eşlenebilir. Tüm cihazlara olan mesafeler ölçülür ve döndürülür.

Örneğin, bir istek, mesafenin ölçüleceği bir 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 noktaları, WifiManager.getScanResults() çağrısı yapılarak elde edilebilen ScanResult nesneleriyle tanımlanır. Bir grup halinde birden fazla erişim noktası eklemek için addAccessPoints(List<ScanResult>) simgesini kullanabilirsiniz.

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

Benzer şekilde, bir menzil 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şdeğeri ekleyebilir. Wi-Fi Aware eşlerini keşfetme hakkında daha fazla bilgi için Wi-Fi Aware belgelerini inceleyin.

İstek aralığı

Uygulama, WifiRttManager.startRanging() yöntemini kullanarak bir menzil isteğinde bulunur ve aşağıdakileri sağlar: işlemi belirtmek için bir RangingRequest, geri çağırma bağlamını belirtmek için bir Executor ve sonuçları almak için bir RangingResultCallback.

Örnek:

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

Aralık belirleme işlemi eşzamansız olarak gerçekleştirilir ve aralık belirleme sonuçları, RangingResultCallback geri çağırma işlevlerinden birinde döndürülür:

• Aralık belirleme 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. Bu tür bir hata, hizmet o anda bir menzil belirleme işlemi yürütemiyorsa (ör. kablosuz ağ devre dışı olduğu için, uygulama çok fazla menzil belirleme işlemi istediği ve sınırlandığı için veya izin sorunu nedeniyle) ortaya çıkabilir.
• Aralık belirleme 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. Aralık belirleme işleminin tamamlanmış olabileceğini ancak her sonucun söz konusu ölçümün başarısız olduğunu gösterebileceğini unutmayın.

Aralık belirleme sonuçlarını yorumlama

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

1. İsteği tanımlama

RangingRequest oluşturulurken sağlanan bilgilere göre isteği tanımlayın: Genellikle bir erişim noktasını tanımlayan ScanResult içinde sağlanan bir MAC adresi. MAC adresi, getMacAddress() yöntemi kullanılarak menzil belirleme sonucundan elde edilebilir.

Aralık belirleme sonuçlarının listesi, aralık belirleme isteğinde belirtilen eşler (erişim noktaları) ile farklı bir sırada olabilir. Bu nedenle, eşleri 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 tüm değerler hatayı gösterir. Başarısızlık, bu sonucun diğer tüm alanlarının (yukarıdaki 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ün sonuçlarını alma

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

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

  getDistanceMm()

  getDistanceStdDevMm()

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

  getRssi()

• Ölçümün alındığı milisaniye cinsinden süre (açılıştan itibaren geçen süreyi belirtir):

  getRangingTimestampMillis()

• Denenen ölçümlerin ve başarılı olan (ve mesafe ölçümlerinin temel aldığı) ölçümlerin sayısı:

  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. Sonraki menzil ölçümü minimum süre dolmadan önce istenirse API, önbelleğe alınmış menzil sonucunu döndürür. Sonraki menzil ölçümü, maksimum süre dolduktan sonra istenirse API, tetikleyici olmayan menzil oturumunu sonlandırır ve yanıt veren istasyonla yeni bir menzil oturumu için pazarlık yapar. Yeni bir menzil belirleme oturumu istemekten kaçının. Bu işlem, menzil belirleme ölçüm süresine ek yük ekler. 802.11az tetikleyici tabanlı olmayan menzil belirleme verimliliğinden tam olarak yararlanmak için bir sonraki menzil belirleme isteğini, önceki RangingResult ölçümünde belirtilen minimum ve maksimum ölçüm süresi arasında tetikleyin.

• Yanıtlayıcı ve başlatıcı istasyonların IEEE 802.11az NTB sonucunun önsözünde kullandığı uzun eğitim alanı (LTF) tekrarları:

  get80211azResponderTxLtfRepetitionsCount()

  get80211azInitiatorTxLtfRepetitionsCount()

• Başlatıcı istasyonunun IEEE 802.11az NTB sonucu için kullandığı gönderme ve alma 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. Bu örnekler kapsamlı değildir. RTT özellikli ürünlerinizi burada listelemek için bize ulaşabilirsiniz.

Erişim Noktaları

Telefonlar

Perakende, Depolama ve Dağıtım Merkezi Cihazları