Android के लिए थ्रेड नेटवर्क SDK टूल

Thread Network के SDK टूल की सुविधा, डिजिटल कीचेन से मिलती-जुलती है. इससे आपके Android ऐप्लिकेशन, Google Play services के साथ Thread नेटवर्क के क्रेडेंशियल शेयर कर पाते हैं. इससे आपके ऐप्लिकेशन, किसी भी स्मार्ट होम नेटवर्क से कोई भी थ्रेड डिवाइस सेट अप कर सकते हैं. ऐसा करने पर, क्रेडेंशियल और उपयोगकर्ता का डेटा सीधे तौर पर ज़ाहिर नहीं होता.

कुछ ही एपीआई कॉल से, ये काम किए जा सकते हैं:

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

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

मुख्य शब्दावली और एपीआई के सिद्धांत

शुरू करने से पहले, इन शब्दों को समझना ज़रूरी है:

• थ्रेड नेटवर्क क्रेडेंशियल: किसी थ्रेड डिवाइस नेटवर्क में शामिल होने के लिए, किसी थ्रेड डिवाइस की ज़रूरत के हिसाब से, थ्रेड नेटवर्क का नाम, नेटवर्क कुंजी, और अन्य प्रॉपर्टी को कोड में बदलने वाली Thread TLV का बाइनरी ब्लॉब.

• पसंदीदा Thread नेटवर्क के क्रेडेंशियल: अपने-आप चुने गए Thread नेटवर्क के क्रेडेंशियल, जिन्हें getPreferredCredentials एपीआई का इस्तेमाल करके, अलग-अलग वेंडर के ऐप्लिकेशन के साथ शेयर किया जा सकता है.

• बॉर्डर एजेंट आईडी: Thread बॉर्डर राऊटर डिवाइस के लिए, 16-बाइट का ग्लोबल यूनीक आईडी. यह आईडी, बॉर्डर राऊटर वेंडर बनाते और मैनेज करते हैं.

• Thread Border राऊटर ऐप्लिकेशन: यह आपका Android ऐप्लिकेशन है. यह नए Thread बॉर्डर राऊटर डिवाइस सेट अप करता है. साथ ही, यह Google Play सेवाओं के लिए, Thread नेटवर्क के क्रेडेंशियल जोड़ता है. आपका ऐप्लिकेशन, जोड़े गए क्रेडेंशियल के आधिकारिक मालिक है और आपके पास उनका ऐक्सेस है.

Thread Network के कई एपीआई टास्क दिखाते हैं, जो एसिंक्रोनस तरीके से पूरा होता है. नतीजे पाने के लिए, कॉलबैक जोड़ने के लिए addOnsuccessListener और addOnFailureListener का इस्तेमाल करें. ज़्यादा जानने के लिए, टास्क दस्तावेज़ देखें.

क्रेडेंशियल का मालिकाना हक और रखरखाव

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

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

बॉर्डर एजेंट को खोजना

क्रेडेंशियल को बॉर्डर एजेंट आईडी के साथ सेव करना ज़रूरी है. आपको यह पक्का करना होगा कि आपके Thread बॉर्डर राऊटर सेट अप के तहत, आपके थ्रेड बॉर्डर राऊटर के बॉर्डर एजेंट आईडी की जानकारी ली जा सकती है.

थ्रेड बॉर्डर राऊटर को थ्रेड नेटवर्क की जानकारी, जैसे कि नेटवर्क का नाम, एक्सटेंडेड पैन आईडी, और बॉर्डर एजेंट आईडी का विज्ञापन देने के लिए, mDNS का इस्तेमाल करना होगा. इन एट्रिब्यूट की txt वैल्यू nn, xp, और id हैं.

Google बॉर्डर राऊटर वाले नेटवर्क के लिए, Google Play services को, इस्तेमाल करने के लिए अपने-आप Google Thread नेटवर्क के क्रेडेंशियल मिलते हैं.

SDK टूल को अपने Android ऐप्लिकेशन से जोड़ना

शुरू करने के लिए, यह तरीका अपनाएं:

1. Google Play सेवाएं सेट अप करें में दिए गए निर्देशों का पालन करें.

2. अपनी build.gradle फ़ाइल में, Google Play सेवाओं की डिपेंडेंसी जोड़ें:

   implementation 'com.google.android.gms:play-services-threadnetwork:16.0.0'
   

