SDK Thread Network pour Android

Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Le SDK Thread Network offre des fonctionnalités semblables à un trousseau numérique, qui permet à vos applications Android de partager les identifiants réseau de Thread avec les services Google Play. Cela permet à vos applications de configurer n'importe quel appareil Thread depuis n'importe quel écosystème de maison connectée, sans divulguer directement les identifiants et les données utilisateur.

En quelques appels d'API, vous pouvez:

  1. Demandez vos identifiants de réseau Thread préférés aux services Google Play.
  2. Configurez de nouveaux routeurs de bordure et ajoutez vos identifiants de réseau Thread aux services Google Play.
  3. Si vous disposez déjà de routeurs de bordure sur le terrain, vous pouvez vérifier s'ils se trouvent dans le réseau préféré et les migrer si nécessaire.

Il existe plusieurs parcours utilisateur et développeurs. Nous les présenterons dans la plupart de ce guide, ainsi que d'autres fonctionnalités clés et leur utilisation recommandée.

Terminologie clé et concepts d'API

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

  • Thread Network Credentials (Identifiants de réseau Thread) : blob binaire des TLV de Thread qui encode le nom, la clé réseau et d'autres propriétés Thread requis par un appareil Thread pour rejoindre un réseau Thread donné.

  • Identifiants réseau Thread préférés : 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.

  • Border Agent ID : ID unique global de 16 octets pour un appareil de routeur de bordure Thread. Cet ID est créé et géré par les fournisseurs de routeurs à la périphérie.

  • Application de configuration du routeur de bordure dans Thread : il s'agit de votre application Android qui configure les nouveaux appareils de routeur de bordure dans le fil de discussion et ajoute les identifiants de réseau Thread aux services Google Play. Votre application est le propriétaire officiel des identifiants ajoutés, et son accès est offert.

Un grand nombre d'API Thread Network renvoient une tâche qui se termine de manière asynchrone. Vous pouvez utiliser addOnSuccessListener et addOnFailureListener pour enregistrer des rappels permettant de recevoir le résultat. Pour en savoir plus, consultez la documentation sur Tasks.

Propriété des identifiants et maintenance

L'application qui ajoute les identifiants du réseau Thread devient le propriétaire des identifiants et dispose d'une autorisation totale d'accès aux identifiants. Si vous essayez d'accéder aux identifiants ajoutés par d'autres applications, vous recevrez un message d'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 du routeur de bordure Thread est mis à jour. Cela implique d'ajouter des identifiants lorsque nécessaire, de mettre à jour les identifiants lorsque le routeur de bordure Thread modifie les identifiants du réseau Thread, et de les supprimer lorsque le routeur de bordure du thread est supprimé ou de rétablir la configuration d'usine.

Détection de l'agent de bordure

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

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

Pour les réseaux dotés de routeurs de bordure Google, les services Google Play obtiennent automatiquement des identifiants de réseau Google Thread pour une utilisation.

Intégrer le SDK à votre application Android

Pour commencer, procédez comme suit:

  1. Suivez les instructions fournies dans Configurer les services Google Play.

  2. Ajoutez la dépendance des services Google Play à votre fichier build.gradle:

    implementation 'com.google.android.gms:play-services-threadnetwork:16.0.0-beta01'
    
  3. Facultatif : Définissez data class pour BorderAgent pour stocker les informations sur le routeur de bordure. Ces données seront utilisé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 ensuite suivre les étapes recommandées pour ajouter et gérer les identifiants préférés.

Nouvelles configurations du routeur de bordure

Avant de créer un réseau pour de nouveaux routeurs bordures, il est important d'essayer d'utiliser les identifiants réseau préférés. Cela garantit que les appareils Thread sont connectés à un seul réseau Thread dans la mesure du possible.

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

Identifiants de requête

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

  1. Déclarez une ActivityLauncher :

    private lateinit var preferredCredentialsLauncher: ActivityResultLauncher<IntentSenderRequest>
    
  2. Gérez le résultat de l'activité, renvoyé en tant que 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. Appelez preferredCredentials et lancez l'activité:

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

Créer un réseau Thread

Si aucun identifiant de réseau Thread préféré 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 également un objet ThreadNetworkCredentials.

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

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

Pour spécifier le nom du réseau Thread, procédez comme suit:

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

Ajouter des identifiants

Pour rendre vos identifiants réseau Thread 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 routeur de bordure 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 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 routeurs de bordure sur le terrain

Si vous disposez actuellement de routeurs de bordure sur le terrain, vous pouvez utiliser isPreferredCredentials pour déterminer si vos routeurs de bordure appartiennent au réseau préféré. Cette API ne demande pas d'autorisation à l'utilisateur et vérifie les identifiants du routeur de bordure par rapport aux éléments stockés dans les services Google Play.

isPreferredCredentails renvoie 0 pour les correspondances sans correspondance et 1 pour les correspondances avec le 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. Dans les étapes suivantes, nous allons examiner ces options.

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

Dans certains cas, votre routeur de bordure Thread est déjà configuré avec un réseau Thread, et vous souhaitez l'ajouter aux services Google Play pour le partager avec d'autres fournisseurs. Vous pouvez créer une instance ThreadNetworkCredential à partir d'une liste TLV d'ensembles de données opérationnels opérationnels bruts pour Thread:

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

    val activeDataset =
          "0e080000000000010000000300000f35060004001fffe0020833333333...".dsToByteArray()
    
    fun String.dsToByteArray(): ByteArray {
      return chunked(2).map { it.toInt(16).toByte() }.toByteArray()
    }
    
  2. Utilisez fromActiveOperationalDataset pour créer le ThreadNetworkCredentials. Si l'opération réussit, vous pouvez obtenir le nom du réseau Thread, la chaîne ainsi que d'autres informations, Pour obtenir la liste complète des propriétés, consultez la page sur ThreadNetworkCredentials.

    val threadNetworkCredentials =
        ThreadNetworkCredentials.fromActiveOperationalDataset(activeDataset)
    Log.d(
        "threadNetworkCredentials",
        threadNetworkCredentials.channel.toString() + " - " + threadNetworkCredentials.networkName)
    
  3. 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 Border

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

Une fois l'objet ThreadBorderAgent créé, 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 de panoramique étendu

Comme pour getPreferredCredentials, vous pouvez également demander à l'utilisateur de vous fournir les identifiants d'un routeur étendu à l'ID de panoramique étendu. Le getCredentialsByExtendedPanId renvoie un IntentSender, et le résultat de l'activité contient un objet ThreadNetworkCredentials lorsque l'utilisateur approuve l'opération.

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 routeur de bordure est supprimé de votre maison ou lorsque vous rétablissez la configuration d'usine, 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}]") }
}

Resources

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