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

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

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

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

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

मुख्य शब्दावली और API कॉन्सेप्ट

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

   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}]") }
   }
   

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

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

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

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

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

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

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

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

इस उदाहरण में, हम बॉर्डर एजेंट आईडी से एक ThreadBorderAgent बनाएंगे. साथ ही, उन थ्रेड थ्रेड के नए क्रेडेंशियल पास करेंगे जिन्हें आपने अभी बनाया है:

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 और मिलान के लिए 1 दिखाता है, Int डेटाटाइप के तौर पर. नतीजों की जांच करने के लिए IsPreferredCredentialsResultका इस्तेमाल किया जा सकता है.

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

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

ऑपरेशनल डेटासेट के आधार पर थ्रेड नेटवर्क के क्रेडेंशियल

कुछ मामलों में, आपका Thread बॉर्डर राऊटर पहले से ही किसी थ्रेड नेटवर्क के साथ सेट अप हो गया है. आपको यह थ्रेड नेटवर्क, Google Play सेवाओं में जोड़ना होगा, ताकि इसे दूसरे वेंडर के साथ शेयर किया जा सके. किसी रॉ थ्रेड ऐक्टिव ऑपरेशनल डेटासेट की TLV सूची से आप 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}]") }
   

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

बॉर्डर एजेंट आईडी, बॉर्डर राऊटर डिवाइस की खास तौर पर पहचान करता है. 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}]") }
}

एक्सटेंडेड पैन आईडी के हिसाब से, थ्रेड के नेटवर्क के क्रेडेंशियल

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 नेटवर्क के SDK टूल के बारे में ज़्यादा जानने के लिए, एपीआई का रेफ़रंस देखें.