راهنمای دستگاه رهیاب مرزی برای iOS

توسعه‌دهندگان برنامه iOS می‌توانند از Home APIs برای مدیریت Thread Border Router (TBR) استفاده کنند.

GoogleBorderRouterDevice بااستفاده از دو مشخصه اصلی دستگاه پیاده‌سازی می‌شود: ThreadNetworkCapabilitiesTrait، که ویژگی‌های فقط‌خواندنی برای بازرسی ویژگی‌های border router ارائه می‌دهد، و ThreadNetworkManagementTrait، که دستورات چرخه حیات شبکه و هم‌رسانی اطلاعات اعتباری را بااستفاده از «کلید پیش‌هم‌رسانی‌شده موقت» برای «کارگزار» (ePSKc) مدیریت می‌کند. خط‌مشی‌های دسترسی به اینترنت در سطح ساختار بااستفاده از ویژگی ThreadNetworkSettingsTrait مدیریت می‌شود.

همیشه قبل‌از استفاده از هر ویژگی یا تلاش برای به‌روزرسانی مشخصه‌ها، پشتیبانی از مشخصه و فرمان را برای دستگاه بررسی کنید. برای اطلاعات بیشتر، کنترل دستگاه‌ها در iOS را ببینید.

نوع دستگاه Home APIs ویژگی‌ها برنامه نمونه Swift کاربرد

رهیاب مرزی

GoogleBorderRouterDeviceType

home.matter.6006.types.0161

ویژگی‌های الزامی
     google ThreadNetworkCapabilitiesTrait
     google ThreadNetworkManagementTrait

رهیاب مرزی

دریافت اطلاعات پایه درباره دستگاه

   در «برنامه نمونه برای iOS» پیاده‌سازی شده است   

ویژگی 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 را (مثل پشتیبانی از 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 را مشاهده کنید

وقتی جلسه ePSKc پایان می‌یابد (برای مثال، چون از کلید استفاده شده است، جلسه منقضی شده است، یا به‌صورت دستی لغو شده است)، TBR رویدادهایی منتشر می‌کند.

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

می‌توانید به TBR دستور دهید با ارائه کردن «مقادیر نوع طول مقدار مجموعه داده‌های عملیاتی» فعال به شبکه Thread جدید بپیوندد، یا به آن دستور دهید از شبکه فعلی‌اش خارج شود.

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 (نشان‌دهنده خانه یا ساختمان) پیوست شده است. این امکان را به توسعه‌دهندگان می‌دهد تا خط‌مشی دسترسی به اینترنت در سراسر ساختار را برای 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)")
    }
}