دليل أجهزة توجيه الحدود على Android

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

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

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

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

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

GoogleBorderRouterDevice

home.matter.6006.types.0161

السمات المطلوبة
     google ThreadNetworkCapabilities
     google ThreadNetworkManagement

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

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

تتضمّن السمة BasicInformation معلومات مثل اسم المورّد ورقم تعريف المورّد ورقم تعريف المنتج، اسم المنتج (يتضمّن معلومات الطراز) وإصدار البرنامج لجهاز معيّن:

// Get device basic information. All general information traits are on the RootNodeDevice type.
    device.type(RootNodeDevice).first().standardTraits.basicInformation?.let { basicInformation ->
        println("vendorName ${basicInformation.vendorName}")
        println("vendorId ${basicInformation.vendorId}")
        println("productId ${basicInformation.productId}")
        println("productName ${basicInformation.productName}")
        println("softwareVersion ${basicInformation.softwareVersion}")
    }

فحص إمكانات جهاز توجيه الحدود

يمكنك فحص إمكانات جهاز توجيه الحدود للقراءة فقط (مثل إمكانية استخدام ePSKc وإعدادات الوصول إلى الإنترنت) باستخدام السمة ThreadNetworkCapabilities.

suspend fun checkBorderRouterCapabilities(device: HomeDevice) {
    // Filter for GoogleBorderRouterDevice device type
    val gtbrDevice = device.type(GoogleBorderRouterDevice).firstOrNull()
    if (gtbrDevice == null) {
        println("Device is not a Google border router.")
        return
    }

    // Retrieve the ThreadNetworkCapabilities trait
    val capabilitiesTrait = gtbrDevice.trait(ThreadNetworkCapabilities)
    if (capabilitiesTrait == null) {
        println("ThreadNetworkCapabilities trait not found on device.")
        return
    }

    val isEpskcSupported = capabilitiesTrait.epskcSupported ?: false
    val internetAccessOption = capabilitiesTrait.internetAccessOption?.name ?: "None"
    val isIasSupported = !internetAccessOption.equals("None", ignoreCase = true)

    println("ePSKc Supported: $isEpskcSupported")
    println("Internet Access Setting Supported: $isIasSupported")
}

إدارة مشاركة بيانات اعتماد شبكة Thread (ePSKc)

تتم مشاركة بيانات اعتماد شبكة Thread باستخدام مفتاح مشترك مسبقًا مؤقتًا للمفوّض (ePSKc). ينشئ وضع ePSKc مفتاح مرور مؤقتًا وآمنًا يمكن للأجهزة الخارجية أو المفوّضين استخدامه للحصول على مجموعة بيانات شبكة Thread بشكل آمن.

تفعيل وضع ePSKc

suspend fun startEpskcSession(device: HomeDevice, durationSeconds: Short): ActivateEpskcModeCommand.Response? {
    val gtbrDevice = device.type(GoogleBorderRouterDevice).firstOrNull()
    val mgmtTrait = gtbrDevice?.trait(ThreadNetworkManagement)

    if (mgmtTrait == null) {
        println("ThreadNetworkManagement trait not found.")
        return null
    }

    return try {
        val response = mgmtTrait.activateEpskcMode(
            optionalArgs = { this.requestedDurationSeconds = durationSeconds }
        )

        println("ePSKc Session Activated!")
        println("Status: ${response.status}")
        println("Ephemeral PSKc: ${response.epskc}")
        println("Valid Duration (s): ${response.validDurationSeconds}")

        response
    } catch (e: Exception) {
        println("Failed to activate ePSKc mode: ${e.message}")
        null
    }
}

إيقاف وضع ePSKc

suspend fun stopEpskcSession(device: HomeDevice) {
    val gtbrDevice = device.type(GoogleBorderRouterDevice).firstOrNull()
    val mgmtTrait = gtbrDevice?.trait(ThreadNetworkManagement)

    mgmtTrait?.deactivateEpskcMode()
    println("ePSKc mode deactivated.")
}

تتبُّع أحداث إيقاف وضع ePSKc

تُرسِل أجهزة توجيه حدود شبكة Thread أحداثًا عند انتهاء جلسة ePSKc (على سبيل المثال، بسبب استخدام المفتاح أو انتهاء صلاحية الجلسة أو إلغائها يدويًا).

suspend fun observeEpskcEvents(device: HomeDevice) {
    val gtbrDevice = device.type(GoogleBorderRouterDevice).firstOrNull()
    val mgmtTrait = gtbrDevice?.trait(ThreadNetworkManagement)

    mgmtTrait?.epskcModeDeactivatedEventFlow()?.collect { event ->
        println("ePSKc Session Ended. Reason: ${event.reason}")
        when (event.reason?.name) {
            "KeyUsed" -> println("Key was successfully used to commission a device.")
            "Expired" -> println("Session timed out before the key was used.")
            "Cancelled" -> println("Session was manually cancelled.")
        }
    }
}

إدارة العضوية في شبكة Thread

يمكنك توجيه جهاز توجيه حدود شبكة Thread للانضمام إلى شبكة Thread جديدة من خلال توفير قيم TLV لمجموعة البيانات التشغيلية النشطة، أو توجيهه لمغادرة الشبكة الحالية.

suspend fun joinNetwork(device: HomeDevice, datasetTlvs: ByteArray) {
    val gtbrDevice = device.type(GoogleBorderRouterDevice).firstOrNull()
    val mgmtTrait = gtbrDevice?.trait(ThreadNetworkManagement)

    try {
        val response = mgmtTrait?.joinNetwork(operationalDatasetTlvs = datasetTlvs)
        println("Join network command sent. Status: ${response?.status}")
    } catch (e: Exception) {
        println("Join network failed: ${e.message}")
    }
}

suspend fun leaveNetwork(device: HomeDevice) {
    val gtbrDevice = device.type(GoogleBorderRouterDevice).firstOrNull()
    val mgmtTrait = gtbrDevice?.trait(ThreadNetworkManagement)

    try {
        mgmtTrait?.leaveNetwork()
        println("Leave network command sent successfully.")
    } catch (e: Exception) {
        println("Leave network failed: ${e.message}")
    }
}

ضبط الوصول إلى الإنترنت على مستوى الهيكل

السمة ThreadNetworkSettings هي سمة قابلة للتعديل مرتبطة بـ Structure (تمثّل منزلاً أو مبنىً). تسمح هذه السمة للمطوّرين بضبط سياسة الوصول إلى الإنترنت على مستوى الهيكل لأجهزة توجيه حدود شبكة Thread.

suspend fun updateStructureInternetAccess(structure: Structure, enableInternetAccess: Boolean) {
    // Retrieve the ThreadNetworkSettings trait for the structure
    val settingsTrait = structure.trait(ThreadNetworkSettings).firstOrNull()
    if (settingsTrait == null) {
        println("ThreadNetworkSettings trait not found on structure.")
        return
    }

    val option = if (enableInternetAccess) {
        InternetAccessOption.InternetAccessOptionAll
    } else {
        InternetAccessOption.InternetAccessOptionNone
    }

    try {
        settingsTrait.update {
            setInternetAccessOption(option)
        }
        println("Successfully updated Thread internet access policy to: ${option.name}")
    } catch (e: Exception) {
        println("Failed to update Thread internet access policy: ${e.message}")
    }
}