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

Android 向け Thread ネットワーク SDK

Thread Network SDK は、デジタルインターネットにキーチェーンを使用すると、Android アプリが Google Play 開発者サービス。これにより、アプリは任意の Thread デバイスを認証情報やユーザーデータを直接公開することなく、あらゆるスマートホームエコシステムで利用できます。

わずか数回の API 呼び出しで、次のことができます。

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

考慮すべきユーザーと開発者のジャーニーはいくつかあります。ここでは、Terraform ワークフローの主な機能および推奨される使用方法とともに、このガイドでその内容を確認します。

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

始める前に、以下の用語を理解しておくと役に立ちます。

Thread ネットワーク認証情報: エンコードするスレッド TLV のバイナリ blob スレッドネットワーク名、ネットワークキー、および Thread デバイス: 特定の Thread ネットワークに接続します。
Preferred Thread Network Credentials: 自動的に選択された Thread ネットワーク使用してさまざまなベンダーのアプリと共有できる getPreferredCredentials API。
Border Agent ID（ボーダーエージェント ID）: Thread ボーダールーターのグローバルに一意の 16 バイトの ID ダウンロードしますこの ID はボーダールーターベンダーによって作成、管理されます。
Thread Border Router Setup アプリ: 新しい Thread ボーダールーターデバイスに接続し、Thread ネットワーク認証情報を Google Play 開発者サービス。お客様のアプリは、追加されたアプリの正式な所有者です認証情報にアクセスしてアクセスできます。

Thread Network API の多くは、タスク非同期で完了します次を使用: addOnSuccessListener および addOnFailureListener 結果を受け取るコールバックを登録します。詳しくは、タスクご覧ください

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

Thread のネットワーク認証情報を追加したアプリが、その認証情報にアクセスするための完全な権限があります。試した場合他のアプリによって追加された認証情報にアクセスするには、PERMISSION_DENIED を受け取りますエラーが発生します。

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

ボーダーエージェントの探索

認証情報は Border Agent ID と一緒に保存する必要があります。これらを Thread Border Router Setup アプリで Border Agent ID を判別できる直接接続できます

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

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

Android アプリに SDK を統合する

開始するには、次の手順を完了します。

次のリンクの手順に沿って設定してください。 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>

ThreadNetworkCredentials として返される Activity の結果を処理します。

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 開発者サービスに追加する必要があります。新しい P-MAX キャンペーンをどのボーダールーターデバイスに対してこの 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 開発者サービスに追加したい他のベンダーと共有することもできます。ThreadNetworkCredentialを作成することで未加工のスレッドのアクティブオペレーショナルデータセットの TLV リストから抽出されます。

運用データセットを 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 は、ボーダールーターデバイスを一意に識別する ID です。用途 getCredentialsByBorderAgent API を作成するには、まず、 ThreadBorderAgent オブジェクトを作成し、ボーダーエージェント 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 別の Thread ネットワーク認証情報

getPreferredCredentials と同様に、ユーザーに次の入力を促すこともできます。認証情報をボーダールーターの Extended Pan 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}]") }
}

認証情報を削除

ボーダールーターデバイスを家から削除したり、出荷時の設定にリセットしたりすると、 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 リファレンス。