Google, içerikleri tercih ettiğiniz dile çevirmek için yapay zeka teknolojisini kullanır. Yapay zeka çevirilerinde hata olabilir.

Android için Thread Network SDK'sı

Thread Network SDK'sı, dijital anahtarlığa benzer bir işlev sunarak Android uygulamalarınızın Thread ağ kimlik bilgilerini Google Play Hizmetleri ile paylaşmasına olanak tanır. Bu sayede uygulamalarınız, kimlik bilgilerini ve kullanıcı verilerini doğrudan göstermeden herhangi bir akıllı ev ekosistemindeki Thread cihazlarını kurabilir.

Yalnızca birkaç API çağrısıyla şunları yapabilirsiniz:

Google Play Hizmetleri'nden tercih edilen Thread ağı kimlik bilgilerini isteyin.
Yeni Thread Border Router (TBR) cihazları kurun ve Thread ağı kimlik bilgilerinizi Google Play Hizmetleri'ne ekleyin.
Sahada TBR cihazlarınız varsa TBR cihazlarınızın tercih edilen ağda olup olmadığını kontrol edebilir ve gerekirse bunları taşıyabilirsiniz.

Dikkate alınması gereken birkaç kullanıcı ve geliştirici yolculuğu vardır. Bu rehberde, diğer önemli özellikler ve önerilen kullanım şekilleriyle birlikte bu özelliklerin çoğunu ele alacağız.

Temel terminoloji ve API kavramları

Başlamadan önce aşağıdaki terimleri anlamanız faydalı olacaktır:

Thread Ağı Kimlik Bilgileri: Thread ağ adını, ağ anahtarını ve bir Thread cihazının belirli bir Thread ağına katılması için gereken diğer özellikleri kodlayan Thread TLV'lerinin ikili blob'u.
Tercih Edilen Thread Ağ Kimlik Bilgileri: getPreferredCredentials API'si kullanılarak farklı tedarikçilerin uygulamalarıyla paylaşılabilen, otomatik olarak seçilen Thread ağ kimlik bilgileri.
Sınır aracısı kimliği: Bir cihaz için 16 baytlık genel olarak benzersiz kimlik. TBR Bu kimlik, border router tedarikçileri tarafından oluşturulur ve yönetilir.
TBR kurulum uygulaması: Yeni TBR cihazları kuran ve Thread ağı kimlik bilgilerini Google Play Hizmetleri'ne ekleyen Android uygulamanızdır. Uygulamanız, eklenen kimlik bilgilerinin yetkili sahibidir ve bunlara erişebilir.

Thread Network API'lerinin çoğu, eşzamansız olarak tamamlanan bir Task döndürür. Sonucu almak üzere geri çağırmaları kaydetmek için addOnSuccessListener ve addOnFailureListener'ı kullanabilirsiniz. Daha fazla bilgi edinmek için Task belgelerine bakın.

Kimlik bilgilerinin sahipliği ve bakımı

Thread ağı kimlik bilgilerini ekleyen uygulama, kimlik bilgilerinin sahibi olur ve kimlik bilgilerine erişmek için tam izinlere sahip olur. Diğer uygulamalar tarafından eklenen kimlik bilgilerine erişmeye çalışırsanız PERMISSION_DENIED hatası alırsınız.

Uygulama sahibi olarak, TBR ağı güncellendiğinde Google Play Hizmetleri'nde depolanan kimlik bilgilerini güncel tutmanız önerilir. Bu, gerektiğinde kimlik bilgilerini eklemek, border router cihazının Thread ağı kimlik bilgileri değiştiğinde kimlik bilgilerini güncellemek ve TBR kaldırıldığında veya fabrika ayarlarına sıfırlandığında kimlik bilgilerini kaldırmak anlamına gelir.

Sınır Temsilcisi keşfi

Kimlik bilgileri, sınır aracısı kimliğiyle kaydedilmelidir. TBR kurulum uygulamanızın, TBR cihazlarınızın sınır aracısı kimliklerini belirleyebildiğinden emin olmanız gerekir.

TBR, Thread ağ bilgilerini (Ağ Adı, Genişletilmiş Pan Kimliği ve Sınır Aracısı Kimliği dahil) bildirmek için mDNS kullanmalıdır. Bu özelliklerin karşılık gelen txt değerleri sırasıyla nn, xp ve id şeklindedir.

Google Thread Border Router (gTBR) bulunan ağlarda Google Play Hizmetleri, Google Thread ağ kimlik bilgilerini otomatik olarak alır.

