Das Thread Network SDK bietet Funktionen, die der eines digitalen der es deinen Android-Apps ermöglicht, Thread-Netzwerkanmeldedaten Google Play-Dienste. So können deine Apps jedes Thread-Gerät von Smart-Home-Systemen nutzen, ohne Anmeldedaten und Nutzerdaten direkt preiszugeben.
Mit nur wenigen API-Aufrufen können Sie:
- Fordere bevorzugte Thread-Netzwerkanmeldedaten von den Google Play-Diensten an.
- Neue Border-Router einrichten und Thread-Netzwerkanmeldedaten bei Google hinzufügen Google Play-Dienste.
- Wenn ihr bereits einen Border-Router vor Ort habt, könnt ihr prüfen, Router im bevorzugten Netzwerk und migrieren diese bei Bedarf.
Dabei müssen mehrere Nutzer- und Entwicklerpfade berücksichtigt werden. Wir werden die meisten in diesem Leitfaden zusammen mit anderen wichtigen Funktionen und der empfohlenen Verwendung.
Wichtige Terminologie und API-Konzepte
Bevor Sie loslegen, sollten Sie sich mit den folgenden Begriffen vertraut machen:
Thread-Netzwerkanmeldedaten:Binäres Blob der Thread-TLVs, die codieren Thread-Netzwerkname, Netzwerkschlüssel und andere Eigenschaften, die für ein Thread-Gerät mit einem bestimmten Thread-Netzwerk verbinden kann.
Bevorzugte Thread-Netzwerkanmeldedaten:Das automatisch ausgewählte Thread-Netzwerk Anmeldedaten, die über das
getPreferredCredentials
API verwenden.Border Agent-ID:Eine global eindeutige 16-Byte-ID für einen Thread-Border-Router . Diese ID wird von Anbietern von Border-Routern erstellt und verwaltet.
Einrichtungs-App für Thread-Border-Router:Dies ist Ihre Android-App, die neuen Thread-Border-Router-Geräten und fügt die Thread-Netzwerkanmeldedaten Google Play-Dienste. Ihre App ist der maßgebliche Inhaber der hinzugefügten Anmeldedaten erstellt und auf sie zugreifen kann.
Viele Thread-Netzwerk-APIs geben eine Fehlermeldung Aufgabe das asynchron abgeschlossen wird. Sie können addOnSuccessListener und addOnFailureListener um Callbacks für den Empfang des Ergebnisses zu registrieren. Weitere Informationen finden Sie im Aufgabe Dokumentation.
Inhaberschaft und Verwaltung von Anmeldedaten
Die App, die die Thread-Netzwerkanmeldedaten hinzufügt, wird zum Eigentümer des
Anmeldedaten und verfügt über uneingeschränkte Berechtigungen für den Zugriff auf die Anmeldedaten. Wenn Sie versuchen,
für den Zugriff auf Anmeldedaten, die von anderen Apps hinzugefügt wurden, erhältst du ein PERMISSION_DENIED
Fehler.
Als App-Inhaber sollten Sie die Anmeldedaten in Google Die Dienste werden auf dem neuesten Stand gehalten, wenn das Netzwerk des Thread-Border-Routers aktualisiert wird. Dieses das Hinzufügen von Anmeldedaten bei Bedarf, das Aktualisieren der Anmeldedaten, wenn der Rand ändern sich die Thread-Netzwerkanmeldedaten des Routers. Der Thread-Border-Router wurde entfernt oder auf die Werkseinstellungen zurückgesetzt.
Erkennung des Border Agent
Anmeldedaten müssen mit einer Border Agent-ID gespeichert werden. Sie müssen sicherstellen, Ihre Thread-Border-Router-Einrichtungs-App kann die Border-Agent-IDs ermitteln. der Thread-Border-Router.
Thread-Border-Router müssen mDNS verwenden,
um Thread-Netzwerkinformationen anzubieten.
einschließlich Netzwerkname, Extended Pan ID und Border Agent ID. Die
entsprechende txt
-Werte für diese Attribute sind nn
, xp
und id
.
.
Bei Netzwerken mit Google-Border-Routern werden die Google Play-Dienste ruft Google Thread-Netzwerkanmeldedaten ab.
SDK in Ihre Android-App einbinden
Führen Sie zunächst die folgenden Schritte aus:
Folgen Sie dazu der Anleitung unter Richten Sie die Google Play-Dienste ein.
Fügen Sie der Datei
build.gradle
die Abhängigkeit der Google Play-Dienste hinzu:implementation 'com.google.android.gms:play-services-threadnetwork:16.0.0'
Optional: Definieren Sie eine
BorderAgent
-Datenklasse zum Speichern des Border-Routers. Informationen. Wir verwenden diese Daten in diesem Leitfaden:data class BorderAgentInfo( // Network Name max 16 len val networkName: String = "", val extPanId: ByteArray = ByteArray(16), val borderAgentId: ByteArray = ByteArray(16), ... )
Als Nächstes sehen wir uns die empfohlenen Schritte zum Hinzufügen und Verwalten von bevorzugten Anmeldedaten.
Neue Border-Router-Einrichtungen
Bevor Sie ein neues Netzwerk für neue Border-Router erstellen, ist es wichtig, dass Sie versuchen, Ihre bevorzugten Anmeldedaten für das Netzwerk zu verwenden. Dadurch wird sichergestellt, Thread-Geräte werden nach Möglichkeit mit einem einzelnen Thread-Netzwerk verbunden.
Ein Aufruf an getPreferredCredentials
wird gestartet.
eine Aktivität und fordert Nutzer auf, die Netzwerkanfrage zuzulassen. Wenn Netzwerk
Anmeldedaten im digitalen Thread SDK-Schlüsselbund gespeichert sind,
an Ihre App zurückgegeben.
Anmeldedaten anfordern
So fordern Sie den Nutzer zur Eingabe bevorzugter Anmeldedaten auf:
Deklarieren Sie ein
ActivityLauncher
:private lateinit var preferredCredentialsLauncher: ActivityResultLauncher<IntentSenderRequest>
Verarbeiten Sie das Aktivitätsergebnis, das als
ThreadNetworkCredentials
zurückgegeben wird: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.") } }
Rufen Sie
preferredCredentials
auf und starten Sie die Aktivität: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}]") } }
Neues Thread-Netzwerk erstellen
Wenn keine bevorzugten Thread-Netzwerkanmeldedaten im
Thread-Netzwerk verbunden sind, können Sie die addCredentials
API verwenden, um Anmeldedaten hinzuzufügen.
Google Play-Dienste. Dazu müssen Sie ein ThreadBorderAgent
erstellen,
und geben auch ein ThreadNetworkCredentials
-Objekt an.
Rufen Sie newRandomizeBuilder
auf, um ein zufälliges Netzwerk zu erstellen:
val threadCredentials = ThreadNetworkCredentials.newRandomizedBuilder().build()
So geben Sie den Thread-Netzwerknamen an:
val threadCredentials = ThreadNetworkCredentials.newRandomizedBuilder()
.setNetworkName("ThreadNetworkSDK")
.build()
Anmeldedaten hinzufügen
So machen Sie Ihre Thread-Netzwerkanmeldedaten für andere Thread-Anbieter verfügbar: müssen wir sie den Google Play-Diensten hinzufügen. Bevor wir die neue müssen wir wissen, an welchen Border-Router dieses Thread-Gerät verwendet wird. Netzwerk gehört.
In diesem Beispiel erstellen wir eine ThreadBorderAgent
aus einer Border Agent-ID.
und die soeben erstellten Anmeldedaten für das Thread-Netzwerk übergeben:
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}]") }
}
In-Field-Border-Router erkennen und migrieren
Wenn Sie bereits Border-Router vor Ort haben, können Sie
isPreferredCredentials
, um festzustellen, ob deine Border-Router
mit dem bevorzugten Netzwerk. Diese API fordert den
Nutzer um Erlaubnis und prüft die Anmeldedaten des Border-Routers mit den gespeicherten Daten
in den Google Play-Diensten.
isPreferredCredentails
gibt 0
für keine Übereinstimmung und 1
für
als Datentyp Int
. Du kannst IsPreferredCredentialsResult
verwenden
um die Ergebnisse zu überprüfen.
public @interface IsPreferredCredentialsResult {
int PREFERRED_CREDENTIALS_NOT_FOUND = -1;
int PREFERRED_CREDENTIALS_NOT_MATCHED = 0;
int PREFERRED_CREDENTIALS_MATCHED = 1;
}
Wenn Sie isPreferredCredentials
verwenden möchten, müssen Sie ein
ThreadNetworkCredentials
-Objekt. Es gibt mehrere Möglichkeiten, ThreadNetworkCredentials
zu instanziieren. In den nächsten Schritten werden diese Optionen erläutert.
Thread-Netzwerkanmeldedaten nach operativem Dataset
Es kann vorkommen, dass Ihr Thread-Border-Router bereits mit einem
Thread-Netzwerk und du möchtest dieses Thread-Netzwerk den Google Play-Diensten hinzufügen
um sie mit anderen Anbietern zu teilen. Sie können eine ThreadNetworkCredential
erstellen
-Instanz aus einer TLV-Liste mit den aktiven Operational-Rohdaten-Datasets für Threads:
Konvertieren Sie das operative Dataset in ein
ByteArray
-Objekt. Beispiel:val activeDataset = "0e080000000000010000000300000f35060004001fffe0020833333333...".dsToByteArray()
fun String.dsToByteArray(): ByteArray { return chunked(2).map { it.toInt(16).toByte() }.toByteArray() }
Verwenden Sie
fromActiveOperationalDataset
, um dieThreadNetworkCredentials
zu erstellen. Wenn der Vorgang erfolgreich war, können Sie den Netzwerknamen, den Kanal und andere Netzwerkinformationen. Eine vollständige Liste der Unterkünfte finden Sie unter ThreadNetworkCredentials.val threadNetworkCredentials = ThreadNetworkCredentials.fromActiveOperationalDataset(activeDataset) Log.d( "threadNetworkCredentials", threadNetworkCredentials.channel.toString() + " - " + threadNetworkCredentials.networkName)
Rufen Sie die
isPreferredCredentials
API auf und übergeben Sie dieThreadNetworkCredentials
.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}]") }
Thread-Netzwerkanmeldedaten nach Border Agent
Mit einer Border Agent-ID wird ein Border-Router-Gerät eindeutig identifiziert. Zur Verwendung
getCredentialsByBorderAgent
API verwenden möchten, müssen Sie zuerst eine
ThreadBorderAgent
-Objekt und übergeben Sie die Border Agent-ID.
Nachdem Sie das ThreadBorderAgent
-Objekt erstellt haben, rufen Sie
getCredentialsByBorderAgent
. Wurden die Anmeldedaten gespeichert, sehen Sie nach,
wenn sie bevorzugt werden.
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}]") }
}
Thread-Netzwerkanmeldedaten nach Extended Pan-ID
Ähnlich wie bei getPreferredCredentials
können Sie den Nutzer auch zu einer Eingabe auffordern
Anmeldedaten der erweiterten Panorama-ID eines Border-Routers. Die
getCredentialsByExtendedPanId
gibt IntentSender
zurück und die Aktivität
Ergebnis enthält bei Genehmigung des Nutzers ein ThreadNetworkCredentials
-Objekt.
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}]") }
}
Anmeldedaten entfernen
Wenn Ihr Border Router aus Ihrem Zuhause entfernt oder auf die Werkseinstellungen zurückgesetzt wird, das Thread-Netzwerk aus den Google Play-Diensten entfernen muss.
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}]") }
}
Ressourcen
Weitere Informationen zum Thread Network SDK finden Sie in der API-Referenz