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

توسعه‌دهندگان برنامه‌های iOS می‌توانند از رابط‌های برنامه‌نویسی کاربردی (API) صفحه اصلی برای مدیریت یک روتر مرزی Thread استفاده کنند.

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

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

نوع دستگاه APIهای خانگی صفات نمونه برنامه سویفت مورد استفاده

روتر مرزی

Google Border Router DeviceType

home.matter.6006.types.0161

ویژگی‌های مورد نیاز
گوگل ترد ( google Thread)
گوگل ترید (google thread) مدیریت شبکه (Network Management) ویژگی (Trait)

روتر مرزی

دریافت اطلاعات اولیه در مورد یک دستگاه

ویژگی 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

روترهای حاشیه‌ای ترد، رویدادهایی را هنگام پایان یک جلسه 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

شما می‌توانید با ارائه TLV های فعال مجموعه داده‌های عملیاتی، به یک روتر مرزی Thread دستور دهید تا به یک شبکه 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 (که نشان‌دهنده یک خانه یا ساختمان است) متصل شده است. این ویژگی به توسعه‌دهندگان اجازه می‌دهد تا سیاست دسترسی به اینترنت در سطح ساختار را برای روترهای مرزی 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)")
    }
}