SDK'yı Android uygulamanıza entegre etme

Başlamak için aşağıdaki adımları uygulayın:

Google Play Hizmetleri'ni ayarlama bölümündeki talimatları uygulayın.

build.gradle dosyanıza Google Play Hizmetleri bağımlılığını ekleyin:

implementation 'com.google.android.gms:play-services-threadnetwork:16.2.1'

İsteğe bağlı: TBR bilgilerini depolamak için bir BorderAgent veri sınıfı tanımlayın. Bu kılavuzda şu verileri kullanacağız:

data class BorderAgentInfo(
  // Network Name max 16 len
  val networkName: String = "",
  val extPanId: ByteArray = ByteArray(16),
  val borderAgentId: ByteArray = ByteArray(16),
  ...
)

Ardından, tercih edilen kimlik bilgilerini eklemek ve yönetmek için önerilen adımları inceleyeceğiz.

Yeni Thread sınır yönlendirici kurulumları

Yeni sınır yönlendiriciler için yeni bir ağ oluşturmadan önce tercih edilen ağ kimlik bilgilerini kullanmayı denemeniz önemlidir. Bu sayede, Thread cihazlar mümkün olduğunda tek bir Thread ağına bağlanır.

getPreferredCredentials çağrısı bir Activity başlatarak kullanıcılardan ağ isteğine izin vermelerini ister. Ağ kimlik bilgileri Thread SDK dijital anahtarlığında depolanmışsa kimlik bilgileri uygulamanıza döndürülür.

Kimlik bilgisi isteği

Kullanıcıdan tercih edilen kimlik bilgilerini istemek için:

ActivityLauncher beyan edin:

private lateinit var preferredCredentialsLauncher: ActivityResultLauncher<IntentSenderRequest>

ThreadNetworkCredentials olarak döndürülen etkinlik sonucunu işleyin:

preferredCredentialsLauncher =
 registerForActivityResult(
   StartIntentSenderForResult()
 ) { result: ActivityResult ->
   if (result.resultCode == RESULT_OK) {
     val threadNetworkCredentials = ThreadNetworkCredentials.fromIntentSenderResultData(result.data!!)
     Log.d("debug", threadNetworkCredentials.networkName)
   } else {
     Log.d("debug", "User denied request.")
   }
 }

Yeni bir TBR oluşturuyorsanız preferredCredentials yöntemini çağırıp etkinliği başlatmanız önerilir. Bu çağrı, yeni TBR cihazınızın telefonda tercih edilen olarak depolanan kimlik bilgilerini kullanmasını sağlayarak farklı TBR'lerin aynı ağda birleşmesini sağlar.

private fun getPreferredThreadNetworkCredentials() {
  ThreadNetwork.getClient(this)
    .preferredCredentials
  .addOnSuccessListener { intentSenderResult ->
    intentSenderResult.intentSender?.let {
      preferredCredentialsLauncher.launch(IntentSenderRequest.Builder(it).build())
      } ?: Log.d("debug", "No preferred credentials found.")
    }
  .addOnFailureListener { e: Exception -> Log.d(TAG, "ERROR: [${e}]") }
}

Kullanım alanınız, yeni bir Matter-over-Thread uç cihazı gibi TBR olmayan cihazların kurulumuyla ilgiliyse kimlik bilgilerini almak için allActiveCredentials API'sini kullanmanız önerilir. Bu çağrı, yerel ağda bulunan TBR'leri tarar. Bu nedenle, yerel olarak mevcut bir TBR tarafından kullanılamayan kimlik bilgilerini döndürmez.

// Creates the IntentSender result launcher for the getAllActiveCredentials API
private val getAllActiveCredentialsLauncher =
  registerForActivityResult(
    StartIntentSenderForResult()
  ) { result: ActivityResult ->
    if (result.resultCode == RESULT_OK) {
      val activeCredentials: List<ThreadNetworkCredentials> =
        ThreadNetworkCredentials.parseListFromIntentSenderResultData(
          result.data!!
        )
      // Use the activeCredentials list
    } else {
      // The user denied to share!
    }
  }

// Invokes the getAllActiveCredentials API and starts the dialog activity with the returned
// IntentSender
threadNetworkClient
.getAllActiveCredentials()
.addOnSuccessListener { intentSenderResult: IntentSenderResult ->
  val intentSender = intentSenderResult.intentSender
  if (intentSender != null) {
    getAllActiveCredentialsLauncher.launch(
      IntentSenderRequest.Builder(intentSender).build()
    )
  } else {
    // No active network credentials found!
  }
}
// Handles the failure
.addOnFailureListener { e: Exception ->
  // Handle the exception
}

