このページは Cloud Translation API によって翻訳されました。

Thread Network SDK for Android

Thread ネットワーク SDK は、デジタルキーチェーンに類似した機能を提供し、Android アプリが Thread ネットワーク認証情報を Google Play 開発者サービスと共有できるようにします。これにより、認証情報やユーザーデータを直接公開することなく、任意のスマートホームエコシステムから任意の Thread デバイスを設定できます。

ほんの数個の API 呼び出しで、次のことができます。

Google Play 開発者サービスから希望する Thread ネットワーク認証情報をリクエストします。
新しいボーダールーターを設定し、Thread ネットワーク認証情報を Google Play 開発者サービスに追加します。
フィールドボーダールーターがすでにある場合は、ボーダールーターが優先ネットワークにあるかどうかを確認し、必要に応じて移行できます。

ユーザーとデベロッパーのジャーニーがいくつか検討されます。このガイドでは、これらのほとんどの要素に加え、その他の主な機能と推奨使い方も説明します。

主な用語と API のコンセプト

始める前に、次の用語を理解しておくことをおすすめします。

Thread ネットワーク認証情報: Thread TLV のバイナリ blob。Thread ネットワーク名、ネットワークキー、および Thread デバイスが特定の Thread ネットワークに接続するために必要なその他のプロパティをエンコードします。
優先スレッドネットワーク認証情報: 自動的に選択された Thread ネットワーク認証情報。getPreferredCredentials API を使用してさまざまなベンダーのアプリと共有することができます。
Border Agent ID: Thread ボーダールーターデバイスのグローバルに一意の 16 バイトの ID。この ID は、ボーダールーターベンダーによって作成、管理されます。
Thread ボーダールーター設定アプリ: 新しい Thread ボーダールーターデバイスをセットアップし、Thread ネットワーク認証情報を Google Play 開発者サービスに追加する Android アプリです。アプリが、追加された認証情報の権威オーナーであり、認証情報にアクセスできます。

Thread ネットワーク API の多くが、非同期で完了するタスクを返します。addOnSuccessListener と addOnFailureListener を使用して、結果を受け取るコールバックを登録できます。詳細については、タスクのドキュメントをご覧ください。

認証情報の所有権とメンテナンス

Thread ネットワーク認証情報を追加するアプリは、認証情報の所有者となり、認証情報にアクセスするための完全な権限を持ちます。他のアプリによって追加された認証情報にアクセスしようとすると、PERMISSION_DENIED エラーが表示されます。

アプリのオーナーとしては、Thread ボーダールーターネットワークの更新時に、Google Play 開発者サービスに保存されている認証情報を最新の状態に保つことをおすすめします。つまり、必要に応じて認証情報を追加し、ボーダールーターの Thread ネットワーク認証情報が変更されたときに認証情報を更新し、Thread ボーダールーターを削除または出荷時設定にリセットしたときに認証情報を削除します。

Border Agent の検出

認証情報は Border Agent ID で保存する必要があります。Thread ボーダールーターセットアップアプリで Thread ボーダールーターのボーダーエージェント ID を判断できるようにする必要があります。

Thread ボーダールーターは、ネットワーク名、拡張パン ID、ボーダーエージェント ID などの Thread ネットワーク情報をアドバタイズするために mDNS を使用する必要があります。これらの属性に対応する txt 値は、それぞれ nn、xp、id です。

Google ボーダールーターネットワークの場合、Google Play 開発者サービスは、使用する Google Thread ネットワーク認証情報を自動的に取得します。

SDK を Android アプリに統合する

使用を開始するには、以下のステップを実行してください。

Google Play 開発者サービスをセットアップするの手順を行います。
Google Play 開発者サービスの依存関係を build.gradle ファイルに追加します。
```
implementation 'com.google.android.gms:play-services-threadnetwork:16.0.0'
```

省略可: ボーダールーター情報を保存する BorderAgent データクラスを定義します。このデータはこのガイド全体を通して使用します。

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

