Hướng dẫn về thiết bị bộ định tuyến biên dành cho Android

Nhà phát triển ứng dụng Android có thể sử dụng Home API để quản lý bộ định tuyến biên sử dụng giao thức Thread.

GoogleBorderRouterDevice được triển khai bằng cách sử dụng hai đặc điểm chính của thiết bị: ThreadNetworkCapabilities (cung cấp các thuộc tính chỉ có thể đọc để kiểm tra các tính năng của bộ định tuyến biên) và ThreadNetworkManagement (xử lý các lệnh vòng đời mạng và chia sẻ thông tin đăng nhập bằng Khoá được chia sẻ trước tạm thời cho Người uỷ quyền (ePSKc)). Các chính sách truy cập Internet ở cấp cấu trúc được quản lý bằng cách sử dụng ThreadNetworkSettings đặc điểm.

Luôn kiểm tra xem thiết bị có hỗ trợ thuộc tính và lệnh hay không trước khi sử dụng bất kỳ tính năng nào hoặc cố gắng cập nhật thuộc tính. Hãy xem bài viết Kiểm soát thiết bị trên Android để biết thêm thông tin.

Loại thiết bị Home API Đặc điểm tính cách Ứng dụng mẫu Kotlin Trường hợp sử dụng

Bộ định tuyến biên

GoogleBorderRouterDevice

home.matter.6006.types.0161

 Đặc điểm tính cách bắt buộc
     google ThreadNetworkCapabilities
     google ThreadNetworkManagement

 Bộ định tuyến biên

Nhận thông tin cơ bản về thiết bị

Đặc điểm tính cách BasicInformation bao gồm các thông tin như tên nhà cung cấp, mã nhận dạng nhà cung cấp, mã nhận dạng sản phẩm, tên sản phẩm (bao gồm thông tin về kiểu máy) và phiên bản phần mềm của thiết bị:

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

Kiểm tra các chức năng của bộ định tuyến biên

Bạn có thể kiểm tra các chức năng chỉ có thể đọc của bộ định tuyến biên (chẳng hạn như hỗ trợ ePSKc và cấu hình chế độ cài đặt Quyền truy cập Internet) bằng cách sử dụng đặc điểm tính cách 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")
}

Quản lý việc chia sẻ thông tin đăng nhập mạng Thread (ePSKc)

Việc chia sẻ thông tin đăng nhập mạng Thread được thực hiện bằng cách sử dụng Khoá được chia sẻ trước tạm thời cho Người uỷ quyền (ePSKc). Chế độ ePSKc tạo một khoá tạm thời và an toàn mà các thiết bị hoặc người uỷ quyền bên ngoài có thể sử dụng để lấy tập dữ liệu mạng Thread một cách an toàn.

Kích hoạt chế độ 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
    }
}

Huỷ kích hoạt chế độ ePSKc

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

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

Quan sát các sự kiện huỷ kích hoạt ePSKc

Bộ định tuyến biên sử dụng giao thức Thread phát ra các sự kiện khi phiên ePSKc kết thúc (ví dụ: do khoá đã được sử dụng, phiên đã hết hạn hoặc bị huỷ theo cách thủ công).

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

Quản lý tư cách thành viên mạng Thread

Bạn có thể yêu cầu bộ định tuyến biên sử dụng giao thức Thread tham gia mạng Thread mới bằng cách cung cấp các TLV Tập dữ liệu hoạt động hiện đang hoạt động hoặc yêu cầu bộ định tuyến này rời khỏi mạng hiện tại.

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

Định cấu hình quyền truy cập Internet ở cấp cấu trúc

Đặc điểm tính cách ThreadNetworkSettings là một đặc điểm tính cách có thể cập nhật được đính kèm với Structure (đại diện cho một ngôi nhà hoặc toà nhà). Đặc điểm này cho phép nhà phát triển định cấu hình chính sách truy cập Internet trên toàn cấu trúc cho bộ định tuyến biên sử dụng giao thức 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}")
    }
}