Google utiliza tecnología de IA para traducir contenido a tu idioma preferido. Las traducciones realizadas con IA pueden contener errores.

SDK de Thread Network para Android

El SDK de Thread Network proporciona una funcionalidad similar a un llavero digital, lo que permite que tus apps para Android compartan credenciales de red de Thread con los Servicios de Google Play. Esto permite que tus apps configuren cualquier dispositivo Thread desde cualquier ecosistema de casa inteligente, sin exponer directamente las credenciales ni los datos del usuario.

Con solo unas pocas llamadas a la API, puedes hacer lo siguiente:

Solicitar credenciales de red de Thread preferidas de los Servicios de Google Play
Configurar nuevos Thread Border Router (TBR) y agregar las credenciales de red de Thread a los Servicios de Google Play
Si ya tienes TBR en el campo, puedes verificar si tus TBR están en la red preferida y migrarlos, si es necesario.

Hay varios recorridos del usuario y del desarrollador que debes tener en cuenta. En esta guía, abordaremos la mayoría de ellos, junto con otras funciones clave y el uso recomendado.

Terminología clave y conceptos de la API

Antes de comenzar, es útil comprender los siguientes términos:

Credenciales de red de Thread: Es un objeto binario de TLV de Thread que codifica el nombre de la red de Thread, la clave de red y otras propiedades que requiere un dispositivo Thread para unirse a una red de Thread determinada.
Credenciales de red de Thread preferidas: Son las credenciales de red de Thread seleccionadas automáticamente que se pueden compartir con apps de diferentes proveedores mediante la API de getPreferredCredentials.
ID del agente de borde: Es un ID único de 16 bytes a nivel global para un TBR dispositivo. Los proveedores de border router crean y administran este ID.
TBR app de configuración: Es tu app para Android que configura dispositivos TBR nuevos y agrega las credenciales de red de Thread a los Servicios de Google Play. Tu app es el propietario autorizado de las credenciales agregadas y tiene acceso a ellas.

Muchas de las APIs de Thread Network muestran una 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 documentación de Task.

Propiedad y mantenimiento de las credenciales

La app que agrega las credenciales de red de Thread se convierte en el propietario de las credenciales y tiene permisos completos para acceder a ellas. Si intentas acceder a las credenciales agregadas por otras apps, recibirás un error PERMISSION_DENIED.

Como propietario de la app, te recomendamos que mantengas actualizadas las credenciales almacenadas en los Servicios de Google Play cuando se actualice la red TBR. Esto significa agregar credenciales cuando sea necesario, actualizarlas cuando cambien las credenciales de red de Thread de border router y quitarlas cuando se quite o se restablezca la configuración de fábrica de TBR.

Descubrimiento del agente de borde

Las credenciales deben guardarse con un ID del agente de borde. Deberás asegurarte de que tu TBR app de configuración pueda determinar los IDs del agente de borde de tus TBRs.

Los TBR deben usar mDNS para anunciar la información de la red de Thread, incluidos el nombre de la red, el ID de PAN extendido y el ID del agente de borde. Los valores txt correspondientes para estos atributos son nn, xp y id, respectivamente.

En el caso de las redes con Google Thread Border Router (gTBR), los Servicios de Google Play obtienen automáticamente las credenciales de red de Thread de Google para su uso.

Integra el SDK en tu app para Android

Para comenzar, completa los siguientes pasos:

Sigue las instrucciones que se proporcionan en Cómo configurar 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.2.1'
```

Opcional: Define una clase de datos BorderAgent para almacenar TBR información. Usaremos estos datos en toda 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 credenciales preferidas.

Configuraciones nuevas del router de borde Thread

Antes de crear una red nueva para los routers de borde nuevos, es importante que primero intentes usar las credenciales de red preferidas. Esto garantiza que los dispositivos Thread estén conectados a una sola red de Thread cuando sea posible.

Una llamada a getPreferredCredentials inicia una actividad que les solicita a los usuarios que permitan la solicitud de red. Si las credenciales de red se almacenaron en el llavero digital del SDK de Thread, se mostrarán en tu app.

Solicita credenciales

Para solicitarle al usuario las credenciales preferidas, haz lo siguiente:

Declara un ActivityLauncher:

private lateinit var preferredCredentialsLauncher: ActivityResultLauncher<IntentSenderRequest>

Controla el resultado de la actividad, 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.")
   }
 }

Si vas a configurar un TBR nuevo, te recomendamos que llames a preferredCredentials y que inicies la actividad. Esta llamada garantizará que tu nuevo TBR use las mismas credenciales ya almacenadas como preferidas en el teléfono, lo que promoverá la convergencia de diferentes TBR a la misma red.

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 tu caso de uso se relaciona con la configuración de dispositivos que no son TBR, como un nuevo dispositivo final Matter-over-Thread, te recomendamos que uses la API de allActiveCredentials para recuperar las credenciales. Esta llamada buscará los TBR que se encuentren en la red local y, por lo tanto, no mostrará las credenciales que no estén disponibles en un TBR existente de forma local.

// 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) {