Android için sınır yönlendirici cihaz kılavuzu

Android uygulama geliştiricileri, Thread sınır yönlendiriciyi yönetmek için Home API'lerini kullanabilir.

GoogleBorderRouterDevice, iki temel cihaz özelliği kullanılarak uygulanır: ThreadNetworkCapabilities, sınır yönlendirici özelliklerini incelemek için salt okunur özellikler sağlar ve ThreadNetworkManagement, Komisyon Üyesi için Geçici Önceden Paylaşılan Anahtar (ePSKc) kullanarak ağ yaşam döngüsü komutlarını ve kimlik bilgisi paylaşımını yönetir. Yapı düzeyi internet erişimi politikaları, ThreadNetworkSettings özelliği kullanılarak yönetilir.

Herhangi bir özelliği kullanmadan veya özellikleri güncellemeye çalışmadan önce cihazın özellik ve komut desteğini mutlaka kontrol edin. Daha fazla bilgi için Androidcihazlarını kontrol etme başlıklı makaleye bakın.

Home API'leri Cihaz Türü Özellikler Kotlin Örnek Uygulaması Kullanım Örneği

Sınır Yönlendirici

GoogleBorderRouterDevice

home.matter.6006.types.0161

 Zorunlu Özellikler
     google ThreadNetworkCapabilities
     google ThreadNetworkManagement

 Sınır yönlendirici

Cihaz hakkında temel bilgileri edinme

BasicInformation özelliği, bir cihazın satıcı adı, satıcı kimliği, ürün kimliği, ürün adı (model bilgilerini içerir) ve yazılım sürümü gibi bilgileri içerir:

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

Sınır yönlendirici özelliklerini inceleme

ThreadNetworkCapabilities özelliğini kullanarak bir sınır yönlendiricinin salt okunur özelliklerini (ör. ePSKc desteği ve internet erişimi ayar yapılandırması) inceleyebilirsiniz.

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 kimlik bilgisi paylaşımını (ePSKc) yönetme

Thread kimlik bilgisi paylaşımı, Komisyon Üyesi için Geçici Önceden Paylaşılan Anahtar (ePSKc) kullanılarak gerçekleştirilir. ePSKc modu, harici cihazların veya komisyon üyelerinin Thread ağı veri kümesini güvenli bir şekilde elde etmek için kullanabileceği geçici ve güvenli bir geçiş anahtarı oluşturur.

ePSKc modunu etkinleştirme

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 modunu devre dışı bırakma

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

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

ePSKc devre dışı bırakma etkinliklerini gözlemleme

Thread sınır yönlendiriciler, bir ePSKc oturumu sona erdiğinde (örneğin, anahtar kullanıldığı, oturumun süresi dolduğu veya oturumun manuel olarak iptal edildiği için) etkinlik yayınlar.

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 ağı üyeliğini yönetme

Etkin operasyonel veri kümesi TLV'lerini sağlayarak bir Thread sınır yönlendiricinin yeni bir Thread ağına katılmasını veya mevcut ağından ayrılmasını sağlayabilirsiniz.

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

Yapı düzeyinde internet erişimini yapılandırma

ThreadNetworkSettings özelliği, Structure öğesine (evi veya binayı temsil eder) eklenen ve güncellenebilen bir özelliktir. Bu politika, geliştiricilerin Thread sınır yönlendiriciler için yapı genelinde internet erişim politikasını yapılandırmasına olanak tanır.

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