מדריך למכשיר נתב גבולות ל-Android

מפתחי אפליקציות ל-Android יכולים להשתמש בממשקי ה-API של Home כדי לנהל Thread Border Router (TBR).

ה-GoogleBorderRouterDevice מיושם באמצעות שני מאפייני מכשיר עיקריים: ThreadNetworkCapabilities, שמספק מאפיינים לקריאה בלבד כדי לבדוק תכונות של border router, ו-ThreadNetworkManagement, שמטפל בפקודות של מחזור החיים של הרשת ובשיתוף אישורים באמצעות מפתח זמני ששותף מראש עבור המנהל (ePSKc). מדיניות גישה לאינטרנט ברמת המבנה מנוהלת באמצעות המאפיין ThreadNetworkSettings.

לפני שמשתמשים בתכונות או מנסים לעדכן מאפיינים, תמיד צריך לבדוק אם המכשיר תומך במאפיינים ובפקודות. מידע נוסף זמין במאמר שליטה במכשירים ב-Android.

Home APIs Device Type תכונות אפליקציה לדוגמה ב-Kotlin תרחיש לדוגמה

נתב גבולות

GoogleBorderRouterDevice

home.matter.6006.types.0161

מאפיינים נדרשים
     google ThreadNetworkCapabilities
     google ThreadNetworkManagement

נתב גבולות

קבלת מידע בסיסי על מכשיר

   Implemented in Sample App for Android   

מאפיין BasicInformation כולל מידע כמו שם הספק, מזהה הספק, מזהה המוצר, שם המוצר (כולל פרטי הדגם) וגרסת התוכנה של המכשיר:

// Get device basic information. All general information traits are on the RootNodeDevice type.
    device.type(RootNodeDevice).first().standardTraits.basicInformation?.let { basicInformation ->
        println("vendorName ${basicInformation.vendorName}")
        println("vendorId ${basicInformation.vendorId}")
        println("productId ${basicInformation.productId}")
        println("productName ${basicInformation.productName}")
        println("softwareVersion ${basicInformation.softwareVersion}")
    }

בדיקת היכולות של נתב הגבול

אפשר לבדוק את היכולות של border routerקריאה בלבד (כמו תמיכה ב-ePSKc והגדרת גישה לאינטרנט) באמצעות המאפיין ThreadNetworkCapabilities.

suspend fun checkBorderRouterCapabilities(device: HomeDevice) {
    // Filter for GoogleBorderRouterDevice device type
    val gtbrDevice = device.type(GoogleBorderRouterDevice).firstOrNull()
    if (gtbrDevice == null) {
        println("Device is not a Google border router.")
        return
    }

    // Retrieve the ThreadNetworkCapabilities trait
    val capabilitiesTrait = gtbrDevice.trait(ThreadNetworkCapabilities)
    if (capabilitiesTrait == null) {
        println("ThreadNetworkCapabilities trait not found on device.")
        return
    }

    val isEpskcSupported = capabilitiesTrait.epskcSupported ?: false
    val internetAccessOption = capabilitiesTrait.internetAccessOption?.name ?: "None"
    val isIasSupported = !internetAccessOption.equals("None", ignoreCase = true)

    println("ePSKc Supported: $isEpskcSupported")
    println("Internet Access Setting Supported: $isIasSupported")
}

ניהול שיתוף פרטי הכניסה של פרוטוקול Thread‏ (ePSKc)

שיתוף פרטי הכניסה של ה-Thread מתבצע באמצעות מפתח זמני ששותף מראש עבור ה-Commissioner‏ (ePSKc). במצב ePSKc נוצר מפתח גישה זמני ומאובטח שמכשירים חיצוניים או Commissioners יכולים להשתמש בו כדי לקבל בצורה מאובטחת את מערך הנתונים של רשת ה-Thread.

הפעלת מצב ePSKc

