Eine Android-App für wirklich relevante Apps

1. Willkommen

Matter wurde zur Vereinheitlichung von IoT-Standards entwickelt und verbindet Smart-Home-Geräte in verschiedenen Systemen wie Google Home, Zigbee, Bluetooth Mesh und Z-Wave.

Mobilgeräte sind ein zentraler Interaktionspunkt mit Smart-Home-Geräten. Wenn Sie Ihre eigenen Android-Apps für Matter-Geräte entwickeln möchten, können wir Ihnen helfen, schnell loszulegen.

In der Google Home-Beispiel-App für Matter (GHSA) werden die Home Mobile SDK APIs vorgestellt, mit denen Nutzer Geräte in Betrieb nehmen und mit anderen teilen können. Du kannst die Beispiel-App auch als Lerntool verwenden, um wichtige Matter-Konzepte besser zu verstehen. Außerdem kannst du damit Probleme bei Interaktionen mit Matter-Geräten beheben.

Aufgaben

In diesem Codelab lädst du den Quellcode für die Beispiel-App herunter und erlernst, wie du mit dem Home Mobile SDK Geräte in Betrieb nehmen und mit anderen teilen kannst. Außerdem erfahren Sie, wie Sie Inbetriebnahme- und Clusterbibliotheken aus dem Matter-Repository (connectedhomeip) verwenden.

Nachdem Sie die Beispiel-App heruntergeladen haben, überprüfen wir den Quellcode in Android Studio und implementieren die folgenden Home Mobile SDK APIs:

Außerdem erfährst du mehr über Konzepte zur Inbetriebnahme, die Matter-Struktur und die Steuerung von Matter-Geräten.

Voraussetzungen

Führe zuerst die folgenden Schritte aus:

Sie benötigen keinen Hub, z. B. Google Nest Hub (2. Generation), um Geräte mit der Beispiel-App in Betrieb zu nehmen und zu steuern.

2. Einrichten

Die Codelab-Start-App befindet sich im codelab-Zweig. Wenn Sie mit dem Codelab-Quellcode arbeiten möchten, können Sie die ZIP-Datei herunterladen.

Mit dieser ZIP-Datei (codelab) erstellen Sie ein funktionsfähiges Beispiel.

Codelab-Versionen

Der Zweig codelab ist mit dem Release 2.0.0 der Beispiel-App gekennzeichnet. Wenn Sie die Updates vergleichen möchten, während Sie die einzelnen Schritte durchlaufen, können Sie den vollständigen Quellcode für diesen Release herunterladen.

Wenn Sie das GitHub-Repository klonen möchten, folgen Sie der Anleitung in der Readme-Datei für die Beispiel-App.

Abhängigkeiten

Wir führen Sie durch den Quellcode, der für die Freigabe und Inbetriebnahme von Geräten erforderlich ist. Es kann jedoch hilfreich sein, sich der folgenden Abhängigkeiten bewusst zu machen, bevor Sie beginnen. Diese Abhängigkeiten sind in der Datei libs.versions.toml deklariert und die Nutzung wird in der Datei build.gradle.kts angegeben.

Quellcode

Die Benutzeroberfläche und die meisten Funktionen wurden bereits für Sie erstellt.

In diesem Codelab fügen wir den folgenden Dateien Matter-Funktionen hinzu:

  • java/commissioning/AppCommissioningService: ermöglicht die Inbetriebnahme von Geräten in der Entwicklungsstruktur
  • java/screens/home/HomeScreen und java/screens/home/HomeViewModel.kt: beinhalten die Home Mobile SDK-Inbetriebnahme-Funktion
  • java/screens/device/DeviceScreen und java/screens/device/DeviceViewModel: einschließlich der Share Device API-Aufrufe

Jede Datei ist mit dem Codeblock kommentiert, den Sie ändern werden. Beispiel:

// CODELAB: add commissioningFunction()

So können Sie schnell den entsprechenden Abschnitt im Codelab finden.

