Thread Network SDK для Android

Thread Network SDK предоставляет функции, похожие на цифровой брелок, позволяя приложениям Android передавать учетные данные сети Thread сервисам Google Play. Это позволяет вашим приложениям настраивать любое устройство Thread из любой экосистемы умного дома, не раскрывая напрямую учетные данные и пользовательские данные.

С помощью всего нескольких вызовов API вы можете:

  1. Запросите у сервисов Google Play учетные данные предпочтительной сети Thread.
  2. Настройте новые устройства (Thread Border Router (TBR)) и добавьте учетные данные сети Thread в сервисы Google Play.
  3. Если у вас уже есть TBR, вы можете проверить, находятся ли TBRони в предпочтительной сети, и при необходимости перенести их.

Существует несколько путей пользователей и разработчиков, которые следует учитывать. В этом руководстве мы рассмотрим большинство из них, а также другие ключевые функции и рекомендации по использованию.

Основные термины и понятия API

Прежде чем начать, ознакомьтесь со следующими терминами:

  • Учетные данные сети Thread. Двоичный большой объект TLV-структур Thread, который кодирует название сети Thread, ключ сети и другие свойства, необходимые устройству Thread для подключения к определенной сети Thread.

  • Предпочитаемые учетные данные сети Thread. Автоматически выбранные учетные данные сети Thread, которыми можно делиться с приложениями разных поставщиков с помощью getPreferredCredentials API.

  • Идентификатор пограничного агента. 16-байтовый глобально уникальный идентификатор устройства. TBR Этот идентификатор создается и управляется поставщиками border router.

  • Приложение для настройки TBR. Это приложение для Android, которое настраивает новые устройства TBR и добавляет учетные данные сети Thread в сервисы Google Play. Ваше приложение является уполномоченным владельцем добавленных учетных данных и имеет к ним доступ.

Многие API Thread Network возвращают Task, который выполняется асинхронно. Чтобы зарегистрировать обратные вызовы для получения результата, можно использовать addOnSuccessListener и addOnFailureListener. Подробную информацию можно найти в документации по задачам.

Владение учетными данными и их обслуживание

Приложение, которое добавляет учетные данные сети Thread, становится их владельцем и получает полный доступ к ним. Если вы попытаетесь получить доступ к учетным данным, добавленным другими приложениями, то получите ошибку PERMISSION_DENIED.

Как владельцу приложения, вам рекомендуется обновлять учетные данные, хранящиеся в хранилище учетных данных сервисов Google Play, при обновлении сети TBR. Это означает, что вы должны добавлять учетные данные, когда это необходимо, обновлять их при изменении учетных данных сети Thread устройства border router и удалять их, когда устройство TBR удаляется или сбрасывается до заводских настроек.

Обнаружение агентов Border

Учетные данные должны быть сохранены с идентификатором пограничного агента. Убедитесь, что приложение для настройки TBR может определить идентификаторы пограничных агентов ваших устройств TBR.

TBR должны использовать mDNS для передачи информации о сети Thread, включая название сети, расширенный идентификатор PAN и идентификатор пограничного агента. Соответствующие значения txt для этих атрибутов – nn, xp и id.

Для сетей с Google Thread Border Router (gTBR) сервисы Google Play автоматически получают учетные данные сети Google Thread.

Интегрируйте SDK в приложение для Android

Чтобы начать работу, выполните следующие действия:

  1. Следуйте инструкциям в статье Как настроить сервисы Google Play.

  2. Добавьте зависимость сервисов Google Play в файл build.gradle:

    implementation 'com.google.android.gms:play-services-threadnetwork:16.2.1'
    
  3. Необязательно. Определите класс данных BorderAgent для хранения информации TBR. Мы будем использовать эти данные в этом руководстве:

    data class BorderAgentInfo(
      // Network Name max 16 len
      val networkName: String = "",
      val extPanId: ByteArray = ByteArray(16),
      val borderAgentId: ByteArray = ByteArray(16),
      ...
    )
    

Далее мы расскажем, как добавлять предпочтительные учетные данные и управлять ими.

Новые настройки пограничного маршрутизатора Thread

Прежде чем создавать новую сеть для новых пограничных маршрутизаторов, попробуйте использовать учетные данные предпочтительной сети. Это позволяет подключать устройства Thread к одной сети Thread, когда это возможно.

Вызов getPreferredCredentials запускает Activity, предлагающее пользователям разрешить сетевой запрос. Если учетные данные сети были сохранены в цифровой связке ключей Thread SDK, они будут возвращены в ваше приложение.

Запрос учетных данных

