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

Android için Thread Network SDK'sı

Thread Network SDK, dijital ortama benzer bir işleve sahip anahtar zincirini kullanabilirsiniz. Bu özellik, Android uygulamalarınızın Thread ağ kimlik bilgilerini Google Play Hizmetleri. Bu işlem, uygulamalarınızın kimlik bilgileri ve kullanıcı verilerini doğrudan açığa çıkarmadan tüm akıllı ev ekosistemlerini destekler.

Birkaç API çağrısıyla şunları yapabilirsiniz:

Google Play Hizmetleri'nden tercih edilen Thread ağ kimlik bilgilerini isteme.
Yeni sınır yönlendiricileri kurun ve Thread ağ kimlik bilgilerinizi Google Play hizmetlerine ekleyin.
Halihazırda saha içi sınır yönlendiricileriniz varsa sınırınızın olup olmadığını kontrol edebilirsiniz. yönlendiriciler tercih edilen ağdadır ve gerekirse bunları taşır.

Dikkate alınması gereken birkaç kullanıcı ve geliştirici yolculuğu vardır. Risklerin çoğunu diğer temel özellikler ve önerilen kullanımlarla birlikte bu kılavuzda bulabilirsiniz.

Temel terminoloji ve API kavramları

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

Thread Network Credentials (İş Parçacığı Ağ Kimlik Bilgileri): Kodlayan iş parçacığı TLV'lerinin ikili blob'u belirli bir Thread ağına katılmak için bir Thread cihazı.
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.
Sınır Aracısı Kimliği: Thread Sınır Yönlendirici cihazı için 16 baytlık, dünya genelinde benzersiz bir kimlik. Bu kimlik, sınır yönlendiricisi tedarikçileri tarafından oluşturulur ve yönetilir.
Thread Border Router Kurulum uygulaması: Yeni Thread Border Router cihazlarını ayarlayan ve Thread ağı kimlik bilgilerini Google Play Hizmetleri'ne ekleyen Android uygulamanızdır. Uygulamanız, eklenen öğenin yetkili sahibidir ve bunlara erişebilmesi gerekir.

Thread Network API'lerinin çoğu, asenkron olarak tamamlanan bir Görev döndürür. Sonuçları almak için geri çağırma işlevleri kaydetmek üzere addOnSuccessListener ve addOnFailureListener yöntemlerini kullanabilirsiniz. Daha fazla bilgi edinmek için Görev belgelerinden faydalanabilirsiniz.

Kimlik bilgilerinin sahipliği ve bakımı

Thread ağ kimlik bilgilerini ekleyen uygulama, kimlik bilgilerine sahip olması ve kimlik bilgilerine erişmek için tüm izinlere sahip olması gerekir. Denemek için diğer uygulamalar tarafından eklenen kimlik bilgilerine erişmek için bir PERMISSION_DENIED hatası.

Uygulama sahibi olarak, Thread Sınır Yönlendirici ağı güncellendiğinde Google Play Hizmetleri'nde depolanan kimlik bilgilerini güncel tutmanız önerilir. Bu gerektiğinde kimlik bilgileri eklemek, sınır olduğunda kimlik bilgilerinin güncellenmesi Thread ağ kimlik bilgileri değiştiğinde ve İş Parçacığı Sınır Yönlendiricisi kaldırıldı veya fabrika ayarlarına sıfırlandı.

Sınır aracısı bulma

Kimlik bilgileri, sınır acentesi kimliğiyle kaydedilmelidir. Thread sınır yönlendirici kurulum uygulamanızın, Thread sınır yönlendiricilerinizin sınır aracısı kimliklerini belirleyebildiğinden emin olmanız gerekir.

İş Parçacığı Sınırı Yönlendiricileri, Thread ağ bilgilerini tanıtmak için mDNS kullanmalıdır, Ağ Adı, Genişletilmiş Kaydırma Kimliği ve Sınır Aracısı Kimliği dahil. Bu özelliklerin karşılık gelen txt değerleri sırasıyla nn, xp ve id'dır.

Google sınır yönlendiricileri olan ağlarda Google Play Hizmetleri, kullanılmak üzere 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.

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

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

İsteğe bağlı: Sınır yönlendiricinin depolanması için bir BorderAgent veri sınıfı tanımlayın ekleyebilirsiniz. Bu verileri bu kılavuz boyunca 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 uygulama ekleyip yönetmek için önerilen adımları kimlik bilgileri.

Yeni sınır yönlendirici kurulumları

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

