SDK של רשת Thread ל-Android

ערכת ה-SDK של Thread Network מספקת פונקציונליות שדומה למחזיק מפתחות דיגיטלי, ומאפשרת לאפליקציות Android לשתף את פרטי הכניסה לרשת Thread עם Google Play Services. ההרשאה הזו מאפשרת לאפליקציות להגדיר כל מכשיר Thread מכל מערכת אקולוגית של בית חכם, בלי לחשוף ישירות את פרטי הכניסה ואת נתוני המשתמש.

בעזרת כמה קריאות ל-API, אפשר:

  1. שליחת בקשה לפרטי הכניסה המועדפים של רשת Thread מ-Google Play Services.
  2. מגדירים Thread Border Router (TBR) חדשים ומוסיפים את פרטי הכניסה לרשת Thread ל-Google Play Services.
  3. אם כבר יש לכם מכשירי TBR בשטח, אתם יכולים לבדוק אם מכשירי TBR נמצאים ברשת המועדפת ולהעביר אותם, אם צריך.

יש כמה תהליכים שעוברים משתמשים ומפתחים שכדאי להביא בחשבון. במדריך הזה נסביר על רוב התכונות האלה, וגם על תכונות חשובות אחרות ועל אופן השימוש המומלץ בהן.

מונחים חשובים ומושגים שקשורים ל-API

לפני שמתחילים, כדאי להבין את המונחים הבאים:

  • פרטי הכניסה לרשת Thread: Blob בינארי של Thread TLV שמקודד את שם רשת Thread, מפתח הרשת ומאפיינים אחרים שנדרשים למכשיר Thread כדי להצטרף לרשת Thread נתונה.

  • פרטי הכניסה המועדפים לרשת Thread: פרטי הכניסה לרשת Thread שנבחרו באופן אוטומטי שאפשר לשתף עם אפליקציות של ספקים שונים באמצעות getPreferredCredentials API.

  • ‫Border Agent ID: מזהה ייחודי בעולם של 16 בייט למכשיר TBR. המזהה הזה נוצר ומנוהל על ידי ספקי border router.

  • TBR אפליקציית ההגדרה: זו אפליקציית Android שמגדירה מכשירי TBR חדשים ומוסיפה את פרטי הכניסה לרשת Thread ל-Google Play Services. האפליקציה שלכם היא הבעלים הסמכותי של פרטי הכניסה שנוספו ויש לה גישה אליהם.

הרבה ממשקי Thread Network API מחזירים Task שמושלם באופן אסינכרוני. אפשר להשתמש ב-addOnSuccessListener וב-addOnFailureListener כדי לרשום קריאות חוזרות לקבלת התוצאה. מידע נוסף מופיע במאמר בנושא משימות.

בעלות על פרטי הכניסה ותחזוקה שלהם

האפליקציה שמוסיפה את פרטי הכניסה לרשת Thread הופכת לבעלים של פרטי הכניסה, ויש לה הרשאות מלאות לגשת אליהם. אם תנסו לגשת לפרטי כניסה שנוספו על ידי אפליקציות אחרות, תקבלו הודעת שגיאה PERMISSION_DENIED

בתור בעלי האפליקציה, מומלץ לעדכן את פרטי הכניסה שמאוחסנים ב-Google Play Services כשמתבצע עדכון של רשת TBR. זה אומר שצריך להוסיף פרטי כניסה כשנדרש, לעדכן את פרטי הכניסה כשפרטי הכניסה של רשת Thread של border router משתנים, ולהסיר את פרטי הכניסה כשמסירים את TBR או מאפסים אותו להגדרות המקוריות.

גילוי של סוכני גבול

צריך לשמור את פרטי הכניסה עם מזהה סוכן Border. צריך לוודא שאפליקציית ההגדרה של TBR יכולה לקבוע את מזהי סוכן הגבול של TBR.

‫TBRs חייבים להשתמש ב-mDNS כדי לפרסם מידע על רשת Thread, כולל שם הרשת, מזהה PAN מורחב ומזהה סוכן הגבול. הערכים התואמים של txt למאפיינים האלה הם nn, xp ו-id, בהתאמה.

צריך לוודא שהתכונה OTBR_PUBLISH_MESHCOP_BA_ID מופעלת.

ברשתות עם Google Thread Border Router (gTBR)s, שירות Google Play Services מקבל באופן אוטומטי את פרטי הכניסה לרשת Google Thread לשימוש.

שילוב ה-SDK באפליקציה ל-Android

כדי להתחיל, מבצעים את השלבים הבאים:

  1. פועלים לפי ההוראות שמופיעות במאמר בנושא הגדרת Google Play Services.

  2. מוסיפים את התלות ב-Google Play Services לקובץ 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 מפעילה Activity, ומבקשת מהמשתמשים לאשר את בקשה לאחזור מהרשת. אם פרטי הכניסה לרשת אוחסנו במחזיק המפתחות הדיגיטלי של 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. אם אתם מגדירים 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, מומלץ להשתמש ב-allActiveCredentialsAPI כדי לאחזר פרטי כניסה. במהלך השיחה הזו יתבצע סריקה של 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 של המשתמש, אפשר להשתמש בממשק ה-API של addCredentials כדי להוסיף פרטי כניסה ל-Google Play Services. כדי לעשות את זה, צריך ליצור ThreadBorderAgent ולספק גם אובייקט ThreadNetworkCredentials.

כדי ליצור רשת אקראית, קוראים ל-newRandomizeBuilder:

val threadCredentials