หน้านี้ได้รับการแปลโดย Cloud Translation API

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

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

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

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

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

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

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

ข้อมูลเข้าสู่ระบบเครือข่ายเทรด: BLOB ของ TLV ของเทรดแบบเข้ารหัสที่เข้ารหัส ชื่อเครือข่ายเทรด คีย์เครือข่าย และพร็อพเพอร์ตี้อื่นๆ ที่อุปกรณ์เทรดกําหนดให้ต้องเข้าร่วมเครือข่ายเทรดที่ระบุ
ข้อมูลเข้าสู่ระบบเครือข่ายเทรดที่ต้องการ: ข้อมูลเข้าสู่ระบบเครือข่ายเทรดที่เลือกโดยอัตโนมัติซึ่งแชร์กับแอปของผู้ให้บริการต่างๆ ได้โดยใช้ getPreferredCredentials API
รหัสตัวแทนเส้นขอบ: รหัสที่ไม่ซ้ํากันทั่วโลกขนาด 16 ไบต์สําหรับอุปกรณ์เราเตอร์ Thread Border Border รหัสนี้สร้างและจัดการโดยผู้ให้บริการเราเตอร์เส้นขอบ
แอปการตั้งค่า Thread Border Router: เป็นแอป Android ที่ตั้งค่าอุปกรณ์ Thread Border Router ใหม่ และเพิ่มข้อมูลเข้าสู่ระบบของเครือข่าย "เทรด" ไปยังบริการ Google Play แอปของคุณเป็นเจ้าของข้อมูลเข้าสู่ระบบที่ได้รับอนุญาตที่เชื่อถือได้และมีสิทธิ์เข้าถึงข้อมูลเหล่านั้น

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

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

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

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

การค้นพบตัวแทนเส้นขอบ

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

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

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

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

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

ทําตามวิธีการที่ระบุไว้ในการตั้งค่าบริการ Google Play
เพิ่มทรัพยากร Dependency ของบริการ Google Play ไปยังไฟล์ build.gradle ดังนี้
```
implementation 'com.google.android.gms:play-services-threadnetwork:16.0.0'
```
ไม่บังคับ: กําหนดคลาสข้อมูล 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 ไว้ ระบบจะคืนข้อมูลเข้าสู่ระบบให้กับแอป

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

หากต้องการแจ้งผู้ใช้ด้วยข้อมูลเข้าสู่ระบบที่ต้องการ ให้ทําดังนี้

ประกาศ ActivityLauncher:

private lateinit var preferredCredentialsLauncher: ActivityResultLauncher<IntentSenderRequest>

จัดการผลลัพธ์ของกิจกรรมซึ่งแสดงเป็น 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.")
   }
 }

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

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

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

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

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

ใช้ fromActiveOperationalDataset เพื่อสร้าง ThreadNetworkCredentials แต่เมื่อสําเร็จ คุณจะดูชื่อเครือข่าย ช่อง และข้อมูลอื่นๆ ของเครือข่ายได้ ดูรายการพร็อพเพอร์ตี้ทั้งหมดได้ที่ ThreadNetworkCredentials
```
val threadNetworkCredentials =
    ThreadNetworkCredentials.fromActiveOperationalDataset(activeDataset)
Log.d(
    "threadNetworkCredentials",
    threadNetworkCredentials.channel.toString() + " - " + threadNetworkCredentials.networkName)
```

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