Android 向けボーダー ルーター デバイスガイド

Android アプリ デベロッパーは、Google Home の API を使用して Thread ボーダー ルーターを管理できます。

GoogleBorderRouterDevice は、2 つの主要なデバイス トレイトを使用して実装されます。 ThreadNetworkCapabilities は、ボーダー ルーターの機能を検査するための読み取り専用属性を提供し、 ThreadNetworkManagement は、コミッショナー（ePSKc）の一時的な事前共有キーを使用してネットワーク ライフサイクル コマンドと認証情報の共有を処理します。構造レベルの インターネット アクセス ポリシーは、 ThreadNetworkSettings トレイトを使用して管理します。

機能を使用したり、属性を更新したりする前に、デバイスの属性とコマンドのサポートを必ず確認してください。詳しくは、でデバイスを制御する Androidをご覧ください。

Google Home の API のデバイスタイプ トレイト Kotlin サンプルアプリ ユースケース

ボーダー ルーター

GoogleBorderRouterDevice

home.matter.6006.types.0161

 必須トレイト
     google ThreadNetworkCapabilities
     google ThreadNetworkManagement

 ボーダー ルーター

デバイスに関する基本情報を取得する

BasicInformation トレイトには、デバイスのベンダー名、ベンダー ID、プロダクト ID、 プロダクト名（モデル情報を含む）、ソフトウェア バージョンなどの情報が含まれます。

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

ボーダー ルーターの機能を確認する

ThreadNetworkCapabilities トレイトを使用すると、ボーダー ルーターの読み取り専用機能（ePSKc サポートやインターネット アクセス設定の構成など）を確認できます。

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

Thread 認証情報の共有（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 セッションが終了すると（キーが使用された、セッションが期限切れになった、手動でキャンセルされたなど）、Thread ボーダー ルーターからイベントが発行されます。

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 ネットワーク メンバーシップを管理する

アクティブな Operational Dataset TLV を指定して、Thread ボーダー ルーターに新しい Thread ネットワークに参加するよう指示したり、現在のネットワークから離脱するよう指示したりできます。

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