Thread Network SDK für Android

Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

Das Thread Network SDK bietet ähnliche Funktionen wie ein digitaler Schlüsselbund, sodass deine Android-Apps Thread-Netzwerkanmeldedaten mit Google Play-Diensten teilen können. Dadurch können Ihre Anwendungen jedes Thread-Gerät von jedem Smart-Home-System aus einrichten, ohne Anmeldedaten und Nutzerdaten direkt verfügbar zu machen.

Mit nur wenigen API-Aufrufen können Sie:

  1. Bevorzugte Thread-Netzwerkanmeldedaten von Google Play-Diensten anfordern
  2. Richten Sie neue Border-Router ein und fügen Sie den Google Play-Diensten Ihre Thread-Netzwerkanmeldedaten hinzu.
  3. Wenn Sie bereits In-Field-Border-Router haben, können Sie prüfen, ob sich Ihre Border-Router im bevorzugten Netzwerk befinden, und sie bei Bedarf migrieren.

Es gibt mehrere Ansätze für Nutzer und Entwickler. Die meisten dieser Funktionen werden in diesem Leitfaden beschrieben. Außerdem werden weitere wichtige Funktionen und die empfohlene Verwendung beschrieben.

Wichtige Begriffe und API-Konzepte

Bevor Sie beginnen, sollten Sie die folgenden Begriffe kennen:

  • Anmeldedaten für das Thread-Netzwerk:Binäres Blob mit Thread-TLVs, das den Thread-Netzwerknamen, den Netzwerkschlüssel und andere Attribute codiert, die von einem Thread-Gerät benötigt werden, um einem bestimmten Thread-Netzwerk beizutreten.

  • Bevorzugte Anmeldedaten für das Thread-Netzwerk: Die automatisch ausgewählten Anmeldedaten für das Thread-Netzwerk, die über die getPreferredCredentials API für Apps verschiedener Anbieter freigegeben werden können.

  • Border Agent ID (ID des Border-Agents): Eine global eindeutige 16-Byte-ID für ein Thread-Border-Gerät. Diese ID wird von Border Router-Anbietern erstellt und verwaltet.

  • App zur Einrichtung von Thread-Border-Routern:Diese Android-App richtet neue Thread-Border-Router ein und fügt den Google Play-Diensten die Anmeldedaten des Thread-Netzwerks hinzu. Ihre App ist der autorisierte Inhaber der hinzugefügten Anmeldedaten und hat Zugriff darauf.

Viele der Thread Network APIs geben eine Aufgabe zurück, die asynchron ausgeführt wird. Sie können addOnSuccessListener und addOnFailureListener verwenden, um Callbacks für den Empfang des Ergebnisses zu registrieren. Weitere Informationen finden Sie in der Dokumentation zu Aufgaben.

Anmeldedaten – Inhaber und Verwaltung

Die App, die die Thread-Netzwerkanmeldedaten hinzufügt, wird zum Inhaber der Anmeldedaten und verfügt über volle Berechtigungen für den Zugriff auf die Anmeldedaten. Wenn Sie versuchen, auf Anmeldedaten zuzugreifen, die von anderen Anwendungen hinzugefügt wurden, wird die Fehlermeldung PERMISSION_DENIED angezeigt.

Als App-Inhaber sollten Sie die in den Google Play-Diensten gespeicherten Anmeldedaten bei der Aktualisierung des Thread-Border-Routers immer auf dem neuesten Stand halten. Das bedeutet, dass Anmeldedaten bei Bedarf hinzugefügt, Anmeldedaten aktualisiert werden, wenn sich die Anmeldedaten für den Thread-Netzwerk des Border-Routers ändern, und Anmeldedaten entfernt werden, wenn der Thread-Border-Router entfernt oder auf die Werkseinstellungen zurückgesetzt wird.

Border Agent Discovery

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

Thread-Border-Router müssen mDNS verwenden, um Thread-Netzwerkinformationen zu bewerben, einschließlich des Netzwerknamens, der Extended Pan-ID und der Border Agent-ID. Die entsprechenden txt-Werte für diese Attribute sind nn, xp bzw. id.

Bei Netzwerken mit Google-Border-Routern erhalten Google Play-Dienste automatisch Anmeldedaten für das Google Thread-Netzwerk.

SDK in Ihre Android-App einbinden

