Halaman ini diterjemahkan oleh Cloud Translation API.

Thread Network SDK untuk Android

Thread Network SDK menyediakan fungsi yang mirip dengan kunci digital, yang memungkinkan aplikasi Android Anda membagikan kredensial jaringan Thread dengan 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:

Meminta kredensial jaringan Thread yang diinginkan dari layanan Google Play.
Siapkan router pembatas baru dan tambahkan kredensial jaringan Thread Anda ke Google Layanan Play.
Jika sudah memiliki router pembatas di lapangan, Anda dapat memeriksa apakah router pembatas berada di jaringan yang diinginkan 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 lainnya yang diperlukan oleh perangkat Thread untuk bergabung ke 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 Perbatasan: ID unik global 16 byte untuk perangkat Thread Border Router. ID ini dibuat dan dikelola oleh vendor router perbatasan.
Aplikasi Penyiapan Router Pembatas Thread: Ini adalah aplikasi Android Anda yang menyiapkan perangkat Router Pembatas Thread 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 guna menerima hasilnya. Untuk mempelajari lebih lanjut, lihat dokumentasi Tugas.

Kepemilikan dan pemeliharaan kredensial

Aplikasi yang menambahkan kredensial jaringan Thread menjadi pemilik kredensial, dan memiliki izin penuh untuk mengakses kredensial. 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 diupdate 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 Perbatasan

Kredensial harus disimpan dengan ID Agen Batas. Anda harus memastikan bahwa aplikasi Penyiapan Router Pembatas Thread dapat menentukan ID Agen Pembatas router pembatas Thread Anda.

Router Batas Thread harus menggunakan mDNS untuk mengiklankan informasi jaringan Thread, termasuk Nama Jaringan, ID Pan 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.2.1'

Opsional: Tentukan class data BorderAgent untuk menyimpan router pembatas tidak akurat atau tidak sesuai. Kita 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 Anda membuat jaringan baru untuk {i> router<i} pembatas baru, penting untuk coba gunakan kredensial jaringan pilihan Anda terlebih dahulu. Tindakan 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 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.")
   }
 }

Jika Anda menyiapkan Thread Border Router baru, sebaiknya panggil preferredCredentials dan luncurkan Aktivitas. Panggilan ini akan memastikan bahwa Thread Border Router baru Anda akan menggunakan kredensial yang sama yang telah disimpan sebagai lebih disukai di ponsel, sehingga mendorong konvergensi TBR yang berbeda ke jaringan yang sama.

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}]") }
}

Jika kasus penggunaan Anda berkaitan dengan penyiapan perangkat non-TBR, seperti perangkat akhir Matter-over-Thread baru, sebaiknya gunakan allActiveCredentials api untuk mengambil kredensial. Panggilan ini akan memindai TBR yang ditemukan di area lokal jaringan dan dengan demikian tidak akan mengembalikan kredensial yang tidak tersedia oleh TBR yang ada secara lokal.

// Creates the IntentSender result launcher for the getAllActiveCredentials API
private val getAllActiveCredentialsLauncher =
  registerForActivityResult(
    StartIntentSenderForResult()
  ) { result: ActivityResult ->
    if (result.resultCode == RESULT_OK) {
      val activeCredentials: List<ThreadNetworkCredentials> =
        ThreadNetworkCredentials.parseListFromIntentSenderResultData(
          result.data!!
        )
      // Use the activeCredentials list
    } else {
      // The user denied to share!
    }
  }

// Invokes the getAllActiveCredentials API and starts the dialog activity with the returned
// IntentSender
threadNetworkClient
.getAllActiveCredentials()
.addOnSuccessListener { intentSenderResult: IntentSenderResult ->
  val intentSender = intentSenderResult.intentSender
  if (intentSender != null) {
    getAllActiveCredentialsLauncher.launch(
      IntentSenderRequest.Builder(intentSender).build()
    )
  } else {
    // No active network credentials found!
  }
}
// Handles the failure
.addOnFailureListener { e: Exception ->
  // Handle the exception
}

Membuat jaringan Thread baru

Jika tidak ada kredensial jaringan Thread pilihan atau kredensial thread aktif 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 lainnya, kami harus 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 di lapangan

Jika saat ini Anda memiliki router pembatas di lapangan, Anda dapat menggunakan isPreferredCredentials untuk menentukan apakah router pembatas Anda termasuk dalam jaringan yang diinginkan. API ini tidak meminta izin pengguna, dan memeriksa kredensial router perbatasan dengan yang disimpan di layanan Google Play.

isPreferredCredentails menampilkan 0 untuk tidak cocok, dan 1 untuk cocok, sebagai jenis data Int. Anda dapat menggunakan IsPreferredCredentialsResult untuk memeriksa hasil.

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 berikutnya, kita akan membahas opsi ini.

Kredensial jaringan Thread menurut Set Data Operasional

Ada kalanya Router 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 membuat ThreadNetworkCredentials. 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)
```

Panggil isPreferredCredentials API dan teruskan 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}]") }

Kredensial jaringan Thread oleh Border Agent

ID Agen Perbatasan secara unik mengidentifikasi perangkat router perbatasan. 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 apakah kredensial tersebut 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}]") }
}

Menghapus 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.