دليل أجهزة توجيه حدود الشبكة لأجهزة iOS

يمكن لمطوّري تطبيقات iOS استخدام Home APIs لإدارة جهاز توجيه حدود شبكة Thread.

يتم تنفيذ GoogleBorderRouterDevice باستخدام صفتَين أساسيتَين للجهاز: ThreadNetworkCapabilitiesTrait التي توفّر سمات للقراءة فقط لفحص ميزات جهاز توجيه الحدود، و ThreadNetworkManagementTrait التي تعالج أوامر دورة حياة الشبكة ومشاركة بيانات الاعتماد باستخدام مفتاح مشترك مسبقًا مؤقتًا للمفوّض (ePSKc). تتم إدارة سياسات الوصول إلى الإنترنت على مستوى الهيكل باستخدام السمة ThreadNetworkSettingsTrait.

يُرجى التحقّق دائمًا من توفّر سمة ودعم أمر لجهاز قبل استخدام أي ميزات أو محاولة تعديل السمات. لمزيد من المعلومات، يمكنك الاطّلاع على مقالة التحكّم في الأجهزة على iOS.

نوع الجهاز في Home APIs الصفات نموذج تطبيق Swift حالة الاستخدام

جهاز توجيه الحدود

GoogleBorderRouterDeviceType

home.matter.6006.types.0161

السمات المطلوبة
     google ThreadNetworkCapabilitiesTrait
     google ThreadNetworkManagementTrait

جهاز توجيه الحدود

الحصول على معلومات أساسية عن جهاز

تتضمّن السمة 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

تُرسِل أجهزة توجيه حدود شبكة Thread أحداثًا عند انتهاء جلسة 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 للانضمام إلى شبكة 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.

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