Android के लिए Thread Network का SDK टूल

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

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

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

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

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

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

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

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

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

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

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

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

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

ऐप्लिकेशन के मालिक के तौर पर, हमारा सुझाव है कि TBR नेटवर्क अपडेट होने पर, Google Play services में सेव किए गए क्रेडेंशियल अप-टू-डेट रखें. इसका मतलब है कि ज़रूरत पड़ने पर क्रेडेंशियल जोड़ना, border router के Thread नेटवर्क के क्रेडेंशियल बदलने पर क्रेडेंशियल अपडेट करना, और TBR को हटाने या फ़ैक्ट्री रीसेट करने पर क्रेडेंशियल हटाना.

बॉर्डर एजेंट डिस्कवरी

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

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

Google Thread Border Router (gTBR) वाले नेटवर्क के लिए, Google Play services को Google Thread नेटवर्क के क्रेडेंशियल अपने-आप मिल जाते हैं.

एसडीके को अपने Android ऐप्लिकेशन में इंटिग्रेट करना

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

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

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

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

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

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

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

नए थ्रेड बॉर्डर राऊटर सेटअप

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

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. अगर आपको नया TBR सेट अप करना है, तो हमारा सुझाव है कि आप preferredCredentials को कॉल करें और गतिविधि लॉन्च करें. इस कॉल से यह पक्का किया जाएगा कि आपका नया TBR, फ़ोन में पसंदीदा के तौर पर पहले से सेव किए गए क्रेडेंशियल का इस्तेमाल करेगा. इससे अलग-अलग टीबीआर को एक ही नेटवर्क पर इस्तेमाल करने में मदद मिलेगी.

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

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

   // Creates the IntentSender result launcher for the getAllActiveCredentials API
   private val getAllActiveCredentialsLauncher =
     registerForActivityResult(
       StartIntentSenderForResult()
     ) { result: ActivityResult ->
       if (result.resultCode == RESULT_OK) {
         val activeCredentials: List<ThreadNetworkCredentials> =
           ThreadNetworkCredentials.parseListFromIntentSenderResultData(
             result.data!!
           )
         // Use the activeCredentials list
       } else {
         // The user denied to share!
       }
     }
   
   // Invokes the getAllActiveCredentials API and starts the dialog activity with the returned
   // IntentSender
   threadNetworkClient
   .getAllActiveCredentials()
   .addOnSuccessListener { intentSenderResult: IntentSenderResult ->
     val intentSender = intentSenderResult.intentSender
     if (intentSender != null) {
       getAllActiveCredentialsLauncher.launch(
         IntentSenderRequest.Builder(intentSender).build()
       )
     } else {
       // No active network credentials found!
     }
   }
   // Handles the failure
   .addOnFailureListener { e: Exception ->
     // Handle the exception
   }
   

नया Thread नेटवर्क बनाना

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

कोई रैंडम नेटवर्क बनाने के लिए, newRandomizeBuilder को कॉल करें:

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

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

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

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

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

इस उदाहरण में, हम बॉर्डर एजेंट आईडी से 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}]") }
}

इन-फ़ील्ड border router का पता लगाना और उन्हें माइग्रेट करना

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

isPreferredCredentials, Int डेटा टाइप के तौर पर, मैच न होने पर 0 और मैच होने पर 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 को इंस्टैंशिएट करने के कई तरीके हैं. अगले चरणों में, हम इन विकल्पों के बारे में जानेंगे.

ऑपरेशनल डेटासेट के हिसाब से Thread नेटवर्क के क्रेडेंशियल

ऐसा हो सकता है कि आपका TBR पहले से ही किसी Thread नेटवर्क के साथ सेट अप किया गया हो और आपको इस Thread नेटवर्क को Google Play services में जोड़ना हो, ताकि इसे अन्य वेंडर के साथ शेयर किया जा सके. Thread Active Operational Dataset TLV की रॉ लिस्ट से, ThreadNetworkCredential इंस्टेंस बनाया जा सकता है:

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

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

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

2. ThreadNetworkCredentials बनाने के लिए, fromActiveOperationalDataset का इस्तेमाल करें. ऐसा करने पर, आपको Thread नेटवर्क का नाम, चैनल, और नेटवर्क की अन्य जानकारी मिल जाएगी. प्रॉपर्टी की पूरी सूची देखने के लिए, ThreadNetworkCredentials पर जाएं.

   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 नेटवर्क के क्रेडेंशियल

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

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

getPreferredCredentials की तरह ही, TBR के एक्सटेंडेड पैन आईडी से क्रेडेंशियल के लिए भी उपयोगकर्ता को प्रॉम्प्ट किया जा सकता है. 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}]") }
}

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

जब आपके border router डिवाइस को आपके होम से हटा दिया जाता है या फ़ैक्ट्री रीसेट कर दिया जाता है, तो आपको Google Play services से उसका 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 के बारे में ज़्यादा जानने के लिए, एपीआई का रेफ़रंस देखें.