3. ज़रूरी नहीं: बॉर्डर राऊटर की जानकारी सेव करने के लिए, BorderAgent डेटा क्लास तय करें. हम इस गाइड में इस डेटा का इस्तेमाल करेंगे:

   data class BorderAgentInfo(
     // Network Name max 16 len
     val networkName: String = "",
     val extPanId: ByteArray = ByteArray(16),
     val borderAgentId: ByteArray = ByteArray(16),
     ...
   )
   

इसके बाद, हम सुझाए गए क्रेडेंशियल जोड़ने और मैनेज करने के सुझाए गए तरीकों के बारे में जानेंगे.

बॉर्डर बॉर्डर के नए सेटअप

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

getPreferredCredentials को कॉल करने से, एक गतिविधि लॉन्च होती है, जिसमें उपयोगकर्ताओं से नेटवर्क अनुरोध को अनुमति देने का संकेत मिलता है. अगर नेटवर्क क्रेडेंशियल, Thread SDK टूल के डिजिटल कीचेन में सेव किए गए हैं, तो क्रेडेंशियल आपके ऐप्लिकेशन पर वापस भेज दिए जाएंगे.

क्रेडेंशियल का अनुरोध करें

उपयोगकर्ता को पसंदीदा क्रेडेंशियल मांगने के लिए:

1. ActivityLauncher का एलान करें:

   private lateinit var preferredCredentialsLauncher: ActivityResultLauncher<IntentSenderRequest>
   

2. गतिविधि के नतीजे को मैनेज करें, इसे ThreadNetworkCredentials के तौर पर दिखाया गया है:

   preferredCredentialsLauncher =
    registerForActivityResult(
      StartIntentSenderForResult()
    ) { result: ActivityResult ->
      if (result.resultCode == RESULT_OK) {
        val threadNetworkCredentials = ThreadNetworkCredentials.fromIntentSenderResultData(result.data!!)
        Log.d("debug", threadNetworkCredentials.networkName)
      } else {
        Log.d("debug", "User denied request.")
      }
    }
   

3. preferredCredentials पर कॉल करें और गतिविधि लॉन्च करें:

   private fun getPreferredThreadNetworkCredentials() {
     ThreadNetwork.getClient(this)
       .preferredCredentials
     .addOnSuccessListener { intentSenderResult ->
       intentSenderResult.intentSender?.let {
         preferredCredentialsLauncher.launch(IntentSenderRequest.Builder(it).build())
         } ?: Log.d("debug", "No preferred credentials found.")
       }
     .addOnFailureListener { e: Exception -> Log.d(TAG, "ERROR: [${e}]") }
   }
   

नया थ्रेड नेटवर्क बनाएं

अगर उपयोगकर्ता के Thread नेटवर्क में, कोई पसंदीदा Thread नेटवर्क क्रेडेंशियल उपलब्ध नहीं है, तो Google Play services में क्रेडेंशियल जोड़ने के लिए, addCredentials एपीआई का इस्तेमाल किया जा सकता है. ऐसा करने के लिए, आपको ThreadBorderAgent बनाना होगा और ThreadNetworkCredentials ऑब्जेक्ट भी देना होगा.

कोई भी नेटवर्क बनाने के लिए, newRandomizeBuilder पर कॉल करें:

val threadCredentials = ThreadNetworkCredentials.newRandomizedBuilder().build()

Thread नेटवर्क का नाम बताने के लिए:

val threadCredentials = ThreadNetworkCredentials.newRandomizedBuilder()
  .setNetworkName("ThreadNetworkSDK")
  .build()

क्रेडेंशियल जोड़ें

Thread नेटवर्क के दूसरे वेंडर को आपके क्रेडेंशियल उपलब्ध कराने के लिए, हमें उन्हें Google Play services में जोड़ना होगा. इससे पहले कि हम अपने नए क्रेडेंशियल जोड़ें, हमें यह भी जानना होगा कि यह थ्रेड नेटवर्क, किस बॉर्डर राऊटर डिवाइस से जुड़ा है.

इस उदाहरण में, हम बॉर्डर एजेंट आईडी से ThreadBorderAgent बनाएंगे और हाल ही में बनाए गए नए Thread नेटवर्क क्रेडेंशियल को पास करेंगे:

