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

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

لجعل بيانات اعتماد شبكة Thread متاحة لمورّدي سلاسل المحادثات الآخرين، علينا إضافتها إلى خدمات Google Play. قبل أن نتمكن من إضافة بيانات الاعتماد الجديدة، نحتاج أيضًا إلى معرفة جهاز توجيه الحدود الذي تنتمي إليه شبكة 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}]") }
}

اكتشاف أجهزة توجيه الحدود الميدانية ونقلها

وإذا كانت لديك أجهزة توجيه حدودية في الحقل، يمكنك استخدام 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 عن طريق مجموعة البيانات التشغيلية

هناك حالات تم فيها إعداد جهاز توجيه حدود سلسلة المحادثات باستخدام شبكة سلاسل محادثات، وتريد إضافة شبكة سلسلة المحادثات هذه إلى خدمات 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 API، عليك أولاً إنشاء كائن 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}]") }
}

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

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