वाई-फ़ाई की जगह की जानकारी: आरटीटी की सुविधा

आस-पास के आरटीटी की सुविधा वाले वाई-फ़ाई ऐक्सेस पॉइंट और Wi-Fi Aware डिवाइसों की दूरी का पता लगाने के लिए, वाई-फ़ाई आरटीटी (राउंड-ट्रिप-टाइम) एपीआई की मदद से उपलब्ध कराई गई, वाई-फ़ाई की जगह की जानकारी देने वाली सुविधा का इस्तेमाल किया जा सकता है.

अगर तीन या उससे ज़्यादा ऐक्सेस पॉइंट के बीच की दूरी मापी जाती है, तो डिवाइस की उस जगह का अनुमान लगाने के लिए मल्टीलेटरेशन एल्गोरिदम का इस्तेमाल किया जा सकता है जो उन मेज़रमेंट के हिसाब से सबसे सही हो. आम तौर पर, नतीजे में एक से दो मीटर तक का अंतर हो सकता है.

इस सटीक जानकारी की मदद से, जगह के हिसाब से काम करने वाली बेहतर सेवाएं डेवलप की जा सकती हैं. जैसे, घर के अंदर नेविगेशन, आवाज़ से कंट्रोल करने की सुविधा (उदाहरण के लिए, "यह लाइट चालू करो") और जगह के हिसाब से जानकारी (उदाहरण के लिए, "क्या इस प्रॉडक्ट के लिए कोई खास ऑफ़र उपलब्ध हैं?").

अनुरोध करने वाले डिवाइस को, वाई-फ़ाई आरटीटी की मदद से दूरी का पता लगाने के लिए, ऐक्सेस पॉइंट से कनेक्ट करने की ज़रूरत नहीं होती. निजता बनाए रखने के लिए, सिर्फ़ अनुरोध करने वाला डिवाइस ही ऐक्सेस पॉइंट से दूरी का पता लगा सकता है. ऐक्सेस पॉइंट के पास यह जानकारी नहीं होती. फ़ोरग्राउंड ऐप्लिकेशन के लिए, वाई-फ़ाई आरटीटी की कार्रवाइयों की कोई सीमा नहीं होती. हालांकि, बैकग्राउंड ऐप्लिकेशन के लिए इनकी संख्या सीमित होती है.

वाई-फ़ाई आरटीटी और इससे जुड़ी फ़ाइन-टाइम-मेज़रमेंट (एफ़टीएम) की क्षमताओं के बारे में, IEEE 802.11-2016 स्टैंडर्ड में बताया गया है. Wi-Fi RTT को सटीक समय की ज़रूरत होती है. यह समय, FTM से मिलता है. ऐसा इसलिए, क्योंकि यह दो डिवाइसों के बीच की दूरी का हिसाब लगाता है. इसके लिए, यह मेज़र करता है कि एक पैकेट को डिवाइसों के बीच राउंड ट्रिप करने में कितना समय लगता है. इसके बाद, यह उस समय को रोशनी की गति से गुणा करता है.

Android 15 (एपीआई लेवल 35) में, IEEE 802.11az नॉन-ट्रिगर आधारित (एनटीबी) रेंजिंग की सुविधा जोड़ी गई है.

Android वर्शन के हिसाब से लागू करने के तरीके में अंतर

वाई-फ़ाई आरटीटी को Android 9 (एपीआई लेवल 28) में पेश किया गया था. Android 9 पर चलने वाले डिवाइसों के साथ मल्टीलेटरेशन का इस्तेमाल करके, किसी डिवाइस की जगह की जानकारी का पता लगाने के लिए इस प्रोटोकॉल का इस्तेमाल करते समय, आपके पास ऐप्लिकेशन में पहले से तय किए गए ऐक्सेस पॉइंट (एपी) की जगह की जानकारी का डेटा ऐक्सेस करने का विकल्प होना चाहिए. इस डेटा को सेव करने और वापस पाने का तरीका तय करना आपका काम है.

Android 10 (एपीआई लेवल 29) और इसके बाद के वर्शन पर काम करने वाले डिवाइसों पर, एपी की जगह की जानकारी को ResponderLocation ऑब्जेक्ट के तौर पर दिखाया जा सकता है. इनमें अक्षांश, देशांतर, और ऊंचाई शामिल होती है. जिन वाई-फ़ाई आरटीटी एपी में लोकेशन कॉन्फ़िगरेशन की जानकारी/लोकेशन सिविक रिपोर्ट (एलसीआई/एलसीआर डेटा) की सुविधा होती है उनके लिए, प्रोटोकॉल रेंजिंग प्रोसेस के दौरान ResponderLocation ऑब्जेक्ट दिखाता है.

इस सुविधा की मदद से ऐप्लिकेशन, ऐक्सेस पॉइंट से सीधे तौर पर उनकी जगह की जानकारी मांग सकते हैं. इसके लिए, उन्हें पहले से यह जानकारी सेव करने की ज़रूरत नहीं होती. इसलिए, आपका ऐप्लिकेशन एपी ढूंढ सकता है और उनकी जगह की जानकारी का पता लगा सकता है. भले ही, एपी के बारे में पहले से जानकारी न हो. जैसे, जब कोई उपयोगकर्ता किसी नई बिल्डिंग में जाता है.

IEEE 802.11az NTB रेंजिंग की सुविधा, Android 15 (एपीआई लेवल 35) और इसके बाद के वर्शन वाले डिवाइसों पर उपलब्ध है. इसका मतलब है कि अगर डिवाइस, IEEE 802.11az NTB इनिशिएटर मोड के साथ काम करता है (WifiRttManager.CHARACTERISTICS_KEY_BOOLEAN_NTB_INITIATOR से पता चलता है), तो आपका ऐप्लिकेशन, एक ही रेंज के अनुरोध से IEEE 802.11mc और IEEE 802.11az के साथ काम करने वाले एपी ढूंढ सकता है. RangingResult एपीआई को अब इस तरह से अपडेट किया गया है कि यह रेंजिंग मेज़रमेंट के बीच के इंटरवल के लिए, कम से कम और ज़्यादा से ज़्यादा वैल्यू के बारे में जानकारी दे सके. इससे, इंटरवल को सटीक तरीके से कंट्रोल करने का विकल्प आपके ऐप्लिकेशन के पास होगा.

ज़रूरी शर्तें

• रेंजिंग का अनुरोध करने वाले डिवाइस के हार्डवेयर में, 802.11-2016 FTM स्टैंडर्ड या 802.11az स्टैंडर्ड (नॉन-ट्रिगर आधारित रेंजिंग) लागू होना चाहिए.
• रेंजिंग का अनुरोध करने वाले डिवाइस पर Android 9 (एपीआई लेवल 28) या उसके बाद का वर्शन होना चाहिए. Android 15 (एपीआई लेवल 35) और इसके बाद के वर्शन पर काम करने वाले डिवाइसों पर, IEEE 802.11az नॉन-ट्रिगर आधारित रेंजिंग की सुविधा चालू है.
• रेंजिंग का अनुरोध करने वाले डिवाइस पर, जगह की जानकारी देने वाली सेवाएं चालू होनी चाहिए. साथ ही, वाई-फ़ाई स्कैनिंग की सुविधा चालू होनी चाहिए. यह सुविधा सेटिंग > जगह की जानकारी में जाकर चालू की जा सकती है.
• अगर रेंजिंग का अनुरोध करने वाला ऐप्लिकेशन, Android 13 (एपीआई लेवल 33) या उसके बाद के वर्शन को टारगेट करता है, तो उसके पास NEARBY_WIFI_DEVICES अनुमति होनी चाहिए. अगर ऐसा ऐप्लिकेशन, Android के पुराने वर्शन को टारगेट करता है, तो उसके पास ACCESS_FINE_LOCATION की अनुमति होनी चाहिए.
• ऐप्लिकेशन को ऐक्सेस पॉइंट की रेंज के बारे में तब क्वेरी करनी चाहिए, जब ऐप्लिकेशन दिख रहा हो या फ़ोरग्राउंड सेवा में हो. ऐप्लिकेशन, बैकग्राउंड में जगह की जानकारी ऐक्सेस नहीं कर सकता.
• ऐक्सेस पॉइंट में, आईईईई 802.11-2016 एफ़टीएम स्टैंडर्ड या आईईईई 802.11az स्टैंडर्ड (नॉन-ट्रिगर आधारित रेंजिंग) लागू होना चाहिए.

सेटअप

वाई-फ़ाई आरटीटी का इस्तेमाल करने के लिए, अपने ऐप्लिकेशन को सेट अप करने के लिए यह तरीका अपनाएं.

1. अनुमतियों का अनुरोध करना

