Google verwendet KI-Technologie, um Inhalte in Ihre bevorzugte Sprache zu übersetzen. KI-Übersetzungen können Fehler enthalten.

Thread Network SDK für Android

Das Thread Network SDK bietet Funktionen, die einem digitalen Schlüsselbund ähneln. So können Ihre Android-Apps Anmeldedaten für das Thread-Netzwerk mit den Google Play-Diensten teilen. Dadurch können Ihre Apps jedes Thread-Gerät aus jedem Smart-Home-Ökosystem einrichten, ohne Anmeldedaten und Nutzerdaten direkt preiszugeben.

Mit nur wenigen API-Aufrufen können Sie Folgendes tun:

Bevorzugte Anmeldedaten für das Thread-Netzwerk von den Google Play-Diensten anfordern.
Neue Thread Border Router (TBR) einrichten und Ihre Anmeldedaten für das Thread-Netzwerk zu den Google Play-Diensten hinzufügen.
Wenn Sie bereits TBRs im Feld haben, können Sie prüfen, ob Ihre TBRs sich im bevorzugten Netzwerk befinden, und sie gegebenenfalls migrieren.

Es gibt mehrere Nutzer- und Entwicklerpfade. Die meisten davon werden in diesem Leitfaden behandelt, zusammen mit anderen wichtigen Funktionen und der empfohlenen Verwendung.

Wichtige Begriffe und API-Konzepte

Bevor Sie beginnen, sollten Sie die folgenden Begriffe kennen:

Anmeldedaten für das Thread-Netzwerk:Binärer Blob von Thread-TLVs, der den Namen des Thread-Netzwerks, den Netzwerkschlüssel und andere Eigenschaften codiert, die ein Thread-Gerät benötigt, um einem bestimmten Thread-Netzwerk beizutreten.
Bevorzugte Anmeldedaten für das Thread-Netzwerk:Die automatisch ausgewählten Anmeldedaten für das Thread-Netzwerk, die mit der getPreferredCredentials API für Apps verschiedener Anbieter freigegeben werden können.
Border-Agent-ID: Eine 16-Byte-ID, die weltweit eindeutig für ein TBR Gerät ist. Diese ID wird von border router Anbietern erstellt und verwaltet.
TBR Einrichtungs-App: Ihre Android-App, mit der neue TBR Geräte eingerichtet und die Anmeldedaten für das Thread-Netzwerk zu den Google Play-Diensten hinzugefügt werden. Ihre App ist der maßgebliche Eigentümer der hinzugefügten Anmeldedaten und hat Zugriff darauf.

Viele der Thread Network APIs geben eine Aufgabe zurück, die asynchron abgeschlossen wird. Mit addOnSuccessListener und addOnFailureListener können Sie Callbacks registrieren, um das Ergebnis zu erhalten. Weitere Informationen finden Sie in der Dokumentation zu Aufgaben.

Eigentümerschaft und Wartung von Anmeldedaten

Die App, die die Anmeldedaten für das Thread-Netzwerk hinzufügt, wird Eigentümer der Anmeldedaten und hat uneingeschränkten Zugriff darauf. Wenn Sie versuchen, auf Anmeldedaten zuzugreifen, die von anderen Apps hinzugefügt wurden, erhalten Sie den Fehler PERMISSION_DENIED.

Als App-Inhaber sollten Sie die in den Google Play-Diensten gespeicherten Anmeldedaten auf dem neuesten Stand halten, wenn das TBR Netzwerk aktualisiert wird. Das bedeutet, dass Sie bei Bedarf Anmeldedaten hinzufügen, Anmeldedaten aktualisieren, wenn sich die Anmeldedaten für das Thread-Netzwerk des border router ändern, und Anmeldedaten entfernen, wenn der TBR entfernt oder auf die Werkseinstellungen zurückgesetzt wird.

Border-Agent-Erkennung

Anmeldedaten müssen mit einer Border-Agent-ID gespeichert werden. Sie müssen dafür sorgen, dass Ihre TBR Einrichtungs-App die Border-Agent IDs Ihrer TBRs ermitteln kann.

