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, kimlik bilgilerini ve kullanıcı verilerini doğrudan göstermeden akıllı ev ekosisteminden herhangi bir Thread cihazını kurabilir.
Sadece birkaç API çağrısıyla:
- Google Play Hizmetleri'nden tercih edilen Thread ağ kimlik bilgisi isteyin.
- Yeni sınır yönlendiricileri kurun ve Thread ağ kimlik bilgilerinizi Google Play hizmetlerine ekleyin.
- Alanda 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 birçok 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ız yararlı olacaktır:
Thread Network Credentials:Thread Ağının, Ağ Anahtarının ve bir Thread cihazının belirli bir Thread ağına katılması için gereken diğer özelliklerin kodlandığı Thread TLV'lerin ikili blob'u.
Tercih Edilen Thread Ağ Kimlik Bilgileri:
getPreferredCredentials
API'si kullanılarak farklı tedarikçi firmaların uygulamalarıyla paylaşılabilecek, otomatik olarak seçilen Thread ağ kimlik bilgisi.Sınır Temsilcisi Kimliği: Thread Sınırı Yönlendiricisi cihazı için 16 baytlık genel bir benzersiz kimlik. Bu kimlik, sınır yönlendirici satıcıları tarafından oluşturulur ve yönetilir.
İleti Dizisi Sınır Yönlendiricisi uygulaması: Bu, yeni İleti dizisi sınırı yönlendirici cihazları oluşturan ve ileti dizisi ağ kimlik bilgilerini Google Play Hizmetleri'ne ekleyen Android uygulamanızdır. Uygulamanız, eklenen kimlik bilgilerinin yetkili sahibidir ve bunlara 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şmek 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.
Uygulama sahibi olarak, Mesaj 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 bilgileri eklemek, sınır yönlendiricisinin İleti dizisi ağı kimlik bilgileri değiştiğinde kimlik bilgilerini güncellemek ve İleti Dizisi Sınır Yönlendiricisi kaldırıldığında veya fabrika ayarlarına sıfırlandığında kimlik bilgilerini kaldırmak anlamına gelir.
Sınır Temsilcisi keşfi
Kimlik bilgileri, bir Sınır Temsilcisi Kimliği ile kaydedilmelidir. Thread Sınır Yönlendirici Kurulumu 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 özelliklere karşılık gelen txt
değerleri sırasıyla nn
, xp
ve id
'dir.
Google sınır hizmetleri Google ağ yönlendiricileri olan ağlarda kullanılmak üzere Google Thread ağ kimlik bilgilerini otomatik olarak alır.
SDK'yı Android uygulamanıza entegre edin
Başlamak için aşağıdaki adımları uygulayın:
Google Play Hizmetleri'ni ayarlama başlıklı makalede 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 rehberde 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), ... )
Daha sonra, tercih edilen kimlik bilgilerini eklemek ve yönetmek için önerilen adımlara değineceğ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. Bu şekilde, Thread cihazları mümkün olduğunda tek bir Thread ağına bağlanır.
getPreferredCredentials
çağrısı bir Etkinlik başlatı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ıya tercih edilen kimlik bilgilerini istemek için:
ActivityLauncher
beyan edin:private lateinit var preferredCredentialsLauncher: ActivityResultLauncher<IntentSenderRequest>
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.") } }
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 bilgisi 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
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 ekleyin
Thread ağ kimlik bilgilerinizi diğer Thread tedarikçilerine sunmak için bu bilgileri 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 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}]") }
}
Alandaki sınır yönlendiricilerini algılama ve taşıma
Şu anda alan içinde 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önlendiricisi kimlik bilgilerini Google Play Hizmetleri'nde depolanan bilgilerle karşılaştırır.
isPreferredCredentails
, eşleşmeyen veri türleri için 0
ve eşleşenler için 1
veri türünü Int
veri türü olarak 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
Mesaj Dizisi Sınır Yönlendiricinizin zaten bir Thread ağıyla kurulduğu durumlar vardır ve bu mesaj dizisi ağını diğer tedarikçilerle paylaşmak için Google Play hizmetlerine ekleyebilirsiniz. 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ını, kanalını ve diğer ağ bilgilerini alabilirsiniz. Özelliklerin tam listesi için ThreadNetworkCredentials konusuna bakın.val threadNetworkCredentials = ThreadNetworkCredentials.fromActiveOperationalDataset(activeDataset) Log.d( "threadNetworkCredentials", threadNetworkCredentials.channel.toString() + " - " + threadNetworkCredentials.networkName)
isPreferredCredentials
API'sini ç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
yöntemini çağırı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 ağ kimlik bilgilerini işleyin
getPreferredCredentials
kullanıcısına benzer şekilde, bir sınır yönlendiricisinin Genişletilmiş Kaydırma Kimliği'nden kullanıcıdan kimlik bilgilerini 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ırlama işleminizden kaldırıldığında cihazın 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 bakın.