Ta strona została przetłumaczona przez Cloud Translation API.

Thread Network SDK na Androida

Pakiet Thread Network SDK udostępnia funkcje podobne do usług cyfrowych, pęku kluczy, który umożliwia aplikacjom na Androida udostępnianie danych logowania do sieci Thread, Usługi Google Play. Dzięki temu Twoje aplikacje będą mogły skonfigurować dowolne urządzenie Thread do dowolnego ekosystemu inteligentnego domu bez ujawniania bezpośrednio danych logowania i danych użytkownika.

Za pomocą zaledwie kilku wywołań interfejsu API możesz:

Wysyłanie do Usług Google Play preferowanych danych logowania do sieci Thread.
Skonfiguruj nowe routery graniczne i dodaj dane logowania do sieci Thread do Google Usługi Google Play.
Jeśli masz już routery graniczne w terenie, możesz sprawdzić, routery znajdują się w preferowanej sieci i w razie potrzeby mogą je przenieść.

Należy wziąć pod uwagę kilka ścieżek użytkowników i deweloperów. Omówimy większość w tym przewodniku, a także z innymi kluczowymi funkcjami i zalecanym użyciem.

Kluczowa terminologia i koncepcje związane z interfejsami API

Zanim zaczniesz, zapoznaj się z tymi terminami:

Dane logowania do sieci typu Thread: Binarny obiekt blob TLV Thread, który koduje Nazwa sieci wątku, klucz sieci i inne właściwości wymagane przez urządzenie Thread, aby dołączyło do danej sieci Thread.
Preferowane dane logowania do sieci Thread:automatycznie wybrana sieć Thread. dane logowania, które można udostępniać aplikacjom różnych dostawców za pomocą Interfejs API getPreferredCredentials.
Border Agent ID (Identyfikator agenta granicznego): 16-bajtowy, globalny identyfikator routera Border Router urządzenia. Ten identyfikator jest tworzony i zarządzany przez dostawców routerów granicznych.
Aplikacja do konfiguracji routera granic wątków: to aplikacja na Androida, w której nowe urządzenia Thread Border Router i doda dane logowania do sieci Thread Usługi Google Play. Twoja aplikacja jest autorytetem w dodanych dane logowania i ma do nich dostęp.

Wiele interfejsów Thread Network API zwraca błąd Zadanie który kończy się asynchronicznie. Za pomocą addOnSuccessListener i addOnFailureListener , aby zarejestrować wywołania zwrotne związane z odebraniem wyniku. Aby dowiedzieć się więcej, zapoznaj się z Zadanie dokumentacji.

Własność i obsługa danych logowania

Aplikacja, która dodaje dane logowania do sieci Thread, staje się właścicielem dane logowania i ma pełne uprawnienia dostępu do danych logowania. Jeśli spróbujesz na dostęp do danych logowania dodanych przez inne aplikacje, otrzymasz PERMISSION_DENIED .

Jako właściciel aplikacji zalecamy przechowywanie danych logowania w Google Usługi Google Play są aktualne po zaktualizowaniu sieci routera Thread Border Router. Ten oznacza dodawanie danych logowania, gdy są wymagane, i aktualizowanie danych logowania, gdy obramowanie dane logowania do sieci Thread routera zmienią się, a dane logowania zostaną usunięte, Router granic wątków został usunięty lub przywrócony do ustawień fabrycznych.

Wykrywanie agenta granicznego

Dane logowania muszą być zapisane przy użyciu identyfikatora agenta Border. Musisz upewnić się, aplikacja konfiguracji Thread Border Router może określić identyfikatory agentów Border Twoich routerów granicznych Thread.

Routery granic Thread muszą używać mDNS do rozgłaszania informacji o sieci Thread, w tym nazwę sieci, identyfikator Extended Pan ID i identyfikator agenta granicy. odpowiednie wartości txt dla tych atrybutów to nn, xp i id, .

W przypadku sieci z routerami granicznymi Google Usługi Google Play automatycznie pobiera dane logowania do sieci Google Thread, których można użyć.

Zintegruj pakiet SDK z aplikacją na Androida

Aby rozpocząć, wykonaj następujące czynności:

Postępuj zgodnie z instrukcjami podanymi na stronie Skonfiguruj Usługi Google Play.

Dodaj zależność Usługi Google Play do pliku build.gradle:

implementation 'com.google.android.gms:play-services-threadnetwork:16.0.0'

Opcjonalnie: zdefiniuj klasę danych BorderAgent do przechowywania routera granicy i informacjami o nich. W tym przewodniku będziemy używać tych danych:

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

Następnie omówię zalecane czynności, które należy wykonać, aby dodać reklamy preferowane i nimi zarządzać. dane logowania.

Nowe konfiguracje routerów granicznych

Zanim utworzysz nową sieć dla nowych routerów granicznych, spróbuj użyć preferowanych danych logowania. Dzięki temu Urządzenia Thread w miarę możliwości są połączone z pojedynczą siecią Thread.

