حزمة تطوير البرامج لشبكة 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 التي تم اختيارها تلقائيًا بيانات الاعتماد التي يمكن مشاركتها مع تطبيقات من موردين مختلفين باستخدام واجهة برمجة تطبيقات getPreferredCredentials.

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

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

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

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

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

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

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

يجب حفظ بيانات الاعتماد باستخدام "معرّف وكيل الحدود". ستحتاج إلى التأكد من يستطيع تطبيق Thread Border Router Setup تحديد أرقام تعريف وكيل الحدود أجهزة توجيه حدود 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),
     ...
   )
   

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

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

قبل إنشاء شبكة جديدة لأجهزة توجيه الحدود، من المهم أن تحاول استخدام بيانات اعتماد الشبكة المفضلة أولاً. يضمن ذلك أن يتم ربط أجهزة 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. الاتصال بـ "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 المفضَّلة متاحة في حساب المستخدم 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 من قبل باستخدام شبكة Thread، وتريد إضافة شبكة Thread هذه إلى خدمات Google Play لمشاركتها مع البائعين الآخرين. يمكنك إنشاء ThreadNetworkCredential. مثال من قائمة مجموعة بيانات تشغيلية أولية لسلسلة Thread Active:

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

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

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