Thread Network SDK มีฟังก์ชันการทํางานที่คล้ายกับคีย์เชนดิจิทัล ช่วยให้แอป Android แชร์ข้อมูลเข้าสู่ระบบของเครือข่ายกับเทรดกับบริการ Google Play ได้ วิธีนี้ช่วยให้แอปของคุณตั้งค่าอุปกรณ์เทรดใดก็ได้จากระบบนิเวศของสมาร์ทโฮมทั้งหมด โดยไม่ต้องเปิดเผยข้อมูลเข้าสู่ระบบและข้อมูลผู้ใช้โดยตรง
คุณทําสิ่งต่อไปนี้ได้ด้วยการเรียก API เพียงไม่กี่ครั้ง
- ขอข้อมูลเข้าสู่ระบบเครือข่าย "เทรด" ที่ต้องการจากบริการ Google Play
- ตั้งค่าเราเตอร์เส้นขอบใหม่ และเพิ่มข้อมูลเข้าสู่ระบบเครือข่ายเทรดไปยังบริการ Google Play
- หากมีเราเตอร์เส้นขอบสนามอยู่แล้ว คุณสามารถตรวจสอบว่าเราเตอร์เส้นขอบอยู่ในเครือข่ายที่ต้องการหรือไม่ และย้ายข้อมูลได้หากจําเป็น
เส้นทางของผู้ใช้และนักพัฒนาซอฟต์แวร์มีหลายแบบที่ควรพิจารณา เราจะพูดถึงคู่มือนี้ส่วนใหญ่ในคู่มือนี้ รวมไปถึงฟีเจอร์หลักและการใช้งานที่แนะนํา
คําศัพท์ที่สําคัญและแนวคิด API
ก่อนที่จะเริ่มต้น คุณควรทําความเข้าใจข้อกําหนดต่อไปนี้
ข้อมูลเข้าสู่ระบบเครือข่ายเทรด: BLOB ของ TLV ของเทรดแบบเข้ารหัสที่เข้ารหัส ชื่อเครือข่ายเทรด คีย์เครือข่าย และพร็อพเพอร์ตี้อื่นๆ ที่อุปกรณ์เทรดกําหนดให้ต้องเข้าร่วมเครือข่ายเทรดที่ระบุ
ข้อมูลเข้าสู่ระบบเครือข่ายเทรดที่ต้องการ: ข้อมูลเข้าสู่ระบบเครือข่ายเทรดที่เลือกโดยอัตโนมัติซึ่งแชร์กับแอปของผู้ให้บริการต่างๆ ได้โดยใช้
getPreferredCredentials
APIรหัสตัวแทนเส้นขอบ: รหัสที่ไม่ซ้ํากันทั่วโลกขนาด 16 ไบต์สําหรับอุปกรณ์เราเตอร์ Thread Border Border รหัสนี้สร้างและจัดการโดยผู้ให้บริการเราเตอร์เส้นขอบ
แอปการตั้งค่า Thread Border Router: เป็นแอป Android ที่ตั้งค่าอุปกรณ์ Thread Border Router ใหม่ และเพิ่มข้อมูลเข้าสู่ระบบของเครือข่าย "เทรด" ไปยังบริการ Google Play แอปของคุณเป็นเจ้าของข้อมูลเข้าสู่ระบบที่ได้รับอนุญาตที่เชื่อถือได้และมีสิทธิ์เข้าถึงข้อมูลเหล่านั้น
Thread Network API จํานวนมากแสดง Task ที่ทํางานไม่พร้อมกัน คุณใช้ addOnSuccessListener และ addOnFailureListener เพื่อลงทะเบียนโค้ดเรียกกลับสําหรับรับผลลัพธ์ได้ หากต้องการดูข้อมูลเพิ่มเติม โปรดดูเอกสารประกอบ งาน
การเป็นเจ้าของและการบํารุงรักษาข้อมูลเข้าสู่ระบบ
แอปที่เพิ่มข้อมูลเข้าสู่ระบบของเครือข่ายเทรดจะกลายเป็นเจ้าของข้อมูลเข้าสู่ระบบและมีสิทธิ์เข้าถึงข้อมูลเข้าสู่ระบบอย่างเต็มรูปแบบ หากคุณพยายามเข้าถึงข้อมูลเข้าสู่ระบบที่แอปอื่นๆ เพิ่ม คุณจะได้รับข้อผิดพลาด PERMISSION_DENIED
ในฐานะเจ้าของแอป เราขอแนะนําให้รักษาข้อมูลเข้าสู่ระบบที่จัดเก็บไว้ในบริการ Google Play ให้เป็นปัจจุบันเสมอเมื่ออัปเดตเครือข่ายเราเตอร์ของชุดข้อความ หมายถึงการเพิ่มข้อมูลเข้าสู่ระบบเมื่อจําเป็น การอัปเดตข้อมูลเข้าสู่ระบบเมื่อข้อมูลเข้าสู่ระบบเครือข่ายเทรดของเราเตอร์เปลี่ยนแปลงข้อมูลเข้าสู่ระบบ และการนําข้อมูลเข้าสู่ระบบออกเมื่อมีการนําเราเตอร์ของชุดข้อความออกหรือรีเซ็ตเป็นค่าเริ่มต้น
การค้นพบตัวแทนเส้นขอบ
ต้องบันทึกข้อมูลเข้าสู่ระบบด้วยรหัสตัวแทนเส้นขอบ คุณต้องตรวจสอบว่าแอปการตั้งค่า Thread Border Router สามารถระบุรหัสตัวแทนเส้นขอบของเราเตอร์ Thread Thread ได้
เราเตอร์ของเทรดเทรดต้องใช้ mDNS เพื่อโฆษณาข้อมูลเครือข่ายเทรด ซึ่งรวมถึงชื่อเครือข่าย รหัสการแพนที่ขยาย และรหัสตัวแทนเส้นขอบ ค่า txt
ที่เกี่ยวข้องสําหรับแอตทริบิวต์เหล่านี้คือ nn
, xp
และ id
ตามลําดับ
สําหรับเครือข่ายที่มีเราเตอร์เส้นขอบของ Google บริการ Google Play จะได้รับข้อมูลเข้าสู่ระบบเครือข่าย Google เทรดโดยอัตโนมัติเพื่อนําไปใช้
ผสานรวม 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}]") } }
สร้างเครือข่ายเทรดใหม่
หากไม่มีข้อมูลเข้าสู่ระบบเครือข่ายเทรดที่ต้องการในเครือข่ายเครือข่ายของผู้ใช้ คุณจะใช้ addCredentials
API เพื่อเพิ่มข้อมูลเข้าสู่ระบบลงในบริการ 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 Router ในขณะนี้ คุณสามารถใช้ isPreferredCredentials
เพื่อตรวจสอบว่าเราเตอร์ Border Router เป็นของเครือข่ายที่ต้องการหรือไม่ 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 มีการตั้งค่ากับเครือข่าย 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 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 ออกจากบ้านหรือการรีเซ็ตเป็นค่าเริ่มต้น คุณจะต้องนําเครือข่ายเทรดออกจากบริการ 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