คู่มืออุปกรณ์ Border Router สำหรับ Android

นักพัฒนาแอป Android สามารถใช้ Home API เพื่อจัดการ Thread Border Router (TBR)

GoogleBorderRouterDevice ได้รับการติดตั้งใช้งานโดยใช้ลักษณะเฉพาะของอุปกรณ์หลัก 2 รายการ ได้แก่ ThreadNetworkCapabilities ซึ่งมีแอตทริบิวต์แบบอ่านอย่างเดียวเพื่อตรวจสอบฟีเจอร์ border router และ ThreadNetworkManagement ซึ่งจัดการคำสั่งวงจรชีวิตของเครือข่ายและการแชร์ข้อมูลเข้าสู่ระบบโดยใช้คีย์แบบแชร์ล่วงหน้าชั่วคราวสำหรับผู้ดูแลระบบ (ePSKc) ระบบจะจัดการนโยบายการเข้าถึงอินเทอร์เน็ตระดับโครงสร้าง โดยใช้ลักษณะเฉพาะ ThreadNetworkSettings

ตรวจสอบการรองรับแอตทริบิวต์และคำสั่งสำหรับอุปกรณ์ก่อนใช้ฟีเจอร์หรือพยายามอัปเดตแอตทริบิวต์ ดูข้อมูลเพิ่มเติมได้ที่ควบคุมอุปกรณ์ใน Androidสำหรับ ข้อมูล

ประเภทอุปกรณ์ของ Home API ลักษณะเฉพาะ แอปตัวอย่าง Kotlin กรณีการใช้งาน

Border Router

GoogleBorderRouterDevice

home.matter.6006.types.0161

ลักษณะเฉพาะที่จำเป็น
     google ThreadNetworkCapabilities
     google ThreadNetworkManagement

Border Router

ดูข้อมูลพื้นฐานเกี่ยวกับอุปกรณ์

   ติดตั้งใช้งานในแอปตัวอย่างสำหรับ Android   

ลักษณะเฉพาะ 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}")
    }

ตรวจสอบความสามารถของ Border Router

คุณสามารถตรวจสอบความสามารถแบบอ่านอย่างเดียวของ border router's (เช่น การรองรับ 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

TBRs จะส่งเหตุการณ์เมื่อเซสชัน 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

คุณสามารถสั่งให้ TBR เข้าร่วมเครือข่าย 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 (แสดงถึงบ้านหรืออาคาร) ซึ่งช่วยให้นักพัฒนาแอปกำหนดค่า นโยบายการเข้าถึงอินเทอร์เน็ตทั่วทั้งโครงสร้างสำหรับ 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}")
    }
}