Thread Network SDK برای اندروید

Thread Network SDK عملکردی شبیه به زنجیره کلید دیجیتال ارائه می دهد و به برنامه های Android شما اجازه می دهد اعتبار شبکه Thread را با سرویس های Google Play به اشتراک بگذارند. این به برنامه‌های شما اجازه می‌دهد تا هر دستگاه Thread را از هر اکوسیستم خانه هوشمند، بدون افشای مستقیم اطلاعات کاربری و اطلاعات کاربری، راه‌اندازی کنند.

تنها با چند تماس API، می توانید:

  1. اطلاعات کاربری ترجیحی شبکه Thread را از خدمات Google Play درخواست کنید.
  2. مسیریاب‌های مرزی جدید را راه‌اندازی کنید و اعتبار شبکه Thread خود را به خدمات Google Play اضافه کنید.
  3. اگر از قبل روترهای مرزی داخلی دارید، می‌توانید بررسی کنید که آیا روترهای مرزی شما در شبکه ترجیحی هستند یا خیر و در صورت لزوم آنها را مهاجرت کنید.

چندین سفر کاربر و توسعه دهنده وجود دارد که باید در نظر گرفته شود. ما بیشتر آنها را در این راهنما به همراه سایر ویژگی های کلیدی و استفاده توصیه شده پوشش خواهیم داد.

اصطلاحات کلیدی و مفاهیم API

قبل از شروع، درک عبارات زیر مفید است:

  • Thread Network Credentials: حباب باینری از Thread TLV که نام شبکه Thread، کلید شبکه و سایر خصوصیاتی را که توسط یک دستگاه Thread برای پیوستن به یک شبکه Thread معین مورد نیاز است، رمزگذاری می‌کند.

  • Preferred Thread Network Credentials: اعتبار شبکه Thread انتخاب شده خودکار است که می تواند با برنامه های فروشندگان مختلف با استفاده از getPreferredCredentials API به اشتراک گذاشته شود.

  • Border Agent ID: یک شناسه جهانی منحصر به فرد 16 بایتی برای دستگاه Thread Border Router. این شناسه توسط فروشندگان روتر مرزی ایجاد و مدیریت می شود.

  • برنامه راه‌اندازی Thread Border Router: این برنامه Android شما است که دستگاه‌های Thread Border Router جدیدی را راه‌اندازی می‌کند و اعتبار شبکه Thread را به خدمات Google Play اضافه می‌کند. برنامه شما مالک معتبر اعتبارنامه های اضافه شده است و به آنها دسترسی دارد.

بسیاری از API های شبکه Thread یک Task را برمی گردانند که به صورت ناهمزمان تکمیل می شود. می‌توانید از addOnSuccessListener و addOnFailureListener برای ثبت تماس‌ها برای دریافت نتیجه استفاده کنید. برای کسب اطلاعات بیشتر، به مستندات Task مراجعه کنید.

مالکیت و نگهداری مدارک

برنامه ای که اعتبار شبکه Thread را اضافه می کند، مالک اعتبارنامه می شود و مجوزهای کامل برای دسترسی به اعتبارنامه ها را دارد. اگر سعی کنید به اطلاعات کاربری اضافه شده توسط برنامه های دیگر دسترسی پیدا کنید، یک خطای PERMISSION_DENIED دریافت خواهید کرد.

به‌عنوان مالک برنامه، توصیه می‌شود زمانی که شبکه Thread Border Router به‌روزرسانی می‌شود، اعتبارنامه‌های ذخیره شده در سرویس‌های Google Play را به‌روز نگه دارید. این به معنای افزودن اعتبارنامه ها در صورت لزوم، به روز رسانی اعتبار زمانی که اعتبار شبکه Thread مسیریاب مرزی تغییر می کند، و حذف اعتبار زمانی که Thread Border Router یا بازنشانی کارخانه ای انجام می شود، حذف می شود.

کشف مامور مرزی

اعتبارنامه ها باید با شناسه عامل مرزی ذخیره شوند. باید مطمئن شوید که برنامه راه‌اندازی Thread Border Router شما قادر به تعیین شناسه‌های Border Agent روترهای Thread border شما است.