Чтобы предложить пользователю выбрать учетные данные:

  1. Объявите ActivityLauncher:

    private lateinit var preferredCredentialsLauncher: ActivityResultLauncher<IntentSenderRequest>
    
  2. Обработайте результат действия, возвращенный как 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.")
       }
     }
    
  3. Если вы настраиваете новый TBR, рекомендуется вызвать preferredCredentials и запустить действие. Этот вызов гарантирует, что новый TBR будет использовать те же учетные данные, которые уже сохранены в телефоне как предпочтительные, что способствует конвергенции различных TBR в одну сеть.

    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}]") }
    }
    
  4. Если вам нужно настроить устройства, не являющиеся пограничными маршрутизаторами Thread, например новое конечное устройство Matter-over-Thread, рекомендуем использовать API allActiveCredentials для получения учетных данных. Этот вызов выполнит поиск TBR в локальной сети и не вернет учетные данные, которые недоступны через существующий локальный TBR.

    // 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) {
        getAllActiveCredentialsLauncher.launch(
          IntentSenderRequest.Builder(intentSender).build()
        )
      } else {
        // No active network credentials found!
      }
    }
    // Handles the failure
    .addOnFailureListener { e: Exception ->
      // Handle the exception
    }
    

Как создать сеть Thread

Если в сети Thread пользователя нет ни предпочтительных, ни активных учетных данных, вы можете добавить их в сервисы Google Play с помощью addCredentials API. Для этого вам нужно создать объект ThreadBorderAgent и предоставить объект ThreadNetworkCredentials.

Чтобы создать случайную сеть, вызовите newRandomizeBuilder:

val threadCredentials = ThreadNetworkCredentials.newRandomizedBuilder().build()

Чтобы указать название сети Thread:

val threadCredentials = ThreadNetworkCredentials.newRandomizedBuilder()
  .setNetworkName("ThreadNetworkSDK")
  .build()

Добавление учетных данных

Чтобы учетные данные вашей сети Thread были доступны другим поставщикам Thread, их нужно добавить в сервисы Google Play. Прежде чем добавить новые учетные данные, нам также нужно знать, какому устройству TBR принадлежит эта сеть Thread.

В этом примере мы создадим ThreadBorderAgent из идентификатора пограничного агента и передадим новые учетные данные сети Thread, которые вы только что создали:

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

Обнаружение и перенос border router в полевых условиях

Если у вас есть border router, вы можете использовать isPreferredCredentials, чтобы определить, принадлежат ли ваши border router к предпочтительной сети. Этот API не запрашивает у пользователя разрешение и сравнивает учетные данные border router с теми, что хранятся в сервисах Google Play.

Функция isPreferredCredentials возвращает 0, если совпадений нет, и 1, если совпадения есть. Тип данных – Int. Проверить результаты можно с помощью IsPreferredCredentialsResult.

public @interface IsPreferredCredentialsResult {
    int PREFERRED_CREDENTIALS_NOT_FOUND = -1;
    int PREFERRED_CREDENTIALS_NOT_MATCHED = 0;
    int PREFERRED_CREDENTIALS_MATCHED = 1;
}

Чтобы использовать isPreferredCredentials, сначала нужно создать объект ThreadNetworkCredentials. Создать экземпляр ThreadNetworkCredentials можно несколькими способами. Ниже мы расскажем о них подробнее.

Учетные данные сети Thread по набору операционных данных

В некоторых случаях в вашем приложении TBR уже настроена сеть Thread и вы хотите добавить ее в сервисы Google Play, чтобы поделиться ею с другими поставщиками. Вы можете создать экземпляр ThreadNetworkCredential из необработанного списка TLV активного операционного набора данных Thread:

  1. Преобразуйте набор операционных данных в ByteArray. Пример:

    val activeDataset =
          "0e080000000000010000000300000f35060004001fffe0020833333333...".dsToByteArray()
    
    fun String.dsToByteArray(): ByteArray {
      return chunked(2).map { it.toInt(16).toByte() }.toByteArray()
    }
    
  2. Используйте fromActiveOperationalDataset, чтобы создать ThreadNetworkCredentials. Если все пройдет успешно, вы сможете получить название сети Thread, канал и другую информацию о сети. Полный список свойств приведен в разделе ThreadNetworkCredentials.

    val threadNetworkCredentials =
        ThreadNetworkCredentials.fromActiveOperationalDataset(activeDataset)
    Log.d(
        "threadNetworkCredentials",
        threadNetworkCredentials.channel.toString() + " - " + threadNetworkCredentials.networkName)
    
  3. Вызовите API isPreferredCredentials и передайте 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}]") }
    

Учетные данные сети Thread от пограничного агента

Идентификатор пограничного агента уникален для каждого устройства TBR. Чтобы использовать API getCredentialsByBorderAgent, сначала создайте объект ThreadBorderAgent и передайте идентификатор пограничного агента.

После создания объекта ThreadBorderAgent вызовите метод getCredentialsByBorderAgent. Если учетные данные сохранены, проверьте, являются ли они предпочтительными.

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

Учетные данные сети Thread по расширенному идентификатору PAN

Как и в случае с getPreferredCredentials, вы также можете запросить у пользователя учетные данные из расширенного идентификатора PAN TBR. getCredentialsByExtendedPanId возвращает IntentSender, а результат действия содержит объект ThreadNetworkCredentials, если пользователь дает согласие.

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

Удалить учетные данные

Если вы удалили устройство border router из дома или сбросили его настройки, вам нужно удалить его сеть Thread из сервисов 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}]") }
}

Ресурсы

Дополнительную информацию о Thread Network SDK можно найти в справочнике по API.