Diese Seite wurde von der Cloud Translation API übersetzt.

Thread Network SDK für Android

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 die ThreadNetworkCredentials 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 die ThreadNetworkCredentials.

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