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

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

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

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

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

16.0.0

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

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

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

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

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

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

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

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

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

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

การค้นพบของเส้นขอบชายแดน

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

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

สําหรับเครือข่ายที่มี 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 เพื่อจัดเก็บข้อมูลของเราเตอร์เส้นขอบ เราจะใช้ข้อมูลนี้ตลอดเวลาในคําแนะนํา

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

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

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

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

และเช่นเดียวกับ getPreferredCredentials คุณสามารถแจ้งให้ผู้ใช้ รับข้อมูลเข้าสู่ระบบได้จากรหัส Extended Pan ID ของเราเตอร์เส้นขอบ 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