TBRs müssen mDNS verwenden, um Informationen zum Thread-Netzwerk zu bewerben, einschließlich des Netzwerknamens, der erweiterten PAN-ID und der Border-Agent-ID. Die entsprechenden txt-Werte für diese Attribute sind nn, xp und id.

Bei Netzwerken mit Google Thread Border Router (gTBR)s ruft Google Play-Dienste automatisch Anmeldedaten für das Google Thread-Netzwerk ab.

SDK in Ihre Android-App einbinden

Führen Sie die folgenden Schritte aus, um zu beginnen:

Folgen Sie der Anleitung unter Google Play-Dienste einrichten.
Fügen Sie die Google Play-Dienste-Abhängigkeit Ihrer build.gradle-Datei hinzu:
```
implementation 'com.google.android.gms:play-services-threadnetwork:16.2.1'
```

Optional: Definieren Sie eine BorderAgent-Datenklasse, um TBR Informationen zu speichern. 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 werden die empfohlenen Schritte zum Hinzufügen und Verwalten bevorzugter Anmeldedaten beschrieben.

Neue Thread-Border-Router-Einrichtungen

Bevor Sie ein neues Netzwerk für neue Border-Router erstellen, sollten Sie zuerst die bevorzugten Anmeldedaten für das Netzwerk verwenden. So wird sichergestellt, dass Thread-Geräte nach Möglichkeit mit einem einzigen Thread-Netzwerk verbunden sind.

Ein Aufruf von getPreferredCredentials startet eine Aktivität, in der Nutzer die Netzwerkanfrage zulassen müssen. Wenn Anmeldedaten für das Netzwerk im digitalen Schlüsselbund des Thread SDK gespeichert wurden, werden sie an Ihre App zurückgegeben.

Anmeldedaten anfordern

So fordern Sie den Nutzer auf, bevorzugte Anmeldedaten anzugeben:

Deklarieren Sie einen 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.")
   }
 }

Wenn Sie ein neues TBR einrichten, sollten Sie preferredCredentials aufrufen und die Aktivität starten. Durch diesen Aufruf wird sichergestellt, dass Ihr neues TBR dieselben Anmeldedaten verwendet, die bereits als bevorzugt auf dem Smartphone gespeichert sind. So werden verschiedene TBRs im selben Netzwerk zusammengeführt.

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}]") }
}

Wenn Ihr Anwendungsfall die Einrichtung von Geräten betrifft, die keine TBRs sind, z. B. ein neues Matter-over-Thread-Endgerät, sollten Sie die allActiveCredentials API verwenden, um Anmeldedaten abzurufen. Bei diesem Aufruf werden TBRs im lokalen Netzwerk gesucht. Es werden also keine Anmeldedaten zurückgegeben, die nicht lokal von einem vorhandenen TBR verfügbar sind.

// Creates the IntentSender result launcher for the getAllActiveCredentials API
private val getAllActiveCredentialsLauncher =
  registerForActivityResult(
    StartIntentSenderForResult()
  ) { result: ActivityResult ->
    if (result.resultCode == RESULT_OK) {
      val activeCredentials: List<ThreadNetworkCredentials> =
        ThreadNetworkCredentials.parseListFromIntentSenderResultData(
          result.data!!
        )
      // Use the activeCredentials list
    } else {
      // The user denied to share!
    }
  }

// Invokes the getAllActiveCredentials API and starts the dialog activity with the returned
// IntentSender
threadNetworkClient
.getAllActiveCredentials()
.addOnSuccessListener { intentSenderResult: IntentSenderResult ->
  val intentSender = intentSenderResult.intentSender
  if (intentSender != null) {
    getAllActiveCredentialsLauncher.launch(
      IntentSenderRequest.Builder(intentSender).build()
    )
  } else {
    // No active network credentials found!
  }
}
// Handles the failure
.addOnFailureListener { e: Exception ->
  // Handle the exception
}

Neues Thread-Netzwerk erstellen

