Google utilise la technologie IA pour traduire le contenu dans votre langue préférée. Les traductions générées par IA peuvent contenir des erreurs.

SDK Thread Network pour Android

Le SDK Thread Network fournit des fonctionnalités semblables à celles d'un trousseau numérique, ce qui permet à vos applications Android de partager les identifiants du réseau Thread avec les services Google Play. Vos applications peuvent ainsi configurer n'importe quel appareil Thread de n'importe quel écosystème de maison connectée, sans exposer directement les identifiants et les données utilisateur.

En quelques appels d'API, vous pouvez :

Demandez les identifiants du réseau Thread préféré aux services Google Play.
Configurez de nouveaux Thread Border Router (TBR) et ajoutez les identifiants de votre réseau Thread aux services Google Play.
Si vous disposez déjà de TBR sur le terrain, vous pouvez vérifier si vos TBR se trouvent dans le réseau préféré et les migrer, si nécessaire.

Il existe plusieurs parcours utilisateur et développeur à prendre en compte. Nous aborderons la plupart d'entre eux dans ce guide, ainsi que d'autres fonctionnalités clés et l'utilisation recommandée.

Terminologie clé et concepts d'API

Avant de commencer, il est utile de comprendre les termes suivants :

Identifiants du réseau Thread : blob binaire de TLV Thread qui encode le nom du réseau Thread, la clé réseau et d'autres propriétés requises par un appareil Thread pour rejoindre un réseau Thread donné.
Identifiants du réseau Thread préféré : identifiants du réseau Thread sélectionnés automatiquement qui peuvent être partagés avec des applications de différents fournisseurs à l'aide de l'API getPreferredCredentials.
ID d'agent de bordure : un identifiant unique de 16 octets pour un appareil TBR. Cet ID est créé et géré par les fournisseurs border router.
Application de configuration TBR : il s'agit de votre application Android qui configure les nouveaux appareils TBR et ajoute les identifiants du réseau Thread aux services Google Play. Votre application est le propriétaire officiel des identifiants ajoutés et y a accès.

De nombreuses API Thread Network renvoient une Task qui s'exécute de manière asynchrone. Vous pouvez utiliser addOnSuccessListener et addOnFailureListener pour enregistrer des rappels afin de recevoir le résultat. Pour en savoir plus, consultez la documentation sur les tâches.

Propriété et maintenance des identifiants

L'application qui ajoute les identifiants du réseau Thread devient propriétaire des identifiants et dispose d'un accès complet à ceux-ci. Si vous essayez d'accéder aux identifiants ajoutés par d'autres applications, vous recevrez une erreur PERMISSION_DENIED.

En tant que propriétaire de l'application, nous vous recommandons de maintenir à jour les identifiants stockés dans les services Google Play lorsque le réseau TBR est mis à jour. Cela signifie qu'il faut ajouter des identifiants si nécessaire, les mettre à jour lorsque les identifiants du réseau Thread du border router changent, et les supprimer lorsque le TBR est supprimé ou que sa configuration d'usine est rétablie.

Découverte de l'agent de bordure

Les identifiants doivent être enregistrés avec un ID d'agent de bordure. Vous devez vous assurer que votre application de configuration TBR peut déterminer les ID d'agent de bordure de vos TBR.

Les TBR doivent utiliser mDNS pour annoncer les informations sur le réseau Thread, y compris le nom du réseau, l'ID PAN étendu et l'ID de l'agent de bordure. Les valeurs txt correspondantes pour ces attributs sont respectivement nn, xp et id.

Pour les réseaux avec Google Thread Border Router (gTBR), les services Google Play obtiennent automatiquement les identifiants du réseau Google Thread.

Intégrer le SDK à votre application Android

Pour commencer, procédez comme suit :

Suivez les instructions fournies dans Configurer les services Google Play.
Ajoutez la dépendance des services Google Play à votre fichier build.gradle :
```
implementation 'com.google.android.gms:play-services-threadnetwork:16.2.1'
```

Facultatif : Définissez une classe de données BorderAgent pour stocker les informations TBR. Nous utiliserons ces données tout au long de ce guide :

data class BorderAgentInfo(
  // Network Name max 16 len
  val networkName: String = "",
  val extPanId: ByteArray = ByteArray(16),
  val borderAgentId: ByteArray = ByteArray(16),
  ...
)

Nous allons maintenant passer en revue les étapes recommandées pour ajouter et gérer les identifiants préférés.

Nouvelles configurations de routeur de bordure Thread

Avant de créer un réseau pour de nouveaux routeurs de bordure, il est important d'essayer d'utiliser les identifiants du réseau préféré. Cela permet de s'assurer que les appareils Thread sont connectés à un seul réseau Thread lorsque cela est possible.

Un appel à getPreferredCredentials lance une activité, invitant les utilisateurs à autoriser la requête réseau. Si des identifiants réseau ont été stockés dans le trousseau numérique du SDK Thread, ils sont renvoyés à votre application.

Demander des identifiants

Pour inviter l'utilisateur à saisir ses identifiants préférés :

