Le SDK Thread Network offre des fonctionnalités semblables à celles qui permet à vos applications Android de partager les identifiants du réseau Thread avec services Google Play. Cela permet à vos applications de configurer n'importe quel appareil Thread dans n'importe quel écosystème de maison connectée, sans exposer directement les identifiants et les données utilisateur.
Quelques appels d'API suffisent pour:
- Demandez les identifiants de réseau Thread préférés aux services Google Play.
- Configurer de nouveaux routeurs de bordure et ajouter vos identifiants de réseau Thread à Google Services Play.
- Si vous disposez déjà de routeurs de bordure sur le terrain, les routeurs se trouvent dans le réseau préféré et les migrez, si nécessaire.
Il existe plusieurs parcours utilisateur et développeur à prendre en compte. Nous aborderons la plupart des dans ce guide, ainsi que d'autres fonctionnalités clés et l'utilisation recommandée.
Terminologie et concepts clés des API
Avant de commencer, il est important de comprendre les termes suivants:
Identifiants réseau Thread:blob binaire des TLV Thread qui encodent. Nom du réseau du thread, clé réseau et autres propriétés requises par un appareil Thread à rejoindre un réseau Thread donné.
Preferred Thread Network Credentials (Identifiants réseau Thread préférés) : réseau Thread sélectionné automatiquement d'identifiants qui peuvent être partagés avec les applications de différents fournisseurs à l'aide du
getPreferredCredentials
.ID d'agent de bordure:ID unique de 16 octets pour un routeur de bordure Thread appareil. Cet identifiant est créé et géré par les fournisseurs de routeurs de bordure.
Application de configuration du routeur de bordure Thread:il s'agit de l'application Android qui configure de nouveaux routeurs de bordure Thread et ajoute les identifiants du réseau Thread au services Google Play. Votre application est le propriétaire faisant autorité identifiants et y a accès.
De nombreuses API Thread Network renvoient un Tâche qui s'effectue 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 les Tâche dans la documentation Google Cloud.
Propriété et maintenance des identifiants
L'application qui ajoute les identifiants du réseau Thread devient propriétaire du
des identifiants et dispose de toutes les autorisations d'accès à ceux-ci. Si vous essayez
pour accéder aux identifiants ajoutés par d'autres applications, vous recevez une PERMISSION_DENIED
.
En tant que propriétaire de l'application, nous vous recommandons de conserver les identifiants stockés dans Google Les services Play sont à jour lorsque le réseau du routeur de bordure Thread est mis à jour. Ce consiste à ajouter des identifiants si nécessaire, à les mettre à jour lorsque la bordure les identifiants réseau Thread du routeur changent et suppriment des identifiants lorsque le Le routeur de bordure Thread a été supprimé ou sa configuration d'usine est rétablie.
Détection de l'agent de bordure
Les identifiants doivent être enregistrés avec un ID d'agent frontal. Vous devrez vous assurer que l'application de configuration du routeur de bordure Thread peut déterminer les ID d'agents de bordure des routeurs de bordure Thread.
Les routeurs de bordure Thread doivent utiliser un mDNS pour annoncer les informations du réseau Thread.
y compris le nom du réseau, l'ID de panoramique étendu et l'ID de l'agent de frontière. La
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 sont automatiquement obtient les identifiants du réseau Google Thread à utiliser.
Intégrer le SDK à votre application Android
Pour commencer, procédez comme suit:
Suivez les instructions fournies sur la page Configurez 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 le routeur de bordure des informations. 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 identifiants de connexion.
Nouvelles configurations de routeur de bordure
Avant de créer un nouveau réseau pour de nouveaux routeurs de bordure, il est important essayez d'utiliser d'abord les identifiants réseau préférés. Cela garantit que Dans la mesure du possible, les appareils Thread sont connectés à un seul réseau Thread.
Un appel à getPreferredCredentials
est lancé
une activité, invitant les utilisateurs
à autoriser la requête réseau. Si le réseau
ont été stockées dans le trousseau numérique du SDK Thread, les identifiants
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é 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.") } }
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 réseau Thread préféré n'est disponible dans le
réseau Thread, vous pouvez utiliser l'API addCredentials
pour ajouter des identifiants
services Google Play. Pour ce faire, vous devez créer un ThreadBorderAgent
,
ainsi qu'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:
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 notre nouveau nous devons également savoir sur quel routeur de bordure ce Thread auquel appartient le réseau.
Dans cet exemple, nous allons créer un ThreadBorderAgent
à partir d'un ID d'agent de service frontière, puis
transmettez 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 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 n'invite pas
demande l'autorisation de l'utilisateur, et compare les identifiants du routeur de bordure aux données stockées
dans les services Google Play.
isPreferredCredentails
renvoie 0
si aucune correspondance n'est trouvée et 1
pour
correspondant, 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 créer un
ThreadNetworkCredentials
. Il existe plusieurs façons d'instancier ThreadNetworkCredentials
. Dans les étapes suivantes, nous allons passer en revue 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é
Réseau Thread, et vous souhaitez l'ajouter aux services Google Play
pour le partager avec
d'autres fournisseurs. Vous pouvez créer un ThreadNetworkCredential
à partir d'une liste brute des TLV d'un ensemble de données opérationnel actif 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éer leThreadNetworkCredentials
. Lorsque l'opération réussit, vous pouvez obtenir le nom, le canal et la valeur d'autres informations sur le réseau. Pour obtenir la liste complète des établissements, consultez ThreadNetworkCredentials.val threadNetworkCredentials = ThreadNetworkCredentials.fromActiveOperationalDataset(activeDataset) Log.d( "threadNetworkCredentials", threadNetworkCredentials.channel.toString() + " - " + threadNetworkCredentials.networkName)
Appelez l'API
isPreferredCredentials
et transmettez laThreadNetworkCredentials
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 réseau Thread par agent de bordure
Cet ID identifie de manière unique un routeur de bordure. Pour utiliser
l'API getCredentialsByBorderAgent
, vous devez d'abord créer une
ThreadBorderAgent
et transmettez l'ID de l'agent frontal.
Une fois l'objet ThreadBorderAgent
créé, appelez
getCredentialsByBorderAgent
Si les identifiants ont été enregistrés, vérifiez
si elles sont de préférence.
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 de threads par ID de panoramique étendu
Comme pour getPreferredCredentials
, vous pouvez également inviter l'utilisateur à saisir
à partir de l'ID de panoramique étendu d'un routeur de bordure. La
getCredentialsByExtendedPanId
renvoie un IntentSender
, et l'activité
Le résultat contient un objet ThreadNetworkCredentials
lorsque l'utilisateur les 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 retiré de votre maison ou rétablissez la configuration d'usine, 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 réseau Thread, consultez Documentation de référence de l'API