Thread Network SDK menyediakan fungsi yang mirip dengan keychain, yang memungkinkan aplikasi Android Anda membagikan kredensial jaringan Thread kepada Layanan Google Play. Hal ini memungkinkan aplikasi Anda menyiapkan perangkat Thread apa pun dari ekosistem smart home, tanpa mengekspos kredensial dan data pengguna secara langsung.
Hanya dengan beberapa panggilan API, Anda dapat:
- Minta kredensial jaringan Thread pilihan dari layanan Google Play.
- Siapkan router pembatas baru dan tambahkan kredensial jaringan Thread Anda ke Google Layanan Play.
- Jika Anda sudah memiliki {i>router<i} pembatas dalam lapangan, Anda dapat memeriksa apakah {i>border<i} Anda {i>router<i} berada di jaringan pilihan dan memigrasikannya, jika perlu.
Ada beberapa perjalanan pengguna dan developer yang perlu dipertimbangkan. Kita akan membahas sebagian besar dalam panduan ini, beserta fitur utama lainnya dan penggunaan yang disarankan.
Terminologi utama dan konsep API
Sebelum memulai, sebaiknya pahami istilah-istilah berikut:
Kredensial Jaringan Thread: Blob biner TLV Thread yang mengenkode Nama Jaringan Thread, Kunci Jaringan dan properti lain yang diperlukan oleh perangkat Thread untuk bergabung dengan jaringan Thread tertentu.
Kredensial Jaringan Thread Pilihan: Jaringan Thread yang dipilih otomatis yang dapat dibagikan ke aplikasi dari vendor yang berbeda menggunakan API
getPreferredCredentials
.ID Agen Border: ID unik global 16 byte untuk Router Pembatas Thread perangkat seluler. ID ini dibuat dan dikelola oleh vendor router pembatas.
Aplikasi Penyiapan Router Pembatas Thread: Ini adalah aplikasi Android yang menyiapkan perangkat Thread Border Router baru dan menambahkan kredensial jaringan Thread ke Layanan Google Play. Aplikasi Anda adalah pemilik resmi dari dan memiliki akses ke kredensial tersebut.
Banyak Thread Network API menampilkan Tugas yang selesai secara asinkron. Anda dapat menggunakan addOnSuccessListener dan addOnFailureListener untuk mendaftarkan callback agar bisa menerima hasilnya. Untuk mempelajari selengkapnya, lihat Tugas dokumentasi tambahan.
Kepemilikan dan pemeliharaan kredensial
Aplikasi yang menambahkan kredensial jaringan Thread akan menjadi pemilik
kredensial, dan memiliki izin penuh
untuk mengakses kredensial tersebut. Jika Anda mencoba
untuk mengakses kredensial yang ditambahkan oleh aplikasi lain, Anda akan menerima PERMISSION_DENIED
{i>error<i}.
Sebagai pemilik aplikasi, sebaiknya Anda menyimpan kredensial yang disimpan di Google Layanan Play akan mendapatkan update terbaru saat jaringan Router Thread Border diupdate. Ini berarti menambahkan kredensial jika diperlukan, memperbarui kredensial saat kredensial jaringan Thread router berubah, dan menghapus kredensial saat Router Pembatas Thread dihapus atau direset ke setelan pabrik.
Penemuan Agen Border
Kredensial harus disimpan dengan ID Agen Batas. Anda harus memastikan bahwa aplikasi Penyiapan Router Thread Border Anda dapat menentukan ID Agen Border router pembatas Thread Anda.
{i>Thread Border Router<i} harus menggunakan mDNS
untuk mengiklankan informasi jaringan Thread,
termasuk Nama Jaringan, ID Geser yang Diperluas, dan ID Agen Batas. Tujuan
nilai txt
yang sesuai untuk atribut ini adalah nn
, xp
, dan id
,
secara berurutan.
Untuk jaringan dengan router pembatas Google, layanan Google Play otomatis mendapatkan kredensial jaringan Google Thread untuk digunakan.
Mengintegrasikan SDK ke dalam aplikasi Android
Untuk memulai, selesaikan langkah-langkah berikut:
Ikuti petunjuk yang diberikan 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'
Opsional: Tentukan class data
BorderAgent
untuk menyimpan router pembatas tidak akurat atau tidak sesuai. 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 memiliki kredensial yang lengkap.
Penyiapan router pembatas baru
Sebelum Anda membuat jaringan baru untuk {i> router<i} pembatas baru, penting untuk coba gunakan kredensial jaringan pilihan Anda terlebih dahulu. Hal ini memastikan bahwa Perangkat Thread terhubung ke satu jaringan Thread jika memungkinkan.
Panggilan ke getPreferredCredentials
diluncurkan
Aktivitas, yang meminta pengguna untuk
mengizinkan permintaan jaringan. Jika jaringan
kredensial yang telah disimpan di keychain digital Thread SDK,
dikembalikan ke aplikasi Anda.
Meminta kredensial
Untuk meminta kredensial pilihan 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, Anda dapat menggunakan addCredentials
API untuk menambahkan kredensial
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 tersedia untuk vendor Thread lainnya, kita perlu menambahkannya ke layanan Google Play. Sebelum kita dapat menambahkan kita juga perlu mengetahui ke perangkat {i>router<i} pembatas mana Thread ini jaringan tersebut.
Dalam contoh ini, kita akan membuat ThreadBorderAgent
dari ID Agen Batas, dan
teruskan 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 pembatas dalam lapangan
Jika saat ini Anda memiliki router pembatas
di lapangan, Anda dapat menggunakan
isPreferredCredentials
untuk menentukan apakah router pembatas Anda termasuk
ke jaringan pilihan. API ini tidak meminta
izin pengguna, dan memeriksa kredensial {i>
router<i} pembatas terhadap apa yang disimpan
di layanan Google Play.
isPreferredCredentails
menampilkan 0
untuk yang tidak cocok, dan 1
untuk
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
ThreadNetworkCredentials
terlebih dahulu. Ada beberapa cara untuk membuat instance ThreadNetworkCredentials
. Pada langkah selanjutnya, kita akan
membahas opsi ini.
Thread kredensial jaringan berdasarkan Set Data Operasional
Ada kasus bahwa {i>Router<i} Pembatas Thread
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 ThreadNetworkCredential
dari daftar TLV Set Data Operasional Thread mentah:
Konversi 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 bisa mendapatkan Nama jaringan Thread, Saluran, dan informasi jaringan lainnya. Untuk mengetahui daftar lengkap properti, lihat ThreadNetworkCredentials.val threadNetworkCredentials = ThreadNetworkCredentials.fromActiveOperationalDataset(activeDataset) Log.d( "threadNetworkCredentials", threadNetworkCredentials.channel.toString() + " - " + threadNetworkCredentials.networkName)
Memanggil
isPreferredCredentials
API dan meneruskanThreadNetworkCredentials
.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 kredensial jaringan oleh Border Agent
ID Agen Perbatasan secara unik mengidentifikasi perangkat router pembatas. Untuk menggunakan
API getCredentialsByBorderAgent
, pertama-tama Anda harus membuat
ThreadBorderAgent
dan teruskan Border Agent ID.
Setelah Anda membuat objek ThreadBorderAgent
, panggil
getCredentialsByBorderAgent
. Jika kredensial telah disimpan, periksa untuk melihat
jika lebih disukai.
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 kredensial jaringan dengan ID Geser yang Diperluas
Mirip dengan getPreferredCredentials
, Anda juga dapat meminta pengguna untuk
dari ID Geser Diperpanjang router pembatas. Tujuan
getCredentialsByExtendedPanId
menampilkan IntentSender
, dan Aktivitas
hasil 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 direset ke setelan pabrik, Anda perlu 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}]") }
}
Resource
Untuk mempelajari Thread Network SDK lebih lanjut, lihat Referensi API.