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