Guide des routeurs de bordure pour Android

Les développeurs d'applications Android peuvent utiliser les API Home pour gérer un Thread Border Router (TBR).

Le GoogleBorderRouterDevice est implémenté à l'aide de deux traits d'appareil principaux : ThreadNetworkCapabilities, qui fournit des attributs en lecture seule pour inspecter les fonctionnalités border router, et ThreadNetworkManagement, qui gère les commandes de cycle de vie du réseau et le partage des identifiants à l'aide d'une clé pré-partagée éphémère pour le commissaire (ePSKc). Les règles d'accès à Internet au niveau de la structure sont gérées à l'aide du ThreadNetworkSettings trait.

Assurez-vous toujours qu'un appareil prend en charge les attributs et les commandes nécessaires avant d'utiliser une fonctionnalité ou de tenter de mettre à jour des attributs. Pour en savoir plus, consultez Contrôler les appareils sur Android pour plus d'informations.

Type d'appareil des API Home Traits de caractère Exemple d'application Kotlin Cas d'utilisation

Routeur de bordure

GoogleBorderRouterDevice

home.matter.6006.types.0161

 Traits requis
     google ThreadNetworkCapabilities
     google ThreadNetworkManagement

 Routeur de bordure

Obtenir des informations de base sur un appareil

   Implémenté dans l'exemple d'application pour Android   

Le BasicInformation trait inclut des informations telles que le nom du fournisseur, l'ID du fournisseur, l'ID du produit, le nom du produit (y compris les informations sur le modèle) et la version du logiciel d'un appareil :

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

Inspecter les fonctionnalités du routeur de bordure

Vous pouvez examiner les fonctionnalités en lecture seule d'un border router's (telles que la compatibilité avec ePSKc et la configuration du paramètre d'accès à Internet) à l'aide du ThreadNetworkCapabilities trait.

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

Gérer le partage des identifiants Thread (ePSKc)

Le partage des identifiants Thread est effectué à l'aide d'une clé pré-partagée éphémère pour le commissaire (ePSKc). Le mode ePSKc génère une clé d'accès temporaire et sécurisée que les appareils externes ou les commissaires peuvent utiliser pour obtenir en toute sécurité l'ensemble de données du réseau Thread.

Activer le 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
    }
}

Désactiver le mode ePSKc

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

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

Observer les événements de désactivation d'ePSKc

TBRs émettent des événements lorsqu'une session ePSKc se termine (par exemple, parce que la clé a été utilisée, que la session a expiré ou qu'elle a été annulée manuellement).

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

Gérer l'appartenance au réseau Thread

Vous pouvez demander à un TBR de rejoindre un nouveau réseau Thread en fournissant les TLV de l'ensemble de données opérationnel actif ou lui demander de quitter son réseau actuel.

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

Configurer l'accès à Internet au niveau de la structure

Le trait ThreadNetworkSettings est un trait pouvant être mis à jour, associé à une Structure (représentant une maison ou un bâtiment). Il permet aux développeurs de configurer la règle d'accès à Internet à l'échelle de la structure pour les 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}")
    }
}