3. Provision an Google

Bevor du Geräte steuern und innerhalb desselben Stoffs miteinander kommunizieren kannst, müssen sie von einem Kommissar in Betrieb genommen werden. In diesem Fall handelt es sich um diese Beispiel-App, die Google Home-Beispiel-App für Matter.

Es ist wichtig, die folgenden Konzepte zur Inbetriebnahme von Matter zu verstehen:

  • Fabrics ermöglichen die Kommunikation von Geräten untereinander.
  • Fabrics verwalten einen gemeinsamen Satz eindeutiger Anmeldedaten.
  • Ökosysteme sind für die Ausstellung vertrauenswürdiger Root-Zertifikate sowie für die Zuweisung von Fabric-IDs und eindeutigen Knoten-IDs verantwortlich. Ein Ökosystem ist der Backend-Dienst eines Auftraggebers, z. B. Home Graph für das Google Home-System.
  • Geräte können für mehrere Strukturen in Betrieb genommen werden (Funktion für mehrere Administratoren).

Zur Inbetriebnahme eines Geräts müssen Sie die CommissioningClient API verwenden. Beim Aufruf von .commissionDevice() wird ein IntentSender zurückgegeben, der die richtige Aktivität in den Google Play-Diensten startet:

interface CommissioningClient {
  Task<IntentSender> commissionDevice(CommissioningRequest request);
}

In den nächsten Abschnitten geht es um den Mindestcode, der erforderlich ist, um Geräte in der Google-Struktur in Betrieb zu nehmen.

Schritt 1: Aktivitäts-Launcher

Zum Verarbeiten des IntentSender aus dem CommissioningClient kann ein ActivityResultLauncher verwendet werden:

val commissioningLauncher = registerForActivityResult(
    StartIntentSenderForResult()
) { result: ActivityResult ->
    if (result.resultCode == RESULT_OK) {
        Timber.d(TAG, "Commissioning succeeded.")
    } else {
        Timber.d(TAG, "Commissioning failed. " + result.resultCode)
    }
}

Schritt 2: Inbetriebnahmefunktion

Im Folgenden finden Sie ein einfaches Beispiel, in dem die CommissioningClient API verwendet wird, um ein Gerät für die Google-Struktur in Betrieb zu nehmen.

  1. Die Inbetriebnahme beginnt mit der Funktion commissionDevice(). Zuerst wird ein CommissioningRequest definiert. Mit dieser Standardkonfiguration werden Geräte nur in der lokalen Android-Struktur in Betrieb genommen.
  2. Matter ist der Einstiegspunkt für das Home Mobile SDK. Im nächsten Aufruf ruft .getCommissioningClient einen CommissioningClient von this (Activity) ab.
  3. .commissionDevice() akzeptiert die CommissioningRequest.
  4. Und schließlich wird .addOnSuccessListener aufgerufen, um die CommissioningResult zu verarbeiten und die Provisionsgeräteaktivitäten der Google Play-Dienste (GPS) zu starten.
private fun commissionDevice() {
    val request: CommissioningRequest = CommissioningRequest.builder().build()
    Matter.getCommissioningClient(this)
        .commissionDevice(request)
        .addOnSuccessListener { result ->
            commissioningLauncher.launch(IntentSenderRequest.Builder(result).build())
        }
}

Die Local Android Fabric kann über die Android-Einstellungen genutzt werden, um die Inbetriebnahme der Geräte für andere Plattformen zu vereinfachen.

Als Nächstes erfahren Sie, wie Sie ein Gerät in einer Entwicklungsstruktur in Betrieb nehmen.

Einen Überblick über die Benutzeroberfläche während der Inbetriebnahme findest du im Leitfaden zur Google Home-Beispiel-App für Matter.

4. Provision auf Entwicklungsstruktur

