Google menggunakan teknologi AI untuk menerjemahkan konten ke dalam bahasa pilihan Anda. Terjemahan AI mungkin mengandung kesalahan.

Thread Network SDK untuk Android

Thread Network SDK menyediakan fungsi yang mirip dengan keychain digital, sehingga aplikasi Android Anda dapat membagikan kredensial jaringan Thread ke layanan Google Play. Hal ini memungkinkan aplikasi Anda menyiapkan perangkat Thread apa pun dari ekosistem smart home mana pun, 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 Thread Border Router (TBR) baru dan tambahkan kredensial jaringan Thread Anda ke layanan Google Play.
Jika sudah memiliki TBR di lapangan, Anda dapat memeriksa apakah TBR berada di jaringan pilihan dan memigrasikannya, jika perlu.

Ada beberapa perjalanan pengguna dan developer yang perlu dipertimbangkan. Kami akan membahas sebagian besar fitur tersebut dalam panduan ini, beserta fitur utama lainnya dan penggunaan yang direkomendasikan.

Terminologi 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 lain yang diperlukan oleh perangkat Thread untuk bergabung ke jaringan Thread tertentu.
Kredensial Jaringan Thread Pilihan: Kredensial jaringan Thread yang dipilih otomatis yang dapat dibagikan ke aplikasi dari berbagai vendor menggunakan API getPreferredCredentials.
ID Agen Pembatas: ID unik global 16 byte untuk perangkat TBR. ID ini dibuat dan dikelola oleh vendor border router.
Aplikasi penyiapan TBR: Ini adalah aplikasi Android Anda yang menyiapkan perangkat TBR baru dan menambahkan kredensial jaringan Thread ke layanan Google Play. Aplikasi Anda adalah pemilik kredensial yang ditambahkan dan memiliki akses ke kredensial tersebut.

Banyak Thread Network API menampilkan Task yang selesai secara asinkron. Anda dapat menggunakan addOnSuccessListener dan addOnFailureListener untuk mendaftarkan callback guna menerima hasilnya. Untuk mempelajari lebih lanjut, lihat dokumentasi Task.

Kepemilikan dan pemeliharaan kredensial

Aplikasi yang menambahkan kredensial jaringan Thread akan menjadi pemilik kredensial, dan memiliki izin penuh untuk mengakses kredensial. Jika Anda mencoba mengakses kredensial yang ditambahkan oleh aplikasi lain, Anda akan menerima error PERMISSION_DENIED.

Sebagai pemilik aplikasi, sebaiknya Anda terus memperbarui kredensial yang disimpan di layanan Google Play saat jaringan TBR diupdate. Artinya, menambahkan kredensial saat diperlukan, memperbarui kredensial saat kredensial jaringan Thread border router berubah, dan menghapus kredensial saat TBR dihapus atau direset ke setelan pabrik.

Penemuan Agen Pembatas

Kredensial harus disimpan dengan ID Agen Border. Anda harus memastikan bahwa aplikasi penyiapan TBR dapat menentukan ID Agen Border TBR Anda.

TBR harus menggunakan mDNS untuk memberitahukan informasi jaringan Thread, termasuk Nama Jaringan, ID Pan yang Diperluas, dan ID Agen Pembatas. Nilai txt yang sesuai untuk atribut ini masing-masing adalah nn, xp, dan id.

Untuk jaringan dengan Google Thread Border Router (gTBR), layanan Google Play otomatis mendapatkan kredensial jaringan Google Thread untuk digunakan.

Mengintegrasikan SDK ke dalam aplikasi Android Anda

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 informasi TBR. 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 Thread baru

Sebelum membuat jaringan baru untuk router pembatas baru, sebaiknya coba gunakan 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 di keychain digital Thread SDK, kredensial tersebut akan ditampilkan 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 TBR baru, sebaiknya panggil preferredCredentials dan luncurkan Aktivitas. Panggilan ini akan memastikan bahwa TBR baru Anda akan menggunakan kredensial yang sama yang sudah disimpan sebagai pilihan di ponsel, sehingga mendorong konvergensi berbagai TBR 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 terkait 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 jaringan lokal, sehingga tidak akan menampilkan 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 perlu menambahkannya ke layanan Google Play. Sebelum dapat menambahkan kredensial baru, kita juga perlu mengetahui perangkat TBR mana yang memiliki jaringan Thread ini.

Dalam contoh ini, kita akan membuat ThreadBorderAgent dari ID Agen Pembatas, 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 border router di lapangan

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

isPreferredCredentials 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 objek 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 kasus saat TBR Anda sudah disiapkan dengan jaringan Thread, dan Anda ingin menambahkan jaringan Thread ini ke layanan Google Play untuk membagikannya kepada vendor lain. Anda dapat membuat instance ThreadNetworkCredential dari daftar TLV Set Data Operasional Aktif 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, Saluran, dan informasi jaringan Thread lainnya. Untuk mengetahui daftar lengkap properti, lihat ThreadNetworkCredentials.

val threadNetworkCredentials =
    ThreadNetworkCredentials.fromActiveOperationalDataset(activeDataset)
Log.d(
    "threadNetworkCredentials",
    threadNetworkCredentials.channel.toString() + " - " + threadNetworkCredentials.networkName)

Panggil API isPreferredCredentials 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 Agen Pembatas

ID Agen Pembatas mengidentifikasi perangkat TBR secara unik. Untuk menggunakan getCredentialsByBorderAgent API, pertama-tama Anda harus membuat objek ThreadBorderAgent dan meneruskan ID Agen Pembatas.

Setelah membuat objek ThreadBorderAgent, panggil getCredentialsByBorderAgent. Jika kredensial telah disimpan, periksa 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}]") }
}

Kredensial jaringan Thread menurut ID Pan yang Diperluas

Sama seperti getPreferredCredentials, Anda juga dapat meminta kredensial pengguna dari ID Pan yang Diperluas TBR. getCredentialsByExtendedPanId menampilkan IntentSender, dan hasil Aktivitas berisi objek ThreadNetworkCredentials saat pengguna menyetujui.

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

Jika perangkat border router Anda dihapus dari rumah atau direset 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}]") }
}

Resource

Untuk mempelajari lebih lanjut Thread Network SDK, lihat Referensi API.