Thread Network SDK menyediakan fungsionalitas yang mirip dengan keychain digital, memungkinkan aplikasi Android Anda untuk berbagi kredensial jaringan Thread dengan layanan Google Play. Hal ini memungkinkan aplikasi Anda menyiapkan perangkat Thread apa pun dari ekosistem smart home apa pun, tanpa mengungkap kredensial dan data pengguna secara langsung.
Hanya dengan beberapa panggilan API, Anda dapat:
- Meminta kredensial jaringan Thread pilihan dari layanan Google Play.
- Siapkan router perbatasan baru dan tambahkan kredensial jaringan Thread Anda ke layanan Google Play.
- Jika sudah memiliki router perbatasan di lapangan, Anda dapat memeriksa apakah router perbatasan Anda berada di jaringan pilihan dan memigrasikannya, jika perlu.
Ada beberapa perjalanan pengguna dan developer yang perlu dipertimbangkan. Kami akan membahas sebagian besar dalam panduan ini, bersama dengan fitur utama dan penggunaan yang direkomendasikan.
Istilah utama dan konsep API
Sebelum memulai, sebaiknya pahami istilah berikut:
Kredensial Jaringan Thread: Blob biner TLV Thread yang mengenkode Nama Jaringan Thread, Kunci Jaringan, dan properti lainnya yang diperlukan oleh perangkat Thread untuk bergabung ke jaringan Thread tertentu.
Kredensial Jaringan Thread yang Dipilih: Kredensial jaringan Thread yang dipilih otomatis yang dapat dibagikan dengan aplikasi dari vendor yang berbeda menggunakan
getPreferredCredentials
API.Border Agent ID: ID unik global 16 byte untuk perangkat Thread Border Router. ID ini dibuat dan dikelola oleh vendor router perbatasan.
Aplikasi Penyiapan Border Thread: Ini adalah aplikasi Android yang menyiapkan perangkat Border Thread Router baru dan menambahkan kredensial jaringan Thread ke layanan Google Play. Aplikasi Anda adalah pemilik resmi kredensial yang ditambahkan, dan memiliki akses gratis ke kredensial.
Banyak Thread Network API yang menampilkan Task yang selesai secara asinkron. Anda dapat menggunakan addOnSuccessListener dan addOnFailureListener untuk mendaftarkan callback guna menerima hasil. Untuk mempelajari lebih lanjut, baca dokumentasi Task.
Kepemilikan dan pemeliharaan kredensial
Aplikasi yang menambahkan kredensial jaringan Thread akan menjadi pemilik
kredensial, dan memiliki izin penuh untuk mengakses kredensial. Jika mencoba mengakses kredensial yang ditambahkan oleh aplikasi lain, Anda akan menerima error PERMISSION_DENIED
.
Sebagai pemilik aplikasi, sebaiknya Anda terus memperbarui kredensial di layanan Google Play saat jaringan Thread Border Router diperbarui. Hal ini berarti menambahkan kredensial jika diperlukan, memperbarui kredensial saat kredensial jaringan Thread router router diubah, dan menghapus kredensial saat Route Border Router dihapus atau direset ke setelan pabrik.
Penemuan Border Agent
Kredensial harus disimpan dengan ID Border Agent. Anda harus memastikan bahwa aplikasi Penyiapan Thread Border Router dapat menentukan ID Border Agent router router Thread Anda.
Thread Border Router harus menggunakan mDNS untuk mengiklankan informasi jaringan Thread,
termasuk Network Name, Extended Pan ID, dan Border Agent ID. Nilai txt
yang sesuai untuk atribut ini masing-masing adalah nn
, xp
, dan id
.
Untuk jaringan dengan router perbatasan Google, layanan Google Play secara otomatis mendapatkan kredensial jaringan Google Thread untuk digunakan.
Mengintegrasikan SDK ke dalam aplikasi Android Anda
Untuk memulai, selesaikan langkah-langkah berikut:
Ikuti petunjuk yang tersedia di Menyiapkan layanan Google Play.
Tambahkan dependensi layanan Google Play ke file
build.gradle
Anda:implementation 'com.google.android.gms:play-services-threadnetwork:16.0.0-beta02'
Opsional: Tentukan class data
BorderAgent
untuk menyimpan informasi router batas. Kami akan menggunakan data ini di seluruh panduan ini:data class BorderAgentInfo( // Network Name max 16 len val networkName: String = "", val extPanId: ByteArray = ByteArray(16), val borderAgentId: ByteArray = ByteArray(16), ... )
Selanjutnya, kita akan membahas langkah-langkah yang direkomendasikan untuk menambahkan dan mengelola kredensial pilihan.
Penyiapan router pembatas baru
Sebelum membuat jaringan baru untuk router perbatasan baru, Anda harus mencoba menggunakan kredensial jaringan pilihan terlebih dahulu. Hal ini memastikan bahwa perangkat Thread terhubung ke satu jaringan Thread jika memungkinkan.
Panggilan ke getPreferredCredentials
akan meluncurkan
Aktivitas, yang meminta pengguna untuk mengizinkan permintaan jaringan. Jika kredensial
jaringan telah disimpan dalam keychain digital Thread SDK, kredensial
akan ditampilkan ke aplikasi Anda.
Minta kredensial
Untuk meminta kredensial pilihan kepada pengguna:
Deklarasikan
ActivityLauncher
:private lateinit var preferredCredentialsLauncher: ActivityResultLauncher<IntentSenderRequest>
Tangani hasil Aktivitas, yang ditampilkan sebagai
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.") } }
Panggil
preferredCredentials
dan luncurkan Aktivitas: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}]") } }
Membuat jaringan Thread baru
Jika tidak ada kredensial Jaringan thread pilihan yang tersedia di jaringan
Thread pengguna, Anda dapat menggunakan addCredentials
API untuk menambahkan kredensial ke
Layanan Google Play. Untuk melakukannya, Anda harus membuat ThreadBorderAgent
, dan juga menyediakan objek ThreadNetworkCredentials
.
Untuk membuat jaringan acak, panggil newRandomizeBuilder
:
val threadCredentials = ThreadNetworkCredentials.newRandomizedBuilder().build()
Untuk menentukan Nama jaringan thread:
val threadCredentials = ThreadNetworkCredentials.newRandomizedBuilder()
.setNetworkName("ThreadNetworkSDK")
.build()
Tambahkan kredensial
Agar kredensial jaringan Thread Anda tersedia untuk vendor Thread lain, kami perlu menambahkannya ke layanan Google Play. Sebelum dapat menambahkan kredensial baru, kita juga perlu mengetahui perangkat router perbatasan tempat jaringan Thread ini berada.
Dalam contoh ini, kita akan membuat ThreadBorderAgent
dari ID Border Agent, dan meneruskan kredensial jaringan Thread baru yang baru saja Anda buat:
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}]") }
}
Mendeteksi dan memigrasikan router perbatasan di lapangan
Jika saat ini Anda memiliki router perbatasan di lapangan, Anda dapat menggunakan isPreferredCredentials
untuk menentukan apakah router perbatasan Anda termasuk dalam jaringan yang dipilih. API ini tidak meminta izin
pengguna, dan memeriksa kredensial router perbatasan terhadap apa saja yang disimpan
di layanan Google Play.
isPreferredCredentails
menampilkan 0
untuk yang tidak cocok, dan 1
untuk
yang cocok, sebagai jenis data Int
. Anda dapat menggunakan IsPreferredCredentialsResult
untuk memeriksa hasil Anda.
public @interface IsPreferredCredentialsResult {
int PREFERRED_CREDENTIALS_NOT_FOUND = -1;
int PREFERRED_CREDENTIALS_NOT_MATCHED = 0;
int PREFERRED_CREDENTIALS_MATCHED = 1;
}
Untuk menggunakan isPreferredCredentials
, Anda harus membuat
objek ThreadNetworkCredentials
terlebih dahulu. Ada beberapa cara untuk membuat instance ThreadNetworkCredentials
. Pada langkah berikutnya, kita akan membahas opsi tersebut.
Thread jaringan thread oleh Operational Dataset
Ada kasus ketika Thread Border Router Anda sudah disiapkan dengan
jaringan Thread, dan Anda ingin menambahkan jaringan Thread ini ke layanan Google Play
untuk membagikannya dengan vendor lain. Anda dapat membuat instance ThreadNetworkCredential
dari daftar TLV Rangkaian Data Operasional Aktif Thread mentah:
Konversikan Set Data Operasional menjadi
ByteArray
. Contoh:val activeDataset = "0e080000000000010000000300000f35060004001fffe0020833333333...".dsToByteArray()
fun String.dsToByteArray(): ByteArray { return chunked(2).map { it.toInt(16).toByte() }.toByteArray() }
Gunakan
fromActiveOperationalDataset
untuk membuatThreadNetworkCredentials
. Jika berhasil, Anda akan mendapatkan Nama jaringan Thread, Channel, dan informasi jaringan lainnya. Untuk mengetahui daftar lengkap properti, lihat ThreadNetworkCredentials.val threadNetworkCredentials = ThreadNetworkCredentials.fromActiveOperationalDataset(activeDataset) Log.d( "threadNetworkCredentials", threadNetworkCredentials.channel.toString() + " - " + threadNetworkCredentials.networkName)
Panggil
isPreferredCredentials
API dan teruskanThreadNetworkCredentials
.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}]") }
Kredensial jaringan thread oleh Border Agent
ID Agen Batas yang mengidentifikasi perangkat router perbatasan secara unik. Untuk menggunakan
getCredentialsByBorderAgent
API, pertama-tama Anda harus membuat
objek ThreadBorderAgent
dan meneruskan ID Agen Batas.
Setelah Anda membuat objek ThreadBorderAgent
, panggil getCredentialsByBorderAgent
. Jika kredensial telah disimpan, periksa apakah
kredensial tersebut diinginkan.
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}]") }
}
Kredensial jaringan thread menurut ID Pan yang Diperluas
Serupa dengan getPreferredCredentials
, Anda juga dapat meminta kredensial
pengguna dari Extended Pan ID router batas. getCredentialsByExtendedPanId
menampilkan IntentSender
, dan hasil Aktivitas
berisi objek ThreadNetworkCredentials
saat pengguna menyetujuinya.
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}]") }
}
Hapus Kredensial
Saat perangkat Border Router dihapus dari rumah atau reset ke setelan pabrik, Anda harus menghapus jaringan Thread-nya dari layanan 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}]") }
}
Materi
Untuk mempelajari Thread Network SDK lebih lanjut, lihat Referensi API.