次に、優先認証情報を追加して管理するために推奨される手順について説明します。

新しいボーダールーターのセットアップ

新しいボーダールーター用に新しいネットワークを作成する前に、優先ネットワーク認証情報を使用してみることが重要です。これにより、可能であれば Thread デバイスが単一の Thread ネットワークに接続されます。

getPreferredCredentials を呼び出すとアクティビティが起動され、ユーザーにネットワークリクエストを許可するように促します。ネットワーク認証情報が Thread SDK デジタルキーチェーンに保存されている場合、その認証情報はアプリに返されます。

認証情報をリクエストする

優先認証情報をユーザーに求めるには:

ActivityLauncher を宣言します。

private lateinit var preferredCredentialsLauncher: ActivityResultLauncher<IntentSenderRequest>

Activity の結果を処理し、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.")
   }
 }

preferredCredentials を呼び出して、アクティビティを起動します。

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

新しい Thread ネットワークの作成

ユーザーの Thread ネットワークで利用可能な Thread ネットワーク認証情報がない場合は、addCredentials API を使用して Google Play 開発者サービスに認証情報を追加できます。そのためには、ThreadBorderAgent を作成し、ThreadNetworkCredentials オブジェクトも指定する必要があります。

ランダムなネットワークを作成するには、newRandomizeBuilder を呼び出します。

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

Thread ネットワーク名を指定するには:

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

認証情報を追加

他の Thread ベンダーで Thread ネットワーク認証情報を利用できるようにするには、その認証情報を Google Play 開発者サービスに追加する必要があります。新しい認証情報を追加する前に、この Thread ネットワークがどのボーダールーターデバイスに属しているかを知る必要もあります。

この例では、Border Agent ID から 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}]") }
}

フィールドボーダールーターの検出と移行

現在、フィールドボーダールーターがある場合は、isPreferredCredentials を使用して、ボーダールーターが優先ネットワークに属しているかどうかを判断できます。この API はユーザーに権限の許可を求めず、Google Play 開発者サービスに保存されているものとしてボーダールーターの認証情報をチェックします。

isPreferredCredentails は、一致しない場合は 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 ボーダールーターに Thread ネットワークがすでに設定されていて、この Thread ネットワークを Google Play 開発者サービスに追加して、他のベンダーと共有したい場合があります。未加工のスレッドのアクティブな運用データセット TLV リストから ThreadNetworkCredential インスタンスを作成できます。

運用データセットを ByteArray に変換します。例:

val activeDataset =
      "0e080000000000010000000300000f35060004001fffe0020833333333...".dsToByteArray()

fun String.dsToByteArray(): ByteArray {
  return chunked(2).map { it.toInt(16).toByte() }.toByteArray()
}

fromActiveOperationalDataset を使用して ThreadNetworkCredentials を作成します。成功すると、Thread ネットワーク名、チャネル、その他のネットワーク情報を取得できます。プロパティの完全なリストについては、ThreadNetworkCredentials をご覧ください。
```
val threadNetworkCredentials =
    ThreadNetworkCredentials.fromActiveOperationalDataset(activeDataset)
Log.d(
    "threadNetworkCredentials",
    threadNetworkCredentials.channel.toString() + " - " + threadNetworkCredentials.networkName)
```

isPreferredCredentials API を呼び出して、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}]") }

Border Agent による Thread ネットワーク認証情報

ボーダーエージェント ID でボーダールーターデバイスを一意に識別します。getCredentialsByBorderAgent API を使用するには、まず ThreadBorderAgent オブジェクトを作成し、Border エージェント ID を渡す必要があります。

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

拡張パン ID によるネットワークの認証情報のスレッド化

getPreferredCredentials と同様に、ボーダールーターの拡張パン ID からの認証情報の入力をユーザーに求めることもできます。getCredentialsByExtendedPanId は IntentSender を返します。ユーザーが承認すると、Activity の結果には 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 リファレンスをご覧ください。