Thread Network के SDK टूल की सुविधा, डिजिटल कीचेन से मिलती-जुलती है. इससे आपके Android ऐप्लिकेशन, Google Play services के साथ Thread नेटवर्क के क्रेडेंशियल शेयर कर पाते हैं. इससे आपके ऐप्लिकेशन, किसी भी स्मार्ट होम नेटवर्क से कोई भी थ्रेड डिवाइस सेट अप कर सकते हैं. ऐसा करने पर, क्रेडेंशियल और उपयोगकर्ता का डेटा सीधे तौर पर ज़ाहिर नहीं होता.
कुछ ही एपीआई कॉल से, ये काम किए जा सकते हैं:
- Google Play सेवाओं से, थ्रेड नेटवर्क के पसंदीदा क्रेडेंशियल का अनुरोध करें.
- नए बॉर्डर राऊटर सेट अप करें और Google Play की सेवाओं में अपने Thread नेटवर्क के क्रेडेंशियल जोड़ें.
- अगर आपके पास पहले से ही इन-फ़ील्ड बॉर्डर राऊटर हैं, तो आप देख सकते हैं कि क्या आपके बॉर्डर राऊटर पसंदीदा नेटवर्क में हैं और ज़रूरी होने पर उन्हें माइग्रेट कर सकते हैं.
इसमें कई उपयोगकर्ताओं और डेवलपर के अनुभवों पर विचार किया जा सकता है. हम गाइड में दी गई ज़्यादातर सुविधाओं के साथ-साथ, मुख्य सुविधाओं और सुझाए गए इस्तेमाल के बारे में भी बात करेंगे.
मुख्य शब्दावली और एपीआई के सिद्धांत
शुरू करने से पहले, इन शब्दों को समझना ज़रूरी है:
थ्रेड नेटवर्क क्रेडेंशियल: किसी थ्रेड डिवाइस नेटवर्क में शामिल होने के लिए, किसी थ्रेड डिवाइस की ज़रूरत के हिसाब से, थ्रेड नेटवर्क का नाम, नेटवर्क कुंजी, और अन्य प्रॉपर्टी को कोड में बदलने वाली 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 ऐप्लिकेशन से जोड़ना
शुरू करने के लिए, यह तरीका अपनाएं:
Google Play सेवाएं सेट अप करें में दिए गए निर्देशों का पालन करें.
अपनी
build.gradle
फ़ाइल में, Google Play सेवाओं की डिपेंडेंसी जोड़ें:implementation 'com.google.android.gms:play-services-threadnetwork:16.0.0'
ज़रूरी नहीं: बॉर्डर राऊटर की जानकारी सेव करने के लिए,
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 टूल के डिजिटल कीचेन में सेव किए गए हैं, तो क्रेडेंशियल आपके ऐप्लिकेशन पर वापस भेज दिए जाएंगे.
क्रेडेंशियल का अनुरोध करें
उपयोगकर्ता को पसंदीदा क्रेडेंशियल मांगने के लिए:
ActivityLauncher
का एलान करें:private lateinit var preferredCredentialsLauncher: ActivityResultLauncher<IntentSenderRequest>
गतिविधि के नतीजे को मैनेज करें, इसे
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.") } }
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
इंस्टेंस बना सकते हैं:
ऑपरेशनल डेटासेट को
ByteArray
में बदलें. उदाहरण के लिए:val activeDataset = "0e080000000000010000000300000f35060004001fffe0020833333333...".dsToByteArray()
fun String.dsToByteArray(): ByteArray { return chunked(2).map { it.toInt(16).toByte() }.toByteArray() }
ThreadNetworkCredentials
बनाने के लिए,fromActiveOperationalDataset
का इस्तेमाल करें. डेटा ट्रांसफ़र होने के बाद, आपको थ्रेड नेटवर्क का नाम, चैनल, और नेटवर्क की दूसरी जानकारी मिलेगी. प्रॉपर्टी की पूरी सूची देखने के लिए, ThreadNetworkक्रेडेंशियल देखें.val threadNetworkCredentials = ThreadNetworkCredentials.fromActiveOperationalDataset(activeDataset) Log.d( "threadNetworkCredentials", threadNetworkCredentials.channel.toString() + " - " + threadNetworkCredentials.networkName)
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 टूल के बारे में ज़्यादा जानने के लिए, एपीआई का रेफ़रंस देखें.