Geräte können für mehrere Stoffe in Betrieb genommen werden. Zum Verwalten vertrauenswürdiger Kopplungen speichern Geräte eine FabricTable mit verschiedenen FabricInfo-Mitgliedern, z. B.:

  • Fabric-Identifikation
  • Knoten-ID, die dem Gerät von der Fabric zugewiesen wird
  • Anbieter-ID
  • Fabric-ID
  • Anmeldedaten für den Betrieb des Geräts

Der Administrator Domain Manager (ADM) definiert die Anmeldedaten für die Struktur. Im vorherigen Szenario sind die Google Play-Dienste das System, das als vertrauenswürdige Root-Zertifizierungsstelle fungiert. Wenn Sie Geräte in der lokalen Android-Struktur in Betrieb nehmen, enthält jedes Gerät dieselben Fabric-Anmeldedaten und -CAs.

Individuelle Inbetriebnahme

Für die Provision der lokalen Android-Struktur haben wir die Standardparameter verwendet, um die CommissioningRequest in der CommissioningClient API zu erstellen:

val request: CommissioningRequest = CommissioningRequest.builder().build()

Wenn Sie neue Geräte über Ihre App steuern und verwalten möchten, müssen Sie eine lokale Entwicklungsstruktur erstellen und die operativen Anmeldedaten zur Inbetriebnahme von Geräten abrufen. In diesem Szenario wird Ihre App zu einer einzigartigen, unabhängigen Umgebung, die Geräten die entsprechenden Knotenanmeldedaten zuweist.

Sie können Home Mobile SDK darüber informieren, dass Sie Geräte für Ihren eigenen Stoff in Betrieb nehmen möchten, indem Sie einen benutzerdefinierten Dienst an die CommissioningRequest übergeben:

class CommissioningRequest {
  static CommissioningRequest.Builder builder();

  class Builder {
    Builder setCommissioningService(@Nullable ComponentName commissioningService);

    CommissioningRequest build();
  }
}

In den nächsten Schritten ändern wir die Funktion commissionDevice(), um einen benutzerdefinierten Dienst zu verwenden. Außerdem werden wir dem Startseiten-Fragment einen Aktivitäts-Launcher hinzufügen und LiveData-Objekte zur Verwaltung des API-Ablaufs verwenden.

Schritt 1: GPS-Aktivitäts-Launcher erstellen

Erstellen wir zunächst einen Aktivitäts-Launcher, um die IntentSender aus der CommissioningClient API zu verarbeiten.

  1. Öffnen Sie HomeScreen im Ordner java/screens/home/.
  2. Ersetzen Sie den Kommentar // CODELAB: commissionDeviceLauncher definition durch den folgenden Code, um das Ergebnis der Inbetriebnahmeaktivität zu registrieren und zu verarbeiten:
    val commissionDeviceLauncher =
  rememberLauncherForActivityResult(
    contract = ActivityResultContracts.StartIntentSenderForResult()
  ) { result ->
    // Commission Device Step 5.
    // The Commission Device activity in GPS (step 4) has completed.
    val resultCode = result.resultCode
    if (resultCode == Activity.RESULT_OK) {
      Timber.d("CommissionDevice: Success")
      // We let the ViewModel know that GPS commissioning has completed successfully.
      // The ViewModel knows that we still need to capture the device name and will\
      // update UI state to trigger the NewDeviceAlertDialog.
      homeViewModel.gpsCommissioningDeviceSucceeded(result)
    } else {
      homeViewModel.commissionDeviceFailed(resultCode)
    }
  }

Schritt 2: Aktion für Gerät auslösen

In diesem Schritt löst der Nutzer die Aktion „Gerät in Betrieb nehmen“ aus, indem er rechts unten auf dem Startbildschirm auf die Schaltfläche „+“ klickt. Daraufhin wird commissionDevice() aufgerufen.

val onCommissionDevice = {
  ...
  commissionDevice(activity!!.applicationContext, commissionDeviceLauncher)
}

