Panduan perangkat router pembatas untuk iOS

Developer aplikasi iOS dapat menggunakan Home API untuk mengelola router pembatas Thread.

GoogleBorderRouterDevice diimplementasikan menggunakan dua sifat perangkat utama: ThreadNetworkCapabilitiesTrait, yang menyediakan atribut hanya baca untuk memeriksa fitur router batas, dan ThreadNetworkManagementTrait, yang menangani perintah siklus proses jaringan dan berbagi kredensial menggunakan Ephemeral Pre-Shared Key untuk Commissioner (ePSKc). Kebijakan akses internet tingkat struktur dikelola menggunakan trait ThreadNetworkSettingsTrait.

Selalu periksa dukungan atribut dan perintah untuk perangkat sebelum menggunakan fitur atau mencoba memperbarui atribut. Lihat Mengontrol perangkat di iOS untuk mengetahui informasi selengkapnya.

Jenis Perangkat Home API Sifat Aplikasi Contoh Swift Kasus Penggunaan

router pembatas

GoogleBorderRouterDeviceType

home.matter.6006.types.0161

 Ciri Wajib
     google ThreadNetworkCapabilitiesTrait
     google ThreadNetworkManagementTrait

 Router pembatas

Mendapatkan informasi dasar tentang perangkat

Trait BasicInformation mencakup informasi seperti nama vendor, ID vendor, ID produk, nama produk (mencakup informasi model), dan versi software untuk perangkat:

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!

Memeriksa kemampuan router pembatas

Anda dapat memeriksa kemampuan hanya baca router perbatasan (seperti dukungan ePSKc dan konfigurasi setelan Akses Internet) menggunakan trait 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)")
    }
}

Mengelola berbagi kredensial Thread (ePSKc)

Berbagi kredensial Thread dilakukan menggunakan Kunci Pre-Shared Sementara untuk Commissioner (ePSKc). Mode ePSKc membuat kunci sandi sementara yang aman yang dapat digunakan oleh perangkat atau commissioner eksternal untuk mendapatkan set data jaringan Thread secara aman.

Mengaktifkan mode 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
    }
}

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

Mengamati peristiwa penonaktifan ePSKc

Router batas Thread memancarkan peristiwa saat sesi ePSKc berakhir (misalnya, karena kunci digunakan, sesi berakhir, atau dibatalkan secara manual).

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

Mengelola keanggotaan jaringan Thread

Anda dapat memerintahkan router pembatas Thread untuk bergabung ke jaringan Thread baru dengan memberikan TLV Set Data Operasional aktif, atau memerintahkannya untuk keluar dari jaringan saat ini.

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

Mengonfigurasi akses internet tingkat struktur

Trait ThreadNetworkSettings adalah trait yang dapat diupdate dan dilampirkan ke Structure (yang mewakili rumah atau bangunan). Hal ini memungkinkan developer mengonfigurasi kebijakan akses internet di seluruh struktur untuk router pembatas 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)")
    }
}