حزمة تطوير البرامج لشبكة Thread Network لنظام التشغيل Android

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

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

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

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

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

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

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

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

• رقم تعريف وكيل الحدود: هو رقم تعريف فريد عالميًا مكوّن من 16 بايت TBR للجهاز. يتم إنشاء هذا المعرّف وإدارته من قِبل مورّدي border router.

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

تعرض العديد من واجهات برمجة التطبيقات Thread Network واجهة برمجة تطبيقات Task تكتمل بشكل غير متزامن. يمكنك استخدام addOnSuccessListener وaddOnFailureListener لتسجيل عمليات الاستدعاء من أجل تلقّي النتيجة. لمزيد من المعلومات، يُرجى الرجوع إلى مستندات Task.

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

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

بصفتك مالك التطبيق، ننصحك بالاحتفاظ ببيانات الاعتماد المخزَّنة في "خدمات Google Play" محدَّثة عند تحديث شبكة "TBR". يعني ذلك إضافة بيانات الاعتماد عند الحاجة، وتعديلها عند تغيير بيانات اعتماد شبكة Thread في "border router"، وإزالة بيانات الاعتماد عند إزالة "TBR" أو إعادة ضبطه على الإعدادات الأصلية.

اكتشاف Border Agent

يجب حفظ بيانات الاعتماد باستخدام معرّف Border Agent. عليك التأكّد من أنّ تطبيق إعداد TBR قادر على تحديد معرّفات Border Agent لأجهزة TBR.

يجب أن تستخدم أجهزة "TBR" نظام أسماء النطاقات المتعدد البث (mDNS) للإعلان عن معلومات شبكة Thread، بما في ذلك اسم الشبكة ورقم تعريف PAN الموسّع ورقم تعريف Border Agent. القيم المقابلة لهذه السمات في txt هي nn وxp وid على التوالي.

بالنسبة إلى الشبكات التي تتضمّن Google Thread Border Router (gTBR)، تحصل "خدمات Google Play" تلقائيًا على بيانات اعتماد شبكة Google Thread لاستخدامها.

دمج حزمة SDK في تطبيق Android

للبدء، يُرجى إكمال الخطوات التالية:

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

2. أضِف تبعية "خدمات Google Play" إلى ملف build.gradle:

   implementation 'com.google.android.gms:play-services-threadnetwork:16.2.1'
   

3. اختياري: حدِّد فئة بيانات BorderAgent لتخزين معلومات TBR. سنستخدم هذه البيانات خلال هذا الدليل:

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

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

عمليات إعداد جديدة لأجهزة توجيه حدود شبكة Thread

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

يؤدي استدعاء getPreferredCredentials إلى تشغيل نشاط يطلب من المستخدمين السماح بطلب الشبكة. إذا تم تخزين بيانات اعتماد الشبكة في سلسلة المفاتيح الرقمية لحزمة تطوير البرامج (SDK) لبروتوكول Thread، يتم عرض بيانات الاعتماد إلى تطبيقك.

طلب بيانات الاعتماد

لطلب بيانات الاعتماد المفضّلة من المستخدم:

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

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

4. إذا كانت حالة الاستخدام تتعلّق بإعداد أجهزة غير متوافقة مع TBR، مثل جهاز طرفي جديد متوافق مع Matter-over-Thread، ننصحك باستخدام واجهة برمجة التطبيقات allActiveCredentials لجلب بيانات الاعتماد. ستبحث هذه المكالمة عن أجهزة TBR في الشبكة المحلية، وبالتالي لن تعرض بيانات الاعتماد غير المتوفّرة من خلال جهاز TBR حالي على الجهاز.

   // Creates the IntentSender result launcher for the getAllActiveCredentials API
   private val getAllActiveCredentialsLauncher =
     registerForActivityResult(
       StartIntentSenderForResult()
     ) { result: ActivityResult ->
       if (result.resultCode == RESULT_OK) {
         val activeCredentials: List<ThreadNetworkCredentials> =
           ThreadNetworkCredentials.parseListFromIntentSenderResultData(
             result.data!!
           )
         // Use the activeCredentials list
       } else {
         // The user denied to share!
       }
     }
   
   // Invokes the getAllActiveCredentials API and starts the dialog activity with the returned
   // IntentSender
   threadNetworkClient
   .getAllActiveCredentials()
   .addOnSuccessListener { intentSenderResult: IntentSenderResult ->
     val intentSender = intentSenderResult.intentSender
     if (intentSender != null) {
       getAllActiveCredentialsLauncher.launch(
         IntentSenderRequest.Builder(intentSender).build()
       )
     } else {
       // No active network credentials found!
     }
   }
   // Handles the failure
   .addOnFailureListener { e: Exception ->
     // Handle the exception
   }
   

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

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

لإنشاء شبكة عشوائية، يمكنك استدعاء newRandomizeBuilder:

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

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

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

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

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

في هذا المثال، سننشئ ThreadBorderAgent من معرّف Border Agent، ونمرّر بيانات اعتماد شبكة 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}]") }
}

رصد أجهزة border router ونقل بياناتها في الميدان

إذا كان لديك border router في الميدان، يمكنك استخدام isPreferredCredentials لتحديد ما إذا كانت border router تنتمي إلى الشبكة المفضّلة. لا تطلب واجهة برمجة التطبيقات هذه من المستخدم الحصول على إذن، وتتحقّق من بيانات اعتماد "border router" مقارنةً بما هو مخزَّن في "خدمات Google Play".

تُرجع الدالة isPreferredCredentials القيمة 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 حسب مجموعة البيانات التشغيلية

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

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 حسب Border Agent

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

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

على غرار getPreferredCredentials، يمكنك أيضًا أن تطلب من المستخدم إدخال بيانات الاعتماد من رقم تعريف PAN الموسّع الخاص بـ TBR. يعرض الإجراء 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}]") }
}

الموارد

لمزيد من المعلومات حول حزمة تطوير البرامج (SDK) لشبكة Thread، يُرجى الاطّلاع على مرجع واجهة برمجة التطبيقات.