مسیریاب‌های مرزی Thread باید از mDNS برای تبلیغ اطلاعات شبکه Thread از جمله نام شبکه، شناسه Extended Pan و شناسه عامل مرزی استفاده کنند. مقادیر txt مربوط به این ویژگی ها به ترتیب nn ، xp و id هستند.

برای شبکه‌های دارای مسیریاب‌های مرزی Google، خدمات Google Play به‌طور خودکار اعتبار شبکه Google Thread را برای استفاده دریافت می‌کند.

SDK را در برنامه اندروید خود ادغام کنید

برای شروع مراحل زیر را انجام دهید:

  1. دستورالعمل های ارائه شده در راه اندازی سرویس های Google Play را دنبال کنید.

  2. وابستگی خدمات 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),
      ...
    )
    

در مرحله بعد، مراحل توصیه شده برای افزودن و مدیریت اعتبارنامه های ترجیحی را مرور می کنیم.

تنظیمات جدید روتر مرزی

قبل از ایجاد یک شبکه جدید برای روترهای مرزی جدید، مهم است که ابتدا از اعتبار شبکه ترجیحی استفاده کنید. این تضمین می کند که دستگاه های Thread در صورت امکان به یک شبکه Thread متصل هستند.

تماس با getPreferredCredentials یک Activity را راه اندازی می کند و از کاربران می خواهد که درخواست شبکه را مجاز کنند. اگر اعتبار شبکه در زنجیره کلید دیجیتال Thread SDK ذخیره شده باشد، اعتبارنامه به برنامه شما برگردانده می شود.

درخواست اعتبار

برای درخواست از کاربر برای اطلاعات کاربری ترجیحی:

  1. یک ActivityLauncher را اعلام کنید:

    private lateinit var preferredCredentialsLauncher: ActivityResultLauncher<IntentSenderRequest>
    
  2. نتیجه Activity را که به عنوان 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 تماس بگیرید و Activity را راه اندازی کنید:

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

یک شبکه Thread جدید ایجاد کنید

اگر اعتبار شبکه Thread ترجیحی در شبکه Thread کاربر وجود ندارد، می توانید از addCredentials API برای افزودن اعتبارنامه به خدمات Google Play استفاده کنید. برای انجام این کار، باید یک ThreadBorderAgent ایجاد کنید، و همچنین یک شی ThreadNetworkCredentials را تهیه کنید.

برای ایجاد یک شبکه تصادفی، newRandomizeBuilder فراخوانی کنید:

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

برای تعیین نام شبکه Thread:

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

اعتبارنامه را اضافه کنید

برای در دسترس قرار دادن اطلاعات کاربری شبکه Thread شما برای سایر فروشندگان Thread، باید آنها را به خدمات Google Play اضافه کنیم. قبل از اینکه بتوانیم اعتبار جدید خود را اضافه کنیم، همچنین باید بدانیم که این شبکه Thread متعلق به کدام دستگاه روتر مرزی است.

در این مثال، ما یک ThreadBorderAgent از یک شناسه عامل مرزی ایجاد می کنیم و اعتبار شبکه Thread جدیدی را که به تازگی ایجاد کرده اید، ارسال می کنیم:

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 Router شما قبلاً با یک شبکه Thread راه‌اندازی شده است و می‌خواهید این شبکه Thread را به خدمات Google Play اضافه کنید تا آن را با سایر فروشندگان به اشتراک بگذارید. شما می‌توانید یک نمونه ThreadNetworkCredential از یک لیست خام Thread Active Operational Dataset 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

شناسه عامل مرزی به طور منحصربه‌فرد دستگاه روتر مرزی را شناسایی می‌کند. برای استفاده از getCredentialsByBorderAgent API، ابتدا باید یک شی ThreadBorderAgent ایجاد کنید و ID 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}]") }
}

اعتبار شبکه موضوعی توسط Extended Pan ID

مشابه getPreferredCredentials ، همچنین می‌توانید از کاربر برای دریافت اعتبارنامه از Extended Pan ID یک روتر مرزی بخواهید. getCredentialsByExtendedPanId یک IntentSender را برمی‌گرداند و نتیجه Activity حاوی یک شی 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 مراجعه کنید.