suspend fun startEpskcSession(device: HomeDevice, durationSeconds: Short): ActivateEpskcModeCommand.Response? {
    val gtbrDevice = device.type(GoogleBorderRouterDevice).firstOrNull()
    val mgmtTrait = gtbrDevice?.trait(ThreadNetworkManagement)

    if (mgmtTrait == null) {
        println("ThreadNetworkManagement trait not found.")
        return null
    }

    return try {
        val response = mgmtTrait.activateEpskcMode(
            optionalArgs = { this.requestedDurationSeconds = durationSeconds }
        )

        println("ePSKc Session Activated!")
        println("Status: ${response.status}")
        println("Ephemeral PSKc: ${response.epskc}")
        println("Valid Duration (s): ${response.validDurationSeconds}")

        response
    } catch (e: Exception) {
        println("Failed to activate ePSKc mode: ${e.message}")
        null
    }
}

השבתת מצב ePSKc

suspend fun stopEpskcSession(device: HomeDevice) {
    val gtbrDevice = device.type(GoogleBorderRouterDevice).firstOrNull()
    val mgmtTrait = gtbrDevice?.trait(ThreadNetworkManagement)

    mgmtTrait?.deactivateEpskcMode()
    println("ePSKc mode deactivated.")
}

מעקב אחרי אירועי השבתה של ePSKc

TBRפולטים אירועים כשסשן ePSKc מסתיים (לדוגמה, כי נעשה שימוש במפתח, כי תוקף הסשן פג או כי הוא בוטל באופן ידני).

suspend fun observeEpskcEvents(device: HomeDevice) {
    val gtbrDevice = device.type(GoogleBorderRouterDevice).firstOrNull()
    val mgmtTrait = gtbrDevice?.trait(ThreadNetworkManagement)

    mgmtTrait?.epskcModeDeactivatedEventFlow()?.collect { event ->
        println("ePSKc Session Ended. Reason: ${event.reason}")
        when (event.reason?.name) {
            "KeyUsed" -> println("Key was successfully used to commission a device.")
            "Expired" -> println("Session timed out before the key was used.")
            "Cancelled" -> println("Session was manually cancelled.")
        }
    }
}

ניהול החברות ברשת Thread

אתם יכולים להנחות את TBR להצטרף לרשת Thread חדשה על ידי הזנת ערכי TLV של מערך הנתונים הפעיל, או להנחות אותו לצאת מהרשת הנוכחית.

suspend fun joinNetwork(device: HomeDevice, datasetTlvs: ByteArray) {
    val gtbrDevice = device.type(GoogleBorderRouterDevice).firstOrNull()
    val mgmtTrait = gtbrDevice?.trait(ThreadNetworkManagement)

    try {
        val response = mgmtTrait?.joinNetwork(operationalDatasetTlvs = datasetTlvs)
        println("Join network command sent. Status: ${response?.status}")
    } catch (e: Exception) {
        println("Join network failed: ${e.message}")
    }
}

suspend fun leaveNetwork(device: HomeDevice) {
    val gtbrDevice = device.type(GoogleBorderRouterDevice).firstOrNull()
    val mgmtTrait = gtbrDevice?.trait(ThreadNetworkManagement)

    try {
        mgmtTrait?.leaveNetwork()
        println("Leave network command sent successfully.")
    } catch (e: Exception) {
        println("Leave network failed: ${e.message}")
    }
}

הגדרת גישה לאינטרנט ברמת המבנה

מאפיין ThreadNetworkSettings הוא מאפיין שאפשר לעדכן שמצורף לStructure (שמייצג בית או בניין). היא מאפשרת למפתחים להגדיר את מדיניות הגישה לאינטרנט של TBR בכל המבנה.

suspend fun updateStructureInternetAccess(structure: Structure, enableInternetAccess: Boolean) {
    // Retrieve the ThreadNetworkSettings trait for the structure
    val settingsTrait = structure.trait(ThreadNetworkSettings).firstOrNull()
    if (settingsTrait == null) {
        println("ThreadNetworkSettings trait not found on structure.")
        return
    }

    val option = if (enableInternetAccess) {
        InternetAccessOption.InternetAccessOptionAll
    } else {
        InternetAccessOption.InternetAccessOptionNone
    }

    try {
        settingsTrait.update {
            setInternetAccessOption(option)
        }
        println("Successfully updated Thread internet access policy to: ${option.name}")
    } catch (e: Exception) {
        println("Failed to update Thread internet access policy: ${e.message}")
    }
}