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

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

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

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

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

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

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

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

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

يجب حفظ بيانات الاعتماد باستخدام رقم تعريف وكيل الحدود. عليك التأكّد من أنّ تطبيق إعداد TBR يمكنه تحديد أرقام تعريف وكيل الحدود لـ TBRs.

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

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

دمج حزمة تطوير البرامج (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 (TBR)

قبل إنشاء شبكة جديدة لأجهزة توجيه حدود جديدة، من المهم محاولة استخدام بيانات اعتماد الشبكة المفضّلة أولاً. يضمن ذلك اتصال أجهزة 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. إذا كنت تُعدّ جهاز توجيه حدود شبكة Thread (TBR) جديدًا، ننصحك بطلب بيانات من TBRpreferredCredentials وتشغيل النشاط. سيضمن هذا الطلب أن يستخدم TBR الجديد بيانات الاعتماد نفسها المخزّنة حاليًا على أنّها مفضّلة في الهاتف، ما يعزّز تقارب أجهزة توجيه حدود شبكة Thread (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. إذا كانت حالة الاستخدام مرتبطة بإعداد أجهزة غير أجهزة توجيه حدود شبكة Thread (TBR)، مثل جهاز نهائي جديد من نوع Matter-over-Thread، ننصحك باستخدام واجهة برمجة التطبيقات allActiveCredentials لجلب بيانات الاعتماد. سيؤدي هذا الطلب إلى البحث عن أجهزة توجيه حدود شبكة Thread (TBR) في الشبكة المحلية، وبالتالي لن يعرض بيانات الاعتماد التي لا يوفّرها جهاز توجيه حدود شبكة Thread (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 (TBR) الذي تنتمي إليه شبكة 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}]") }
}

اكتشاف border router في الموقع ونقلها

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

في بعض الحالات، يكون جهاز توجيه حدود شبكة Thread (TBR) TBR مُعدًا مسبقًا باستخدام شبكة 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. عند نجاح العملية، ستتمكّن من الحصول على اسم شبكة 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 حسب وكيل الحدود

يحدّد رقم تعريف وكيل الحدود جهاز TBR بشكل فريد. لاستخدام واجهة برمجة التطبيقات 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 حسب رقم تعريف 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، يُرجى الرجوع إلى مرجع واجهة برمجة التطبيقات.