Schritt 3: API aufrufen

  1. Sie befinden sich immer noch in HomeScreen.kt im Ordner java/screens/home/.
  2. Ersetzen Sie den // CODELAB: commissionDevice-Kommentar durch den folgenden commissionDeviceRequest. setCommissioningService bindet AppCommissioningService an eine CommissioningService-Instanz, die in einer Callback-Funktion zurückgegeben wird. Wenn du einen benutzerdefinierten Dienst übergibst, autorisiert das Home Mobile SDK zuerst die Geräte auf der lokalen Android-Struktur und sendet dann die Onboarding-Nutzlast zurück an AppCommissioningService.
    val commissionDeviceRequest =
    CommissioningRequest.builder()
        .setCommissioningService(ComponentName(
            context, AppCommissioningService::class.java))
        .build()
  3. Rufen Sie .getCommissioningClient() und dann .commissionDevice() auf.
Matter.getCommissioningClient(context)
    .commissionDevice(commissionDeviceRequest)

Fügen Sie zum Abschließen der commissionDevice-Funktion addOnSuccessListener und addOnFailureListener hinzu:

    .addOnSuccessListener { result ->
      commissionDeviceLauncher.launch(IntentSenderRequest.Builder(result).build())
    }
    .addOnFailureListener { error ->
      Timber.e(error)
    }

5. ProvisioningService erstellen

In der Funktion commissionDevice() haben wir den Abruf eines CommissioningService von der CommissioningClient API angefordert. In diesem Ablauf nimmt die CommissioningClient API zuerst Geräte in der lokalen Android-Struktur in Betrieb und gibt dann einen Callback zurück, der das CommissioningRequestMetadata-Objekt enthält:

public interface CommissioningService {
interface Callback {
    void onCommissioningRequested(CommissioningRequestMetadata metadata);
  }
}

Jetzt müssen wir den „ProvisioningService.Callback“ übernehmen und die zur Inbetriebnahme von Geräten erforderlichen Funktionen in unserer Beispiel-App bereitstellen. Hier ein Beispiel für eine grundlegende „ProvisioningService“-Implementierung:

class MatterCommissioningService : Service(), CommissioningService.Callback {
   private val commissioningServiceDelegate =
     CommissioningService.Builder(this)
       .setCallback(this)
       .build()

   override fun onBind(intent: Intent) = commissioningServiceDelegate.asBinder()

   override fun onCommissioningRequested(metadata: CommissioningRequestMetadata) {
     // perform commissioning

     commissioningServiceDelegate
       .sendCommissioningComplete(CommissioningCompleteMetadata.builder().build())
   }
 }

Schritt 1: Benutzerdefinierten AppCommissioningService untersuchen

Um Ihnen den Einstieg zu erleichtern, haben wir bereits die grundlegende Klassenstruktur für unseren benutzerdefinierten CommissioningService definiert. Im Folgenden erhalten Sie eine kurze Übersicht über die Dienstfunktionen. Wenn du fortfahren möchtest, öffne AppCommissioningService in java/commissioning.

Wir haben die folgenden Importe für die Home Mobile SDK APIs hinzugefügt:

import com.google.android.gms.home.matter.commissioning.CommissioningCompleteMetadata
import com.google.android.gms.home.matter.commissioning.CommissioningRequestMetadata
import com.google.android.gms.home.matter.commissioning.CommissioningService

AppCommissioningService enthält auch Bibliotheken aus dem Matter-Repository (connectedhomeip):

import com.google.home_sample_app_for_matter.chip.ChipClient

Außerdem umfasst der Dienst Importe zur Unterstützung von Hilt- und Kotlin-Coroutinen.

Als Nächstes erstellen wir den Konstruktor und richten einige Dinge ein, einschließlich des commissioningServiceDelegate-Objekts, über das wir die Google Play-Dienste informieren, wenn die Inbetriebnahme abgeschlossen ist.

private lateinit var commissioningServiceDelegate: CommissioningService
...
commissioningServiceDelegate = CommissioningService.Builder(this).setCallback(this).build()

