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

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

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

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

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

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

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

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

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

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

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

IEEE 802.11az NTB रेंजिंग की सुविधा, Android 15 (एपीआई लेवल 35) और उसके बाद के वर्शन वाले डिवाइसों पर उपलब्ध है. इसका मतलब है कि अगर डिवाइस पर IEEE 802.11az NTB initiator mode काम करता है (इसका पता 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 की अनुमति होनी चाहिए.
• ऐप्लिकेशन के दिखने या फ़ोरग्राउंड सेवा के तौर पर काम करने के दौरान, ऐप्लिकेशन को ऐक्सेस पॉइंट की रेंज के बारे में क्वेरी करनी चाहिए. ऐप्लिकेशन, बैकग्राउंड में जगह की जानकारी ऐक्सेस नहीं कर सकता.
• ऐक्सेस पॉइंट में, IEEE 802.11-2016 एफ़टीएम स्टैंडर्ड या IEEE 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 API का इस्तेमाल करें:

context.packageManager.hasSystemFeature(PackageManager.FEATURE_WIFI_RTT)

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

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

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

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

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

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

उदाहरण के लिए, किसी अनुरोध में 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 NTB रेंजिंग की सुविधा वाले डिवाइस, एपी की क्षमता के आधार पर 802.11mc या 802.11az रेंजिंग में से किसी एक का इस्तेमाल करते हैं. अगर एपी, दोनों का इस्तेमाल करता है, तो डिवाइस डिफ़ॉल्ट रूप से 802.11az का इस्तेमाल करता है. IEEE 802.11az के साथ काम न करने वाले डिवाइस, IEEE 802.11mc प्रोटोकॉल का इस्तेमाल करके सभी रेंजिंग करते हैं.

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

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

कोई ऐप्लिकेशन, 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 में दिया गया MAC पता, ऐक्सेस पॉइंट की पहचान करता है. getMacAddress() के तरीके का इस्तेमाल करके, रेंजिंग के नतीजे से MAC पता पाया जा सकता है.

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

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 एनटीबी नतीजे के लिए किया:

  get80211azNumberOfTxSpatialStreams()

  get80211azNumberOfRxSpatialStreams()

ऐसे Android डिवाइस जिनमें WiFi-RTT की सुविधा काम करती है

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

ऐक्सेस पॉइंट

फ़ोन

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