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

Android için Thread Network SDK'sı

Thread Network SDK, dijital anahtar zincirine benzer işlevler sunarak Android uygulamalarınızın, Thread ağ kimlik bilgilerini Google Play hizmetleriyle paylaşmasını sağlar. Bu sayede uygulamalarınız, kimlik bilgilerini ve kullanıcı verilerini doğrudan açığa çıkarmadan akıllı ev ekosisteminden herhangi bir Thread cihazı kurabilir.

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

Google Play hizmetlerinden tercih edilen Thread ağ kimlik bilgisini isteyin.
Yeni sınır yönlendiricileri ayarlayın ve Thread ağ kimlik bilgilerinizi Google Play hizmetlerine ekleyin.
Alan içi 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 birden fazla 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ıza yardımcı olabilir:

Thread Ağ Kimlik Bilgileri: Thread Network Name, Network Key ve bir Thread cihazının gerekli olduğu diğer iş parçacıklarını kodlayan, Thread USDV'lerin ikili program blob'u.
Tercih Edilen İleti Dizisi Ağ Kimlik Bilgileri: getPreferredCredentials API'si kullanılarak, farklı tedarikçi firmaların uygulamalarıyla paylaşılabilecek, otomatik olarak seçilen Mesaj dizisi ağ kimlik bilgileri.
Kenarlık Aracısı Kimliği: Mesaj Dizisi Sınır Yönlendiricisi için 16 baytlık benzersiz bir genel kimlik. Bu kimlik, sınır yönlendirici sağlayıcıları tarafından oluşturulur ve yönetilir.
Thread Kenarlık Yönlendirici Kurulumu uygulaması: Bu, yeni Thread Border Yönlendirici cihazlarını kuran ve Google Thread'e ait ağ kimlik bilgilerini Google Play hizmetlerine ekleyen Android uygulamanızdır. Uygulamanız, eklenen kimlik bilgilerinin yetkili sahibidir ve kimlik bilgilerine ücretsiz erişebilir.

Thread Network API'lerin birçoğu eşzamansız olarak tamamlanan bir Görev döndürür. Sonucu almak için geri çağırmaları kaydetmek üzere addOnsuccessListener ve addOnFailureListener'ı kullanabilirsiniz. Daha fazla bilgi edinmek için Görev belgelerini inceleyin.

Kimlik bilgisi sahipliği ve bakımı

Mesaj dizisi ağ kimlik bilgilerini ekleyen uygulama, kimlik bilgilerinin sahibi olur ve kimlik bilgilerine erişim 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.

Uygulamanın sahibi olarak İleti 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 bilgilerinin eklenmesi, sınır yönlendiricinin İleti dizisi ağı kimlik bilgileri değiştiğinde kimlik bilgilerinin güncellenmesi ve İleti Dizisi Sınır Yönlendiricisi kaldırıldığında veya fabrika ayarlarına sıfırlandığında kimlik bilgilerinin kaldırılması anlamına gelir.

Sınır Aracısı keşfi

Kimlik bilgileri, bir Sınır Aracısı Kimliği ile kaydedilmelidir. Thread Kenar Yönlendiricisi Kurulum 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 özellikler için karşılık gelen txt değerleri, sırasıyla nn, xp ve id'dir.

Google Play Hizmetleri, Google sınır yönlendiricileri olan ağlarda kullanım için 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 hizmetlerini kurma makalesindeki 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-beta02'

İsteğe bağlı: Sınır yönlendirici bilgilerinin depolanacağı BorderAgent veri sınıfı tanımlayın. Bu kılavuzda 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),
  ...
)

Şimdi, tercih edilen kimlik bilgilerini eklemek ve yönetmek için önerilen adımları gözden geçireceğ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. Böylece, Thread cihazları mümkün olduğunda tek bir Thread ağına bağlı olur.

getPreferredCredentials çağrısı yapıldığında bir Etkinlik başlatılı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ıdan tercih edilen kimlik bilgilerini girmesini istemek için:

ActivityLauncher bildirin:

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

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 ileti dizisi ağı oluşturun

Kullanıcının iş parçacığı ağında tercih edilen Thread ağ kimlik bilgisi yoksa addCredentials API'sini kullanarak Google Play Hizmetleri'ne kimlik bilgisi ekleyebilirsiniz. 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 çağrısı yapın:

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

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

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

Kimlik bilgisi ekleme

Thread ağ kimlik bilgilerinizi diğer Thread sağlayıcıları tarafından kullanılabilir hale getirmek için bunları Google Play hizmetlerine eklememiz gerekir. Yeni kimlik bilgisi ekleyebilmemiz için ayrıca bu Thread ağının hangi sınır yönlendirici cihazına ait olduğunu bilmemiz de gerekiyor.

Bu örnekte, Kenarlık Aracı Kimliği'nden 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}]") }
}

Alan içi sınır yönlendiricileri algılama ve taşıma

Şu anda sahada sınır yönlendiricileriniz varsa sınır yönlendiricilerinizin tercih edilen ağa ait olup olmadığını belirlemek için isPreferredCredentials özelliğini 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ırarak kontrol eder.

isPreferredCredentails, eşleşmeyen veri türleri için 0 ve 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 öğesini 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 göstermenin birkaç yolu vardır. Sonraki adımlarda bu seçeneklerin üzerinden geçeceğiz.

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

Mesaj Dizisi Sınır Yönlendiriciniz bir İş parçacığı ağıyla zaten yapılandırılmışsa ve bu İş parçacığı ağını Google Play Hizmetleri'ne ekleyerek diğer satıcılarla paylaşmak istiyorsanız. Ham Thread Etkin Operasyonel Veri Kümesi TLV listesinden bir ThreadNetworkCredential örneği oluşturabilirsiniz:

Operasyonel Veri Kümesini ByteArray olarak 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. Başarılı olduğunda Mesaj Dizisi ağ adını, kanalını ve diğer ağ bilgilerini alabilirsiniz. Özelliklerin tam listesi için ThreadNetworkCredentials'a bakın.
```
val threadNetworkCredentials =
    ThreadNetworkCredentials.fromActiveOperationalDataset(activeDataset)
Log.d(
    "threadNetworkCredentials",
    threadNetworkCredentials.channel.toString() + " - " + threadNetworkCredentials.networkName)
```

isPreferredCredentials API'yi ç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 numaralı telefonu arayı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 ileti dizisi ağ kimlik bilgileri

getPreferredCredentials operatörüne benzer şekilde, kullanıcıdan sınır yönlendiricisinin Genişletilmiş Pan Kimliğinden kimlik bilgisini 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ı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 göz atın.