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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

ค้นหา Agent ของเส้นขอบ

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

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

สําหรับเครือข่ายที่มีเราเตอร์เส้นขอบของ Google บริการ Google Play จะได้รับข้อมูลเข้าสู่ระบบเครือข่ายชุดข้อความของ Google โดยอัตโนมัติ

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

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

  1. ทําตามวิธีการที่ระบุไว้ที่ตั้งค่าบริการ Google Play

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

    implementation 'com.google.android.gms:play-services-threadnetwork:16.0.0-beta01'
    
  3. ไม่บังคับ: กําหนด BorderAgent data class เพื่อจัดเก็บข้อมูลเราเตอร์เส้นขอบ เราจะใช้ข้อมูลนี้ตลอดทั้งคู่มือนี้

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

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

หากไม่มีข้อมูลเข้าสู่ระบบเครือข่ายชุดข้อความที่ต้องการในเครือข่ายชุดข้อความของผู้ใช้ คุณจะใช้ addCredentials API เพื่อเพิ่มข้อมูลเข้าสู่ระบบในบริการ 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}]") }
}

ตรวจหาและย้ายข้อมูลเราเตอร์เส้นขอบภาคสนาม

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

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

มีกรณีที่เราเตอร์ Thread Border มีการตั้งค่ากับเครือข่าย Thread อยู่แล้ว และคุณต้องการเพิ่มเครือข่าย Thread นี้ไปยังบริการ 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

รหัส Agent Border จะระบุอุปกรณ์ของเราเตอร์เส้นขอบโดยไม่ซ้ํากัน หากต้องการใช้ 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

เช่นเดียวกับ 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 ออกจากบ้านหรือรีเซ็ตเป็นค่าเริ่มต้น คุณต้องนําเครือข่ายเทรดออกจากบริการ 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