Uruchomi się połączenie z numerem getPreferredCredentials działanie, które wyświetla użytkownikom prośbę o zezwolenie na żądanie sieciowe. Jeśli sieć dane logowania zostały zapisane w cyfrowym pęku kluczy Thread SDK, są zwracane do aplikacji.

Poproś o dane logowania

Aby poprosić użytkownika o podanie preferowanych danych logowania:

Deklarowanie elementu ActivityLauncher:

private lateinit var preferredCredentialsLauncher: ActivityResultLauncher<IntentSenderRequest>

Przetwórz wynik działania, który jest zwracany jako 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.")
   }
 }

Zadzwoń do użytkownika preferredCredentials i uruchom aktywność:

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

Utwórz nową sieć Thread

Jeśli w urządzeniu użytkownika nie ma preferowanych danych logowania do sieci Thread z siecią Thread, a następnie za pomocą interfejsu API addCredentials możesz dodać do niej dane logowania. Usługi Google Play. Aby to zrobić, musisz utworzyć ThreadBorderAgent, oraz obiekt ThreadNetworkCredentials.

Aby utworzyć losową sieć, wywołaj newRandomizeBuilder:

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

Aby podać nazwę sieci Thread:

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

Dodawanie danych logowania

Aby udostępnić dane logowania do sieci Thread innym dostawcom Thread: musimy dodać je do Usług Google Play. Zanim dodamy nowe dane logowania, musimy wiedzieć, do którego routera granicznego jest przypisany do której należy sieć.

W tym przykładzie utworzymy ThreadBorderAgent z identyfikatora agenta Border. prześlij nowo utworzone dane logowania do sieci 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}]") }
}

Wykrywanie i migracja wewnętrznych routerów granicznych

Jeśli masz obecnie routery graniczne w terenie, isPreferredCredentials, aby sprawdzić, czy routery graniczne należą z preferowaną siecią. Ten interfejs API nie wysyła promptów użytkownika w celu uzyskania uprawnień i porównuje dane logowania do routera granicznego z zapisanymi w Usługach Google Play.

isPreferredCredentails zwraca 0 w przypadku braku dopasowania, a 1 dla jako typ danych Int. Możesz użyć usługi IsPreferredCredentialsResult aby sprawdzić wyniki.

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

Aby skorzystać z usługi isPreferredCredentials, musisz utworzyć Najpierw ThreadNetworkCredentials obiekt. Wystąpienie ThreadNetworkCredentials można utworzyć na kilka sposobów. W kolejnych krokach omówimy te opcje.

Dane logowania do sieci typu Thread według działającego zbioru danych

Zdarzają się sytuacje, w których router Border Router jest już skonfigurowany z parametrem Sieć Thread i chcesz ją dodać do Usług Google Play i udostępniać je innym dostawcom. Możesz utworzyć ThreadNetworkCredential instancji z nieprzetworzonej listy TLV działającego zbioru danych w wątkach:

Przekonwertuj operacyjny zbiór danych na ByteArray. Na przykład:

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

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

Użyj narzędzia fromActiveOperationalDataset, aby utworzyć ThreadNetworkCredentials. Gdy operacja się uda, uzyskasz dostęp do nazwy sieci Thread, kanału inne informacje o sieci. Pełną listę właściwości znajdziesz tutaj: ThreadNetworkCredentials.
```
val threadNetworkCredentials =
    ThreadNetworkCredentials.fromActiveOperationalDataset(activeDataset)
Log.d(
    "threadNetworkCredentials",
    threadNetworkCredentials.channel.toString() + " - " + threadNetworkCredentials.networkName)
```

Wywołaj interfejs API isPreferredCredentials i przekaż 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}]") }

Dane logowania do sieci Thread według agenta Border

Identyfikator agenta Border jednoznacznie identyfikuje urządzenie routera granicznego. Aby użyć funkcji interfejsu API getCredentialsByBorderAgent, musisz najpierw utworzyć ThreadBorderAgent i przekazać identyfikator agenta granicznego.

Po utworzeniu obiektu ThreadBorderAgent wywołaj getCredentialsByBorderAgent Jeśli dane logowania zostały zapisane, sprawdź, czy są preferowane.

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

Dane logowania do sieci typu Thread według rozszerzonego identyfikatora Pan

Podobnie jak w przypadku getPreferredCredentials, możesz też poprosić użytkownika o podanie z identyfikatora Extended Pan ID routera granicznego. getCredentialsByExtendedPanId zwraca: IntentSender, a aktywność zawiera obiekt ThreadNetworkCredentials po zatwierdzeniu przez użytkownika.

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

Usuń dane logowania

Usunięcie urządzenia Border Router z domu lub przywrócenia go do ustawień fabrycznych Musisz usunąć swoją sieć Thread z Usług 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}]") }
}

Zasoby

Więcej informacji o pakiecie SDK Thread Network SDK znajdziesz w Dokumentacja API.