Руководство по использованию маршрутизатора Border для Android

Разработчики Android-приложений могут использовать API Home для управления пограничным маршрутизатором Thread.

Объект GoogleBorderRouterDevice реализован с использованием двух основных характеристик устройства: ThreadNetworkCapabilities , которая предоставляет атрибуты только для чтения для проверки функций пограничного маршрутизатора, и ThreadNetworkManagement , которая обрабатывает команды жизненного цикла сети и совместное использование учетных данных с помощью временного предварительно согласованного ключа для комиссара (ePSKc). Политики доступа в Интернет на уровне структуры управляются с помощью характеристики ThreadNetworkSettings .

Перед использованием каких-либо функций или попыткой обновления атрибутов всегда проверяйте поддержку атрибутов и команд для устройства. См. раздел «Управление устройствами» .Android для получения дополнительной информации.

Главная API Тип устройства Черты Пример приложения на Kotlin Вариант использования

Пограничный маршрутизатор

Google Border Router Device

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

Управление совместным использованием учетных данных потоков (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

Вы можете отдать команду маршрутизатору Thread Border Router подключиться к новой сети 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}")
    }
}