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

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

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

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

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

روتر مرزی

Google Border Router Device

home.matter.6006.types.0161

ویژگی‌های مورد نیاز
قابلیت‌های شبکه‌ی گوگل ترد
مدیریت شبکه گوگل ترد

روتر مرزی

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

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

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

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

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