Führen Sie zuerst die folgenden Schritte aus:

  1. Folgen Sie der Anleitung unter Google Play-Dienste einrichten.

  2. Fügen Sie der Datei build.gradle die Abhängigkeit für Google Play-Dienste hinzu:

    implementation 'com.google.android.gms:play-services-threadnetwork:16.0.0'

  3. Optional: Definieren Sie eine Datenklasse BorderAgent, um Border-Router-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 zeigen wir Ihnen, wie Sie bevorzugte Anmeldedaten hinzufügen und verwalten.

Neue Router-Border-Konfigurationen

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

Durch einen Aufruf von getPreferredCredentials wird eine Aktivität gestartet, in der Nutzer aufgefordert werden, die Netzwerkanfrage zuzulassen. Wenn Anmeldedaten für das Netzwerk im digitalen Schlüsselbund des Thread SDK gespeichert wurden, werden die Anmeldedaten an Ihre Anwendung zurückgegeben.

Anmeldedaten anfordern

So fragen Sie den Nutzer nach bevorzugten Anmeldedaten:

  1. ActivityLauncher deklarieren:

    private lateinit var preferredCredentialsLauncher: ActivityResultLauncher<IntentSenderRequest>

  2. 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.")
   }
 }

  3. 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 im Thread-Netzwerk eines Nutzers keine bevorzugten Thread-Netzwerkanmeldedaten verfügbar sind, können Sie die addCredentials API verwenden, um Anmeldedaten zu Google Play-Diensten hinzuzufügen. Dazu müssen Sie ein ThreadBorderAgent erstellen und außerdem 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 deine Thread-Netzwerkanmeldedaten anderen Thread-Anbietern zur Verfügung stehen, müssen wir sie den Google Play-Diensten hinzufügen. Bevor wir unsere neuen Anmeldedaten hinzufügen können, müssen wir wissen, welchem Border-Router-Gerät dieses Thread-Netzwerk gehört.

In diesem Beispiel erstellen wir eine ThreadBorderAgent aus einer Border Agent-ID und übergeben die soeben erstellten Thread-Netzwerkanmeldedaten:

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 derzeit Border-Router im Feld haben, können Sie mit isPreferredCredentials ermitteln, ob Ihre Grenzrouter zum bevorzugten Netzwerk gehören. Diese API fordert den Nutzer nicht zur Berechtigung an und prüft die Anmeldedaten des Border-Routers anhand der Daten, die in den Google Play-Diensten gespeichert sind.

isPreferredCredentails gibt 0 für nicht abgeglichene Daten und 1 für den Abgleich als Datentyp Int zurück. Sie können IsPreferredCredentialsResult verwenden, um Ihre Ergebnisse zu prüfen.

public @interface IsPreferredCredentialsResult {
    int PREFERRED_CREDENTIALS_NOT_FOUND = -1;
    int PREFERRED_CREDENTIALS_NOT_MATCHED = 0;
    int PREFERRED_CREDENTIALS_MATCHED = 1;
}

Damit Sie isPreferredCredentials verwenden können, müssen Sie zuerst ein ThreadNetworkCredentials-Objekt erstellen. 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 eingerichtet ist und Sie dieses Thread-Netzwerk den Google Play-Diensten hinzufügen möchten, um es mit anderen Anbietern zu teilen. Sie können eine ThreadNetworkCredential-Instanz aus einer TLV-Rohliste eines aktiven Operational-Datasets erstellen:

  1. Konvertieren Sie das operative Dataset in ein ByteArray. Beispiel:

    val activeDataset =
      "0e080000000000010000000300000f35060004001fffe0020833333333...".dsToByteArray()

    fun String.dsToByteArray(): ByteArray {
  return chunked(2).map { it.toInt(16).toByte() }.toByteArray()
}

  2. Verwenden Sie fromActiveOperationalDataset, um ThreadNetworkCredentials zu erstellen. Wenn der Vorgang erfolgreich war, können Sie den Thread-Netzwerknamen, 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)

  3. Rufen Sie die isPreferredCredentials API auf und übergeben Sie 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 von Border Agent

Eine Border Agent-ID identifiziert ein Border-Router-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.

Nachdem Sie das ThreadBorderAgent-Objekt erstellt haben, rufen Sie getCredentialsByBorderAgent auf. Wenn die Anmeldedaten gespeichert wurden, solltest du prüfen, ob 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 erweiterter Schwenk-ID

Ähnlich wie bei getPreferredCredentials können Sie den Nutzer auch über die Extended Pan-ID eines Grenzrouters zur Eingabe von Anmeldedaten auffordern. getCredentialsByExtendedPanId gibt IntentSender zurück und 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 sein 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.