Le SDK Thread Network offre une fonctionnalité semblable à un trousseau numérique qui permet à vos applications Android de partager des identifiants de réseau Thread avec les services Google Play. Cela permet à vos applications de configurer n'importe quel appareil Thread à partir de n'importe quel écosystème de maison connectée, sans exposer directement les identifiants et les données utilisateur.
Avec quelques appels d'API, vous pouvez:
- Demander les identifiants réseau Thread préférés aux services Google Play
- Configurez de nouveaux routeurs de bordure et ajoutez vos identifiants de réseau Thread aux services Google Play.
- Si vous disposez déjà de routeurs de bordure sur le terrain, vous pouvez vérifier s'ils se trouvent sur le réseau préféré et les migrer si nécessaire.
Vous devez envisager plusieurs parcours utilisateur et développeur. Nous aborderons la plupart de ces fonctionnalités dans ce guide, ainsi que d'autres fonctionnalités clés et l'utilisation recommandée.
Termes clés et concepts d'API
Avant de commencer, il est utile de comprendre les termes suivants:
Identifiants réseau Thread:blob binaire des TLV Thread qui encode le nom du réseau Thread, la clé réseau et les autres propriétés requises par un appareil Thread pour rejoindre un réseau Thread donné.
Identifiants réseau Thread préférés:identifiants de 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:ID unique de 16 octets pour un appareil de routeur de bordure Thread. Cet ID est créé et géré par des fournisseurs de routeurs de bordure.
Application de configuration du routeur de bordure Thread:cette application Android configure de nouveaux appareils pour le routeur de bordure Thread et ajoute les identifiants réseau Thread aux services Google Play. Votre application est le propriétaire faisant autorité des identifiants ajoutés et y a accès.
De nombreuses API Thread Network renvoient une tâche qui se termine de manière asynchrone. Vous pouvez utiliser addOnSuccessListener et addOnFailureListener pour enregistrer les rappels permettant de recevoir le résultat. Pour en savoir plus, consultez la documentation de Tasks.
Propriété et maintenance des identifiants
L'application qui ajoute les identifiants du réseau Thread devient le propriétaire des identifiants et dispose de toutes les autorisations nécessaires pour y accéder. Si vous essayez d'accéder aux identifiants ajoutés par d'autres applications, une erreur PERMISSION_DENIED
s'affiche.
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 signifie que vous devez ajouter des identifiants si nécessaire, les mettre à jour lorsque les identifiants du réseau Thread du routeur de bordure changent, et les supprimer lorsque le routeur de bordure Thread est supprimé ou que la configuration d'usine est rétablie.
Détection des agents Border
Les identifiants doivent être enregistrés avec un ID d'agent Border. Vous devez vous assurer que votre application de configuration du routeur de bordure Thread peut déterminer les ID de l'agent de bordure de vos routeurs de bordure Thread.
Les routeurs de bordure Thread doivent utiliser mDNS pour annoncer les informations du réseau Thread, y compris le nom du réseau, l'ID de panorama étendu 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 les identifiants du réseau Google Thread pour les utiliser.
Intégrer le SDK dans 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.0.0'
Facultatif:Définissez une classe de données
BorderAgent
pour stocker les informations sur le routeur de bordure. 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 ensuite passer en revue les étapes recommandées pour ajouter et gérer les identifiants de votre choix.
Configurations des nouveaux routeurs de bordure
Avant de créer un réseau pour les nouveaux routeurs de bordure, il est important d'essayer d'utiliser les identifiants réseau préférés. Dans la mesure du possible, les appareils Thread sont connectés à un seul réseau Thread.
Un appel de 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 de clés numérique du SDK Thread, les identifiants sont renvoyés à votre application.
Demander des identifiants
Pour inviter l'utilisateur à saisir ses identifiants:
Déclarez une
ActivityLauncher
:private lateinit var preferredCredentialsLauncher: ActivityResultLauncher<IntentSenderRequest>
Gérez le résultat d'activité, renvoyé comme
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.") } }
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 les identifiants du réseau Thread préféré ne sont pas disponibles sur 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 réseau Thread soient disponibles pour d'autres fournisseurs Thread, nous devons les ajouter aux services Google Play. Avant d'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 Border et transmettre les identifiants 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 des routeurs de bordure sur le terrain
Si vous disposez actuellement de routeurs de bordure sur le terrain, vous pouvez utiliser isPreferredCredentials
pour déterminer s'ils appartiennent au réseau souhaité. Cette API ne demande pas d'autorisation à l'utilisateur et vérifie les identifiants du routeur de bordure par rapport aux informations stockées dans les services Google Play.
isPreferredCredentails
renvoie 0
pour les correspondances sans correspondance et 1
pour les correspondances comme 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
. Au cours des étapes suivantes, nous allons examiner ces options.
Identifiants 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 afin de le partager avec d'autres fournisseurs. Vous pouvez créer une instance ThreadNetworkCredential
à partir d'une liste TLV brute d'ensemble de données opérationnel Thread:
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() }
Utilisez
fromActiveOperationalDataset
pour créerThreadNetworkCredentials
. Si l'opération réussit, vous pouvez 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 la section ThreadNetworkCredentials.val threadNetworkCredentials = ThreadNetworkCredentials.fromActiveOperationalDataset(activeDataset) Log.d( "threadNetworkCredentials", threadNetworkCredentials.channel.toString() + " - " + threadNetworkCredentials.networkName)
Appelez l'API
isPreferredCredentials
et transmettezThreadNetworkCredentials
.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 Border Agent 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 souhaité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 réseau Thread par ID de panoramique étendu
Comme pour getPreferredCredentials
, vous pouvez également demander à l'utilisateur de saisir les identifiants liés à l'ID de panorama étendu du routeur de bordure. getCredentialsByExtendedPanId
renvoie un IntentSender
, et le résultat d'Activity contient un objet ThreadNetworkCredentials
lorsque l'utilisateur 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 routeur de bordure est supprimé de votre maison ou que vous avez rétabli 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}]") }
}
Ressources
Pour en savoir plus sur le SDK Thread Network, consultez la documentation de référence de l'API.