getPreferredCredentials çağrısı, kullanıcılardan ağ isteğine izin vermelerini isteyen bir Etkinlik başlatır. Ağ kimlik bilgileri Thread SDK dijital anahtar zincirinde depolanmışsa kimlik bilgileri uygulamanıza döndürülür.

Kimlik bilgisi iste

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

ActivityLauncher bildiriminde bulunun:

private lateinit var preferredCredentialsLauncher: ActivityResultLauncher<IntentSenderRequest>

ThreadNetworkCredentials olarak döndürülen Etkinlik sonucunu işleme:

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 İş Parçacığı Kenarlığı Yönlendiricisi kuruyorsanız preferredCredentials ve Etkinliği başlatın. Bu görüşme, yeni İş Parçacığı Sınırı Yönlendiriciniz, önceden kaydedilmiş aynı kimlik bilgilerini kullanır Telefonda tercih edilir ve farklı TBR'lerin yakınlaşmasını sağlar. emin olmanız gerekir.

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 TBR olmayan cihazların kurulumuyla ilgiliyse, örneğin yeni bir Matter-over-Thread son cihazı, allActiveCredentials kullanmanız önerilir API'yi kullanın. Bu görüşmede, yerel düzeyde bulunan TBR'ler taranır ağ ve dolayısıyla web sitesinin yerel olarak mevcut TBR.

// 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 mesaj dizisi ağı oluşturma

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

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 ekleme

Thread ağ kimlik bilgilerinizi diğer Thread tedarikçi firmaları tarafından kullanılabilir hale getirmek için onları Google Play hizmetlerine eklememiz gerekiyor. Yeni e-postalarımızı eklemeden önce bu Thread'in hangi sınır yönlendirici cihazına ait olduğunu da bilmemiz gerekir. ağın ait olduğu kişidir.

Bu örnekte, bir Border Agent 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 sınır yönlendiricilerini algılama ve taşıma

Saha içi sınır yönlendiricileriniz varsa şunları kullanabilirsiniz: Sınır yönlendiricilerinizin ait olup olmadığını belirlemek için isPreferredCredentials . Bu API, kullanıcıdan izin istemez ve sınır yönlendirici kimlik bilgilerini Google Play Hizmetleri'nde depolanan bilgilerle karşılaştırır.

isPreferredCredentails, eşleşmeyen için 0 ve eşleşen için 1 değerini Int veri türü olarak döndürür. IsPreferredCredentialsResult kullanabilirsiniz ve sonuçlarınızı kontrol edin.

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 bir Önce ThreadNetworkCredentials nesne. ThreadNetworkCredentials nesnesi oluşturmanın birkaç yolu vardır. Sonraki adımlarda bu seçenekleri inceleyeceğiz.

Ağ kimlik bilgilerini Operasyonel Veri Kümesine göre sıralayın

İş Parçacığı Sınırı Yönlendiricinizin önceden bir Thread ağı ve bu Thread ağını Google Play Hizmetleri'ne eklemek istiyorsunuz paylaşmak istemezsiniz. Ham bir Thread Active Operational Dataset TLV listesinden ThreadNetworkCredential bir örnek 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 öğesini kullanın. Başarılı olduğunda Thread ağının adını, Kanalını ve diğer ağ bilgileri. Tesislerin tam listesi için şuraya bakın: ThreadNetworkCredentials öğesini tıklayın.
```
val threadNetworkCredentials =
    ThreadNetworkCredentials.fromActiveOperationalDataset(activeDataset)
Log.d(
    "threadNetworkCredentials",
    threadNetworkCredentials.channel.toString() + " - " + threadNetworkCredentials.networkName)
```

isPreferredCredentials API'yi çağırın ve ThreadNetworkCredentials.

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 acentesi tarafından gönderilen Thread ağ kimlik bilgileri

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

ThreadBorderAgent nesnesini oluşturduktan sonra şunu çağırın: getCredentialsByBorderAgent. 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ş Pan kimliğine göre Thread ağ kimlik bilgileri

getPreferredCredentials özelliğine benzer şekilde, kullanıcıdan kimlik bilgilerini bir sınır yönlendiricisinin Genişletilmiş Kaydırma Kimliğinden alır. 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ır

Sınır Yönlendirici cihazınız evinizden kaldırıldığında veya fabrika ayarlarına sıfırlandığında, Thread ağını Google Play hizmetlerinden kaldırması gerekiyor.

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'sı hakkında daha fazla bilgi edinmek için API Referansı'na bakın.