Yeni bir Thread ağı oluşturma

Kullanıcının Thread ağında tercih edilen Thread ağı kimlik bilgileri veya etkin Thread kimlik bilgileri yoksa Google Play Hizmetleri'ne kimlik bilgileri eklemek için addCredentials API'sini kullanabilirsiniz. Bunun için bir ThreadBorderAgent oluşturmanız ve bir ThreadNetworkCredentials nesnesi sağlamanız gerekir.

Rastgele bir ağ oluşturmak için newRandomizeBuilder işlevini çağırın:

val threadCredentials = ThreadNetworkCredentials.newRandomizedBuilder().build()

Thread ağ adını belirtmek için:

val threadCredentials = ThreadNetworkCredentials.newRandomizedBuilder()
  .setNetworkName("ThreadNetworkSDK")
  .build()

Kimlik bilgisi ekleyin

Thread ağı kimlik bilgilerinizin diğer Thread tedarikçileri tarafından kullanılabilmesi için bu bilgileri Google Play Hizmetleri'ne eklememiz gerekir. Yeni kimlik bilgilerimizi eklemeden önce bu Thread ağının hangi TBR cihazına ait olduğunu da bilmemiz gerekir.

Bu örnekte, bir sınır aracısı kimliğinden ThreadBorderAgent oluşturacağız ve yeni oluşturduğunuz Thread ağı kimlik bilgilerini ileteceğiz:

private fun addCredentials(borderAgentInfo: BorderAgentInfo, credentialsToBeAdded: ThreadNetworkCredentials) {

  val threadBorderAgent = ThreadBorderAgent.newBuilder(borderAgentInfo.borderAgentId).build()
  Log.d("debug", "border router id:" + threadBorderAgent.id)

  ThreadNetwork.getClient(this)
    .addCredentials(threadBorderAgent, credentialsToBeAdded)
      .addOnSuccessListener {
        Log.d("debug", "Credentials added.")
      }
      .addOnFailureListener { e: Exception -> Log.d(TAG, "ERROR: [${e}]") }
}

Sahadaki border router cihazları algılama ve taşıma

Sahada border router varsa border router cihazlarınızın tercih edilen ağa ait olup olmadığını belirlemek için isPreferredCredentials kullanabilirsiniz. Bu API, kullanıcıdan izin istemez ve border router kimlik bilgilerini Google Play Hizmetleri'nde depolananlarla karşılaştırarak kontrol eder.

isPreferredCredentials, eşleşmeyenler için 0, eşleşenler için 1 değerini Int veri türü olarak döndürür. Sonuçlarınızı kontrol etmek için IsPreferredCredentialsResult aracını kullanabilirsiniz.

public @interface IsPreferredCredentialsResult {
    int PREFERRED_CREDENTIALS_NOT_FOUND = -1;
    int PREFERRED_CREDENTIALS_NOT_MATCHED = 0;
    int PREFERRED_CREDENTIALS_MATCHED = 1;
}

isPreferredCredentials kullanmak için önce bir ThreadNetworkCredentials nesnesi oluşturmanız gerekir. ThreadNetworkCredentials örneği oluşturmanın birkaç yolu vardır. Sonraki adımlarda bu seçenekleri inceleyeceğiz.

İşlem Veri Kümesi'ne göre Thread ağı kimlik bilgileri

TBR cihazınızın Thread ağıyla zaten ayarlanmış olduğu ve bu Thread ağını diğer tedarikçilerle paylaşmak için Google Play Hizmetleri'ne eklemek istediğiniz durumlar olabilir. Ham Thread Etkin İşletim Veri Kümesi TLV listesinden ThreadNetworkCredential örneği oluşturabilirsiniz:

Operasyonel veri kümesini ByteArray biçimine dönüştürün. Örneğin:

val activeDataset =
      "0e080000000000010000000300000f35060004001fffe0020833333333...".dsToByteArray()

fun String.dsToByteArray(): ByteArray {
  return chunked(2).map { it.toInt(16).toByte() }.toByteArray()
}

ThreadNetworkCredentials oluşturmak için fromActiveOperationalDataset kullanın. İşlem başarılı olduğunda Thread ağ adını, kanalı ve diğer ağ bilgilerini alabilirsiniz. Özelliklerin tam listesi için ThreadNetworkCredentials sayfasına bakın.

