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:
- Google Play Hizmetlerinden tercih edilen Thread ağ kimlik bilgisi isteyin.
- Yeni sınır yönlendiricileri kurun 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 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:
Google Play Hizmetleri'ni ayarlama sayfasında verilen 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'
İ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:
ActivityLauncher
tanımlayın: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 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:
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() }
ThreadNetworkCredentials
oluşturmak içinfromActiveOperationalDataset
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)
isPreferredCredentials
API'yi çağırın veThreadNetworkCredentials
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.