Jetzt ist es an der Zeit, die Inbetriebnahmefunktionen hinzuzufügen.

Schritt 2: onCommissioningRequested überschreiben

Führen Sie die folgenden Schritte aus, um Geräte in der Entwicklungsstruktur der App in Betrieb zu nehmen:

  1. AppCommissioningService in java/commissioning öffnen.
  2. Suchen Sie die Funktion onCommissioningRequested(). Wir haben eine Protokollnachricht bereitgestellt, aus der die CommissioningRequestMetadata ausgegeben wird. Ersetzen Sie den // CODELAB: onCommissioningRequested()-Kommentar, um die serviceScope-Koroutine zu starten und den deviceId abzurufen.
    // Perform commissioning on custom fabric for the sample app.
serviceScope.launch {
  val deviceId = devicesRepository.incrementAndReturnLastDeviceId()
  3. Führen Sie die Inbetriebnahme durch. In diesem Schritt können wir die im CommissioningRequestMetadata-Objekt zurückgegebenen Geräteinformationen übergeben. ChipClient verwendet diese Metadaten, um einen sicheren Kanal zwischen der GHSA für Matter-App und deinem Gerät zu erstellen.
    try {
  Timber.d(
      "Commissioning: App fabric -> ChipClient.establishPaseConnection(): deviceId [${deviceId}]")
  chipClient.awaitEstablishPaseConnection(
      deviceId,
      metadata.networkLocation.ipAddress.hostAddress!!,
      metadata.networkLocation.port,
      metadata.passcode)
  Timber.d(
      "Commissioning: App fabric -> ChipClient.commissionDevice(): deviceId [${deviceId}]")
  chipClient.awaitCommissionDevice(deviceId, null)
} catch (e: Exception) {
  Timber.e(e, "onCommissioningRequested() failed")
  // No way to determine whether this was ATTESTATION_FAILED or DEVICE_UNREACHABLE.
  commissioningServiceDelegate
      .sendCommissioningError(CommissioningError.OTHER)
      .addOnSuccessListener {
        Timber.d(
            "Commissioning: commissioningServiceDelegate.sendCommissioningError() succeeded")
      }
      .addOnFailureListener { e2 ->
        Timber.e(e2, "Commissioning: commissioningServiceDelegate.sendCommissioningError() failed")
      }
  return@launch
}
  4. Verwende die commissioningServiceDelegate, um den Google Play-Diensten mitzuteilen, dass die Inbetriebnahme abgeschlossen ist. Übergeben Sie in .sendCommissioningComplete() CommissioningCompleteMetadata.
    commissioningServiceDelegate
    .sendCommissioningComplete(
        CommissioningCompleteMetadata.builder().setToken(deviceId.toString()).build())
    .addOnSuccessListener {
      Timber.d("Commissioning: commissioningServiceDelegate.sendCommissioningComplete() succeeded")
    }
    .addOnFailureListener { e ->
      Timber.e(e, "Commissioning: commissioningServiceDelegate.sendCommissioningComplete() failed")
    }

Anwendung ausführen

Da nun der gesamte erforderliche Code für die Inbetriebnahme auf unserer lokalen Struktur vorhanden ist, ist es an der Zeit, ihn zu testen. Wählen Sie Ihr Android-Gerät aus und führen Sie die App aus. Tippen Sie auf dem Startbildschirm auf Gerät hinzufügen und führen Sie die Schritte zur Inbetriebnahme Ihres Geräts aus.

Wenn die Inbetriebnahme abgeschlossen ist, ist Ihr Gerät jetzt in zwei Strukturen integriert: die lokale Android-Struktur und Ihre lokale Entwicklungsstruktur. Jede Fabric hat ihre eigenen Anmeldedaten und eine eindeutige 64-Bit-Struktur-ID.

6. Geräte steuern

Bei der Inbetriebnahme einer Entwicklungsstruktur können Sie die Bibliotheken aus dem Matter-Repository (connectedhomeip) verwenden, um die Geräte über die Beispiel-App zu steuern.

Wir haben einige Hilfsklassen erstellt, um den Zugriff auf Gerätecluster und das Senden von Befehlen zu vereinfachen. Weitere Informationen findest du, wenn du ClustersHelper in java/clusters öffnest. Dieses Singleton-Hilfsprogramm importiert die folgenden Bibliotheken für den Zugriff auf Geräteinformationen:

import chip.devicecontroller.ChipClusters
import chip.devicecontroller.ChipStructs

Mit dieser Klasse können Sie den On/Off-Cluster für ein Gerät abrufen und dann .toggle aufrufen:

suspend fun toggleDeviceStateOnOffCluster(deviceId: Long, endpoint: Int) {
  Timber.d("toggleDeviceStateOnOffCluster())")
  val connectedDevicePtr =
      try {
        chipClient.getConnectedDevicePointer(deviceId)
      } catch (e: IllegalStateException) {
        Timber.e("Can't get connectedDevicePointer.")
        return
      }
  return suspendCoroutine { continuation ->
    getOnOffClusterForDevice(connectedDevicePtr, endpoint)
        .toggle(
            object : ChipClusters.DefaultClusterCallback {
              override fun onSuccess() {
                continuation.resume(Unit)
              }
              override fun onError(ex: Exception) {
                Timber.e("readOnOffAttribute command failure: $ex")
                continuation.resumeWithException(ex)
              }
            })
  }
}

Gerät ein-/ausschalten

Nachdem Sie ein Gerät in Betrieb genommen haben, wird die im CommissioningResult zurückgegebene Nutzlast dem Datenspeicher hinzugefügt. Dadurch erhält unsere App Zugriff auf Geräteinformationen, die wir zum Senden von Befehlen verwenden können.

Matter-Apps sind ereignisgesteuert. Wenn der Matter-Stack initialisiert wird, warten Clusterdienste auf eingehende Nachrichten. Sobald ein Gerät in Betrieb genommen wurde, senden Matter-Clients Befehle über den sicheren Betriebskanal, der bei der Inbetriebnahme des Geräts eingerichtet wurde.

Auf dem Gerät werden Pakete validiert, entschlüsselt und dann mit einem Callback versandt. Zu den Callback-Funktionen gehören die EndpointId, die ClusterId und die AttributeId, auf die über attributePath zugegriffen werden kann. Dieser Code kann beispielsweise auf einem Matter-Gerät implementiert werden:

void MatterPostAttributeChangeCallback(const chip::app::ConcreteAttributePath & attributePath, uint8_t mask, uint8_t type,
                                       uint16_t size, uint8_t * value)
{
    // handle callback
    ClusterId clusterId     = attributePath.mClusterId;
    AttributeId attributeId = attributePath.mAttributeId;
}

In den nächsten Schritten verwendest du das Matter SDK und ClustersHelper, um ein Gerät ein- und auszuschalten.

  1. Du kannst DeviceViewModel in java/screens/device aufrufen.
  2. Suchen Sie die Funktion updateDeviceStateOn.
  3. Ersetzen Sie den Kommentar // CODELAB: toggle durch den Code zum Aufrufen von clustersHelper und aktualisieren Sie dann das Geräte-Repository:
    Timber.d("Handling real device")
    try {
      clustersHelper.setOnOffDeviceStateOnOffCluster(deviceUiModel.device.deviceId, isOn, 1)
      devicesStateRepository.updateDeviceState(deviceUiModel.device.deviceId, true, isOn)
    } catch (e: Throwable) {
      Timber.e("Failed setting on/off state")
    }

Diese Funktion wird über DeviceScreen aufgerufen:

// On/Off Switch click.
val onOnOffClick: (value: Boolean) -> Unit = { value ->
  deviceViewModel.updateDeviceStateOn(deviceUiModel!!, value)
}

Anwendung ausführen

Führe die App aus, um die Updates zu aktualisieren. Schalte dein Gerät auf dem Startbildschirm ein und aus.

7. Geräte mit anderen Ökosystemen teilen

Die Freigabe eines Geräts wird in der Matter-Spezifikation als Vorgang für mehrere Administratoren bezeichnet.

In den vorherigen Schritten haben wir gelernt, dass das Home Mobile SDK es ermöglicht, Geräte in der lokalen Android-Struktur und auch in einer Entwicklungsstruktur für die Beispiel-App in Betrieb zu nehmen. Dies ist ein Beispiel für den Ablauf für mehrere Administratoren, bei dem Geräte für mehr als eine Fabric in Betrieb genommen werden können.

Vielleicht möchten Sie Geräte mit noch mehr Stoffen teilen, insbesondere wenn dies ein Haushalt ist, in dem die Menschen ihre eigenen Vorlieben in Bezug auf Anwendungen und Plattformen haben.

Das Home Mobile SDK bietet in der ShareDeviceRequest API folgende Funktionen:

  1. Temporäres Fenster zur Inbetriebnahme von Geräten öffnen.
  2. Sie können den Status Ihrer Geräte ändern, damit sie auf einem anderen Stoff in Betrieb genommen werden können.
  3. Du kannst deine Geräte auch über andere Apps und Plattformen steuern.

In den nächsten Schritten verwenden Sie das Home Mobile SDK für die gemeinsame Nutzung von Geräten.

Schritt 1: GPS-Aktivitäts-Launcher erstellen

Ähnlich wie beim Launcher zur Inbetriebnahme, den wir bei der Inbetriebnahme für eine Entwicklungsstruktur erstellt haben, haben wir auch einen Launcher zur gemeinsamen Nutzung von Geräteaktivitäten entwickelt, um die IntentSender aus der CommissioningClient API zu verarbeiten.

  1. Öffnen Sie DeviceScreen im Ordner java/screens/device/.
  2. Ersetzen Sie den Kommentar // CODELAB: shareDeviceLauncher definition durch den folgenden Code, um das Ergebnis der .shareDevice()-Aktivität zu registrieren und zu verarbeiten:
    val shareDeviceLauncher = rememberLauncherForActivityResult(
  contract = ActivityResultContracts.StartIntentSenderForResult()
) { result ->
  // Commission Device Step 5.
  // The Share Device activity in GPS (step 4) has completed.
  val resultCode = result.resultCode
  if (resultCode == Activity.RESULT_OK) {
    deviceViewModel.shareDeviceSucceeded()
  } else {
    deviceViewModel.shareDeviceFailed(resultCode)
  }
}

Schritt 2: Aktion zum Teilen des Geräts auslösen

In diesem Schritt löst der Nutzer die Aktion „Gerät teilen“ aus, indem er auf dem Gerätebildschirm auf die Schaltfläche „Teilen“ klickt. Anschließend wird das Gerät (deviceViewModel) angerufen, um ein Kopplungsfenster für die Gerätefreigabe zu öffnen.

// Share Device button click.
val onShareDevice: () -> Unit = {
 deviceViewModel.openPairingWindow(deviceUiModel!!.device.deviceId)
}

Nachdem das Verknüpfungsfenster erfolgreich geöffnet wurde, sendet deviceViewModel dies an die UI. Die Kommunikation zwischen ViewModel und der Benutzeroberfläche erfolgt über StateFlow-Objekte.

// Communicate to the UI that the pairing window is open.
// UI can then launch the GPS activity for device sharing.
_pairingWindowOpenForDeviceSharing.value = true

Nachdem die Änderung am StateFlow-Objekt erkannt wurde, führt DeviceScreen folgenden Aufruf aus:

shareDevice(activity!!.applicationContext, shareDeviceLauncher, deviceViewModel)

Schritt 3: API aufrufen

Jetzt ist es an der Zeit, die Freigabe des Geräts zu starten.

  1. Öffnen Sie DeviceScreen.kt im Ordner java/screens/device/.
  2. Suchen Sie die Funktion shareDevice(). Ersetzen Sie den Kommentar // CODELAB: shareDevice durch ShareDeviceRequest. Die DeviceDescriptor enthält bestimmte Informationen zum Gerät, z. B. die Anbieter-ID, die Produkt-ID und den Gerätetyp. In diesem Beispiel werden die Werte hartcodiert.
    val shareDeviceRequest =
  ShareDeviceRequest.builder()
    .setDeviceDescriptor(DeviceDescriptor.builder().build())
    .setDeviceName("GHSAFM temp device name")
  3. Legen Sie CommissioningWindow und Parameter fest.
        .setCommissioningWindow(
        CommissioningWindow.builder()
            .setDiscriminator(Discriminator.forLongValue(DISCRIMINATOR))
            .setPasscode(SETUP_PIN_CODE)
            .setWindowOpenMillis(SystemClock.elapsedRealtime())
            .setDurationSeconds(OPEN_COMMISSIONING_WINDOW_DURATION_SECONDS.toLong())
            .build())
    .build()
  4. Rufen Sie .getCommissioningClient() dieses Mal auf. Verwenden Sie dabei die .shareDevice() API.
    Matter.getCommissioningClient(context)
    .shareDevice(shareDeviceRequest)

Der Erfolgs-Callback der commissioningClient.shareDevice() API stellt den IntentSender bereit, mit dem die gemeinsame Geräteaktivität in den Google Play-Diensten gestartet werden kann.

  1. Fügen Sie zur Vervollständigung der shareDevice-Funktion addOnSuccessListener und addOnFailureListener hinzu. Bei Erfolg wird launch am shareDeviceLauncher aufgerufen, um die GPS-Aktivität für die Gerätefreigabe zu starten.
        .addOnSuccessListener { result ->
      Timber.d("ShareDevice: Success getting the IntentSender: result [${result}]")
      shareDeviceLauncher.launch(IntentSenderRequest.Builder(result).build())
    }
    .addOnFailureListener { error ->
      Timber.e(error)
      deviceViewModel.showMsgDialog("Share device failed", error.toString())
    }

Anwendung ausführen

Wenn Sie Ihr Matter-Gerät für andere Plattformen freigeben möchten, muss auf Ihrem Android-Gerät eine weitere Plattform installiert sein. Wir haben eine weitere Instanz der Beispiel-App erstellt, die Sie als Zielbeauftragter verwenden können.

Sobald der Zielauftragsbeauftragte auf Ihrem Android-Gerät installiert ist, prüfen Sie, ob Sie Ihr Matter-Gerät freigeben können. Sie trägt das Label GHSAFM-TC.

Deine Geräte können jetzt in drei Strukturen unterteilt werden:

  1. Die lokale Android-Struktur.
  2. Ihre Entwicklungsstruktur (diese App).
  3. Den dritten Stoff, mit dem du gerade das Gerät geteilt hast.

8. Nächste Schritte

Glückwunsch

Herzlichen Glückwunsch! Du hast dieses Codelab erfolgreich abgeschlossen und gelernt, wie du Geräte mit dem Home Mobile SDK in Betrieb nehmen und freigeben kannst.

Wenn Sie Probleme mit der Beispiel-App haben, führen Sie die folgenden Schritte aus, um Ihre Umgebung zu prüfen:

Wenn Sie Fragen zur Verwendung der Beispiel-App haben oder einen Codefehler entdecken, können Sie den Issue Tracker im GitHub-Repository einreichen:

Offizielle Unterstützung von Google zu technischen Fragen erhalten Sie im Smart-Home-Entwicklerforum:

Verwenden Sie das Tag google-smart-home auf Stack Overflow, um technischen Support von der Community zu erhalten: