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

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

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

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

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

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

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

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

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

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

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

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

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

• दूरी का पता लगाने का अनुरोध करने वाले डिवाइस के हार्डवेयर में, 802.11-2016 एफ़टीएम स्टैंडर्ड या 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. यह देखना कि वाई-फ़ाई आरटीटी की सुविधा उपलब्ध है या नहीं

ऐसा हो सकता है कि डिवाइस पर वाई-फ़ाई आरटीटी की सुविधा मौजूद हो, लेकिन वह उपलब्ध न हो. ऐसा इसलिए, क्योंकि उपयोगकर्ता ने वाई-फ़ाई बंद कर दिया है. हार्डवेयर और फ़र्मवेयर की क्षमताओं के आधार पर, कुछ डिवाइसों पर वाई-फ़ाई आरटीटी की सुविधा काम नहीं करती. ऐसा तब होता है, जब 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 की सुविधा वाले उन डिवाइसों की सूची बनाई जाती है जिनके लिए रेंज का अनुरोध किया जाता है. रेंजिंग के एक अनुरोध में, कई ऐक्सेस पॉइंट या 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 ऑब्जेक्ट में, आईईईई 802.11mc (is80211mcResponder()) और आईईईई 802.11az, दोनों के साथ काम करने वाले एपी शामिल हो सकते हैं. ये एपी, नॉन-ट्रिगर पर आधारित रेंजिंग (is80211azNtbResponder()) के साथ काम करते हैं. IEEE 802.11az एनटीबी रेंजिंग के साथ काम करने वाले डिवाइस, एपी की क्षमता के आधार पर 802.11mc या 802.11az रेंजिंग का इस्तेमाल करते हैं. अगर एपी दोनों के साथ काम करता है, तो डिफ़ॉल्ट रूप से 802.11az का इस्तेमाल किया जाता है. IEEE 802.11az के साथ काम न करने वाले डिवाइस, IEEE 802.11mc प्रोटोकॉल का इस्तेमाल करके रेंजिंग की सभी प्रोसेस पूरी करते हैं.

इसी तरह, रेंजिंग का अनुरोध, मैक पते या PeerHandle का इस्तेमाल करके, Wi-Fi Aware की सुविधा वाले पीयर को जोड़ सकता है. इसके लिए, क्रमशः 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 एनटीबी मेज़रमेंट के बीच कम से कम और ज़्यादा से ज़्यादा कितनी देर इंतज़ार करना होगा:

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

• लॉन्ग ट्रेनिंग फ़ील्ड (एलटीएफ़) के दोहराव, जिनका इस्तेमाल जवाब देने वाले और शुरू करने वाले स्टेशन ने IEEE 802.11az एनटीबी के नतीजे के लिए प्रस्तावना में किया है:

  get80211azResponderTxLtfRepetitionsCount()

  get80211azInitiatorTxLtfRepetitionsCount()

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

  get80211azNumberOfTxSpatialStreams()

  get80211azNumberOfRxSpatialStreams()

वाई-फ़ाई आरटीटी की सुविधा वाले Android डिवाइस

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

ऐक्सेस पॉइंट

फ़ोन

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