अपने ऐप्लिकेशन के मेनिफ़ेस्ट में, इन अनुमतियों का अनुरोध करें:

<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 और ACCESS_FINE_LOCATION अनुमतियां, जोखिम वाली अनुमतियां हैं. इसलिए, जब भी उपयोगकर्ता को आरटीटी स्कैन करने की कार्रवाई करनी हो, तब आपको रनटाइम में इन अनुमतियों का अनुरोध करना होगा. अगर अनुमति पहले से नहीं दी गई है, तो आपके ऐप्लिकेशन को उपयोगकर्ता से अनुमति का अनुरोध करना होगा. रनटाइम अनुमतियों के बारे में ज़्यादा जानने के लिए, ऐप्लिकेशन की अनुमतियों का अनुरोध करना लेख पढ़ें.

2. देखें कि डिवाइस में वाई-फ़ाई आरटीटी की सुविधा काम करती है या नहीं

यह देखने के लिए कि डिवाइस पर वाई-फ़ाई आरटीटी की सुविधा काम करती है या नहीं, PackageManager एपीआई का इस्तेमाल करें:

context.packageManager.hasSystemFeature(PackageManager.FEATURE_WIFI_RTT)

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

3. देखें कि वाई-फ़ाई आरटीटी की सुविधा उपलब्ध है या नहीं

डिवाइस पर वाई-फ़ाई आरटीटी की सुविधा मौजूद हो सकती है, लेकिन यह उपलब्ध नहीं हो सकती, क्योंकि उपयोगकर्ता ने वाई-फ़ाई बंद कर दिया है. हार्डवेयर और फ़र्मवेयर की क्षमताओं के आधार पर, कुछ डिवाइसों में Wi-Fi RTT की सुविधा काम नहीं करती. ऐसा तब होता है, जब SoftAP या टेदरिंग का इस्तेमाल किया जा रहा हो. यह देखने के लिए कि वाई-फ़ाई आरटीटी की सुविधा उपलब्ध है या नहीं, isAvailable() को कॉल करें.

ऐसा हो सकता है कि आने वाले समय में, वाई-फ़ाई आरटीटी की सुविधा की उपलब्धता में बदलाव हो. आपके ऐप्लिकेशन को BroadcastReceiver रजिस्टर करना चाहिए, ताकि उसे ACTION_WIFI_RTT_STATE_CHANGED मिल सके. यह तब भेजा जाता है, जब उपलब्धता में बदलाव होता है. जब आपके ऐप्लिकेशन को ब्रॉडकास्ट इंटेंट मिलता है, तो उसे उपलब्धता की मौजूदा स्थिति की जांच करनी चाहिए. साथ ही, इसके हिसाब से अपने व्यवहार में बदलाव करना चाहिए.

उदाहरण के लिए:

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

ज़्यादा जानकारी के लिए, ब्रॉडकास्ट देखें.

रेंजिंग का अनुरोध करना

रेंजिंग का अनुरोध (RangingRequest) तब किया जाता है, जब एपी या वाई-फ़ाई अवेयर पीयर की सूची दी जाती है. एक ही रेंजिंग के अनुरोध में, कई ऐक्सेस पॉइंट या Wi-Fi Aware पीयर तय किए जा सकते हैं. सभी डिवाइसों की दूरी मापी जाती है और वापस भेजी जाती है.

उदाहरण के लिए, कोई अनुरोध addAccessPoint() मेथड का इस्तेमाल करके, उस ऐक्सेस पॉइंट के बारे में बता सकता है जिससे दूरी को मापना है:

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

ऐक्सेस पॉइंट की पहचान उसके ScanResult ऑब्जेक्ट से होती है. इसे WifiManager.getScanResults() को कॉल करके पाया जा सकता है. एक बैच में कई ऐक्सेस पॉइंट जोड़ने के लिए, addAccessPoints(List<ScanResult>) का इस्तेमाल किया जा सकता है.

ScanResult ऑब्जेक्ट में, IEEE 802.11mc (is80211mcResponder()) और IEEE 802.11az नॉन-ट्रिगर आधारित रेंजिंग (is80211azNtbResponder()) के साथ काम करने वाले एपी, दोनों शामिल हो सकते हैं. IEEE 802.11az NTB रेंजिंग के साथ काम करने वाले डिवाइस, एपी की क्षमता के आधार पर 802.11mc या 802.11az रेंजिंग करते हैं. अगर एपी दोनों के साथ काम करता है, तो डिफ़ॉल्ट रूप से 802.11az रेंजिंग का इस्तेमाल किया जाता है. जिन डिवाइसों पर IEEE 802.11az काम नहीं करता वे IEEE 802.11mc प्रोटोकॉल का इस्तेमाल करके, रेंजिंग की सभी कार्रवाइयां करते हैं.

