डिवाइसों के बीच की रेंज

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

रेंजिंग मॉड्यूल, इन टेक्नोलॉजी के साथ काम करता है:

रेंजिंग की सुविधाएं और उनकी उपलब्धता

RangingManager क्लास, ऐप्लिकेशन को लोकल डिवाइस पर काम करने वाली रेंजिंग टेक्नोलॉजी के साथ-साथ, हर टेक्नोलॉजी की उपलब्धता और क्षमताओं की जानकारी भी उपलब्ध कराती है. ऐप्लिकेशन, Callback के लिए रजिस्टर कर सकते हैं, ताकि वे काम करने वाली किसी भी टेक्नोलॉजी की उपलब्धता या सुविधाओं में हुए किसी भी बदलाव के बारे में अपडेट पा सकें.

डिवाइस की भूमिकाएं

रेंजिंग सेशन में हिस्सा लेने वाले डिवाइस को शुरुआत करने वाला या जवाब देने वाला होना चाहिए. शुरुआत करने वाला डिवाइस, एक या एक से ज़्यादा जवाब देने वाले डिवाइसों के साथ रेंजिंग सेशन शुरू करता है. जवाब देने वाला डिवाइस, एक बार में सिर्फ़ एक शुरू करने वाले डिवाइस के रेंजिंग अनुरोधों का जवाब देता है. RangingPreference क्लास की मदद से, रेंजिंग सेशन में किसी डिवाइस की भूमिका तय की जा सकती है.

अलग-अलग तरह के सेशन

डिवाइसों के बीच रेंजिंग सेशन शुरू करते समय, सेशन के लिए पैरामीटर एक्सचेंज करने के लिए, अक्सर आउट-ऑफ़-बैंड (ओओबी) डेटा ट्रांसपोर्ट सेट अप करना ज़रूरी होता है.

रेंजिंग मॉड्यूल, आपके लिए ओओबी बातचीत को मैनेज कर सकता है. हालांकि, यह पसंद के मुताबिक ओओबी लागू करने की सुविधा भी देता है.

पहली इमेज. सेशन टाइप के लिए, बाहर निकलने का फ़्लो.

डिफ़ॉल्ट रूप से, ओओबी (डिवाइस के बाहर) पुष्टि करने की सुविधा लागू करना

इस सेशन टाइप (RANGING_SESSION_OOB) में, रेंजिंग सेशन शुरू करने के लिए, रेंजिंग मॉड्यूल, ओयूबी नेगोशिएशन को मैनेज करता है. यह ऐप्लिकेशन की दी गई रेंजिंग सेटिंग के आधार पर, सही पैरामीटर चुनता है. साथ ही, यह दोनों डिवाइसों पर काम करने वाली सही टेक्नोलॉजी का इस्तेमाल करता है. इस सेशन टाइप में स्टैंडर्ड OOB specification का इस्तेमाल किया जाता है.

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

कस्टम ओओबी लागू करना

इस सेशन टाइप (RANGING_SESSION_RAW) में, ऐप्लिकेशन रेंजिंग मॉड्यूल के ओओबी फ़्लो को बायपास करता है. साथ ही, अपने ओओबी नेगोशिएशन और पैरामीटर को मैनेज करता है. इसका मतलब है कि ऐप्लिकेशन को यह तय करना होगा कि पीयर डिवाइस पर कौनसी टेक्नोलॉजी काम करती हैं, रेंजिंग पैरामीटर के बारे में बातचीत करें, और रेंजिंग सेशन शुरू करें.

रेंजिंग की प्राथमिकताएं

रेंजिंग सेशन के लिए, अपनी पसंद के पैरामीटर तय करने के लिए, RangingPreference ऑब्जेक्ट का इस्तेमाल करें. इसमें ये शामिल हैं:

  • डिवाइस की भूमिका. इससे पता चलता है कि डिवाइस, कॉल शुरू करने वाला है या रिस्पॉन्स देने वाला.
  • रेंजिंग कॉन्फ़िगरेशन. RangingConfig ऑब्जेक्ट से, रेंजिंग सेशन का टाइप और रेंजिंग सेशन शुरू करने के लिए ज़रूरी अन्य पैरामीटर के बारे में पता चलता है.
  • सेशन कॉन्फ़िगरेशन. SessionConfig ऑब्जेक्ट, रेंजिंग सेशन पर लागू किए जाने वाले पैरामीटर तय करता है. जैसे, मेज़रमेंट की सीमा, सेंसर फ़्यूज़न, जियोफ़ेंस कॉन्फ़िगरेशन वगैरह.

रेंजिंग की अनुमति

रेंजिंग मॉड्यूल को रेंजिंग की सभी मौजूदा और आने वाली टेक्नोलॉजी को ऐक्सेस करने के लिए, एक नई यूनिफ़ाइड अनुमति (android.permission.RANGING) की ज़रूरत होती है. यह अनुमति NEARBY_DEVICES_PERMISSIONS सूची में शामिल है.

<uses-permission android:name="android.permission.RANGING" />

पाबंदियां और सीमाएं

रेंजिंग मॉड्यूल कई वजहों से रेंजिंग पर पाबंदी लगा सकता है. इनमें ये वजहें भी शामिल हैं:

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

रेंजिंग मॉड्यूल की ये सीमाएं भी हैं:

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

रेंजिंग सेशन करना

