Hướng dẫn về thiết bị bộ định tuyến biên cho iOS

Nhà phát triển ứng dụng iOS có thể sử dụng Home API để quản lý Thread Border Router (TBR).

GoogleBorderRouterDevice được triển khai bằng cách sử dụng 2 đặc điểm chính của thiết bị: ThreadNetworkCapabilitiesTrait, cung cấp các thuộc tính chỉ đọc để kiểm tra các tính năng border routerThreadNetworkManagementTrait, xử lý các lệnh vòng đời mạng và chia sẻ thông tin đăng nhập bằng Khoá chia sẻ trước tạm thời cho Người uỷ quyền (ePSKc). Các chính sách truy cập Internet ở cấp cấu trúc được quản lý bằng đặc điểm ThreadNetworkSettingsTrait.

Luôn kiểm tra xem thiết bị có hỗ trợ thuộc tính và lệnh hay không trước khi sử dụng bất kỳ tính năng nào hoặc cố gắng cập nhật thuộc tính. Hãy xem bài viết Điều khiển thiết bị trêniOS để biết thêm thông tin.

Loại thiết bị Home API Đặc điểm Ứng dụng mẫu Swift Trường hợp sử dụng

Bộ định tuyến biên

GoogleBorderRouterDeviceType

home.matter.6006.types.0161

Đặc điểm bắt buộc
     google ThreadNetworkCapabilitiesTrait
     google ThreadNetworkManagementTrait

Bộ định tuyến biên

Lấy thông tin cơ bản về một thiết bị

   Được triển khai trong Ứng dụng mẫu cho iOS   

Đặc điểm BasicInformation bao gồm những thông tin như tên nhà cung cấp, mã nhận dạng nhà cung cấp, mã nhận dạng sản phẩm, tên sản phẩm (bao gồm cả thông tin về kiểu máy) và phiên bản phần mềm của thiết bị:

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!

Kiểm tra các chức năng của bộ định tuyến biên

Bạn có thể kiểm tra các chức năng chỉ đọc của border router (chẳng hạn như hỗ trợ ePSKc và cấu hình chế độ cài đặt Quyền truy cập vào Internet) bằng cách sử dụng đặc điểm 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)")
    }
}

Quản lý hoạt động chia sẻ thông tin đăng nhập mạng Thread (ePSKc)

Tính năng chia sẻ thông tin đăng nhập của luồng được thực hiện bằng Khoá được chia sẻ trước tạm thời cho Người uỷ quyền (ePSKc). Chế độ ePSKc tạo ra một khoá truy cập tạm thời và an toàn mà các thiết bị bên ngoài hoặc người uỷ quyền có thể dùng để lấy tập dữ liệu mạng Thread một cách an toàn.

Kích hoạt chế độ 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
    }
}

Huỷ kích hoạt chế độ 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)")
    }
}

Quan sát các sự kiện huỷ kích hoạt ePSKc

TBR sẽ phát ra các sự kiện khi một phiên ePSKc kết thúc (ví dụ: vì khoá đã được sử dụng, phiên đã hết hạn hoặc phiên đã bị huỷ theo cách thủ công).

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

Quản lý tư cách thành viên mạng Thread

Bạn có thể yêu cầu TBR tham gia một mạng Thread mới bằng cách cung cấp các TLV của Tập dữ liệu hoạt động đang hoạt động hoặc yêu cầu rời khỏi mạng hiện tại.

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

Định cấu hình quyền truy cập Internet ở cấp cấu trúc

Đặc điểm ThreadNetworkSettings là một đặc điểm có thể cập nhật được gắn vào Structure (đại diện cho một ngôi nhà hoặc toà nhà). Chính sách này cho phép nhà phát triển định cấu hình chính sách truy cập Internet trên toàn cấu trúc cho TBR.

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