Se usó la API de Cloud Translation para traducir esta página.

SDK de Thread Network para Android

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

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.