Thread Network SDK สำหรับ Android

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

เพียงเรียก API เพียงไม่กี่ครั้ง คุณก็จะทำสิ่งต่อไปนี้ได้

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

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

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

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

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

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

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

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

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

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

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

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

การค้นหา Border Agent

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

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

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

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

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

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

2. เพิ่มทรัพยากร Dependency ของบริการ Google Play ลงในไฟล์ build.gradle ดังนี้

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

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. โทรหา preferredCredentials และเปิดกิจกรรม:

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

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

หากไม่มีข้อมูลเข้าสู่ระบบเครือข่ายเทรดที่ต้องการใน เครือข่ายเทรด จากนั้นคุณสามารถใช้ 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 ของชุดข้อมูลการดำเนินการเทรดที่ใช้งานอยู่

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