Google ใช้เทคโนโลยี AI เพื่อแปลเนื้อหาเป็นภาษาที่คุณต้องการ การแปลโดย AI อาจมีข้อผิดพลาด

Thread Network SDK สำหรับ Android

Thread Network SDK มีฟังก์ชันการทำงานที่คล้ายกับพวงกุญแจดิจิทัล ซึ่งช่วยให้แอป Android แชร์ข้อมูลเข้าสู่ระบบของเครือข่าย Thread กับบริการ Google Play ได้ ซึ่งจะช่วยให้แอปตั้งค่าอุปกรณ์ Thread จากระบบนิเวศสมาร์ทโฮมได้โดยไม่ต้องเปิดเผยข้อมูลเข้าสู่ระบบและข้อมูลผู้ใช้โดยตรง

คุณทำสิ่งต่อไปนี้ได้ด้วยการเรียกใช้ API เพียงไม่กี่ครั้ง

ขอข้อมูลเข้าสู่ระบบของเครือข่าย Thread ที่ต้องการจากบริการ Google Play
ตั้งค่า Thread Border Router (TBR) ใหม่และเพิ่มข้อมูลเข้าสู่ระบบของเครือข่าย Thread ลงในบริการ Google Play
หากมี TBR ที่ใช้งานอยู่แล้ว คุณสามารถตรวจสอบว่า TBR อยู่ในเครือข่ายที่ต้องการหรือไม่ และย้าย หากจำเป็น

มีเส้นทางของผู้ใช้และนักพัฒนาแอปหลายเส้นทางที่ควรพิจารณา เราจะพูดถึงเส้นทางส่วนใหญ่ในคู่มือนี้ รวมถึงฟีเจอร์หลักอื่นๆ และการใช้งานที่แนะนำ

คำศัพท์และแนวคิดหลักของ API

ก่อนเริ่มต้นใช้งาน คุณควรทำความเข้าใจคำศัพท์ต่อไปนี้

ข้อมูลเข้าสู่ระบบของเครือข่าย Thread: Blob แบบไบนารีของ Thread TLV ที่เข้ารหัสชื่อเครือข่าย Thread, คีย์เครือข่าย และพร็อพเพอร์ตี้อื่นๆ ที่อุปกรณ์ Thread ต้องใช้เพื่อเข้าร่วมเครือข่าย Thread ที่กำหนด
ข้อมูลเข้าสู่ระบบของเครือข่าย Thread ที่ต้องการ: ข้อมูลเข้าสู่ระบบของเครือข่าย Thread ที่เลือกโดยอัตโนมัติซึ่งแชร์กับแอปของผู้ให้บริการรายอื่นได้โดยใช้ API getPreferredCredentials
รหัส Border Agent: รหัสที่ไม่ซ้ำกันทั่วโลกขนาด 16 ไบต์สำหรับอุปกรณ์ TBR ผู้ให้บริการ border router เป็นผู้สร้างและจัดการรหัสนี้
TBR แอปตั้งค่า: แอป Android ที่ตั้ง ค่าอุปกรณ์TBRใหม่และเพิ่มข้อมูลเข้าสู่ระบบ ของเครือข่าย Thread ลงในบริการ Google Play แอปของคุณเป็นเจ้าของข้อมูลเข้าสู่ระบบที่เพิ่มเข้ามาและมีสิทธิ์เข้าถึงข้อมูลดังกล่าว

API ของ Thread Network หลายรายการแสดงผล Task ที่เสร็จสมบูรณ์แบบไม่พร้อมกัน คุณสามารถใช้ addOnSuccessListener และ addOnFailureListener เพื่อลงทะเบียนการเรียกกลับสำหรับการรับผลลัพธ์ ดูข้อมูลเพิ่มเติมได้ที่ เอกสารประกอบของ Task

การเป็นเจ้าของและการดูแลรักษาข้อมูลเข้าสู่ระบบ

