Thread Network SDK สำหรับ Android

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

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

1. ขอข้อมูลเข้าสู่ระบบเครือข่ายเทรดที่ต้องการจากบริการ Google Play
2. ตั้งค่า Border Router ใหม่และเพิ่มข้อมูลเข้าสู่ระบบเครือข่ายเทรดไปยังบริการ Google Play
3. หากมี Border Router ในพื้นที่อยู่แล้ว ให้ตรวจสอบว่า Border Router เราเตอร์อยู่ในเครือข่ายที่ต้องการ และย้ายข้อมูล ถ้าจำเป็น

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

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

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

• ข้อมูลเข้าสู่ระบบของเครือข่ายเทรด: บล็อกไบนารีของ TLV เทรดที่เข้ารหัสชื่อเครือข่ายเทรด คีย์เครือข่าย และพร็อพเพอร์ตี้อื่นๆ ที่อุปกรณ์เทรดต้องใช้เพื่อเข้าร่วมเครือข่ายเทรดหนึ่งๆ

• ข้อมูลเข้าสู่ระบบเครือข่ายเทรดที่ต้องการ: ข้อมูลเข้าสู่ระบบเครือข่ายเทรดที่ระบบเลือกโดยอัตโนมัติ ซึ่งแชร์กับแอปของผู้ให้บริการรายต่างๆ ได้โดยใช้ getPreferredCredentials API

• รหัส Agent ของเส้นขอบ: รหัสที่ไม่ซ้ำกันทั่วโลกขนาด 16 ไบต์สำหรับ Thread Border Router อุปกรณ์ รหัสนี้สร้างและจัดการโดยผู้ให้บริการเราเตอร์ Border

• แอปการตั้งค่า Thread Border Router: นี่คือแอป Android ที่ตั้งค่า อุปกรณ์ Thread Border Router ใหม่และเพิ่มข้อมูลรับรองเครือข่าย Thread ไปยัง บริการ Google Play แอปของคุณเป็นเจ้าของที่ได้รับอนุญาตของ และมีสิทธิ์เข้าถึงข้อมูลดังกล่าว

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

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

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

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

การค้นหา Border Agent

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

Border Router ของเทรดต้องใช้ mDNS เพื่อโฆษณาข้อมูลเครือข่ายเทรด ซึ่งรวมถึงชื่อเครือข่าย รหัส PAN แบบขยาย และรหัส Border Agent ค่า txt ที่สอดคล้องกันสำหรับแอตทริบิวต์เหล่านี้คือ nn, xp และ id ตามลำดับ

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

ผสานรวม SDK ในแอป Android

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

1. ทำตามคำแนะนำที่ให้ไว้ที่ ตั้งค่าบริการ Google Play

2. เพิ่มการพึ่งพาบริการ Google Play ลงในไฟล์ build.gradle

   implementation 'com.google.android.gms:play-services-threadnetwork:16.2.1'
   

3. ไม่บังคับ: กำหนดคลาสข้อมูล BorderAgent เพื่อจัดเก็บข้อมูล Border Router เราจะใช้ข้อมูลนี้ตลอดทั้งคู่มือนี้

   data class BorderAgentInfo(
     // Network Name max 16 len
     val networkName: String = "",
     val extPanId: ByteArray = ByteArray(16),
     val borderAgentId: ByteArray = ByteArray(16),
     ...
   )
   

จากนั้นเราจะไปดูขั้นตอนที่แนะนำเพื่อเพิ่มและจัดการ ข้อมูลเข้าสู่ระบบ

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

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

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

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

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

1. ประกาศ ActivityLauncher:

   private lateinit var preferredCredentialsLauncher: ActivityResultLauncher<IntentSenderRequest>
   

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

4. หากกรณีการใช้งานเกี่ยวข้องกับการตั้งค่าอุปกรณ์ที่ไม่ใช่ TBR เช่น อุปกรณ์ปิดท้าย Matter-over-Thread ขอแนะนำให้คุณใช้ allActiveCredentials API เพื่อดึงข้อมูลเข้าสู่ระบบ การโทรนี้จะสแกนหา 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
   }
   

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

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

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

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

วิธีระบุชื่อเครือข่ายเทรด

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

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

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

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

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

isPreferredCredentails จะแสดงผล 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 Border Router ด้วย เครือข่ายเทรด และคุณต้องการเพิ่มเครือข่ายเทรดนี้ไปยังบริการ Google Play เพื่อนำไปแชร์กับผู้ให้บริการรายอื่น คุณสามารถสร้างThreadNetworkCredential อินสแตนซ์จากรายการ TLV ของชุดข้อมูลการทํางานของ Thread ที่ใช้งานอยู่แบบดิบได้ดังนี้

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

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

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

2. ใช้ fromActiveOperationalDataset เพื่อสร้าง ThreadNetworkCredentials เมื่อดำเนินการสำเร็จ คุณจะเห็นชื่อ ช่อง และข้อมูลอื่นๆ ของเครือข่ายเทรด ดูรายการที่พักทั้งหมดได้ที่ ThreadNetworkCredentials

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

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

ข้อมูลเข้าสู่ระบบเครือข่ายเทรดโดย Border Agent

รหัส Border Agent จะระบุอุปกรณ์ Border Router โดยไม่ซ้ำกัน หากต้องการใช้ getCredentialsByBorderAgent API ก่อนอื่นคุณต้องสร้างออบเจ็กต์ 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}]") }
}

ข้อมูลเข้าสู่ระบบเครือข่ายเทรดตามรหัสการเลื่อนที่ขยาย

ซึ่งคล้ายกับ getPreferredCredentials คุณสามารถแจ้งผู้ใช้ให้ ข้อมูลเข้าสู่ระบบจากรหัส Extended Pan ของ Border Router 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}]") }
}

แหล่งข้อมูล

หากต้องการเรียนรู้เพิ่มเติมเกี่ยวกับ SDK เครือข่ายเทรด โปรดดูที่ เอกสารอ้างอิง API