Bu sayfa, Cloud Translation API ile çevrilmiştir.

Android için Thread Network SDK'sı

Thread Network SDK'sı, dijital anahtar zincirine benzer bir işlev sunarak Android uygulamalarınızın Thread ağ kimlik bilgilerini Google Play hizmetleriyle paylaşmasına olanak tanır. Böylece uygulamalarınız, kimlik bilgilerini ve kullanıcı verilerini doğrudan göstermeden akıllı ev ekosisteminden herhangi bir Thread cihazını kurabilir.

Sadece birkaç API çağrısıyla:

Google Play Hizmetleri'nden tercih edilen Thread ağ kimlik bilgisi isteyin.
Yeni sınır yönlendiricileri kurun ve Thread ağ kimlik bilgilerinizi Google Play hizmetlerine ekleyin.
Alanda sınır yönlendiricileriniz varsa sınır yönlendiricilerinizin tercih edilen ağda olup olmadığını kontrol edebilir ve gerekirse bunları taşıyabilirsiniz.

Göz önünde bulundurulması gereken birçok kullanıcı ve geliştirici yolculuğu vardır. Bunların çoğunu bu kılavuzda diğer önemli özellikler ve önerilen kullanımla birlikte ele alacağız.

Temel terminoloji ve API kavramları

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

Thread Network Credentials:Thread Ağının, Ağ Anahtarının ve bir Thread cihazının belirli bir Thread ağına katılması için gereken diğer özelliklerin kodlandığı Thread TLV'lerin ikili blob'u.
Tercih Edilen Thread Ağ Kimlik Bilgileri: getPreferredCredentials API'si kullanılarak farklı tedarikçi firmaların uygulamalarıyla paylaşılabilecek, otomatik olarak seçilen Thread ağ kimlik bilgisi.
Sınır Temsilcisi Kimliği: Thread Sınırı Yönlendiricisi cihazı için 16 baytlık genel bir benzersiz kimlik. Bu kimlik, sınır yönlendirici satıcıları tarafından oluşturulur ve yönetilir.
İleti Dizisi Sınır Yönlendiricisi uygulaması: Bu, yeni İleti dizisi sınırı yönlendirici cihazları oluşturan ve ileti dizisi 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 Görev döndürür. Sonucu almak için geri çağırmaları kaydetmek için addOnSuccessHearer'ı ve addOnFailureHearer'ı kullanabilirsiniz. Daha fazla bilgi edinmek için Görev belgelerini inceleyin.

Kimlik bilgilerinin sahipliği ve bakımı

Thread ağ kimlik bilgisini ekleyen uygulama, kimlik bilgilerinin sahibi olur ve kimlik bilgilerine erişmek için tüm izinlere sahiptir. Diğer uygulamaların eklediği kimlik bilgilerine erişmeye çalışırsanız PERMISSION_DENIED hatası alırsınız.

Uygulama sahibi olarak, Mesaj Dizisi Sınır Yönlendirici ağı güncellendiğinde Google Play Hizmetleri'nde depolanan kimlik bilgilerinizi güncel tutmanız önerilir. Bu, gerektiğinde kimlik bilgileri eklemek, sınır yönlendiricisinin İleti dizisi ağı kimlik bilgileri değiştiğinde kimlik bilgilerini güncellemek ve İleti Dizisi Sınır Yönlendiricisi 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, bir Sınır Temsilcisi Kimliği ile kaydedilmelidir. Thread Sınır Yönlendirici Kurulumu uygulamanızın, Thread sınır yönlendiricilerinizin Sınır Aracısı Kimliklerini belirleyebildiğinden emin olmanız gerekir.

Mesaj Dizisi Sınır Yönlendiricileri; Ağ Adı, Genişletilmiş Kaydırma Kimliği ve Sınır Aracısı Kimliği dahil olmak üzere Thread ağ bilgilerinin reklamını yapmak için mDNS'yi kullanmalıdır. Bu özelliklere karşılık gelen txt değerleri sırasıyla nn, xp ve id'dir.

Google sınır hizmetleri Google ağ yönlendiricileri olan ağlarda kullanılmak üzere Google Thread ağ kimlik bilgilerini otomatik olarak alır.

SDK'yı Android uygulamanıza entegre edin

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

Google Play Hizmetleri'ni ayarlama başlıklı makalede verilen talimatları uygulayın.

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

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

İsteğe bağlı: Sınır yönlendirici bilgilerini depolamak için bir BorderAgent veri sınıfı tanımlayın. Bu rehberde bu verileri kullanacağız:

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