แอปที่เพิ่มข้อมูลเข้าสู่ระบบของเครือข่าย Thread จะกลายเป็นเจ้าของข้อมูลเข้าสู่ระบบและมีสิทธิ์เข้าถึงข้อมูลเข้าสู่ระบบอย่างเต็มรูปแบบ หากพยายามเข้าถึงข้อมูลเข้าสู่ระบบที่แอปอื่นเพิ่ม คุณจะได้รับข้อผิดพลาด PERMISSION_DENIED

ในฐานะเจ้าของแอป เราขอแนะนำให้คุณเก็บข้อมูลเข้าสู่ระบบที่จัดเก็บไว้ในบริการ Google Play ให้เป็นปัจจุบันเมื่อมีการอัปเดตเครือข่าย TBR ซึ่งหมายถึงการเพิ่มข้อมูลเข้าสู่ระบบเมื่อจำเป็น การอัปเดตข้อมูลเข้าสู่ระบบเมื่อข้อมูลเข้าสู่ระบบของเครือข่าย Thread ของ border routerเปลี่ยนไป และการนำ ข้อมูลเข้าสู่ระบบออกเมื่อนำ TBR ออกหรือรีเซ็ตเป็นค่าเริ่มต้น

การค้นพบ Border Agent

คุณต้องบันทึกข้อมูลเข้าสู่ระบบด้วยรหัส Border Agent และตรวจสอบว่า แอปตั้งค่า TBR สามารถกำหนดรหัส Border Agent ของ TBR ได้

TBRs ต้องใช้ mDNS เพื่อประกาศข้อมูลเครือข่าย Thread ซึ่งรวมถึงชื่อเครือข่าย, Extended Pan ID และรหัส Border Agent ค่า txt ที่เกี่ยวข้องสำหรับแอตทริบิวต์เหล่านี้คือ nn, xp และ id ตามลำดับ

สำหรับเครือข่ายที่มี Google Thread Border Router (gTBR) บริการ Google Play จะรับข้อมูลเข้าสู่ระบบของเครือข่าย Google Thread โดยอัตโนมัติเพื่อใช้งาน

ผสานรวม SDK เข้ากับแอป Android

หากต้องการเริ่มต้นใช้งาน ให้ทำตามขั้นตอนต่อไปนี้

ทำตามวิธีการที่ระบุไว้ใน ตั้งค่าบริการ Google Play
เพิ่มทรัพยากร Dependency ของบริการ Google Play ลงในไฟล์ build.gradle ดังนี้
```
implementation 'com.google.android.gms:play-services-threadnetwork:16.2.1'
```
ไม่บังคับ: กำหนดคลาสข้อมูล BorderAgent เพื่อจัดเก็บ TBR ข้อมูล เราจะใช้ข้อมูลนี้ตลอดทั้งคู่มือ
```
data class BorderAgentInfo(
  // Network Name max 16 len
  val networkName: String = "",
  val extPanId: ByteArray = ByteArray(16),
  val borderAgentId: ByteArray = ByteArray(16),
  ...
)
```

จากนั้น เราจะพูดถึงขั้นตอนที่แนะนำในการเพิ่มและจัดการข้อมูลเข้าสู่ระบบที่ต้องการ

การตั้งค่า Thread Border Router ใหม่

ก่อนสร้างเครือข่ายใหม่สำหรับ Border Router ใหม่ คุณควรลองใช้ข้อมูลเข้าสู่ระบบของเครือข่ายที่ต้องการก่อน ซึ่งจะช่วยให้อุปกรณ์ Thread เชื่อมต่อกับเครือข่าย Thread เดียวกันเมื่อเป็นไปได้

การเรียกใช้ getPreferredCredentials จะเปิดใช้กิจกรรมที่แจ้งให้ผู้ใช้ยินยอมคำขอเครือข่าย หากมีการจัดเก็บข้อมูลเข้าสู่ระบบของเครือข่ายไว้ในพวงกุญแจดิจิทัลของ Thread SDK ระบบจะส่งข้อมูลเข้าสู่ระบบกลับไปยังแอป

ขอข้อมูลเข้าสู่ระบบ

วิธีแจ้งให้ผู้ใช้ขอข้อมูลเข้าสู่ระบบที่ต้องการ

ประกาศ ActivityLauncher ดังนี้

private lateinit var preferredCredentialsLauncher: ActivityResultLauncher<IntentSenderRequest>

