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

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

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

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

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

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

قبل البدء، من المفيد فهم المصطلحات التالية:

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

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

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

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

وتعرض العديد من واجهات برمجة تطبيقات Thread Network مهمة تكتمل بشكل غير متزامن. يمكنك استخدام addOnSuccessالاستماعer وaddOnFailureالاستماعer لتسجيل معاودة الاتصال لتلقي النتيجة. لمزيد من المعلومات، يمكنك الرجوع إلى مستندات المهام.

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

يصبح التطبيق الذي يضيف بيانات اعتماد شبكة 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'
    
  3. خطوة اختيارية: حدِّد فئة بيانات BorderAgent لتخزين معلومات جهاز توجيه الحدود. سنستخدم هذه البيانات في هذا الدليل:

    data class BorderAgentInfo(
      // Network Name max 16 len
      val networkName: String = "",
      val extPanId: ByteArray = ByteArray(16),
      val borderAgentId: ByteArray = ByteArray(16),
      ...
    )
    

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

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

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

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

في هذا المثال، سننشئ 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 حسب رقم تعريف 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}]") }
}

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

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