इसी तरह, रेंजिंग का अनुरोध करने वाला डिवाइस, वाई-फ़ाई अवेयर पीयर को उसके मैक पते या PeerHandle का इस्तेमाल करके जोड़ सकता है. इसके लिए, वह addWifiAwarePeer(MacAddress peer) और addWifiAwarePeer(PeerHandle peer) तरीकों का इस्तेमाल करता है. Wi-Fi Aware की सुविधा वाले आस-पास के डिवाइसों का पता लगाने के बारे में ज़्यादा जानकारी के लिए, Wi-Fi Aware के दस्तावेज़ देखें.

अनुरोध की सीमा

कोई ऐप्लिकेशन, रेंजिंग का अनुरोध करने के लिए WifiRttManager.startRanging() तरीके का इस्तेमाल करता है. साथ ही, यह जानकारी देता है: RangingRequest, ताकि ऑपरेशन के बारे में बताया जा सके, Executor, ताकि कॉलबैक कॉन्टेक्स्ट के बारे में बताया जा सके, और RangingResultCallback, ताकि नतीजे मिल सकें.

उदाहरण के लिए:

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

रेंजिंग की कार्रवाई एसिंक्रोनस तरीके से की जाती है. रेंजिंग के नतीजे, RangingResultCallback के किसी एक कॉलबैक में दिखाए जाते हैं:

• अगर रेंजिंग की पूरी प्रोसेस पूरी नहीं होती है, तो onRangingFailure कॉलबैक ट्रिगर होता है. इसमें RangingResultCallback में बताया गया स्टेटस कोड होता है. ऐसा तब हो सकता है, जब सेवा उस समय रेंजिंग ऑपरेशन नहीं कर पाती है. उदाहरण के लिए, वाई-फ़ाई बंद होने की वजह से, ऐप्लिकेशन ने बहुत ज़्यादा रेंजिंग ऑपरेशन का अनुरोध किया है और उसे थ्रॉटल किया गया है या अनुमति से जुड़ी समस्या की वजह से.
• रेंजिंग की प्रोसेस पूरी होने पर, onRangingResults कॉलबैक ट्रिगर होता है. इसमें नतीजों की एक सूची होती है, जो अनुरोधों की सूची से मेल खाती है. हर अनुरोध के लिए एक नतीजा होता है. नतीजों का क्रम, अनुरोधों के क्रम से मेल खाना ज़रूरी नहीं है. ध्यान दें कि रेंजिंग ऑपरेशन पूरा हो सकता है, लेकिन हर नतीजे में अब भी यह दिख सकता है कि मेज़रमेंट पूरा नहीं हुआ.

रेंजिंग के नतीजों को समझना

onRangingResults कॉलबैक से मिले हर नतीजे को RangingResult ऑब्जेक्ट से तय किया जाता है. हर अनुरोध के लिए, यह तरीका अपनाएं.

1. अनुरोध की पहचान करना

अनुरोध की पहचान करें. इसके लिए, RangingRequest बनाते समय दी गई जानकारी का इस्तेमाल करें: ज़्यादातर मामलों में, ScanResult में दिया गया एमएसी पता, ऐक्सेस पॉइंट की पहचान करता है. getMacAddress() तरीके का इस्तेमाल करके, रेंजिंग के नतीजे से एमएसी पता हासिल किया जा सकता है.

रेंजिंग के नतीजों की सूची, रेंजिंग के अनुरोध में बताए गए पियर (ऐक्सेस पॉइंट) से अलग क्रम में हो सकती है. इसलिए, आपको पियर की पहचान करने के लिए एमएसी पते का इस्तेमाल करना चाहिए, न कि नतीजों के क्रम का.

2. यह पता लगाना कि हर मेज़रमेंट सफल रहा या नहीं

