Thread Network SDK 提供類似數位鑰匙圈的功能,可讓 Android 應用程式與 Google Play 服務共用 Thread 網路憑證。這可讓應用程式設定任何智慧住宅生態系統的任何執行緒裝置,而不必直接提供憑證和使用者資料。
只需呼叫幾項 API 呼叫,即可:
- 向 Google Play 服務要求偏好的 Thread 網路憑證。
- 設定新的邊界路由器,並將 Thread 網路憑證新增至 Google Play 服務。
- 如果您已經有欄位邊界路由器,請檢查邊界路由器是否位於偏好的網路,並視需要進行遷移。
需考量許多使用者和開發人員的歷程。本指南將涵蓋大部分的內容,以及其他重要功能和建議的使用方式。
重要詞彙與 API 概念
開始之前,建議您先瞭解下列條款:
Thread 網路憑證:執行緒 TLV 的二進位 blob,能將 Thread 網路名稱、網路金鑰及其他 Thread 裝置要求的其他屬性編碼,以便加入指定 Thread 網路。
偏好的執行緒網路憑證:自動選取的 Thread 網路憑證,可能會透過
getPreferredCredentials
API 分享給不同供應商的應用程式。邊界代理程式 ID:Thread 邊界路由器裝置的 16 位元組全域 ID。這個 ID 是由邊界路由器廠商建立及管理。
Thread 邊界路由器設定應用程式:這個 Android 應用程式會設定新的 Thread 邊界路由器裝置,並將 Thread 網路憑證新增至 Google Play 服務。您的應用程式是新增憑證的權威擁有者,因此具有這些憑證的存取權。
許多 Thread 網路 API 都會傳回以非同步方式完成的工作。您可以使用 addOnSuccessListener 和 addOnFailureListener 註冊以接收結果的回呼。詳情請參閱工作說明文件。
憑證擁有權與維護
新增 Thread 網路憑證的應用程式會成為憑證的擁有者,並擁有存取憑證的完整權限。如果您嘗試存取其他應用程式新增的憑證,就會收到 PERMISSION_DENIED
錯誤。
我們建議執行緒擁有者更新 Thread 邊界路由器網路時,將憑證儲存至 Google Play 服務。這表示在必要時新增憑證、在邊界路由器的 Thread 網路憑證變更時更新憑證,以及在移除執行緒邊界路由器或恢復原廠設定時移除憑證。
使用邊界代理程式探索功能
憑證必須使用邊界代理程式 ID 儲存。您必須確保 Thread 邊界路由器設定應用程式能夠決定 Thread 邊界路由器的邊界代理程式 ID。
Thread 邊界路由器必須使用 mDNS 通告執行緒網路資訊,包括網路名稱、擴充平移 ID 和邊界代理程式 ID。這些屬性的對應 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 網路憑證新增至 Google Play 服務,才能讓其他 Thread 供應商使用。在您新增憑證之前,還需要知道 Thread 網路所屬的邊界路由器裝置。
在這個範例中,我們會從邊界代理程式 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}]") }
邊界 API 代理程式的執行緒網路憑證
邊界代理程式 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}]") }
}
透過 Extended Pan ID 的執行緒網路憑證
與 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}]") }
}
移除憑證
從住家或恢復原廠設定移除 Border 路由器裝置後,你必須從 Google Play 服務中移除其 Thread 網路。
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 網路 SDK,請參閱 API 參考資料。