حزمة تطوير البرامج (SDK) لشبكة Thread لشبكة Android

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

تقدّم حزمة تطوير البرامج (SDK) الخاصة بـ Thread Network وظائف مشابهة لسلسلة مفاتيح رقمية، ما يسمح لتطبيقات Android بمشاركة بيانات اعتماد شبكة Thread مع خدمات Google Play. ويسمح هذا الإجراء لتطبيقاتك بإعداد أي جهاز Thread من أي منظومة متكاملة للمنزل الذكي، بدون الكشف عن بيانات الاعتماد وبيانات المستخدمين مباشرةً.

ومن خلال بضع طلبات بيانات من واجهة برمجة التطبيقات فقط، يمكنك تنفيذ ما يلي:

  1. يمكنك طلب بيانات اعتماد شبكة Thread المفضّلة من خدمات Google Play.
  2. يمكنك إعداد أجهزة توجيه حدودية جديدة وإضافة بيانات اعتماد شبكة Thread إلى خدمات Google Play.
  3. إذا كانت لديك أجهزة توجيه حدودية في الحقل، يمكنك التحقق مما إذا كانت أجهزة توجيه الحدود موجودة في الشبكة المفضّلة ونقلها، إذا لزم الأمر.

هناك العديد من رحلات المستخدمين ومطوّري البرامج التي يجب وضعها في الاعتبار. سنتناول معظم هذه المواضيع في هذا الدليل، بالإضافة إلى الميزات الرئيسية الأخرى والاستخدام المُقترَح.

المصطلحات الرئيسية ومفاهيم واجهة برمجة التطبيقات

قبل البدء، من المفيد فهم البنود التالية:

  • بيانات اعتماد شبكة Thread: عبارة عن كائن ثنائي كبير من سلاسل TLV التي تعمل على ترميز اسم شبكة Thread ومفتاح الشبكة وخصائص أخرى مطلوبة من خلال جهاز Thread للانضمام إلى شبكة Thread مُحدَّدة.

  • بيانات اعتماد شبكة Thread المفضّلة: هي بيانات اعتماد شبكة Thread المختارة تلقائيًا، والتي يمكن مشاركتها مع تطبيقات مورّدين مختلفين باستخدام واجهة برمجة التطبيقات getPreferredCredentials.

  • رقم تعريف وكيل الحدود: معرّف فريد عالمي يبلغ 16 بايت لجهاز توجيه سلسلة المحادثات. يتم إنشاء هذا المعرّف وإدارته من قِبل مورّدي جهاز توجيه الحدود.

  • تطبيق إعداد جهاز توجيه سلاسل المحادثات: هذا هو تطبيقك المتوافق مع Android الذي يعمل على إعداد أجهزة جهاز توجيه سلسلة المحادثات الجديدة التي تضيف بيانات اعتماد شبكة Thread إلى خدمات Google Play. تطبيقك هو المالك الموثوق به لبيانات الاعتماد التي تمت إضافتها، ويمكنه الوصول مجانًا إلى بيانات الاعتماد.

تعرض العديد من واجهات برمجة تطبيقات Thread Network مهمة مكتملة بشكل غير متزامن. يمكنك استخدام الترميزَين addOnSuccessListener وaddOnFailureListener لتسجيل استدعاءات تلقّي النتيجة. لمزيد من المعلومات، راجِع مستندات مهام Google.

ملكية بيانات الاعتماد وصيانتها

يصبح التطبيق الذي يضيف بيانات اعتماد شبكة Thread هو مالك بيانات الاعتماد، ويمتلك الأذونات الكاملة للوصول إلى بيانات الاعتماد. وإذا حاولت الوصول إلى بيانات الاعتماد التي أضفتها تطبيقات أخرى، ستظهر لك رسالة خطأ PERMISSION_DENIED.

بصفتك مالك التطبيق، ننصحك بالإبقاء على بيانات الاعتماد المخزّنة في خدمات Google Play محدّثة عند تحديث شبكة جهاز توجيه سلاسل المحادثات. وهذا يعني إضافة بيانات الاعتماد عند الطلب وتحديث بيانات الاعتماد عند تغيير بيانات اعتماد شبكة Thread

اكتشاف وكيل الحدود

