Geräteleitfaden für Border-Router für Android

Android-App-Entwickler können die Home APIs verwenden, um ein Thread Border Router (TBR) zu verwalten.

Der GoogleBorderRouterDevice wird mit zwei primären Geräte-Traits implementiert: ThreadNetworkCapabilities, das Lesezugriff-Attribute zum Prüfen von border router-Funktionen bereitstellt, und ThreadNetworkManagement, das Befehle für den Netzwerk-Lebenszyklus und die Freigabe von Anmeldedaten mithilfe eines vorinstallierten Schlüssels für den Commissioner (ePSKc) verarbeitet. Internetzugriffsrichtlinien auf Gebäudeebene werden mit dem Trait ThreadNetworkSettings verwaltet.

Prüfe immer, ob ein Gerät die Attribute und Befehle unterstützt, bevor du Funktionen verwendest oder versuchst, Attribute zu aktualisieren. Weitere Informationen findest du unter Geräte aufAndroidsteuern.

Gerätetyp für Home APIs Merkmale Kotlin-Beispiel-App Anwendungsfall

Border-Router

GoogleBorderRouterDevice

home.matter.6006.types.0161

 Erforderliche Attribute
     google ThreadNetworkCapabilities
     google ThreadNetworkManagement

 Border-Router

Grundlegende Informationen zu einem Gerät abrufen

   In der Beispiel-App für Android implementiert   

Das Attribut BasicInformation enthält Informationen wie den Namen des Anbieters, die Anbieter-ID, die Produkt-ID, den Produktnamen (einschließlich Modellinformationen) und die Softwareversion für ein Gerät:

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

Funktionen des Border-Routers prüfen

Mit dem Attribut ThreadNetworkCapabilities kannst du die schreibgeschützten Funktionen eines border router prüfen, z. B. die ePSKc-Unterstützung und die Konfiguration der Einstellung für den Internetzugriff.

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

Freigabe von Thread-Anmeldedaten (ePSKc) verwalten

Die Freigabe von Thread-Anmeldedaten erfolgt über einen temporären vorinstallierten Schlüssel für den Commissioner (ePSKc). Im ePSKc-Modus wird ein temporärer, sicherer Passkey generiert, mit dem externe Geräte oder Commissioner das Thread-Netzwerk-Dataset sicher abrufen können.

ePSKc-Modus aktivieren

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-Modus deaktivieren

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

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

ePSKc-Deaktivierungsereignisse beobachten

TBRs geben Ereignisse aus, wenn eine ePSKc-Sitzung endet (z. B. weil der Schlüssel verwendet wurde, die Sitzung abgelaufen ist oder sie manuell abgebrochen wurde).

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-Netzwerkmitgliedschaft verwalten

Du kannst ein TBR anweisen, einem neuen Thread-Netzwerk beizutreten, indem du die aktiven Operational Dataset-TLVs bereitstellst, oder es anweisen, das aktuelle Netzwerk zu verlassen.

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

Internetzugriff auf Gebäudeebene konfigurieren

Das Attribut ThreadNetworkSettings ist ein aktualisierbares Attribut, das an ein Structure (ein Zuhause oder Gebäude) angehängt ist. Damit können Entwickler die gebäudeweite Internetzugriffsrichtlinie für TBRs konfigurieren.

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