Thread Network SDK มีฟังก์ชันการทํางานที่คล้ายกับ Keychain ดิจิทัล ซึ่งช่วยให้แอป Android ของคุณแชร์ข้อมูลรับรองของเครือข่าย Thread กับบริการ Google Play ได้ การตั้งค่านี้ช่วยให้อุปกรณ์ตั้งค่าอุปกรณ์เทรดจากระบบนิเวศบ้านอัจฉริยะได้แบบไม่ต้องเปิดเผยข้อมูลรับรองและข้อมูลผู้ใช้โดยตรง
ด้วยการเรียก API เพียงไม่กี่ครั้ง คุณสามารถทําสิ่งต่อไปนี้
- ขอข้อมูลเข้าสู่ระบบเครือข่ายเทรดที่ต้องการจากบริการ Google Play
- ตั้งค่าเราเตอร์เส้นขอบใหม่ และเพิ่มข้อมูลเข้าสู่ระบบเครือข่ายเทรดไปยังบริการ Google Play
- หากคุณมีเราเตอร์ Border Field อยู่แล้ว คุณสามารถตรวจสอบว่าเราเตอร์พรมแดนอยู่ในเครือข่ายที่ต้องการหรือไม่ และหากจําเป็น
มีเส้นทางของผู้ใช้และนักพัฒนาซอฟต์แวร์มากมายที่ต้องพิจารณา เราจะพูดถึงส่วนใหญ่ ในคู่มือนี้ รวมไปถึงคุณลักษณะสําคัญอื่นๆ และการใช้งานที่แนะนํา
16.0.0
คําศัพท์ที่สําคัญและแนวคิดของ API
ก่อนเริ่มต้นใช้งาน คุณควรทําความเข้าใจคําศัพท์ต่อไปนี้
ข้อมูลเข้าสู่ระบบเครือข่ายของเทรด: BLOB แบบไบนารีของ TLV ของเทรดที่เข้ารหัส ชื่อเครือข่ายเทรด คีย์เครือข่าย และพร็อพเพอร์ตี้อื่นๆ ที่อุปกรณ์เทรดกําหนดไว้เพื่อให้เข้าร่วมเครือข่ายเทรดที่ระบุได้
ข้อมูลเข้าสู่ระบบเครือข่ายเทรดที่ต้องการ: ข้อมูลเข้าสู่ระบบเครือข่ายเทรดที่เลือกโดยอัตโนมัติซึ่งแชร์กับแอปของผู้ให้บริการที่แตกต่างกันได้โดยใช้
getPreferredCredentials
APIรหัสตัวแทนชายแดน: รหัสที่ไม่ซ้ํากันทั่วโลก 16 ไบต์สําหรับอุปกรณ์เราเตอร์เทรด รหัสนี้สร้างและจัดการโดยผู้ให้บริการเราเตอร์เส้นขอบ
แอปการตั้งค่า Thread Border Router: คือแอป Android ที่ตั้งค่าอุปกรณ์ Thread Border Router ใหม่และเพิ่มข้อมูลรับรองของเครือข่าย Thread ลงในบริการ Google Play แอปของคุณเป็นเจ้าของที่เชื่อถือได้ของ ข้อมูลเข้าสู่ระบบที่เพิ่มเข้ามาและมีสิทธิ์เข้าถึงข้อมูลเหล่านั้น
Thread Network API จํานวนมากจะส่งคืน Task ที่ไม่พร้อมกัน คุณสามารถใช้ addOnSuccessListener และ addOnFailureListener เพื่อลงทะเบียนการเรียกกลับเพื่อรอรับผลลัพธ์ หากต้องการเรียนรู้เพิ่มเติม โปรดดูเอกสาร งาน
ข้อมูลเข้าสู่ระบบและการเป็นเจ้าของข้อมูลรับรอง
แอปที่เพิ่มข้อมูลเข้าสู่ระบบเครือข่ายเทรดจะกลายเป็นเจ้าของข้อมูลเข้าสู่ระบบและมีสิทธิ์โดยสมบูรณ์ในการเข้าถึงข้อมูลรับรอง หากคุณพยายามเข้าถึงข้อมูลเข้าสู่ระบบที่แอปอื่นๆ เพิ่ม ระบบจะแสดงข้อผิดพลาด PERMISSION_DENIED
ในฐานะเจ้าของแอป เราขอแนะนําให้คุณอัปเดตข้อมูลเข้าสู่ระบบที่จัดเก็บไว้ในบริการ Google Play อยู่เสมอเมื่อมีการอัปเดตเครือข่าย Thread Border Router ซึ่งหมายถึงการเพิ่มข้อมูลรับรองเมื่อจําเป็น และอัปเดตข้อมูลรับรองเมื่อข้อมูลรับรองของเครือข่ายเทรดของเทรดเดอร์มีการเปลี่ยนแปลง และนําข้อมูลรับรองออกเมื่อนํา Thread Border Router ออกหรือรีเซ็ตเป็นค่าเริ่มต้น
การค้นพบของเส้นขอบชายแดน
ต้องบันทึกข้อมูลเข้าสู่ระบบด้วยรหัส Border Agent คุณต้องตรวจสอบว่าแอปการตั้งค่า Thread Border Router สามารถระบุรหัสตัวแทนชายแดนของเราเตอร์ Thread ได้
เราเตอร์ Thread Border ต้องใช้ mDNS เพื่อโฆษณาข้อมูลเครือข่ายของ Thread รวมถึง Network Name, Extended Pan ID และ Border Agent ID ค่า txt
ที่เกี่ยวข้องสําหรับแอตทริบิวต์เหล่านี้คือ nn
, xp
และ id
ตามลําดับ
สําหรับเครือข่ายที่มี Border Router บริการ Google Play จะได้รับข้อมูลรับรองเครือข่ายของ Google Thread โดยอัตโนมัติเพื่อการใช้งาน
ผสานรวม SDK ในแอป Android
ในการเริ่มต้นใช้งาน ให้ทําตามขั้นตอนต่อไปนี้
ทําตามวิธีการตั้งค่าบริการ Google Play
เพิ่มทรัพยากร Dependency ของบริการ Google Play ในไฟล์
build.gradle
ของคุณ ดังนี้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}]") } }
สร้างเครือข่ายเทรดใหม่
หากไม่มีข้อมูลเข้าสู่ระบบเครือข่ายเทรดที่ต้องการให้ใช้งานในเครือข่ายเทรดของผู้ใช้ คุณจะใช้ API ของ addCredentials
เพื่อเพิ่มข้อมูลเข้าสู่ระบบไปยังบริการ Google Play ได้ โดยจะต้องสร้าง ThreadBorderAgent
และรวมออบเจ็กต์ ThreadNetworkCredentials
ด้วย
หากต้องการสร้างเครือข่ายแบบสุ่ม ให้เรียกใช้ newRandomizeBuilder
:
val threadCredentials = ThreadNetworkCredentials.newRandomizedBuilder().build()
หากต้องการระบุชื่อเครือข่ายเทรด:
val threadCredentials = ThreadNetworkCredentials.newRandomizedBuilder()
.setNetworkName("ThreadNetworkSDK")
.build()
เพิ่มข้อมูลรับรอง
ในการทําให้ข้อมูลรับรองของเครือข่ายเทรดพร้อมใช้งานสําหรับผู้ให้บริการเทรดอื่น เราต้องเพิ่มชุดข้อมูลดังกล่าวลงในบริการ 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}]") }
}
ตรวจหาและย้ายข้อมูลเราเตอร์เส้นขอบภาคสนาม
หากปัจจุบันคุณมี Border Routers ในช่อง คุณจะใช้ isPreferredCredentials
เพื่อตัดสินว่าเราเตอร์ Border Network เป็นของเครือข่ายที่ต้องการหรือไม่ API นี้ไม่ได้แจ้งผู้ใช้เพื่อขออนุญาต และจะตรวจสอบข้อมูลรับรองของเราเตอร์เส้นขอบกับสิ่งที่เก็บไว้ในบริการ 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 Border Router ด้วย Thread Network อยู่แล้ว และคุณต้องการเพิ่มเครือข่าย Thread ในบริการของ Google Play เพื่อแชร์กับผู้ให้บริการรายอื่น คุณสร้างอินสแตนซ์ ThreadNetworkCredential
จากรายการ TLV ของชุดข้อมูลการดําเนินการของชุดข้อความที่ใช้งานอยู่ได้โดยทําดังนี้
แปลงชุดข้อมูลด้านการปฏิบัติงานเป็น
ByteArray
เช่นval activeDataset = "0e080000000000010000000300000f35060004001fffe0020833333333...".dsToByteArray()
fun String.dsToByteArray(): ByteArray { return chunked(2).map { it.toInt(16).toByte() }.toByteArray() }
ใช้
fromActiveOperationalDataset
เพื่อสร้างThreadNetworkCredentials
เมื่อเสร็จแล้ว คุณจะได้รับชื่อเครือข่าย ช่อง และข้อมูลเครือข่าย อื่นๆ ของเทรด ดูรายการพร็อพเพอร์ตี้ทั้งหมดได้ที่ ThreadNetworkCredentialsval threadNetworkCredentials = ThreadNetworkCredentials.fromActiveOperationalDataset(activeDataset) Log.d( "threadNetworkCredentials", threadNetworkCredentials.channel.toString() + " - " + threadNetworkCredentials.networkName)
เรียกใช้
isPreferredCredentials
API และส่งต่อ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}]") }
ระบุข้อมูลรับรองเครือข่ายด้วย Border Agent
Border Agent ID ระบุอุปกรณ์ Border Router แบบไม่ซ้ํา หากต้องการใช้ getCredentialsByBorderAgent
API คุณต้องสร้างออบเจ็กต์ 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 Pan ID
และเช่นเดียวกับ getPreferredCredentials
คุณสามารถแจ้งให้ผู้ใช้
รับข้อมูลเข้าสู่ระบบได้จากรหัส Extended Pan ID ของเราเตอร์เส้นขอบ 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 ออกจากบ้านหรือการรีเซ็ตเป็นค่าเริ่มต้นแล้ว คุณต้องนําเครือข่าย Thread ออกจากอุปกรณ์ของ Google Play
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 ได้ที่การอ้างอิง API