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, herhangi bir akıllı ev ekosisteminden herhangi bir Thread cihazını kimlik bilgilerini ve kullanıcı verilerini doğrudan göstermeden ayarlayabilir.

Yalnızca birkaç API çağrısıyla şunları yapabilirsiniz:

  1. Google Play Hizmetlerinden tercih edilen Thread ağ kimlik bilgisi isteyin.
  2. Yeni sınır yönlendiricileri kurun ve 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. 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 şartları anlamanız önerilir:

  • Thread Network Credentials (İleti Dizisi Ağ Kimlik Bilgileri): Thread Ağ Adı, Ağ Anahtarı ve bir Thread cihazının belirli bir Thread ağına katılması için gereken diğer özelliklere sahip Thread TLV'lerin ikili blob'u.

  • Tercih Edilen Thread Ağ Kimlik Bilgileri: Farklı API'lerin uygulamalarıyla getPreferredCredentials API kullanılarak paylaşılabilen, otomatik olarak seçilen Thread ağ kimlik bilgileri.

  • Sınır Temsilcisi Kimliği: Mesaj Dizisi Sınır Yönlendirici cihazı için global olarak 16 baytlık benzersiz bir kimliktir. Bu kimlik, sınır yönlendirici tedarikçileri tarafından oluşturulur ve yönetilir.

  • Thread Limit Router Kurulum uygulaması: Yeni Thread Limit Router cihazlarını ayarlayan ve Thread ağ kimlik bilgilerini Google Play hizmetlerine 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 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şim için tüm izinlere sahiptir. Diğer uygulamalar tarafından eklenen kimlik bilgilerine erişmeye çalışırsanız PERMISSION_DENIED hatası alırsınız.

Uygulama sahibi olarak, İplik 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 İş parçacığı ağı kimlik bilgileri değiştiğinde kimlik bilgilerinin güncellenmesi ve İş parçacığı Sınır Yönlendirici 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 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.

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 kullanmalıdır. Bu özellikler için karşılık gelen txt değerleri sırasıyla nn, xp ve id'dur.

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

SDK'yı Android uygulamanıza entegre edin

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

  1. Google Play Hizmetleri'ni ayarlama sayfasında verilen talimatları uygulayın.

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

    implementation 'com.google.android.gms:play-services-threadnetwork:16.0.0'
    
  3. İsteğe bağlı: Sınır yönlendirici bilgilerini depolamak için bir BorderAgent veri sınıfı tanımlayın. Bu verileri rehberde 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ı 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 edilen ağ kimlik bilgilerini kullanmayı denemeniz gerekir. Bu, Thread cihazlarının mümkün olduğunda tek bir Thread ağına bağlanmasını sağlar.

Bir getPreferredCredentials çağrısı, bir etkinlik başlatarak 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.

Kimlik bilgisi isteme

Kullanıcıya 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 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.")
       }
     }
    
  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 Thread ağı oluşturun

Bir kullanıcının Thread ağında tercih edilen Thread ağ kimlik bilgisi yoksa Google Play Hizmetleri'ne kimlik bilgileri 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 çağrısı yapın:

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

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

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

Kimlik bilgisi ekle

Thread ağ kimlik bilgilerinizi diğer Thread tedarikçi firmasının kullanımına sunmak için 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 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}]") }
}

Alan içi sınır yönlendiricilerini tespit etme 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 Hizmetleri'nde depolananlarla karşılaştırarak kontrol eder.

isPreferredCredentails, eşleştirilmemiş için 0 ve Int 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 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

İş parçacığı sınırı yönlendiricinizin bir iş parçacığı ağıyla kurulduğu durumlar vardır ve bu ileti dizisini diğer tedarikçilerle paylaşmak için Google Play Hizmetleri'ne eklemek istersiniz. Ham Thread Etkin Operasyonel Veri Kümesi 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 Thread ağ Adı, Kanal ve diğer ağ bilgilerini alabilirsiniz. Özelliklerin tam listesi için ThreadNetworkCredentials sayfasına bakın.

    val threadNetworkCredentials =
        ThreadNetworkCredentials.fromActiveOperationalDataset(activeDataset)
    Log.d(
        "threadNetworkCredentials",
        threadNetworkCredentials.channel.toString() + " - " + threadNetworkCredentials.networkName)
    
  3. isPreferredCredentials API'yi çağırın ve 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 bilgisi

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

getPreferredCredentials özelliğine benzer şekilde, bir sınır yönlendiricisinin Genişletilmiş Kaydırma Kimliği ile kullanıcıdan da kimlik bilgisi isteyebilirsiniz. getCredentialsByExtendedPanId bir IntentSender döndürür ve kullanıcı sonuç 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 veya fabrika ayarlarına sıfırlandığında, Thread ağı, Google Play Hizmetleri'nden kaldırılmalıdır.

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ı bölümüne bakın.