private fun addCredentials(borderAgentInfo: BorderAgentInfo, credentialsToBeAdded: ThreadNetworkCredentials) {

  val threadBorderAgent = ThreadBorderAgent.newBuilder(borderAgentInfo.borderAgentId).build()
  Log.d("debug", "border router id:" + threadBorderAgent.id)

  ThreadNetwork.getClient(this)
    .addCredentials(threadBorderAgent, credentialsToBeAdded)
      .addOnSuccessListener {
        Log.d("debug", "Credentials added.")
      }
      .addOnFailureListener { e: Exception -> Log.d(TAG, "ERROR: [${e}]") }
}

फ़ील्ड में बॉर्डर राऊटर का पता लगाना और उन्हें माइग्रेट करना

अगर फ़िलहाल आपके पास इन-फ़ील्ड बॉर्डर राऊटर हैं, तो आप isPreferredCredentials का इस्तेमाल करके यह पता कर सकते हैं कि आपके बॉर्डर राऊटर पसंदीदा नेटवर्क से जुड़े हैं या नहीं. यह एपीआई, उपयोगकर्ता को अनुमति देने के लिए नहीं कहता है. साथ ही, बॉर्डर राऊटर के क्रेडेंशियल की यह जांच करता है कि Google Play की सेवाओं में क्या सेव किया गया है.

isPreferredCredentails मेल न खाने पर 0 और Int datatype के रूप में 1 का मिलान करता है. नतीजों की जांच करने के लिए IsPreferredCredentialsResult का इस्तेमाल किया जा सकता है.

public @interface IsPreferredCredentialsResult {
    int PREFERRED_CREDENTIALS_NOT_FOUND = -1;
    int PREFERRED_CREDENTIALS_NOT_MATCHED = 0;
    int PREFERRED_CREDENTIALS_MATCHED = 1;
}

isPreferredCredentials का इस्तेमाल करने के लिए, आपको पहले ThreadNetworkCredentials ऑब्जेक्ट बनाना होगा. ThreadNetworkCredentials को इंस्टैंशिएट करने के कई तरीके हैं. आगे के चरणों में, हम इन विकल्पों के बारे में जानेंगे.

ऑपरेशनल डेटासेट के मुताबिक थ्रेड नेटवर्क क्रेडेंशियल

कुछ मामलों में, आपका थ्रेड बॉर्डर राऊटर पहले से ही किसी थ्रेड नेटवर्क के साथ सेट अप हो चुका है और आपको यह थ्रेड नेटवर्क Google Play सेवाओं में जोड़ना है. इससे, इसे अन्य वेंडर के साथ शेयर किया जा सकता है. आप किसी रॉ थ्रेड ऐक्टिव ऑपरेशनल डेटासेट टीएलवी सूची से ThreadNetworkCredential इंस्टेंस बना सकते हैं:

1. ऑपरेशनल डेटासेट को ByteArray में बदलें. उदाहरण के लिए:

   val activeDataset =
         "0e080000000000010000000300000f35060004001fffe0020833333333...".dsToByteArray()
   

   fun String.dsToByteArray(): ByteArray {
     return chunked(2).map { it.toInt(16).toByte() }.toByteArray()
   }
   

2. ThreadNetworkCredentials बनाने के लिए, fromActiveOperationalDataset का इस्तेमाल करें. डेटा ट्रांसफ़र होने के बाद, आपको थ्रेड नेटवर्क का नाम, चैनल, और नेटवर्क की दूसरी जानकारी मिलेगी. प्रॉपर्टी की पूरी सूची देखने के लिए, ThreadNetworkक्रेडेंशियल देखें.

   val threadNetworkCredentials =
       ThreadNetworkCredentials.fromActiveOperationalDataset(activeDataset)
   Log.d(
       "threadNetworkCredentials",
       threadNetworkCredentials.channel.toString() + " - " + threadNetworkCredentials.networkName)
   

3. isPreferredCredentials एपीआई को कॉल करें और ThreadNetworkCredentials पास करें.

   ThreadNetwork.getClient(this)
   .isPreferredCredentials(threadNetworkCredentials)
   .addOnSuccessListener { result ->
     when (result) {
       IsPreferredCredentialsResult.PREFERRED_CREDENTIALS_NOT_MATCHED ->
           Log.d("isPreferredCredentials", "Credentials not matched.")
       IsPreferredCredentialsResult.PREFERRED_CREDENTIALS_MATCHED ->
           Log.d("isPreferredCredentials", "Credentials matched.")
     }
   }
   .addOnFailureListener { e: Exception -> Log.d("isPreferredCredentials", "ERROR: [${e}]") }
   