Wenn im Thread-Netzwerk eines Nutzers weder bevorzugte Anmeldedaten für das Thread-Netzwerk noch aktive Anmeldedaten für das Thread-Netzwerk verfügbar sind, können Sie mit der addCredentials API Anmeldedaten zu den Google Play-Diensten hinzufügen. Dazu müssen Sie ein ThreadBorderAgent erstellen und auch ein ThreadNetworkCredentials-Objekt angeben.

Rufen Sie newRandomizeBuilder auf, um ein zufälliges Netzwerk zu erstellen:

val threadCredentials = ThreadNetworkCredentials.newRandomizedBuilder().build()

So geben Sie den Namen des Thread-Netzwerks an:

val threadCredentials = ThreadNetworkCredentials.newRandomizedBuilder()
  .setNetworkName("ThreadNetworkSDK")
  .build()

Anmeldedaten hinzufügen

Damit Ihre Anmeldedaten für das Thread-Netzwerk für andere Thread-Anbieter verfügbar sind, müssen wir sie zu den Google Play-Diensten hinzufügen. Bevor wir unsere neuen Anmeldedaten hinzufügen können, müssen wir auch wissen, zu welchem TBR Gerät dieses Thread-Netzwerk gehört.

In diesem Beispiel erstellen wir ein ThreadBorderAgent aus einer Border-Agent-ID und übergeben die neuen Anmeldedaten für das Thread-Netzwerk, die Sie gerade erstellt haben:

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 In-Field-border routers haben, können Sie isPreferredCredentials verwenden, um festzustellen, ob Ihre border routers zum bevorzugten Netzwerk gehören. Diese API fordert den Nutzer nicht um Erlaubnis auf und vergleicht die border router Anmeldedaten mit den in den Google Play-Diensten gespeicherten Anmeldedaten.

isPreferredCredentials gibt 0 für „nicht übereinstimmend“ und 1 für „übereinstimmend“ als Int-Datentyp zurück. Mit IsPreferredCredentialsResult können Sie Ihre Ergebnisse prü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 zuerst ein ThreadNetworkCredentials-Objekt erstellen. Es gibt mehrere Möglichkeiten, ThreadNetworkCredentials zu instanziieren. In den nächsten Schritten werden diese Optionen beschrieben.

Anmeldedaten für das Thread-Netzwerk nach Betriebs-Dataset

Es kann vorkommen, dass Ihr TBR bereits mit einem Thread-Netzwerk eingerichtet ist und Sie dieses Thread-Netzwerk zu den Google Play-Diensten hinzufügen möchten, um es für andere Anbieter freizugeben. Sie können eine ThreadNetworkCredential-Instanz aus einer Liste mit unformatierten Thread-TLV-Daten für das aktive Betriebs-Dataset erstellen:

Konvertieren Sie das Betriebs-Dataset in ein ByteArray. 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 Namen des Thread-Netzwerks, den Kanal und andere Netzwerkinformationen abrufen. Eine vollständige Liste der Attribute 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}]") }

Anmeldedaten für das Thread-Netzwerk nach Border-Agent

Eine Border-Agent-ID identifiziert ein TBR Gerät eindeutig. Wenn Sie die getCredentialsByBorderAgent API verwenden möchten, müssen Sie zuerst ein ThreadBorderAgent-Objekt erstellen und die Border-Agent-ID übergeben.

Rufen Sie getCredentialsByBorderAgent auf, nachdem Sie das ThreadBorderAgent-Objekt erstellt haben. Wenn die Anmeldedaten gespeichert wurden, prüfen Sie, ob sie bevorzugt sind.

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}]") }
}

Anmeldedaten für das Thread-Netzwerk nach erweiterter PAN-ID

Ähnlich wie bei getPreferredCredentials können Sie den Nutzer auch nach Anmeldedaten von der TBR's erweiterten PAN-ID fragen. getCredentialsByExtendedPanId gibt einen IntentSender zurück. Das Aktivitätsergebnis enthält ein ThreadNetworkCredentials-Objekt, wenn der Nutzer zustimmt.

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 Gerät aus Ihrem Zuhause entfernt oder auf die Werkseinstellungen zurückgesetzt wird, müssen Sie das Thread-Netzwerk aus den Google Play-Diensten entfernen.

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.