SDK לרשת Thread for Android

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

באמצעות כמה קריאות ל-API תוכלו:

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

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

מונחי מפתח וקונספטים של API

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

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

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

• מזהה סוכן גבול: מזהה ייחודי גלובלית של 16 בייט עבור מכשיר מסוג נתב גבולות. המזהה הזה נוצר ומנוהל על ידי ספקים של נתבי גבולות.

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

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

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

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

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

איתור גבולות

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

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

עבור רשתות עם נתבי גבול של Google, שירותי Google Play מקבלים באופן אוטומטי פרטי כניסה לרשת Google Thread.

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

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

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

2. מוסיפים את התלות של Google Play Services לקובץ 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}]") }
   }
   

יצירת רשת שרשור חדשה

אם אין פרטי כניסה מועדפים לרשת השרשורים שזמינים ברשת השרשורים של המשתמש, תוכלו להשתמש ב-API של addCredentials כדי להוסיף פרטי כניסה לשירותי Google Play. לשם כך צריך ליצור ThreadBorderAgent וגם לספק אובייקט ThreadNetworkCredentials.

כדי ליצור רשת אקראית, יש להתקשר למספר newRandomizeBuilder:

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

כדי לציין את שם הרשת של השרשור:

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

הוספת פרטי כניסה

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

בדוגמה הזו, ניצור ThreadBorderAgent ממזהה גבולות גבול, ונעביר את פרטי הכניסה החדשים לרשת השרשורים שיצרתם:

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 כדי לבדוק אם נתבי הגבולות שייכים לרשת המועדפת. ממשק ה-API הזה לא מבקש הרשאה מהמשתמש, ובודק את פרטי הכניסה של נתב הגבולות לעומת הפריטים המאוחסנים בשירותי 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 הפעילה התפעולית בשרשור Thread:

1. המרת מערך הנתונים התפעולי ל-ByteArray. למשל:

   val activeDataset =
         "0e080000000000010000000300000f35060004001fffe0020833333333...".dsToByteArray()
   

   fun String.dsToByteArray(): ByteArray {
     return chunked(2).map { it.toInt(16).toByte() }.toByteArray()
   }
   

2. יש להשתמש בfromActiveOperationalDataset כדי ליצור את ThreadNetworkCredentials. כשהתהליך יסתיים, תוכלו לקבל את שם הרשת, הערוץ ומידע נוסף על הרשת. רשימה מלאה של המאפיינים מופיעה במאמר ThreadNetworkCredentials.

   val threadNetworkCredentials =
       ThreadNetworkCredentials.fromActiveOperationalDataset(activeDataset)
   Log.d(
       "threadNetworkCredentials",
       threadNetworkCredentials.channel.toString() + " - " + threadNetworkCredentials.networkName)
   

3. יש להתקשר אל isPreferredCredentials API ולעבור את 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 by Border Agent

סוכן גבול גבול מזהה באופן ייחודי מכשיר נתב גבול. כדי להשתמש ב-API של 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}]") }
}

פרטי כניסה של שרשור לפי מזהה הזזה מורחבת

בדומה ל-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}]") }
}

הסרת פרטי הכניסה

כשמסירים את נתב הגבולות מהמכשיר שלכם, או מאיפוס להגדרות המקוריות, צריך להסיר את רשת השרשורים משירותי 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}]") }
}

משאבים

למידע נוסף על Thread Network SDK, עיינו בהפניית API.