मेज़रमेंट सफल रहा या नहीं, यह पता लगाने के लिए getStatus() तरीके का इस्तेमाल करें. STATUS_SUCCESS के अलावा कोई भी वैल्यू, अनुरोध पूरा न होने का संकेत देती है. इसका मतलब है कि इस नतीजे के अन्य सभी फ़ील्ड (ऊपर दिए गए अनुरोध की पहचान को छोड़कर) अमान्य हैं. साथ ही, इससे जुड़ी get* विधि, IllegalStateException अपवाद के साथ काम नहीं करेगी.

3. हर मेज़रमेंट के नतीजे पाना

हर मेज़रमेंट के लिए, RangingResult का इस्तेमाल करके नतीजे की वैल्यू वापस पाई जा सकती हैं. इसके लिए, get के इन तरीकों का इस्तेमाल करें:

• दूरी, मिमी में, और मेज़रमेंट का स्टैंडर्ड डिविएशन:

  getDistanceMm()

  getDistanceStdDevMm()

• मेज़रमेंट के लिए इस्तेमाल किए गए पैकेट का आरएसएसआई:

  getRssi()

• मिलीसेकंड में वह समय जब मेज़रमेंट लिया गया था. इससे बूट होने के बाद से गुज़रा समय पता चलता है:

  getRangingTimestampMillis()

• मेज़रमेंट की कोशिशों की संख्या और मेज़रमेंट की वह संख्या जो सफल हुई (और जिसके आधार पर दूरी का मेज़रमेंट किया गया है):

  getNumAttemptedMeasurements()

  getNumSuccessfulMeasurements()

• क्लाइंट डिवाइस को 11az NTB मेज़रमेंट के बीच कम से कम और ज़्यादा से ज़्यादा कितना समय इंतज़ार करना चाहिए:

  getMinTimeBetweenNtbMeasurementsMicros() और getMaxTimeBetweenNtbMeasurementsMicros() कम से कम और ज़्यादा से ज़्यादा समय की जानकारी दिखाओ. अगर रेंजिंग के अगले मेज़रमेंट का अनुरोध, कम से कम समय पूरा होने से पहले किया जाता है, तो एपीआई, रेंजिंग के कैश किए गए नतीजे को दिखाता है. अगर रेंजिंग के अगले मेज़रमेंट का अनुरोध, तय समयसीमा खत्म होने के बाद किया जाता है, तो एपीआई, नॉन-ट्रिगर रेंजिंग सेशन को बंद कर देता है. साथ ही, जवाब देने वाले स्टेशन के साथ नया रेंजिंग सेशन शुरू करता है. आपको रेंजिंग के नए सेशन का अनुरोध नहीं करना चाहिए, क्योंकि इससे रेंजिंग मेज़रमेंट में ज़्यादा समय लगता है. 802.11az के नॉन-ट्रिगर आधारित रेंजिंग की सुविधा का पूरा फ़ायदा पाने के लिए, रेंजिंग का अगला अनुरोध ट्रिगर करें. यह अनुरोध, पिछले RangingResult मेज़रमेंट में तय किए गए कम से कम और ज़्यादा से ज़्यादा मेज़रमेंट के बीच ट्रिगर करें.

• आईईईई 802.11az एनटीबी के नतीजे के लिए, रिस्पॉन्डर और इनिशिएटर स्टेशन ने प्रीऐंबल में एलटीएफ़ को दोहराया:

  get80211azResponderTxLtfRepetitionsCount()

  get80211azInitiatorTxLtfRepetitionsCount()

• IEEE 802.11az NTB के नतीजे के लिए, शुरू करने वाले स्टेशन ने कितनी ट्रांसमिट और रिसीव स्पेशल टाइम स्ट्रीम (एसटीएस) का इस्तेमाल किया:

  get80211azNumberOfTxSpatialStreams()

  get80211azNumberOfRxSpatialStreams()

WiFi-RTT के साथ काम करने वाले Android डिवाइस

यहां दी गई टेबल में, वाई-फ़ाई आरटीटी की सुविधा के साथ काम करने वाले कुछ फ़ोन, ऐक्सेस पॉइंट, और खुदरा, वेयरहाउसिंग, और डिस्ट्रिब्यूशन सेंटर के डिवाइस दिए गए हैं. ये जवाब पूरी जानकारी नहीं देते. हमारा सुझाव है कि आप आरटीटी की सुविधा वाले प्रॉडक्ट को यहां लिस्ट करने के लिए, हमसे संपर्क करें.

ऐक्सेस पॉइंट

फ़ोन

खुदरा, वेयरहाउस, और डिस्ट्रिब्यूशन सेंटर के डिवाइस