คู่มืออุปกรณ์ Border Router สำหรับ iOS

นักพัฒนาแอป iOS สามารถใช้ Home API เพื่อจัดการ Thread Border Router ได้

GoogleBorderRouterDevice ได้รับการติดตั้งใช้งานโดยใช้ลักษณะเฉพาะของอุปกรณ์หลัก 2 รายการ ได้แก่ ThreadNetworkCapabilitiesTrait, ซึ่งมีแอตทริบิวต์แบบอ่านอย่างเดียวเพื่อตรวจสอบฟีเจอร์ของ Border Router และ ThreadNetworkManagementTrait, ซึ่งจัดการคำสั่งวงจรชีวิตของเครือข่ายและการแชร์ข้อมูลเข้าสู่ระบบ โดยใช้คีย์แบบแชร์ล่วงหน้าชั่วคราวสำหรับผู้ดูแลระบบ (ePSKc) ระบบจะจัดการนโยบายการเข้าถึงอินเทอร์เน็ตระดับโครงสร้าง โดยใช้ลักษณะเฉพาะ ThreadNetworkSettingsTrait

ตรวจสอบการรองรับแอตทริบิวต์และคำสั่งสำหรับอุปกรณ์ก่อนใช้ฟีเจอร์หรือพยายามอัปเดตแอตทริบิวต์ ดูข้อมูลเพิ่มเติมได้ที่ควบคุมอุปกรณ์ใน iOSสำหรับ ข้อมูล

ประเภทอุปกรณ์ของ Home API ลักษณะเฉพาะ แอปตัวอย่าง Swift กรณีการใช้งาน

Border Router

GoogleBorderRouterDeviceType

home.matter.6006.types.0161

ลักษณะเฉพาะที่จำเป็น
     google ThreadNetworkCapabilitiesTrait
     google ThreadNetworkManagementTrait

Border Router

ดูข้อมูลพื้นฐานเกี่ยวกับอุปกรณ์

ลักษณะเฉพาะ 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!

ตรวจสอบความสามารถของ Border Router

คุณสามารถตรวจสอบความสามารถแบบอ่านอย่างเดียวของ Border Router (เช่น การรองรับ 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 Border Router จะส่งเหตุการณ์เมื่อเซสชัน 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 Border Router เข้าร่วมเครือข่าย 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 Border Router ได้

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)")
    }
}