बॉर्डर एजेंट के ज़रिए Thread नेटवर्क के क्रेडेंशियल

बॉर्डर एजेंट आईडी, खास तौर पर बॉर्डर राऊटर डिवाइस की पहचान करता है. getCredentialsByBorderAgent एपीआई का इस्तेमाल करने के लिए, आपको सबसे पहले ThreadBorderAgent ऑब्जेक्ट बनाना होगा. साथ ही, बॉर्डर एजेंट आईडी को पास करना होगा.

ThreadBorderAgent ऑब्जेक्ट बनाने के बाद, getCredentialsByBorderAgent को कॉल करें. अगर क्रेडेंशियल सेव कर लिए गए हैं, तो देखें कि उन्हें प्राथमिकता दी गई है या नहीं.

private fun isPreferredThreadNetworkByBorderAgent(borderAgentInfo: BorderAgentInfo) {

  val threadBorderAgent = ThreadBorderAgent.newBuilder(borderAgentInfo.borderAgentId).build()
  Log.d("debug", "border router id:" + threadBorderAgent.id)

  var isPreferred = IsPreferredCredentialsResult.PREFERRED_CREDENTIALS_NOT_FOUND
  var borderAgentCredentials: ThreadNetworkCredentials?
  val taskByBorderAgent = ThreadNetwork.getClient(this)
  taskByBorderAgent
      .getCredentialsByBorderAgent(threadBorderAgent)
      .addOnSuccessListener { result: ThreadNetworkCredentialsResult ->
        borderAgentCredentials = result.credentials
        result.credentials?.let {
          taskByBorderAgent.isPreferredCredentials(it).addOnSuccessListener { result ->
            isPreferred = result
          }
        }
      }
      .addOnFailureListener { e: Exception -> Log.d(TAG, "ERROR: [${e}]") }
}

Extended (पैन) आईडी के साथ थ्रेड के नेटवर्क क्रेडेंशियल

getPreferredCredentials की तरह, उपयोगकर्ता को बॉर्डर राऊटर के एक्सटेंडेड पैन आईडी में मौजूद क्रेडेंशियल का इस्तेमाल करने के लिए भी कहा जा सकता है. getCredentialsByExtendedPanId एक IntentSender दिखाता है. हालांकि, उपयोगकर्ता की अनुमति मिलने पर गतिविधि के नतीजे में एक ThreadNetworkCredentials ऑब्जेक्ट होता है.

private fun getCredentialsByExtPanId(borderAgentInfo: BorderAgentInfo) {
  ThreadNetwork.getClient(this)
    .getCredentialsByExtendedPanId(borderAgentInfo.extPanId)
    .addOnSuccessListener { intentSenderResult ->
      intentSenderResult.intentSender?.let {
        preferredCredentialsLauncher.launch(IntentSenderRequest.Builder(it).build())
      }
        ?: Log.d("debug", "No credentials found.")
    }
    .addOnFailureListener { e: Exception -> Log.d(TAG, "ERROR: [${e}]") }
}

क्रेडेंशियल हटाएं

जब आपका बॉर्डर राऊटर डिवाइस, आपके होम या फ़ैक्ट्री रीसेट से हटा दिया जाता है, तो आपको Google Play सेवाओं से अपना Thread नेटवर्क हटाना होगा.

private fun removeCredentials(borderAgentInfo: BorderAgentInfo) {

  val threadBorderAgent = ThreadBorderAgent.newBuilder(borderAgentInfo.borderAgentId).build()
  Log.d("debug", "border router id:" + threadBorderAgent.id)

  ThreadNetwork.getClient(this)
      .removeCredentials(threadBorderAgent)
      .addOnSuccessListener { Log.d("debug", "Credentials removed.") }
      .addOnFailureListener { e: Exception -> Log.d(TAG, "ERROR: [${e}]") }
}

रिसॉर्स

Thread Network के SDK टूल के बारे में ज़्यादा जानने के लिए, एपीआई का रेफ़रंस देखें.