Daha sonra, tercih edilen kimlik bilgilerini eklemek ve yönetmek için önerilen adımlara değineceğiz.

Yeni sınır yönlendirici kurulumları

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

getPreferredCredentials çağrısı bir Etkinlik başlatır ve kullanıcılardan ağ isteğine izin vermeleri istenir. Ağ kimlik bilgileri, Thread SDK dijital anahtar zincirinde depolandıysa kimlik bilgileri uygulamanıza döndürülür.

Kimlik bilgisi iste

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

ActivityLauncher beyan edin:

private lateinit var preferredCredentialsLauncher: ActivityResultLauncher<IntentSenderRequest>

ThreadNetworkCredentials olarak döndürülen Etkinlik sonucunu ele alın:

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

preferredCredentials numaralı telefonu arayıp Etkinliği başlatın:

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

Yeni bir Thread ağı oluşturun

Bir kullanıcının Thread ağında tercih edilen Thread ağ kimlik bilgisi yoksa Google Play Hizmetleri'ne kimlik bilgisi eklemek için addCredentials API'yi kullanabilirsiniz. Bunu yapmak için bir ThreadBorderAgent nesnesi oluşturmanız ve ayrıca bir ThreadNetworkCredentials nesnesi sağlamanız gerekir.

Rastgele bir ağ oluşturmak için newRandomizeBuilder numaralı telefonu arayın:

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

Mesaj dizisi ağ adını belirtmek için:

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

Kimlik bilgisi ekleyin

Thread ağ kimlik bilgilerinizi diğer Thread tedarikçilerine sunmak için bu bilgileri Google Play hizmetlerine eklememiz gerekir. Yeni kimlik bilgilerimizi eklemeden önce bu iş parçacığı ağının hangi sınır yönlendirici cihazına ait olduğunu da bilmemiz gerekiyor.

Bu örnekte, Sınır Aracısı Kimliğinden bir ThreadBorderAgent oluşturacağız ve az önce oluşturduğunuz yeni Thread ağ kimlik bilgisini 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}]") }
}

Alandaki sınır yönlendiricilerini algılama ve taşıma

Şu anda alan içinde sınır yönlendiricileriniz varsa sınır yönlendiricilerinizin tercih edilen ağa ait olup olmadığını belirlemek için isPreferredCredentials kullanabilirsiniz. Bu API, kullanıcıdan izin istemez ve sınır yönlendiricisi kimlik bilgilerini Google Play Hizmetleri'nde depolanan bilgilerle karşılaştırır.

isPreferredCredentails, eşleşmeyen veri türleri için 0 ve eşleşenler için 1 veri türünü Int veri türü olarak 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 bir ThreadNetworkCredentials nesnesi oluşturmanız gerekir. ThreadNetworkCredentials örneğini oluşturmanın birkaç yolu vardır. Sonraki adımlarda bu seçenekleri inceleyeceğiz.

Operasyonel Veri Kümesine göre ağ kimlik bilgilerini işleyin

Mesaj Dizisi Sınır Yönlendiricinizin zaten bir Thread ağıyla kurulduğu durumlar vardır ve bu mesaj dizisi ağını diğer tedarikçilerle paylaşmak için Google Play hizmetlerine ekleyebilirsiniz. Ham Thread Etkin Operasyonel Veri Kümesi TLV listesinden bir 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ını ve diğer ağ bilgilerini alabilirsiniz. Özelliklerin tam listesi için ThreadNetworkCredentials konusuna bakın.
```
val threadNetworkCredentials =
    ThreadNetworkCredentials.fromActiveOperationalDataset(activeDataset)
Log.d(
    "threadNetworkCredentials",
    threadNetworkCredentials.channel.toString() + " - " + threadNetworkCredentials.networkName)
```

isPreferredCredentials API'sini çağırıp ThreadNetworkCredentials komutunu geçin.

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ı tarafından iş parçacığı ağ kimlik bilgileri

Sınır Aracısı kimliği, sınır yönlendirici cihazını benzersiz olarak tanımlar. getCredentialsByBorderAgent API'yi 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 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ş Kaydı Kimliğine göre ağ kimlik bilgilerini işleyin

getPreferredCredentials kullanıcısına benzer şekilde, bir sınır yönlendiricisinin Genişletilmiş Kaydırma Kimliği'nden kullanıcıdan kimlik bilgilerini de isteyebilirsiniz. getCredentialsByExtendedPanId bir IntentSender döndürür ve Etkinlik sonucu, kullanıcı onayladığında 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ır

Sınır Yönlendirici cihazınız evinizden veya fabrika ayarlarına sıfırlama işleminizden kaldırıldığında cihazın 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.