Déclarez un ActivityLauncher :

private lateinit var preferredCredentialsLauncher: ActivityResultLauncher<IntentSenderRequest>

Gérez le résultat de l'activité, renvoyé sous la forme 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.")
   }
 }

Si vous configurez un nouveau TBR, nous vous conseillons d'appeler preferredCredentials et de lancer l'activité. Cet appel garantit que votre nouveau TBR utilisera les mêmes identifiants déjà stockés comme préférés sur le téléphone, ce qui favorise la convergence de différents TBR vers le même réseau.

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

Si votre cas d'utilisation concerne la configuration d'appareils non TBR, comme un nouvel appareil final Matter-over-Thread, nous vous conseillons d'utiliser l'API allActiveCredentials pour récupérer les identifiants. Cet appel recherche les TBR trouvés sur le réseau local et ne renvoie donc pas d'identifiants qui ne sont pas disponibles par un TBR existant localement.

// 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
}

Créer un réseau Thread

Si aucun identifiant de réseau Thread préféré ni identifiant Thread actif n'est disponible dans le réseau Thread d'un utilisateur, vous pouvez utiliser l'API addCredentials pour ajouter des identifiants aux services Google Play. Pour ce faire, vous devez créer un ThreadBorderAgent et fournir un objet ThreadNetworkCredentials.

Pour créer un réseau aléatoire, appelez newRandomizeBuilder :

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

Pour spécifier le nom du réseau Thread :

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

Ajouter des identifiants

Pour que vos identifiants de réseau Thread soient disponibles pour d'autres fournisseurs Thread, nous devons les ajouter aux services Google Play. Avant de pouvoir ajouter nos nouveaux identifiants, nous devons également savoir à quel appareil TBR ce réseau Thread appartient.

Dans cet exemple, nous allons créer un ThreadBorderAgent à partir d'un ID d'agent de bordure et transmettre les identifiants du nouveau réseau Thread que vous venez de créer :

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

Détecter et migrer les border router sur le terrain

Si vous disposez de border router sur le terrain, vous pouvez utiliser isPreferredCredentials pour déterminer si vos border router appartiennent au réseau préféré. Cette API ne demande pas d'autorisation à l'utilisateur et vérifie les identifiants border router par rapport à ce qui est stocké dans les services Google Play.

isPreferredCredentials renvoie 0 pour les éléments non mis en correspondance et 1 pour les éléments mis en correspondance, en tant que type de données Int. Vous pouvez utiliser IsPreferredCredentialsResult pour vérifier vos résultats.

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

Pour utiliser isPreferredCredentials, vous devez d'abord créer un objet ThreadNetworkCredentials. Il existe plusieurs façons d'instancier ThreadNetworkCredentials. Nous allons examiner ces options dans les étapes suivantes.

Identifiants du réseau Thread par ensemble de données opérationnel

Dans certains cas, votre TBR est déjà configuré avec un réseau Thread, et vous souhaitez ajouter ce réseau Thread aux services Google Play pour le partager avec d'autres fournisseurs. Vous pouvez créer une instance ThreadNetworkCredential à partir d'une liste TLV d'ensemble de données opérationnel actif Thread brut :

Convertissez l'ensemble de données opérationnelles en ByteArray. Exemple :

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

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

Utilisez fromActiveOperationalDataset pour créer l'objet ThreadNetworkCredentials. Si l'opération réussit, vous pourrez obtenir le nom du réseau Thread, le canal et d'autres informations sur le réseau. Pour obtenir la liste complète des propriétés, consultez ThreadNetworkCredentials.
```
val threadNetworkCredentials =
    ThreadNetworkCredentials.fromActiveOperationalDataset(activeDataset)
Log.d(
    "threadNetworkCredentials",
    threadNetworkCredentials.channel.toString() + " - " + threadNetworkCredentials.networkName)
```

Appelez l'API isPreferredCredentials et transmettez le 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}]") }

Identifiants du réseau Thread par l'agent de bordure

Un ID d'agent de bordure identifie de manière unique un appareil TBR. Pour utiliser l'API getCredentialsByBorderAgent, vous devez d'abord créer un objet ThreadBorderAgent et transmettre l'ID de l'agent de bordure.

Une fois que vous avez créé l'objet ThreadBorderAgent, appelez getCredentialsByBorderAgent. Si les identifiants ont été enregistrés, vérifiez s'ils sont préférés.

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

Identifiants du réseau Thread par ID PAN étendu

Comme pour getPreferredCredentials, vous pouvez également demander à l'utilisateur de fournir des identifiants à partir de l'ID PAN étendu d'un TBR. getCredentialsByExtendedPanId renvoie un IntentSender, et le résultat de l'activité contient un objet ThreadNetworkCredentials lorsque l'utilisateur l'approuve.

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

Supprimer les identifiants

Lorsque votre appareil border router est supprimé de votre maison ou que sa configuration d'usine est rétablie, vous devez supprimer son réseau Thread des services Google Play.

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

Ressources

Pour en savoir plus sur le SDK Thread Network, consultez la documentation de référence de l'API.