SDK Jaringan Thread untuk Android

Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Thread Network SDK menyediakan fungsi 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:

  1. Meminta kredensial jaringan Thread pilihan dari layanan Google Play.
  2. Siapkan router batas baru dan tambahkan kredensial jaringan Thread Anda ke layanan Google Play.
  3. Jika sudah memiliki router pembatas lapangan, Anda dapat memeriksa apakah router pembatas berada di jaringan yang diinginkan dan memigrasikannya, jika perlu.

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

Terminologi utama dan konsep API

Sebelum memulai, akan sangat membantu jika Anda memahami persyaratan 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: Kredensial jaringan Thread yang dipilih otomatis, yang dapat dibagikan dengan aplikasi dari berbagai vendor menggunakan getPreferredCredentials API.

  • ID Agen Batas: ID unik global 16-byte untuk perangkat Thread Border Router. ID ini dibuat dan dikelola oleh vendor router pembatas.

  • Aplikasi Thread Border Router: Ini adalah aplikasi Android Anda yang menyiapkan perangkat Thread Border Router baru dan menambahkan kredensial jaringan Thread ke layanan Google Play. Aplikasi Anda adalah pemilik sah dari kredensial yang ditambahkan, dan memiliki akses gratis ke kredensial.

Banyak Thread Network API menampilkan Tugas yang selesai secara asinkron. Anda dapat menggunakan addOnSuccessListener dan addOnFailureListener untuk mendaftarkan callback agar dapat menerima hasil. Untuk mempelajari lebih lanjut, baca dokumentasi Task.

Kepemilikan dan pemeliharaan kredensial

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

Sebagai pemilik aplikasi, sebaiknya Anda selalu memperbarui kredensial di layanan Google Play saat jaringan Thread Border Router diperbarui. Ini berarti menambahkan kredensial jika diperlukan, memperbarui kredensial saat kredensial jaringan Thread router akan berubah, dan menghapus kredensial saat Router Border Border dihapus atau direset ke setelan pabrik.

Penemuan Agen Perbatasan

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

Router Border Border harus menggunakan mDNS untuk mengiklankan informasi jaringan Thread, termasuk Nama Jaringan, 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:

  1. Ikuti petunjuk yang disediakan di Menyiapkan layanan Google Play.

  2. Tambahkan dependensi layanan Google Play ke file build.gradle Anda:

    implementation 'com.google.android.gms:play-services-threadnetwork:16.0.0-beta01'
    
  3. Opsional: Tentukan data class 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 batas 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 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.

Kredensial permintaan

Untuk meminta kredensial pilihan kepada pengguna:

  1. Deklarasikan ActivityLauncher:

    private lateinit var preferredCredentialsLauncher: ActivityResultLauncher<IntentSenderRequest>
    
  2. 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.")
       }
     }
    
  3. 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 lainnya, kami harus menambahkannya ke layanan Google Play. Sebelum menambahkan kredensial baru, kita juga perlu mengetahui perangkat router perbatasan tempat jaringan Thread ini berada.

Pada contoh ini, kami 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 pembatas lapangan

Jika saat ini Anda memiliki router pembatas dalam 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 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 hasilnya.

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 beberapa kasus bahwa Thread Border Router 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:

  1. Konversikan Set Data Operasional menjadi ByteArray. Misalnya:

    val activeDataset =
          "0e080000000000010000000300000f35060004001fffe0020833333333...".dsToByteArray()
    
    fun String.dsToByteArray(): ByteArray {
      return chunked(2).map { it.toInt(16).toByte() }.toByteArray()
    }
    
  2. Gunakan fromActiveOperationalDataset untuk membuat ThreadNetworkCredentials. Jika berhasil, Anda akan bisa mendapatkan Nama jaringan, Channel, dan informasi jaringan lainnya. Untuk daftar lengkap properti, lihat ThreadNetworkCredentials.

    val threadNetworkCredentials =
        ThreadNetworkCredentials.fromActiveOperationalDataset(activeDataset)
    Log.d(
        "threadNetworkCredentials",
        threadNetworkCredentials.channel.toString() + " - " + threadNetworkCredentials.networkName)
    
  3. 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 Batas secara unik mengidentifikasi perangkat router pembatas. Untuk menggunakan API getCredentialsByBorderAgent, pertama-tama Anda harus membuat objek ThreadBorderAgent dan meneruskan ID Agen Pembatas.

Setelah Anda 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 Diperpanjang

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

Hapus Kredensial

Saat perangkat Border Router dihapus dari reset ke setelan pabrik atau rumah, 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 Thread Network SDK lebih lanjut, lihat Referensi API.