适用于 Android 的 Thread 网络 SDK

Thread 网络 SDK 提供类似于数字钥匙串的功能，可让 Android 应用与 Google Play 服务共享 Thread 网络凭据。这样一来，您的应用就可以设置任何智能家居生态系统中的任何 Thread 设备，而无需直接公开凭据和用户数据。

只需进行几次 API 调用，您就可以：

  1. 从 Google Play 服务请求首选 Thread 网络凭据。
  2. 设置新的 Thread Border Router (TBR) 并将 Thread 网络凭据添加到 Google Play 服务。
  3. 如果您已有在野外部署的 TBR，可以检查这些 TBR 是否位于首选网络中，并根据需要迁移它们。

需要考虑多种用户和开发者历程。本指南将介绍其中大部分功能，以及其他关键功能和建议的用法。

关键术语和 API 概念

在开始之前，请先了解以下术语：

  • Thread 网络凭证：Thread TLV 的二进制 blob，用于对 Thread 网络名称、网络密钥以及 Thread 设备加入给定 Thread 网络所需的其他属性进行编码。

  • 首选 Thread 网络凭据：使用 getPreferredCredentials API 可与不同供应商的应用共享的自动选择的 Thread 网络凭据。

  • 边框代理 ID：TBR 设备的 16 字节全局唯一 ID。此 ID 由 border router 供应商创建和管理。

  • TBR 设置应用：这是您的 Android 应用，用于设置新的 TBR 设备并将 Thread 网络凭据添加到 Google Play 服务。您的应用是所添加凭据的权威所有者，并且有权访问这些凭据。

许多 Thread 网络 API 都会返回一个异步完成的 Task。您可以使用 addOnSuccessListener 和 addOnFailureListener 注册用于接收结果的回调。如需了解详情，请参阅任务文档。

凭据所有权和维护

添加 Thread 网络凭据的应用会成为该凭据的所有者，并拥有对该凭据的完整访问权限。如果您尝试访问其他应用添加的凭据，则会收到 PERMISSION_DENIED 错误。

作为应用所有者，建议您在 TBR 网络更新时，及时更新存储在 Google Play 服务中的凭据。这意味着在需要时添加凭据，在 border router 的 Thread 网络凭据发生更改时更新凭据，以及在移除 TBR 或将其恢复出厂设置时移除凭据。

边框代理发现

凭据必须与边框代理 ID 一起保存。您需要确保TBR设置应用能够确定TBR的 Border 代理 ID。

TBR必须使用 mDNS 来通告 Thread 网络信息，包括网络名称、扩展 PAN ID 和边框代理 ID。这些属性对应的 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 形式返回的 Activity 结果：

    preferredCredentialsLauncher =
 registerForActivityResult(
   StartIntentSenderForResult