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

מפתחי אפליקציות ל-iOS יכולים להשתמש בממשקי Home API כדי לנהל נתב גבולות עם פרוטוקול Thread.

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

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

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

נתב גבולות

GoogleBorderRouterDeviceType

home.matter.6006.types.0161

מאפיינים נדרשים
     google ThreadNetworkCapabilitiesTrait
     google ThreadNetworkManagementTrait

נתב גבולות

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

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

let vendorName = basicInfoTrait.attributes.vendorName!
let vendorID = basicInfoTrait.attributes.vendorID!
let productID = basicInfoTrait.attributes.productID!
let productName = basicInfoTrait.attributes.productName!
let softwareVersion = basicInfoTrait.attributes.softwareVersion!

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

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

func checkBorderRouterCapabilities(device: HomeDevice) async {
    // Filter for GoogleBorderRouterDevice device type
    guard let gtbrDevice = device.type(Google.GoogleBorderRouterDevice.self) else {
        print("Device is not a Google border router.")
        return
    }

    // Retrieve the ThreadNetworkCapabilitiesTrait
    guard let capabilitiesTrait = gtbrDevice.traits(Google.ThreadNetworkCapabilitiesTrait.self) else {
        print("ThreadNetworkCapabilitiesTrait not found on device.")
        return
    }

    do {
        let isEpskcSupported = try await capabilitiesTrait.epskcSupported.read()
        let internetAccessOption = try await capabilitiesTrait.internetAccessOption.read()
        let isIasSupported = internetAccessOption != .none

        print("ePSKc Supported: \(isEpskcSupported)")
        print("Internet Access Setting Supported: \(isIasSupported)")
    } catch {
        print("Failed to read capabilities: \(error)")
    }
}

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

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

הפעלת מצב ePSKc

func startEpskcSession(device: HomeDevice, durationSeconds: Int16) async -> Google.ThreadNetworkManagementTrait.ActivateEpskcModeResponse? {
    guard let gtbrDevice = device.type(Google.GoogleBorderRouterDevice.self),
          let mgmtTrait = gtbrDevice.traits(Google.ThreadNetworkManagementTrait.self) else {
        print("ThreadNetworkManagementTrait not found.")
        return nil
    }

    do {
        var request = Google.ThreadNetworkManagementTrait.ActivateEpskcModeRequest()
        request.requestedDurationSeconds = durationSeconds

        let response = try await mgmtTrait.activateEpskcMode(request)

        print("ePSKc Session Activated!")
        print("Status: \(response.status)")
        print("Ephemeral PSKc: \(response.epskc)")
        print("Valid Duration (s): \(response.validDurationSeconds)")

        return response
    } catch {
        print("Failed to activate ePSKc mode: \(error)")
        return nil
    }
}

השבתת מצב ePSKc

func stopEpskcSession(device: HomeDevice) async {
    guard let gtbrDevice = device.type(Google.GoogleBorderRouterDevice.self),
          let mgmtTrait = gtbrDevice.traits(Google.ThreadNetworkManagementTrait.self) else {
        return
    }

    do {
        try await mgmtTrait.deactivateEpskcMode(Google.ThreadNetworkManagementTrait.DeactivateEpskcModeRequest())
        print("ePSKc mode deactivated.")
    } catch {
        print("Failed to deactivate ePSKc mode: \(error)")
    }
}

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

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

func observeEpskcEvents(device: HomeDevice) async {
    guard let gtbrDevice = device.type(Google.GoogleBorderRouterDevice.self),
          let mgmtTrait = gtbrDevice.traits(Google.ThreadNetworkManagementTrait.self) else {
        return
    }

    do {
        for try await event in mgmtTrait.epskcModeDeactivatedEvent.stream() {
            print("ePSKc Session Ended. Reason: \(event.reason)")
            switch event.reason {
            case .keyUsed:
                print("Key was successfully used to commission a device.")
            case .expired:
                print("Session timed out before the key was used.")
            case .cancelled:
                print("Session was manually cancelled.")
            @unknown default:
                print("Unknown deactivation reason.")
            }
        }
    } catch {
        print("Error streaming ePSKc events: \(error)")
    }
}

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

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

func joinNetwork(device: HomeDevice, datasetTlvs: Data) async {
    guard let gtbrDevice = device.type(Google.GoogleBorderRouterDevice.self),
          let mgmtTrait = gtbrDevice.traits(Google.ThreadNetworkManagementTrait.self) else {
        return
    }

    do {
        var request = Google.ThreadNetworkManagementTrait.JoinNetworkRequest()
        request.operationalDatasetTlvs = datasetTlvs

        let response = try await mgmtTrait.joinNetwork(request)
        print("Join network command sent. Status: \(response.status)")
    } catch {
        print("Join network failed: \(error)")
    }
}

func leaveNetwork(device: HomeDevice) async {
    guard let gtbrDevice = device.type(Google.GoogleBorderRouterDevice.self),
          let mgmtTrait = gtbrDevice.traits(Google.ThreadNetworkManagementTrait.self) else {
        return
    }

    do {
        try await mgmtTrait.leaveNetwork(Google.ThreadNetworkManagementTrait.LeaveNetworkRequest())
        print("Leave network command sent successfully.")
    } catch {
        print("Leave network failed: \(error)")
    }
}

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

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

func updateStructureInternetAccess(structure: Structure, enableInternetAccess: Bool) async {
    guard let settingsTrait = structure.traits(Google.ThreadNetworkSettingsTrait.self) else {
        print("ThreadNetworkSettingsTrait not found on structure.")
        return
    }

    let option: Google.ThreadNetworkSettingsTrait.InternetAccessOption = enableInternetAccess ? .internetAccessOptionAll : .internetAccessOptionNone

    do {
        try await settingsTrait.update { mutator in
            mutator.internetAccessOption = option
        }
        print("Successfully updated Thread internet access policy.")
    } catch {
        print("Failed to update Thread internet access policy: \(error)")
    }
}