El SDK de Thread Network proporciona una funcionalidad similar a la de un para que tus apps para Android compartan credenciales de redes de Thread Servicios de Google Play Esto permite que tus apps configuren cualquier dispositivo Thread en cualquier ecosistema de casa inteligente, sin exponer las credenciales ni los datos del usuario directamente.
Con solo unas pocas llamadas a la API, puedes hacer lo siguiente:
- Solicita las credenciales preferidas de la red Thread a los Servicios de Google Play.
- Configura nuevos routers de borde y agrega tus credenciales de red de Thread a Google Servicios de Play
- Si ya tienes routers de borde en campo, puedes comprobar si que los routers estén en la red preferida y, si es necesario, mígralos.
Hay varios recorridos de usuarios y desarrolladores que se deben considerar. Abordaremos la mayoría de en esta guía, junto con otras funciones clave y el uso recomendado.
Terminología y conceptos clave de las APIs
Antes de comenzar, es útil que entiendas los siguientes términos:
Credenciales de red de Thread: BLOB binario de TLV de subprocesos que codifica Thread Network Name, Network Key y otras propiedades requeridas por que un dispositivo Thread se una a una red de Thread determinada.
Preferred Thread Network Credentials: Es la red de Thread que se selecciona automáticamente. credenciales que se pueden compartir con apps de diferentes proveedores usando el API de
getPreferredCredentials
.ID del agente de frontera: Es un ID único global de 16 bytes para un router de borde de Thread. dispositivo. Los proveedores de routers fronterizos crean y administran este ID.
App de configuración del router de borde de Thread: Esta es tu app para Android que configura nuevos dispositivos router de borde de Thread y agrega las credenciales de red de Thread a Servicios de Google Play Tu app es la propietaria autorizada de las credenciales y tiene acceso a ellas.
Muchas de las APIs de Thread Network muestran un Tarea que se completa de forma asíncrona. Puedes usar addOnSuccessListener y addOnFailureListener para registrar devoluciones de llamada para recibir el resultado. Para obtener más información, consulta la Tarea en la documentación de Google Cloud.
Propiedad y mantenimiento de las credenciales
La app que agrega las credenciales de red de Thread se convierte en la propietaria de la
credenciales y tiene permisos completos para acceder a ellas. Si intentas
para acceder a las credenciales que agregaron otras apps, recibirás una PERMISSION_DENIED
.
Como propietario de la app, te recomendamos que mantengas las credenciales almacenadas en Google Los Servicios de Play se actualizan cuando se actualiza la red del router de borde de Thread. Esta significa agregar credenciales cuando sea necesario, actualizarlas cuando se establezca cuando las credenciales de red Thread del router cambian y se quitan Se quitó el router de borde Thread o se restableció su configuración de fábrica.
Descubrimiento del agente de frontera
Las credenciales se deben guardar con un ID de agente de frontera. Deberás asegurarte de que tu app de configuración del router de borde de Thread puede determinar los IDs del agente de frontera. de tus routers de borde Thread.
Los routers de borde de Thread deben usar mDNS para anunciar la información de red de Thread.
incluidos el nombre de la red, el ID de pano extendido y el ID del agente de frontera. El
los valores de txt
correspondientes para estos atributos son nn
, xp
y id
,
respectivamente.
Para redes con routers de borde de Google, los Servicios de Google Play obtiene las credenciales de red de Thread de Google para usarlas.
Integra el SDK en tu app para Android
Para comenzar, completa los siguientes pasos:
Sigue las instrucciones que se indican en Configura los Servicios de Google Play.
Agrega la dependencia de los Servicios de Google Play a tu archivo
build.gradle
:implementation 'com.google.android.gms:play-services-threadnetwork:16.0.0'
Opcional: Define una clase de datos
BorderAgent
para almacenar el router de borde información. Usaremos estos datos a lo largo de esta guía:data class BorderAgentInfo( // Network Name max 16 len val networkName: String = "", val extPanId: ByteArray = ByteArray(16), val borderAgentId: ByteArray = ByteArray(16), ... )
A continuación, revisaremos los pasos recomendados para agregar y administrar dominios credenciales.
Nuevas configuraciones del router de borde
Antes de crear una red nueva para routers de borde nuevos, es importante intenta usar primero las credenciales de red preferidas. Esto garantiza que Los dispositivos Thread se conectan a una sola red de Thread cuando es posible.
Se inicia una llamada a getPreferredCredentials
una actividad que les pide a los usuarios que permitan la solicitud de red. Si la red
credenciales se almacenaron en el llavero digital del SDK de Thread, las credenciales
se devolverán a tu app.
Credenciales de la solicitud
Para solicitarle al usuario las credenciales preferidas, sigue estos pasos:
Declara un
ActivityLauncher
:private lateinit var preferredCredentialsLauncher: ActivityResultLauncher<IntentSenderRequest>
Controla el resultado de Activity, que se muestra como
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.") } }
Llama a
preferredCredentials
y, luego, inicia la actividad: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}]") } }
Crea una red de Thread nueva
Si no hay credenciales de red de Thread preferidas disponibles en la
Thread, puedes usar la API de addCredentials
para agregar credenciales a
Servicios de Google Play. Para ello, deberás crear un ThreadBorderAgent
,
y un objeto ThreadNetworkCredentials
.
Para crear una red aleatoria, llama a newRandomizeBuilder
:
val threadCredentials = ThreadNetworkCredentials.newRandomizedBuilder().build()
Sigue estos pasos para especificar el nombre de la red de Thread:
val threadCredentials = ThreadNetworkCredentials.newRandomizedBuilder()
.setNetworkName("ThreadNetworkSDK")
.build()
Agregar credenciales
Para que tus credenciales de red de Thread estén disponibles para otros proveedores de esta plataforma, sigue estos pasos: necesitamos agregarlas a los Servicios de Google Play. Antes de que podamos agregar nuestro nuevo del Thread, también necesitamos saber en qué dispositivo pertenece la red.
En este ejemplo, crearemos un ThreadBorderAgent
a partir de un ID de agente de frontera.
pasa las nuevas credenciales de red de Thread que acabas de crear:
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}]") }
}
Detecta y migra routers de borde en campo
Si actualmente cuentas con routers de borde en campo, puedes usar
isPreferredCredentials
para determinar si pertenecen los routers de borde
a la red preferida. Esta API no solicita
al usuario para obtener permiso y verifica las credenciales del router de borde con el contenido almacenado
en los Servicios de Google Play.
isPreferredCredentails
muestra 0
para los campos no coincidentes y 1
para
coincide, como un tipo de datos Int
. Puedes usar IsPreferredCredentialsResult
para consultar tus resultados.
public @interface IsPreferredCredentialsResult {
int PREFERRED_CREDENTIALS_NOT_FOUND = -1;
int PREFERRED_CREDENTIALS_NOT_MATCHED = 0;
int PREFERRED_CREDENTIALS_MATCHED = 1;
}
Para usar isPreferredCredentials
, deberás crear un
ThreadNetworkCredentials
primero. Hay varias formas de crear una instancia de ThreadNetworkCredentials
. En los siguientes pasos, revisaremos estas opciones.
Credenciales de red de subprocesos por conjunto de datos operativo
Hay casos en los que tu router de borde Thread ya está configurado con un
red de Thread y quieres agregarla a los Servicios de Google Play
y compartirlo con otros proveedores. Puedes crear un ThreadNetworkCredential
instancia de una lista de TLV de conjuntos de datos operativos activos de subprocesos sin procesar:
Convierte el conjunto de datos operativo en una
ByteArray
. Por ejemplo:val activeDataset = "0e080000000000010000000300000f35060004001fffe0020833333333...".dsToByteArray()
fun String.dsToByteArray(): ByteArray { return chunked(2).map { it.toInt(16).toByte() }.toByteArray() }
Usa
fromActiveOperationalDataset
para crear elThreadNetworkCredentials
. Si se realiza de forma correcta, podrás obtener el nombre, el canal y el nombre de la red de Thread otra información de red. Para obtener una lista completa de las propiedades, consulta ThreadNetworkCredentials.val threadNetworkCredentials = ThreadNetworkCredentials.fromActiveOperationalDataset(activeDataset) Log.d( "threadNetworkCredentials", threadNetworkCredentials.channel.toString() + " - " + threadNetworkCredentials.networkName)
Llama a la API de
isPreferredCredentials
y pasa elThreadNetworkCredentials
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}]") }
Credenciales de red de Thread por agente de frontera
El ID de agente de frontera identifica de forma exclusiva un dispositivo router de borde. Para usar
la API de getCredentialsByBorderAgent
, primero deberás crear una
ThreadBorderAgent
y pasa el ID del agente de frontera.
Una vez que hayas creado el objeto ThreadBorderAgent
, llama
getCredentialsByBorderAgent
Si se guardaron las credenciales, verifica que se cumplan las siguientes condiciones:
si así lo prefieren.
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}]") }
}
Credenciales de red de Thread por ID de barrido extendido
Al igual que con getPreferredCredentials
, también puedes solicitarle al usuario
credenciales de un ID de barrido extendido del router de borde. El
getCredentialsByExtendedPanId
muestra un IntentSender
, y el objeto Activity
El resultado contiene un objeto ThreadNetworkCredentials
cuando el usuario lo aprueba.
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}]") }
}
Quitar credenciales
Cuando quitas el router de borde de tu casa o restableces la configuración de fábrica, debes quitar su red Thread de los Servicios de 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}]") }
}
Recursos
Para obtener más información sobre el SDK de Thread Network, consulta el Referencia de la API.