Panduan perangkat router pembatas untuk Android

Developer aplikasi Android dapat menggunakan Home API untuk mengelola Thread Border Router (TBR).

GoogleBorderRouterDevice diimplementasikan menggunakan dua karakteristik perangkat utama: ThreadNetworkCapabilities, yang menyediakan atribut hanya baca untuk memeriksa fitur border router, dan ThreadNetworkManagement, yang menangani perintah siklus proses jaringan dan berbagi kredensial menggunakan Ephemeral Pre-Shared Key untuk Commissioner (ePSKc). Kebijakan akses internet tingkat struktur dikelola menggunakan karakteristik ThreadNetworkSettings.

Selalu periksa dukungan atribut dan perintah untuk perangkat sebelum menggunakan fitur apa pun atau mencoba memperbarui atribut. Lihat Mengontrol perangkat di Android untuk mengetahui informasi selengkapnya.

Jenis Perangkat Home API Sifat Aplikasi Contoh Kotlin Kasus Penggunaan

router pembatas

GoogleBorderRouterDevice

home.matter.6006.types.0161

 Karakteristik yang Diperlukan
     google ThreadNetworkCapabilities
     google ThreadNetworkManagement

 Router Pembatas

Mendapatkan informasi dasar tentang perangkat

   Diimplementasikan di Aplikasi Contoh untuk Android   

Karakteristik BasicInformation mencakup informasi seperti nama vendor, ID vendor, ID produk, nama produk (termasuk informasi model), dan versi software untuk perangkat:

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

Memeriksa kemampuan router pembatas

Anda dapat memeriksa kemampuan hanya baca border router (seperti dukungan ePSKc dan konfigurasi setelan Akses Internet) menggunakan karakteristik 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")
}

Mengelola berbagi kredensial Thread (ePSKc)

Berbagi kredensial Thread dilakukan menggunakan Ephemeral Pre-Shared Key for the Commissioner (ePSKc). Mode ePSKc menghasilkan kunci sandi sementara yang aman, yang dapat digunakan oleh perangkat eksternal atau commissioner untuk mendapatkan set data jaringan Thread dengan aman.

Mengaktifkan mode 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
    }
}

Menonaktifkan mode ePSKc

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

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

Mengamati peristiwa penonaktifan ePSKc

TBR memunculkan peristiwa saat sesi ePSKc berakhir (misalnya, karena kunci telah digunakan, sesi berakhir, atau dibatalkan secara manual).

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

Mengelola keanggotaan jaringan Thread

Anda dapat memerintahkan TBR untuk bergabung ke jaringan Thread baru dengan memberikan TLV Set Data Operasional yang aktif, atau memerintahkannya untuk keluar dari jaringan saat ini.

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

Mengonfigurasi akses internet tingkat struktur

Sifat ThreadNetworkSettings adalah sifat yang dapat diupdate yang dilampirkan ke Structure (mewakili rumah atau bangunan). Hal ini memungkinkan developer mengonfigurasi kebijakan akses internet di seluruh struktur untuk TBR.

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