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 erişim noktasına olan mesafeyi yalnızca istekte bulunan cihaz 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ü bir paketin cihazlar arasında gidiş dönüş yapması için geçen süreyi ölçüp bu süreyi ışık hızıyla çarparak iki cihaz arasındaki mesafeyi 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ı

Wi-Fi RTT, Android 9 (API düzeyi 28) ile 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 temsil edilebilir. Konum Yapılandırma Bilgileri/Konum Şehir Raporu'nu (LCI/LCR verileri) destekleyen Wi-Fi RTT erişim noktaları için protokol, mesafe ölçümü işlemi sırasında bir ResponderLocation nesnesi döndürür.

Bu özellik, uygulamaların erişim noktalarını sorgulayarak konumlarını doğrudan sormasına olanak tanır. Böylece bu bilgilerin önceden depolanması gerekmez. Böylece 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, ölçüm aralıkları arasında 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 mesafe ölçümü, Android 15 (API düzeyi 35) ve sonraki sürümleri çalıştıran cihazlarda etkinleştirilmiştir.
• Mesafe ölçümü isteğinde bulunan cihazda konum hizmetleri etkinleştirilmiş ve kablosuz ağ taraması açılmış 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ı Kablosuz 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 yapmak 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

Kablosuz RTT cihazda 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. Kablosuz RTT'nin kullanılabilir olup olmadığını kontrol etmek için isAvailable() yöntemini çağırı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 bir BroadcastReceiver kaydetmelidir. Uygulamanız yayın intent'ini 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 menzil isteğinde birden fazla erişim noktası veya Wi-Fi Aware olan eş 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. Toplu olarak birden fazla erişim noktası eklemek için addAccessPoints(List<ScanResult>) kullanabilirsiniz.

ScanResult nesneleri, hem IEEE 802.11mc (is80211mcResponder()) hem de IEEE 802.11az tetikleyici tabanlı olmayan menzil belirleme (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çme 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 aşağıdakileri 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çme işlemi eşzamansız olarak gerçekleştirilir ve mesafe ölçme sonuçları, RangingResultCallback'nin 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: Çoğu zaman, erişim noktasını tanımlayan ScanResult içinde sağlanan bir MAC adresi. 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 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 başarısızlık göstergesidir. Hata, 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 olacağı 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ı olan ölçümlerin sayısı (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 önce istenirse API, önbelleğe alınmış mesafe sonucunu döndürür. Maksimum süre dolduktan 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. Yeni bir mesafe ölçümü oturumu istemekten kaçınmalısınız. Bu, mesafe ölçümü süresine ek yük getirir. 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ığı iletim ve alım uzamsal zaman akışlarının (STS) sayısı:

  get80211azNumberOfTxSpatialStreams()

  get80211azNumberOfRxSpatialStreams()

Kablosuz 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ı