SDK เทรดเครือข่ายสําหรับ Android

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

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

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

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

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

แนวคิดคําศัพท์และ API ที่สําคัญ

ก่อนเริ่มต้น คุณควรทําความเข้าใจข้อกําหนดต่อไปนี้

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

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

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

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

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

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

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

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

การค้นพบพรมแดนตัวแทน

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

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

สําหรับเครือข่ายที่มีเราเตอร์เส้นขอบของ Google บริการ 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-beta02'
    
  3. ไม่บังคับ: กําหนดคลาสข้อมูลใน BorderAgent เพื่อจัดเก็บข้อมูลเราเตอร์เส้นขอบ เราจะใช้ข้อมูลนี้ตลอดทั้งคู่มือนี้

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

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

การตั้งค่าเราเตอร์ขอบใหม่

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

การเรียก 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}]") }
    }
    

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

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

หากต้องการสร้างเครือข่ายแบบสุ่ม ให้โทรหา newRandomizeBuilder:

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

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

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

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

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

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

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 Field แล้ว คุณสามารถใช้ isPreferredCredentials เพื่อพิจารณาว่าเราเตอร์ Border เป็นของเครือข่ายที่ต้องการหรือไม่ API นี้ไม่แจ้งให้ผู้ใช้ขอสิทธิ์ และตรวจสอบข้อมูลเข้าสู่ระบบของเราเตอร์กับสิ่งที่เก็บไว้ในบริการ 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 มีหลายวิธี ในขั้นตอนถัดไป เราจะพูดถึงตัวเลือกเหล่านี้

จัดการข้อมูลรับรองของเครือข่ายตามชุดข้อมูลการดําเนินการ

อาจมีกรณีที่ตั้งค่าเราเตอร์เทรดเส้นขอบกับเครือข่ายเทรดแล้ว และคุณต้องการเพิ่มเครือข่ายเทรดนี้ไปยังบริการ 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. เรียก 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}]") }
    

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

รหัส Border Agent จะระบุอุปกรณ์ Border Router หากต้องการใช้ getCredentialsByBorderAgent API คุณจะต้องสร้างออบเจ็กต์ ThreadBorderAgent แล้วส่งผ่านรหัส Agent Border

เมื่อสร้างออบเจ็กต์ 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}]") }
}

ระบุข้อมูลเข้าสู่ระบบของเครือข่ายเทรดตามรหัส Extended Pan

คุณแจ้งผู้ใช้เกี่ยวกับข้อมูลรับรองจากเราเตอร์ขยายฐานของ B&#39 ได้คล้ายกับ 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}]") }
}

แหล่งข้อมูล

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