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

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

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

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

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

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

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

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

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

• معرّف وكيل الحدود: معرّف فريد عالميًا مكوّن من 16 بايت لجهاز "جهاز توجيه حدودي" Thread ينشئ مورّدو أجهزة توجيه الحدود هذا المعرّف ويديرونه.

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

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

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

يصبح التطبيق الذي يضيف بيانات اعتماد شبكة Thread مالكًا لข้อมูล الاعتماد، ويحصل على أذونات كاملة للوصول إلى بيانات الاعتماد. إذا حاولت للوصول إلى بيانات الاعتماد التي تضيفها تطبيقات أخرى، ستتلقى PERMISSION_DENIED. خطأ.

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

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

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

يجب أن تستخدم أجهزة توجيه الحدود في Thread بروتوكول mDNS للإعلان عن معلومات شبكة Thread، بما في ذلك اسم الشبكة ورقم تعريف Pan الموسّع ورقم تعريف Border Agent. تشير رسالة الأشكال البيانية قيم 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.2.1'
   

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

   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 فوق شبكة البحث، يُنصح باستخدام 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 الخاصة بالمستخدم، يمكنك استخدام واجهة برمجة التطبيقات addCredentials لإضافة بيانات الاعتماد إلى خدمات Google Play. ولإجراء ذلك، عليك إنشاء ThreadBorderAgent وتوفّر أيضًا كائن ThreadNetworkCredentials.

لإنشاء شبكة عشوائية، يمكنك الاتصال بالرقم newRandomizeBuilder:

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

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

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

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

لإتاحة بيانات اعتماد شبكة Thread لمورّدي 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 Border Router قد تم إعداده مسبقًا باستخدام شبكة 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 من قِبل Border Agent

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

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