يجب حفظ بيانات الاعتماد باستخدام رقم تعريف وكيل الحدود. يجب التأكّد من أنّ تطبيق "جهاز توجيه سلسلة المحادثات" قادر على تحديد أرقام تعريف وكيل الحدود في أجهزة توجيه الحدود في سلسلة المحادثات.

يجب أن تستخدم أجهزة توجيه حدود سلسلة المحادثات عنصر mDNS للإعلان عن معلومات شبكة Thread، بما في ذلك اسم الشبكة ومعرّف العرض الشامل الموسَّع ومعرِّف وكيل الحدود. وقيم txt المقابلة لهذه السمات هي nn وxp وid على التوالي.

بالنسبة إلى الشبكات المزوّدة بأجهزة توجيه الحدود من Google، تحصل خدمات Google Play تلقائيًا على بيانات اعتماد شبكة Google Thread لاستخدامها.

دمج حزمة تطوير البرامج (SDK) في تطبيق Android

للبدء، أكمِل الخطوات التالية:

  1. اتّبِع التعليمات المقدّمة في إعداد خدمات Google Play.

  2. إضافة الاعتمادية على خدمات 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),
      ...
    )
    

سننتقل بعد ذلك إلى الخطوات المقترَحة لإضافة بيانات الاعتماد المفضَّلة وإدارتها.

عمليات إعداد أجهزة توجيه الحدود الجديدة

قبل إنشاء شبكة جديدة لأجهزة توجيه الحدود الجديدة، من المهم أن تحاول استخدام بيانات اعتماد الشبكة المفضَّلة أولاً. ويضمن ذلك ربط أجهزة Thread بشبكة Thread واحدة إن أمكن.

يتم الاتصال من خلال getPreferredCredentials بنشاط، يطلب من المستخدمين السماح بطلب الشبكة. وإذا تم تخزين بيانات اعتماد الشبكة في سلسلة مفاتيح حزمة تطوير البرامج (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}]") }
    }
    

إنشاء شبكة Thread جديدة

في حال عدم توفّر بيانات اعتماد شبكة Thread المفضّلة في شبكة للمستخدمين، يمكنك استخدام واجهة برمجة تطبيقات addCredentials لإضافة بيانات الاعتماد إلى خدمات Google Play. لإجراء ذلك، عليك إنشاء ThreadBorderAgent وتوفير عنصر ThreadNetworkCredentials أيضًا.

لإنشاء شبكة عشوائية، اطلب newRandomizeBuilder:

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

لتحديد اسم شبكة Thread:

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

إضافة بيانات الاعتماد

لجعل بيانات اعتماد شبكة 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 لتحديد ما إذا كانت أجهزة توجيه الحدود تنتمي إلى الشبكة المفضَّلة. لا تطلب واجهة برمجة التطبيقات هذه من المستخدم الحصول على الإذن، وتتحقّق من بيانات اعتماد جهاز توجيه الحدود في مقابل ما تم تخزينه في خدمات 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 حسب مجموعة البيانات التشغيلية

هناك حالات تم فيها إعداد جهاز توجيه حدود سلاسل المحادثات باستخدام شبكة 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. عند إتمام هذه الخطوة بنجاح، ستتمكن من الحصول على اسم شبكة Thread واسم القناة ومعلومات أخرى عن الشبكة. للحصول على قائمة كاملة بالخصائص، يمكنك الرجوع إلى ThreadNetworkCredentials.

    val threadNetworkCredentials =
        ThreadNetworkCredentials.fromActiveOperationalDataset(activeDataset)
    Log.d(
        "threadNetworkCredentials",
        threadNetworkCredentials.channel.toString() + " - " + threadNetworkCredentials.networkName)
    
  3. اتّصِل بواجهة برمجة التطبيقات 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}]") }
    

بيانات اعتماد شبكة Thread عن طريق وكيل الحدود

يحدّد "معرّف وكيل الحدود" بشكلٍ فريد جهاز توجيه الحدود. لاستخدام واجهة برمجة التطبيقات getCredentialsByBorderAgent، يجب أولاً إنشاء كائن 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}]") }
}

بيانات اعتماد شبكة Thread حسب رقم تعريف العرض الموسّع

على غرار 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}]") }
}

إزالة بيانات الاعتماد

عند إزالة جهاز توجيه الحدود من منزلك أو الإعدادات الأصلية، تحتاج إلى إزالة شبكة 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) لـ Thread Network، يُرجى الرجوع إلى مرجع واجهة برمجة التطبيقات.