Android için Thread Network SDK'sı

Koleksiyonlar ile düzeninizi koruyun İçeriği tercihlerinize göre kaydedin ve kategorilere ayırın.

Thread Network SDK, 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. Bu, uygulamalarınızın kimlik bilgilerini ve kullanıcı verilerini doğrudan göstermeden herhangi bir akıllı ev ekosisteminden herhangi bir Thread cihazını ayarlamasına olanak tanır.

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

  1. Google Play Hizmetlerinden tercih ettiğiniz İleti Dizisi ağ kimlik bilgileri isteyin.
  2. Yeni sınır yönlendiricileri ayarlayıp Thread ağ kimlik bilgilerinizi Google Play hizmetlerine ekleyin.
  3. 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 birkaç kullanıcı ve geliştirici yolculuğu vardır. Bu rehberde, sunulan diğer önemli özellikler ve önerilen kullanımların yanı sıra 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 Network Credentials (Thread Network Credentials): Bir İş Parçacığı Ağı, Network Key ve bir İş Parçacığı cihazının belirli bir Thread ağına katılması için gereken diğer özellikleri kodlayan Thread $V'lerinin ikili blob'u.

  • Tercih Edilen İleti Dizisi Ağı Kimlik Bilgileri: getPreferredCredentials API'si kullanılarak farklı tedarikçi firmaların uygulamalarıyla paylaşılabilen, otomatik olarak seçilen Mesaj dizisi kimlik bilgileri.

  • Sınır Temsilcisi Kimliği: Bir Mesaj Dizisi Sınır Yönlendirici cihazı için 16 baytlık genel benzersiz kimlik. Bu kimlik, sınır yönlendirici satıcıları tarafından oluşturulur ve yönetilir.

  • Thread Limit Yönlendirici Kurulum uygulaması: Bu, yeni Thread Border Yönlendirici cihazlarını yapılandıran ve Thread ağ kimlik bilgilerini Google Play hizmetlerine ekleyen Android uygulamanızdır. Uygulamanız, eklenen kimlik bilgilerinin yetkili sahibidir ve kimlik bilgilerine ücretsiz erişimi vardır.

Thread Network API'lerinin çoğu eşzamansız olarak tamamlanan bir Görev sağlar. Sonucu almak için geri çağırmaları kaydetmek üzere addOnSuccessListener ve addOnFailureListener özelliklerini kullanabilirsiniz. Daha fazla bilgi için Görev dokümanlarına bakın.

Kimlik bilgilerinin sahipliği ve bakımı

Thread ağ kimlik bilgilerini ekleyen uygulama, kimlik bilgilerinin sahibi olur ve kimlik bilgilerine erişim için tüm izinlere sahiptir. Diğer uygulamalar tarafından eklenen kimlik bilgilerine erişmeye çalışırsanız bir PERMISSION_DENIED hatası alırsınız.

Uygulama sahibi olarak, Thread Band 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 ileti dizisi ağ kimlik bilgilerinin değiştirilmesi durumunda 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 Temsilcisi keşfi

Kimlik bilgileri, Sınır Temsilcisi Kimliği ile kaydedilmelidir. Thread Band 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 Temsilcisi Kimliği dahil olmak üzere Thread ağ bilgilerini tanıtmak için mDNS kullanmalıdır. Bu özelliklere karşılık gelen txt değerleri sırasıyla nn, xp ve id'dur.

Google sınırlayıcı yönlendiricileri olan ağlarda Google Play Hizmetleri, kullanım için otomatik olarak Google Thread ağ kimlik bilgilerini alır.

SDK'yı Android uygulamanıza entegre etme

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

  1. Google Play hizmetlerini ayarlama başlıklı makalede verilen talimatları uygulayın.

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

    implementation 'com.google.android.gms:play-services-threadnetwork:16.0.0-beta01'
    
  3. İsteğe bağlı: Sınır yönlendirici bilgilerini depolamak için bir BorderAgent data class 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),
      ...
    )
    

Bir sonraki bölümde, tercih edilen kimlik bilgilerini eklemek ve yönetmek için önerilen adımları ele alacağız.

Yeni sınır yönlendirici kurulumları

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

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

İstek kimlik bilgileri

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

  1. ActivityLauncher tanımlayın:

    private lateinit var preferredCredentialsLauncher: ActivityResultLauncher<IntentSenderRequest>
    
  2. 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.")
       }
     }
    
  3. 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 İleti dizisi ağı oluşturun

Kullanıcı İş Akışı ağında tercih edilen İleti Dizisi ağ kimlik bilgileri yoksa Google Play Hizmetleri'ne kimlik bilgileri eklemek için addCredentials API'sini 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 ekleme

İş parçacığı ağ kimlik bilgilerinizi diğer Thread sağlayıcıları tarafından kullanılabilir hale getirmek için Google Play hizmetlerine eklememiz gerekir. Yeni kimlik bilgilerimizi eklemeden önce bu İş Parçacığı ağının hangi sınır yönlendirici cihazına ait olduğunu da bilmemiz gerekiyor.

Bu örnekte, Kenarlık Aracı Kimliği'nden bir ThreadBorderAgent oluşturacağız ve az önce oluşturduğunuz yeni 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}]") }
}

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

Şu anda alan içi 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önlendirici kimlik bilgilerini Google Play hizmetlerinde depolanan bilgilerle karşılaştırır.

isPreferredCredentails değeri, eşleşmeyenler için 0, Int için veri türü olarak 1 değerini 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 hazırlamanın birkaç yolu vardır. Sonraki adımlarda bu seçenekleri gözden geçireceğiz.

Operasyonel Veri Kümesine göre iş parçacığı ağ kimlik bilgileri

Mesaj Dizisi Sınır Yönlendiricinizin bir İş Parçacığı ağıyla ayarlanmış olduğu durumlar vardır ve bu İş Parçacığı ağını diğer satıcılarla paylaşmak için Google Play hizmetlerine eklemek istiyorsunuz. Ham Thread Active Operational Dataset TLV listesinden bir ThreadNetworkCredential örneği oluşturabilirsiniz:

  1. 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()
    }
    
  2. ThreadNetworkCredentials oluşturmak için fromActiveOperationalDataset kullanın. İşlem başarılı olduğunda İleti Dizisi ağının Adı, Kanal ve diğer ağ bilgilerini alabilirsiniz. Özelliklerin tam listesi için ThreadNetworkCredentials makalesine bakın.

    val threadNetworkCredentials =
        ThreadNetworkCredentials.fromActiveOperationalDataset(activeDataset)
    Log.d(
        "threadNetworkCredentials",
        threadNetworkCredentials.channel.toString() + " - " + threadNetworkCredentials.networkName)
    
  3. 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ırlama Aracısı tarafından mesaj dizisi ağ kimlik bilgileri

Sınır Aracısı Kimliği, sınır yönlendirici cihazını benzersiz şekilde 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 bunların 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 mesaj dizisi ağ kimlik bilgileri

getPreferredCredentials markasına benzer şekilde, kullanıcıdan bir sınır yönlendiricisinin Genişletilmiş Kaydırma Kimliği'nden kimlik bilgileri 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 Google'ın ileti dizisi ağını 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 Reference (API Referansı) sayfasını inceleyin.