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 Funktionen, die denen eines digitalen Schlüsselbunds ähneln, sodass Ihre Android-Apps Anmeldedaten für das Thread-Netzwerk mit Google Play-Diensten teilen können. Dadurch können deine Apps beliebige Thread-Geräte aus jedem Smart-Home-System einrichten, ohne Anmeldedaten und Nutzerdaten direkt offenzulegen.

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 Grenzrouter im Feld haben, können Sie prüfen, ob sie sich im bevorzugten Netzwerk befinden, und sie bei Bedarf migrieren.

Es gibt mehrere Kaufprozesse für Nutzer und Entwickler. In diesem Leitfaden werden die meisten sowie weitere wichtige Funktionen und die empfohlene Verwendung behandelt.

Wichtige Begriffe und API-Konzepte

Bevor Sie loslegen, sollten Sie sich mit den folgenden Begriffen vertraut machen:

  • Thread Network Credentials (Anmeldedaten des Threadnetzwerks): Binäres Blob von Thread-TLVs, das den Threadnetzwerknamen, den Netzwerkschlüssel und andere Eigenschaften codiert, die von einem Thread-Gerät für den Beitritt zu einem bestimmten Thread-Netzwerk benötigt werden.

  • Bevorzugte Anmeldedaten für das Threadnetzwerk: Die automatisch ausgewählten Anmeldedaten für das Threadnetzwerk, die über die getPreferredCredentials API mit Apps verschiedener Anbieter geteilt werden können.

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

  • Thread Border Router Setup App: Dies ist Ihre Android-App, die neue Thread Border Router-Geräte einrichtet und die Thread-Netzwerkanmeldedaten den Google Play-Diensten hinzufügt. Ihre App ist der autoritative Inhaber der hinzugefügten Anmeldedaten und hat kostenlosen Zugriff auf die Anmeldedaten.

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.

Inhaberschaft und Verwaltung von Anmeldedaten

Die Anwendung, die die Anmeldedaten für das Thread-Netzwerk hinzufügt, wird zum Inhaber der Anmeldedaten und verfügt über alle Berechtigungen für den Zugriff auf die Anmeldedaten. Wenn Sie versuchen, auf Anmeldedaten zuzugreifen, die von anderen Apps hinzugefügt wurden, wird die Fehlermeldung PERMISSION_DENIED angezeigt.

Als App-Inhaber wird empfohlen, die in den Google Play-Diensten gespeicherten Anmeldedaten bei der Aktualisierung des Thread-Border-Router-Netzwerks auf dem neuesten Stand zu halten. Dies bedeutet, dass bei Bedarf Anmeldedaten hinzugefügt, Anmeldedaten aktualisiert werden, wenn sich die Anmeldedaten des Thread-Routers ändern, und Anmeldedaten entfernt werden, wenn der Thread-Border-Router 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 die App für die Einrichtung von Thread-Border-Routern 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 erweiterten PAN-ID und der Border-Agent-ID. Die entsprechenden txt-Werte für diese Attribute sind nn, xp bzw. id.

In Netzwerken mit Google-Border-Routern erhalten die 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 der Google Play-Dienste hinzu:

    implementation 'com.google.android.gms:play-services-threadnetwork:16.0.0-beta02'
    
  3. Optional:Definieren Sie eine Datenklasse BorderAgent, um Informationen zu Border-Routern 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 gehen wir die empfohlenen Schritte zum Hinzufügen und Verwalten bevorzugter Anmeldedaten durch.

Neue Border-Router-Einrichtungen

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

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

Anmeldedaten anfordern

So fragen Sie den Nutzer nach bevorzugten Anmeldedaten:

  1. Deklarieren Sie ActivityLauncher:

    private lateinit var preferredCredentialsLauncher: ActivityResultLauncher<IntentSenderRequest>
    
  2. Verarbeite das Aktivitätsergebnis, zurückgegeben als ThreadNetworkCredentials:

    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. Rufe preferredCredentials auf und starte 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 auch ein ThreadNetworkCredentials-Objekt angeben.

Rufen Sie zum Erstellen eines zufälligen Netzwerks den newRandomizeBuilder auf:

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

So geben Sie den Thread-Netzwerknamen an:

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

Anmeldedaten hinzufügen

Damit Ihre 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 auch wissen, zu welchem Border-Router-Gerät dieses Thread-Netzwerk gehört.

In diesem Beispiel erstellen wir ein 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}]") }
}

Border-Router im Feld erkennen und migrieren

Wenn Sie derzeit Grenzrouter im Feld haben, können Sie mit isPreferredCredentials feststellen, ob Ihre Grenzrouter zum bevorzugten Netzwerk gehören. Diese API fordert den Nutzer nicht zur Berechtigung an und vergleicht die Anmeldedaten des Border-Routers mit den Daten, die in den Google Play-Diensten gespeichert sind.

isPreferredCredentails gibt 0 für nicht abgeglichene Daten und 1 für abgeglichene Daten 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 erläutert.

Thread-Netzwerkanmeldedaten nach operativem Dataset

Es gibt Fälle, in denen 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-Rohdaten zu Active Operational Dataset mit Rohdaten 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 Namen, den Kanal und andere Netzwerkinformationen des Thread-Netzwerks 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. Rufe die isPreferredCredentials API auf und übergib 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

Eine Border Agent-ID kennzeichnet 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 nachsehen, 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}]") }
}

Thread-Netzwerkanmeldedaten nach Extended Pan ID

Ähnlich wie bei getPreferredCredentials können Sie auch den Nutzer um Anmeldedaten eines Border-Routers mit der erweiterten Schwenk-ID bitten. getCredentialsByExtendedPanId gibt eine IntentSender zurück und das Ergebnis der Aktivität 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.