रेंजिंग मॉड्यूल का इस्तेमाल करके रेंजिंग सेशन करने के लिए, यह तरीका अपनाएं:

  1. पुष्टि करें कि सभी डिवाइस Android 16 या इसके बाद के वर्शन पर काम कर रहे हों.
  2. ऐप्लिकेशन के मेनिफ़ेस्ट में, android.permission.RANGING अनुमति का अनुरोध करें.
  3. रेंजिंग टेक्नोलॉजी की सुविधाओं और उपलब्धता का आकलन करें.
  4. रेंजिंग ऑपरेशन के लिए, पीयर डिवाइस ढूंढें.
  5. रेंजिंग सेशन टाइप में बताए गए किसी भी सेशन टाइप का इस्तेमाल करके, आउट-ऑफ-बैंड एक्सचेंज के लिए कनेक्शन सेट अप करें.
  6. रेंजिंग शुरू करना और रेंजिंग डेटा को लगातार हासिल करना.
  7. रेंजिंग सेशन को खत्म करें.

नीचे दिए गए कोड सैंपल में, इन चरणों को शुरू करने वाले और जवाब देने वाले, दोनों की भूमिका के लिए दिखाया गया है.

Kotlin

class RangingApp {

    // Starts a ranging session on the initiator side.
    fun startRangingInitiator(
        context: Context,
        deviceHandle: DeviceHandle,
        executor: Executor,
        callback: RangingSessionCallback
    ) {

        // Get the RangingManager which is the entry point for ranging module.
        val manager = context.getSystemService(RangingManager::class.java)

        // Create a new RangingSession using the provided executor and callback.
        val session = manager.createRangingSession(executor, callback)

        // Create an OobInitiatorRangingConfig, which specifies the ranging parameters for
        // the initiator role.
        val config = OobInitiatorRangingConfig.Builder()
            .setFastestRangingInterval(Duration.ofMillis(100))
            .setSlowestRangingInterval(Duration.ofMillis(5000))
            .setRangingMode(RANGING_MODE_AUTO)
            .setSecurityLevel(SECURITY_LEVEL_BASIC)
            .addDeviceHandle(deviceHandle)
            .build()

        // Create a RangingPreference, which specifies the role (initiator) and
        // configuration for the ranging session.
        val preference =
            RangingPreference.Builder(DEVICE_ROLE_INITIATOR, config).build()

        // Start ranging session.
        session.start(preference)

        // If successful, the ranging data will be sent through callback#onResults

        // Stop ranging session
        session.stop()
    }

    // Starts a ranging session on the responder side.
    fun startRangingResponder(
        context: Context,
        deviceHandle: DeviceHandle,
        executor: Executor,
        callback: RangingSessionCallback
    ) {

        // Get the RangingManager which is the entry point for ranging module.
        val manager = context.getSystemService(RangingManager::class.java)

        // Create a new RangingSession using the provided executor and callback.
        val session = manager.createRangingSession(executor, callback)

        // Create an OobResponderRangingConfig, which specifies the ranging parameters for
        // the responder role.
        val config = OobResponderRangingConfig.Builder(deviceHandle).build()

        // Create a RangingPreference, which specifies the role (responder) and
        // configuration for the ranging session.
        val preference =
            RangingPreference.Builder(DEVICE_ROLE_RESPONDER, config).build()

        // Start the ranging session.
        session.start(preference)

        // Stop the ranging session
        session.stop()
    }
}

Java

public class RangingApp {

    // Starts a ranging session on the initiator side.
    void startRangingInitiator(Context context, DeviceHandle deviceHandle, Executor executor, RangingSessionCallback callback) {

        // Get the RangingManager which is the entry point for ranging module.
        RangingManager manager = context.getSystemService(RangingManager.class);

        // Create a new RangingSession using the provided executor and callback.
        RangingSession session = manager.createRangingSession(executor, callback);

        // Create an OobInitiatorRangingConfig, which specifies the ranging parameters for
        // the initiator role.
        OobInitiatorRangingConfig config = new OobInitiatorRangingConfig.Builder()
                .setFastestRangingInterval(Duration.ofMillis(100))
                .setSlowestRangingInterval(Duration.ofMillis(5000))
                .setRangingMode(RANGING_MODE_AUTO)
                .setSecurityLevel(SECURITY_LEVEL_BASIC)
                .addDeviceHandle(deviceHandle)
                .build();

        // Create a RangingPreference, which specifies the role (initiator) and
        // configuration for the ranging session.
        RangingPreference preference =
                new RangingPreference.Builder(DEVICE_ROLE_INITIATOR, config).build();

        // Start ranging session.
        session.start(preference);

        // If successful, the ranging data will be sent through callback#onResults

        // Stop ranging session
        session.stop();

    }

    // Starts a ranging session on the responder side.
    void startRangingResponder(Context context,  DeviceHandle deviceHandle, Executor executor, RangingSessionCallback callback) {

        // Get the RangingManager which is the entry point for ranging module.
        RangingManager manager = context.getSystemService(RangingManager.class);

        // Create a new RangingSession using the provided executor and callback.
        RangingSession session = manager.createRangingSession(executor, callback);

        // Create an OobResponderRangingConfig, which specifies the ranging parameters for
        // the responder role.
        OobResponderRangingConfig config = new OobResponderRangingConfig.Builder(  deviceHandle).build();

        // Create a RangingPreference, which specifies the role (responder) and
        // configuration for the ranging session.
        RangingPreference preference =
                new RangingPreference.Builder(DEVICE_ROLE_RESPONDER, config).build();

        // Start the ranging session.
        session.start(preference);

        // Stop the ranging session
        session.stop();
    }
}

सैंपल ऐप्लिकेशन

रेंजिंग मॉड्यूल का इस्तेमाल करने के तरीके के बारे में पूरी जानकारी के लिए, AOSP में सैंपल ऐप्लिकेशन देखें. इस सैंपल ऐप्लिकेशन में, रेंजिंग मॉड्यूल के साथ काम करने वाली सभी रेंजिंग टेक्नोलॉजी शामिल हैं. साथ ही, इसमें काम करने वाले दोनों तरह के सेशन के लिए फ़्लो शामिल हैं.