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, 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 açığa çıkarmadan herhangi bir akıllı ev ekosistemindeki tüm 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)ler ayarlayın ve Thread ağı kimlik bilgilerinizi Google Play Hizmetleri'ne ekleyin.
Sahada TBRlarınız varsa TBRlarınızın tercih edilen ağda olup olmadığını kontrol edebilir ve gerekirse bunları taşıyabilirsiniz.

Dikkate alınması gereken çeşitli kullanıcı ve geliştirici yolculukları vardır. Bu kılavuzda, diğer önemli özellikler ve önerilen kullanımlarla birlikte bunların ç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: Belirli bir Thread ağına katılmak için Thread cihazının ihtiyaç duyduğu Thread Ağı Adı, Ağ Anahtarı ve diğer özellikleri kodlayan Thread TLV'lerinin ikili blobu.
Tercih edilen Thread ağ kimlik bilgileri: getPreferredCredentials API kullanılarak farklı tedarikçilerin uygulamalarıyla paylaşılabilen, otomatik olarak seçilen Thread ağ kimlik bilgileri.
Border Agent ID: Bir TBR cihaz için genel olarak benzersiz 16 baytlık kimlik. Bu kimlik, border router tedarikçileri tarafından oluşturulur ve yönetilir.
TBR kurulum uygulaması: Bu, 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 bu bilgilere erişebilir.

Thread Network API'lerinin çoğu, eşzamansız olarak tamamlanan bir Task döndürür. Sonucu almak için geri çağırmaları kaydetmek üzere addOnSuccessListener ve addOnFailureListener'ı kullanabilirsiniz. Daha fazla bilgi için Görevler belgelerine göz atı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 hata 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 ekleme, border router'nın Thread ağı kimlik bilgileri değiştiğinde kimlik bilgilerini güncelleme ve TBR kaldırıldığında veya fabrika ayarlarına sıfırlandığında kimlik bilgilerini kaldırma anlamına gelir.

Border Agent keşfi

Kimlik bilgileri, bir sınır görevlisi kimliğiyle kaydedilmelidir. TBR kurulum uygulamanızın, TBR cihazlarınızın Border Agent kimliklerini belirleyebildiğinden emin olmanız gerekir.

TBR, Ağ Adı, Genişletilmiş Pan Kimliği ve Sınır Aracısı Kimliği dahil olmak üzere Thread ağı bilgilerinin reklamını yapmak için mDNS kullanmalıdır. Bu özelliklerin karşılık gelen txt değerleri sırasıyla nn, xp ve id'dür.

Google Thread Border Router (gTBR) simgesi olan ağlarda Google Play Hizmetleri, kullanılacak 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ı tamamlayın:

Google Play Hizmetleri'ni ayarlama başlıklı makaledeki 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ı: BorderAgent veri sınıfı tanımlayarak TBR bilgileri depolayın. Bu kılavuzda bu verileri şu amaçlarla 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, mümkün olduğunda Thread cihazlarının tek bir Thread ağına bağlanması sağlanır.

getPreferredCredentials çağrısı, kullanıcıları ağ isteğine izin vermeye yönlendiren bir Etkinlik başlatır. Ağ kimlik bilgileri Thread SDK dijital anahtarlığında depolanmışsa kimlik bilgileri uygulamanıza döndürülür.

Kimlik bilgisi isteğinde bulunma

Kullanıcıdan tercih ettiği kimlik bilgilerini girmesini istemek için:

ActivityLauncher tanımlama:

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 numaralı telefonu aramanız ve Etkinliği başlatmanız önerilir. Bu görüşme, 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 getirmek için allActiveCredentials API'sini kullanmanız önerilir. Bu çağrı, yerel ağda bulunan TBR'leri tarar ve 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

Bir 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ğının adını belirtmek için:

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

Kimlik bilgisi ekleyin

Thread ağı kimlik bilgilerinizin diğer Thread sağlayıcıları tarafından kullanılabilmesi için bu bilgileri Google Play Hizmetleri'ne eklememiz gerekir. Yeni kimlik bilgilerimizi ekleyebilmemiz için bu Thread ağının hangi TBR cihaza ait olduğunu da bilmemiz gerekir.

Bu örnekte, bir sınır aracısı kimliğinden ThreadBorderAgent oluşturup 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 routerleri algılama ve taşıma

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

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

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

isPreferredCredentials özelliğini kullanmak için önce ThreadNetworkCredentials nesnesi oluşturmanız gerekir. ThreadNetworkCredentials öğesini başlatmanın çeşitli yolları vardır. Sonraki adımlarda bu seçenekleri inceleyeceğiz.

Operasyonel veri kümesine göre Thread ağı kimlik bilgileri

TBR cihazınızın Thread ağıyla kurulduğu ve bu Thread ağını diğer satıcılarla paylaşmak için Google Play Hizmetleri'ne eklemek istediğiniz durumlar olabilir. Ham Thread Active Operational Dataset TLV listesinden ThreadNetworkCredential örneği oluşturabilirsiniz:

İşlemsel 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 öğesini kullanın. İşlem başarılı olduğunda Thread ağının adını, kanalını ve diğer ağ bilgilerini alabilirsiniz. Özelliklerin tam listesi için ThreadNetworkCredentials başlıklı makaleyi inceleyin.
```
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

Border Agent ID, bir TBR cihazını benzersiz şekilde tanımlar. getCredentialsByBorderAgent API'sini kullanmak için önce bir ThreadBorderAgent nesnesi oluşturmanız ve Border Agent ID'yi iletmeniz gerekir.

ThreadBorderAgent nesnesini oluşturduktan sonra getCredentialsByBorderAgent işlevini çağırın. Kimlik bilgileri kaydedilmişse tercih edilip edilmediğini 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ş kalıcı hesap numarası kimliğine göre Thread ağ kimlik bilgileri

getPreferredCredentials'ya benzer şekilde, kullanıcıdan TBR'nın genişletilmiş kalıcı hesap numarası kimliğinden kimlik bilgisi de isteyebilirsiniz. getCredentialsByExtendedPanId, 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.