จัดการผลลัพธ์ของกิจกรรมที่แสดงผลเป็น 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.")
   }
 }

หากคุณกำลังตั้งค่า TBR ใหม่ เราขอแนะนำให้คุณ เรียกใช้ preferredCredentials และเปิดใช้กิจกรรม การเรียกใช้นี้จะช่วยให้ TBR ใหม่ใช้ข้อมูลเข้าสู่ระบบเดียวกันกับที่จัดเก็บไว้แล้ว เป็น ข้อมูลเข้าสู่ระบบที่ต้องการ ในโทรศัพท์ ซึ่งจะช่วยให้ TBR ต่างๆ รวมกันเป็นเครือข่ายเดียวกัน
```
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}]") }
}
```

หากกรณีการใช้งานของคุณเกี่ยวข้องกับการตั้งค่าอุปกรณ์ที่ไม่ใช่ TBR เช่น อุปกรณ์ปลายทาง Matter-over-Thread ใหม่ เราขอแนะนำให้คุณใช้ API allActiveCredentials เพื่อดึงข้อมูลเข้าสู่ระบบ การเรียกใช้นี้จะสแกนหา TBR ที่พบในเครือข่ายท้องถิ่น จึงจะไม่แสดงผลข้อมูลเข้าสู่ระบบที่ TBR ที่มีอยู่ไม่สามารถเข้าถึงได้ในเครื่อง

// 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
}

สร้างเครือข่าย Thread ใหม่

หากไม่มีข้อมูลเข้าสู่ระบบของเครือข่าย Thread ที่ต้องการและไม่มีข้อมูลเข้าสู่ระบบของ Thread ที่ใช้งานอยู่ในเครือข่าย Thread ของผู้ใช้ คุณสามารถใช้ API addCredentials เพื่อเพิ่มข้อมูลเข้าสู่ระบบลงในบริการ Google Play ได้ โดยคุณจะต้องสร้าง ThreadBorderAgent และระบุออบเจ็กต์ ThreadNetworkCredentials ด้วย

หากต้องการสร้างเครือข่ายแบบสุ่ม ให้เรียกใช้ newRandomizeBuilder ดังนี้

val threadCredentials = ThreadNetworkCredentials.newRandomizedBuilder().build()

หากต้องการระบุชื่อเครือข่าย Thread ให้ทำดังนี้

val threadCredentials = ThreadNetworkCredentials.newRandomizedBuilder()
  .setNetworkName("ThreadNetworkSDK")
  .build()

เพิ่มข้อมูลเข้าสู่ระบบ

หากต้องการให้ผู้ให้บริการ Thread รายอื่นใช้ข้อมูลเข้าสู่ระบบของเครือข่าย Thread ได้ เราต้องเพิ่มข้อมูลเข้าสู่ระบบดังกล่าวลงในบริการ Google Play นอกจากนี้ เรายังต้องทราบว่าเครือข่าย Thread นี้เป็นของอุปกรณ์ TBR ใดก่อนที่จะเพิ่มข้อมูลเข้าสู่ระบบใหม่ได้

ในตัวอย่างนี้ เราจะสร้าง ThreadBorderAgent จากรหัส Border Agent และส่งข้อมูลเข้าสู่ระบบของเครือข่าย Thread ใหม่ที่คุณเพิ่งสร้าง

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

ตรวจหาและย้าย border router ที่ใช้งานอยู่

หากมี border router ที่ใช้งานอยู่ คุณสามารถใช้ isPreferredCredentials เพื่อตรวจสอบว่า border router อยู่ในเครือข่ายที่ต้องการหรือไม่ API นี้จะไม่แจ้งให้ ผู้ใช้ขอสิทธิ์ และจะตรวจสอบborder routerข้อมูลเข้าสู่ระบบกับ ข้อมูลที่จัดเก็บไว้ในบริการ Google Play

isPreferredCredentials จะแสดงผล 0 หากไม่ตรงกัน และ 1 หากตรงกันเป็นประเภทข้อมูล Int คุณสามารถใช้ IsPreferredCredentialsResult เพื่อตรวจสอบผลลัพธ์

