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 TLV का बाइनरी ब्लॉब. इसमें Thread नेटवर्क का नाम, नेटवर्क की कुंजी, और अन्य प्रॉपर्टी शामिल होती हैं. Thread नेटवर्क में शामिल होने के लिए, Thread डिवाइस को इन प्रॉपर्टी की ज़रूरत होती है.

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

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

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

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

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

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

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

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

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

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

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

अपने Android ऐप्लिकेशन में SDK टूल को इंटिग्रेट करना

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

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

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

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

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

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

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

Thread के नए बॉर्डर राऊटर (टीबीआर) सेट अप करना

बॉर्डर राऊटर के लिए नया नेटवर्क बनाने से पहले, यह ज़रूरी है कि आप Thread नेटवर्क के पसंदीदा क्रेडेंशियल का इस्तेमाल करें. इससे यह पक्का होता है कि 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 के चालू क्रेडेंशियल उपलब्ध नहीं हैं, तो Google Play services में क्रेडेंशियल जोड़ने के लिए, addCredentials एपीआई का इस्तेमाल किया जा सकता है. इसके लिए, आपको 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 पसंदीदा नेटवर्क से जुड़े हैं या नहीं. यह एपीआई, उपयोगकर्ता से अनुमति का अनुरोध नहीं करता. साथ ही, Google Play services में सेव किए गए क्रेडेंशियल के हिसाब से, border router क्रेडेंशियल की जांच करता है.

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