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çinfromActiveOperationalDataset
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ıpThreadNetworkCredentials
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.