public @interface IsPreferredCredentialsResult {
    int PREFERRED_CREDENTIALS_NOT_FOUND = -1;
    int PREFERRED_CREDENTIALS_NOT_MATCHED = 0;
    int PREFERRED_CREDENTIALS_MATCHED = 1;
}

หากต้องการใช้ isPreferredCredentials คุณจะต้องสร้างออบเจ็กต์ ThreadNetworkCredentials ก่อน โดยสร้างอินสแตนซ์ ThreadNetworkCredentials ได้หลายวิธี เราจะพูดถึงตัวเลือกเหล่านี้ในขั้นตอนถัดไป

ข้อมูลเข้าสู่ระบบของเครือข่าย Thread ตามชุดข้อมูลการทำงาน

ในบางกรณี TBR ของคุณอาจตั้งค่าด้วยเครือข่าย Thread อยู่แล้ว และคุณต้องการเพิ่มเครือข่าย Thread นี้ลงในบริการ Google Play เพื่อแชร์กับผู้ให้บริการรายอื่น คุณสามารถสร้างอินสแตนซ์ ThreadNetworkCredential จากรายการ TLV ของชุดข้อมูลการทำงานที่ใช้งานอยู่ของ Thread แบบดิบได้ดังนี้

แปลงชุดข้อมูลการทำงานเป็น ByteArray เช่น

val activeDataset =
      "0e080000000000010000000300000f35060004001fffe0020833333333...".dsToByteArray()

fun String.dsToByteArray(): ByteArray {
  return chunked(2).map { it.toInt(16).toByte() }.toByteArray()
}

ใช้ fromActiveOperationalDataset เพื่อสร้าง ThreadNetworkCredentials เมื่อสำเร็จ คุณจะดูชื่อเครือข่าย Thread, ช่อง และข้อมูลเครือข่ายอื่นๆ ได้ โปรดดูรายการพร็อพเพอร์ตี้ทั้งหมดที่ ThreadNetworkCredentials
```
val threadNetworkCredentials =
    ThreadNetworkCredentials.fromActiveOperationalDataset(activeDataset)
Log.d(
    "threadNetworkCredentials",
    threadNetworkCredentials.channel.toString() + " - " + threadNetworkCredentials.networkName)
```

เรียกใช้ API isPreferredCredentials และส่ง 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}]") }

ข้อมูลเข้าสู่ระบบของเครือข่าย Thread ตาม Border Agent

รหัส Border Agent จะระบุอุปกรณ์ TBR ได้อย่างไม่ซ้ำกัน หากต้องการใช้ API getCredentialsByBorderAgent คุณจะต้องสร้างออบเจ็กต์ ThreadBorderAgent และส่งรหัส Border Agent ก่อน

เมื่อสร้างออบเจ็กต์ ThreadBorderAgent แล้ว ให้เรียกใช้ getCredentialsByBorderAgent หากมีการบันทึกข้อมูลเข้าสู่ระบบไว้ ให้ตรวจสอบว่าข้อมูลเข้าสู่ระบบดังกล่าวเป็นข้อมูลเข้าสู่ระบบที่ต้องการหรือไม่

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 ตาม Extended Pan ID

คุณสามารถแจ้งให้ผู้ใช้ขอข้อมูลเข้าสู่ระบบจาก ข้อมูลเข้าสู่ระบบจาก TBR Extended Pan ID ได้เช่นเดียวกับ getPreferredCredentials getCredentialsByExtendedPanId จะแสดงผล IntentSender และผลลัพธ์ของกิจกรรมจะมีออบเจ็กต์ ThreadNetworkCredentials เมื่อผู้ใช้ให้ความยินยอม

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

นำข้อมูลเข้าสู่ระบบออก

เมื่อนำอุปกรณ์ border router ออกจากบ้านหรือรีเซ็ตเป็นค่าเริ่มต้น คุณต้องนำเครือข่าย Thread ของอุปกรณ์ดังกล่าวออกจากบริการ 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}]") }
}

แหล่งข้อมูล

ดูข้อมูลเพิ่มเติมเกี่ยวกับ Thread Network SDK ได้ที่ เอกสารอ้างอิง API