Guida al dispositivo router di confine per Android

Gli sviluppatori di app per Android possono utilizzare le API Home per gestire un Thread Border Router (TBR).

L'elemento GoogleBorderRouterDevice viene implementato utilizzando due tratti di dispositivo principali: ThreadNetworkCapabilities, che fornisce attributi di sola lettura per esaminare le funzionalità border router, e ThreadNetworkManagement, che gestisce i comandi del ciclo di vita della rete e la condivisione delle credenziali utilizzando una chiave precondivisa temporanea per il commissario (ePSKc). I criteri di accesso a internet a livello di struttura vengono gestiti utilizzando il ThreadNetworkSettings tratto.

Prima di utilizzare qualsiasi funzionalità o tentare di aggiornare gli attributi, controlla sempre il supporto degli attributi e dei comandi per un dispositivo. Per ulteriori informazioni, consulta Controllare i dispositivi su Android.

Tipo di dispositivo API Home Tratti App di esempio Kotlin Caso d'uso

Router di confine

GoogleBorderRouterDevice

home.matter.6006.types.0161

 Tratti obbligatori
     google ThreadNetworkCapabilities
     google ThreadNetworkManagement

 Router di confine

Recuperare informazioni di base su un dispositivo

   Implementato nell'app di esempio per Android   

Il BasicInformation tratto include informazioni come il nome del fornitore, l'ID fornitore, l'ID prodotto, il nome del prodotto (incluse le informazioni sul modello) e la versione del software per un dispositivo:

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

Esaminare le funzionalità del router di confine

Puoi esaminare le funzionalità di sola lettura di un border router's (ad esempio il supporto ePSKc e la configurazione dell'impostazione di accesso a internet) utilizzando il ThreadNetworkCapabilities tratto.

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

Gestire la condivisione delle credenziali Thread (ePSKc)

La condivisione delle credenziali Thread viene eseguita utilizzando una chiave precondivisa temporanea per il commissario (ePSKc). La modalità ePSKc genera una passkey temporanea e sicura che i dispositivi o i commissari esterni possono utilizzare per ottenere in modo sicuro il set di dati della rete Thread.

Attivare la modalità 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
    }
}

Disattivare la modalità ePSKc

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

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

Osservare gli eventi di disattivazione ePSKc

TBRs emettono eventi quando una sessione ePSKc termina (ad esempio, perché la chiave è stata utilizzata, la sessione è scaduta o è stata annullata manualmente).

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

Gestire l'appartenenza alla rete Thread

Puoi comandare a un TBR di unirsi a una nuova rete Thread fornendo i TLV del set di dati operativi attivi oppure di lasciare la rete corrente.

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

Configurare l'accesso a internet a livello di struttura

Il tratto ThreadNetworkSettings è un tratto aggiornabile collegato a una Structure (che rappresenta una casa o un edificio). Consente agli sviluppatori di configurare il criterio di accesso a internet a livello di struttura per gli TBRs.

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