val threadNetworkCredentials =
    ThreadNetworkCredentials.fromActiveOperationalDataset(activeDataset)
Log.d(
    "threadNetworkCredentials",
    threadNetworkCredentials.channel.toString() + " - " + threadNetworkCredentials.networkName)

isPreferredCredentials API'sini çağırın ve ThreadNetworkCredentials değerini iletin.

ThreadNetwork.getClient(this)
.isPreferredCredentials(threadNetworkCredentials)
.addOnSuccessListener { result ->
  when (result) {
    IsPreferredCredentialsResult.PREFERRED_CREDENTIALS_NOT_MATCHED ->
        Log.d("isPreferredCredentials", "Credentials not matched.")
    IsPreferredCredentialsResult.PREFERRED_CREDENTIALS_MATCHED ->
        Log.d("isPreferredCredentials", "Credentials matched.")
  }
}
.addOnFailureListener { e: Exception -> Log.d("isPreferredCredentials", "ERROR: [${e}]") }

Sınır aracısına göre Thread ağ kimlik bilgileri

Sınır aracısı kimliği, TBR cihazını benzersiz şekilde tanımlar. getCredentialsByBorderAgent API'sini kullanmak için önce bir ThreadBorderAgent nesnesi oluşturmanız ve sınır aracısı kimliğini iletmeniz gerekir.

ThreadBorderAgent nesnesini oluşturduktan sonra getCredentialsByBorderAgent yöntemini çağırın. Kimlik bilgileri kaydedildiyse tercih edilip edilmediklerini kontrol edin.

private fun isPreferredThreadNetworkByBorderAgent(borderAgentInfo: BorderAgentInfo) {

  val threadBorderAgent = ThreadBorderAgent.newBuilder(borderAgentInfo.borderAgentId).build()
  Log.d("debug", "border router id:" + threadBorderAgent.id)

  var isPreferred = IsPreferredCredentialsResult.PREFERRED_CREDENTIALS_NOT_FOUND
  var borderAgentCredentials: ThreadNetworkCredentials?
  val taskByBorderAgent = ThreadNetwork.getClient(this)
  taskByBorderAgent
      .getCredentialsByBorderAgent(threadBorderAgent)
      .addOnSuccessListener { result: ThreadNetworkCredentialsResult ->
        borderAgentCredentials = result.credentials
        result.credentials?.let {
          taskByBorderAgent.isPreferredCredentials(it).addOnSuccessListener { result ->
            isPreferred = result
          }
        }
      }
      .addOnFailureListener { e: Exception -> Log.d(TAG, "ERROR: [${e}]") }
}

Genişletilmiş PAN kimliğine göre Thread ağ kimlik bilgileri

getPreferredCredentials gibi, kullanıcıdan TBR'ın genişletilmiş PAN kimliğinden kimlik bilgilerini istemesini de talep edebilirsiniz. getCredentialsByExtendedPanId, bir IntentSender döndürür ve kullanıcı onayladığında etkinlik sonucu bir ThreadNetworkCredentials nesnesi içerir.

private fun getCredentialsByExtPanId(borderAgentInfo: BorderAgentInfo) {
  ThreadNetwork.getClient(this)
    .getCredentialsByExtendedPanId(borderAgentInfo.extPanId)
    .addOnSuccessListener { intentSenderResult ->
      intentSenderResult.intentSender?.let {
        preferredCredentialsLauncher.launch(IntentSenderRequest.Builder(it).build())
      }
        ?: Log.d("debug", "No credentials found.")
    }
    .addOnFailureListener { e: Exception -> Log.d(TAG, "ERROR: [${e}]") }
}

Kimlik bilgilerini kaldırma

border router cihazınız evinizden kaldırıldığında veya fabrika ayarlarına sıfırlandığında Thread ağını Google Play Hizmetleri'nden kaldırmanız gerekir.

private fun removeCredentials(borderAgentInfo: BorderAgentInfo) {

  val threadBorderAgent = ThreadBorderAgent.newBuilder(borderAgentInfo.borderAgentId).build()
  Log.d("debug", "border router id:" + threadBorderAgent.id)

  ThreadNetwork.getClient(this)
      .removeCredentials(threadBorderAgent)
      .addOnSuccessListener { Log.d("debug", "Credentials removed.") }
      .addOnFailureListener { e: Exception -> Log.d(TAG, "ERROR: [${e}]") }
}

Kaynaklar

Thread Network SDK hakkında daha fazla bilgi edinmek için API referansına bakın.