Erstellen Sie eine Android-App für Matter

1. Willkommen

Matter wurde mit dem Ziel entwickelt, IoT-Standards zu vereinheitlichen. Der Standard verbindet Smart-Home-Geräte in verschiedenen Ökosystemen wie Google Home, Zigbee, Bluetooth Mesh und Z-Wave.

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

Die Google Home Sample App for Matter (GHSA for Matter) zeigt die Home Mobile SDK APIs, mit denen Nutzer Geräte in Betrieb nehmen und freigeben können. Sie können die Beispiel-App auch als Lernwerkzeug verwenden, um wichtige Matter-Konzepte besser zu verstehen, sowie als Tool zum Debuggen und Beheben von Problemen bei der Interaktion mit Matter-Geräten.

Aufgaben

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

Nachdem Sie die Beispiel-App heruntergeladen haben, sehen wir uns den Quellcode in Android Studio an und implementieren die folgenden Home Mobile SDK-APIs:

Außerdem erfahren Sie mehr über die Konzepte der Inbetriebnahme, Matter-Fabrics und die Steuerung von Matter-Geräten.

Voraussetzungen

Führen Sie zuerst die folgenden Schritte aus:

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

2. Einrichten

Die Starter-App für das Codelab befindet sich im Branch codelab. Wenn Sie mit dem Codelab-Quellcode arbeiten möchten, können Sie die ZIP-Datei herunterladen.

Sie verwenden diese codelab-ZIP-Datei, um ein funktionierendes Beispiel zu erstellen.

Codelab-Versionen

Der Branch codelab ist mit der Version 2.0.0 der Beispiel-App getaggt. Wenn Sie Ihre Aktualisierungen vergleichen möchten, während Sie die einzelnen Schritte durchgehen, können Sie den vollständigen Quellcode für diese Version herunterladen.

Wenn Sie das GitHub-Repository klonen möchten, folgen Sie der Anleitung in der README-Datei der Beispiel-App.

Abhängigkeiten

Wir führen Sie durch den Quellcode, der zum Teilen und Inbetriebnehmen von Geräten erforderlich ist. Es kann jedoch hilfreich sein, sich vorab über die folgenden Abhängigkeiten zu informieren. Diese Abhängigkeiten werden in der Datei libs.versions.toml deklariert und ihre Verwendung wird in der Datei build.gradle.kts angegeben.

Quellcode

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

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

  • java/com/google/homesampleapp/commissioning/AppCommissioningService: Ermöglicht die Inbetriebnahme von Geräten im Entwicklungsnetzwerk.
  • java/com/google/homesampleapp/screens/home/HomeScreen und java/com/google/homesampleapp/screens/home/HomeViewModel.kt: enthält die Inbetriebnahmefunktion des Home Mobile SDK
  • java/com/google/homesampleapp/screens/device/DeviceScreen und java/com/google/homesampleapp/screens/device/DeviceViewModel: Enthält die API-Aufrufe für „Gerät teilen“.

Jede Datei ist mit dem Codeblock kommentiert, den Sie ändern müssen, z. B.:

// CODELAB: add commissioningFunction()

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

3. Provision an Google

Bevor Sie Geräte steuern und ihnen die Kommunikation untereinander im selben Fabric erlauben können, müssen sie von einem Commissioner in Betrieb genommen werden. In diesem Fall ist das diese Beispielanwendung, die Google Home Sample App for Matter.

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

  • Über Fabrics können Geräte miteinander kommunizieren.
  • Für Fabrics wird ein gemeinsamer Satz eindeutiger Anmeldedaten verwaltet.
  • Ökosysteme sind für die Ausstellung vertrauenswürdiger Stammzertifikate, die Zuweisung von Fabric-IDs und die Zuweisung eindeutiger Knoten-IDs verantwortlich. Ein Ökosystem ist der Backend-Dienst eines Beauftragten, z. B. der Home Graph für das Google Home-Ökosystem.
  • Geräte können für mehr als ein Fabric in Betrieb genommen werden (Funktion für mehrere Administratoren).

Zum Inbetriebnehmen eines Geräts müssen Sie die CommissioningClient API verwenden. Ein Aufruf von .commissionDevice() gibt einen IntentSender zurück, der die entsprechende Aktivität in Google Play-Diensten startet:

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

In den nächsten Abschnitten wird der minimale Code beschrieben, der zum Inbetriebnehmen von Geräten in der Google-Struktur erforderlich ist.

Schritt 1: Activity Launcher

Um die IntentSender aus der CommissioningClient zu verarbeiten, können Sie einen ActivityResultLauncher verwenden:

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

Hier ist ein einfaches Beispiel, in dem die CommissioningClient API verwendet wird, um ein Gerät in der Google-Umgebung in Betrieb zu nehmen.

  1. Der Prozess zur Inbetriebnahme beginnt mit der Funktion commissionDevice(). Zuerst wird ein CommissioningRequest definiert. Mit dieser Standardkonfiguration werden Geräte nur für die lokale Android-Umgebung in Betrieb genommen.
  2. Matter ist der Einstiegspunkt für das Home Mobile SDK. Im nächsten Aufruf erhält .getCommissioningClient einen CommissioningClient von this (Activity).
  3. .commissionDevice() akzeptiert die CommissioningRequest.
  4. Schließlich wird .addOnSuccessListener aufgerufen, um das CommissioningResult zu verarbeiten und die Aktivität Commission Device 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 lokale Android-Fabric kann über die Android-Einstellungen verwendet werden, um die Inbetriebnahme von Geräten in anderen Fabrics zu vereinfachen.

Als Nächstes erfahren Sie, wie Sie ein Gerät in einem Entwicklungs-Fabric in Betrieb nehmen.

Eine Übersicht über die Benutzeroberfläche während der Inbetriebnahme finden Sie im Google Home Sample App for Matter Guide.

4. Inbetriebnahme in einem Entwicklungs-Fabric

Geräte können für mehr als ein Fabric in Betrieb genommen werden. Zur Verwaltung vertrauenswürdiger Kopplungen speichern Geräte ein FabricTable mit verschiedenen FabricInfo-Elementen, z. B.:

  • Stoffidentifizierung
  • Knoten-ID, die dem Gerät vom Fabric zugewiesen wurde
  • Anbieter-ID
  • Fabric-ID
  • Betriebsanmeldedaten für Geräte

Der Administrator der administrativen Domain (ADM) definiert die Fabric-Anmeldedaten. Im vorherigen Szenario ist Google Play-Dienste das Ökosystem, das als vertrauenswürdige Stammzertifizierungsstelle fungiert. Wenn Sie Geräte für das lokale Android-Fabric in Betrieb nehmen, enthält jedes Gerät dieselben Fabric-Anmeldedaten und dieselben Zertifizierungsstellen.

Benutzerdefinierte Inbetriebnahmedienste

Für die Inbetriebnahme in der lokalen Android-Umgebung haben wir die Standardparameter verwendet, um 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 ein lokales Entwicklungs-Fabric erstellen und die Betriebs-Anmeldedaten zum Inbetriebnehmen von Geräten abrufen. In diesem Szenario wird Ihre App zu einem einzigartigen, unabhängigen Ökosystem, in dem Geräten die entsprechenden Knotenanmeldedaten zugewiesen werden.

Sie können dem Home Mobile SDK mitteilen, dass Sie Geräte in Ihrer eigenen Struktur in Betrieb nehmen möchten, indem Sie einen benutzerdefinierten Dienst an 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(), damit ein benutzerdefinierter Dienst verwendet wird. Außerdem fügen wir dem Home-Fragment einen Activity Launcher hinzu und verwenden LiveData-Objekte, um den API-Ablauf zu verwalten.

Schritt 1: GPS-Aktivitäts-Launcher erstellen

Erstellen wir zuerst einen Activity Launcher, um die IntentSender aus der CommissioningClient API zu verarbeiten.

  1. Öffnen Sie HomeScreen im Ordner java/com/google/homesampleapp/screens/home/.
  2. Ersetzen Sie den Kommentar // CODELAB: commissionDeviceLauncher definition durch den folgenden Code, um das Ergebnis der Inbetriebnahme-Aktivitä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 zum Inbetriebnehmen des Geräts 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. Anschließend wird commissionDevice() angerufen.

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

Schritt 3: API aufrufen

  1. Sie befinden sich noch immer in HomeScreen.kt im Ordner java/com/google/homesampleapp/screens/home.
  2. Ersetzen Sie den Kommentar // CODELAB: commissionDevice durch Folgendes: commissionDeviceRequest. Mit setCommissioningService wird AppCommissioningService an eine CommissioningService-Instanz gebunden, die in einer Rückruffunktion zurückgegeben wird. Wenn Sie einen benutzerdefinierten Dienst übergeben, werden Geräte mit dem Home Mobile SDK zuerst im lokalen Android-Netzwerk in Betrieb genommen. Anschließend wird die Onboarding-Nutzlast an AppCommissioningService zurückgesendet.
    val commissionDeviceRequest =
    CommissioningRequest.builder()
        .setCommissioningService(ComponentName(
            context, AppCommissioningService::class.java))
        .build()
  3. Rufe .getCommissioningClient() und dann .commissionDevice() an.
Matter.getCommissioningClient(context)
    .commissionDevice(commissionDeviceRequest)

Fügen Sie der Funktion commissionDevice ein addOnSuccessListener und ein addOnFailureListener hinzu:

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

5. Inbetriebnahmedienst erstellen

In der commissionDevice()-Funktion haben wir angefordert, einen CommissioningService von der CommissioningClient API abzurufen. In diesem Ablauf werden Geräte zuerst über die CommissioningClient API für die lokale Android-Struktur in Betrieb genommen. Anschließend wird ein Callback zurückgegeben, der das CommissioningRequestMetadata-Objekt enthält:

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

Jetzt müssen wir CommissioningService.Callback übernehmen und die erforderliche Funktionalität bereitstellen, um Geräte in unserer Beispiel-App in Betrieb zu nehmen. Hier ist ein Beispiel für eine einfache CommissioningService-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. Hier finden Sie einen kurzen Überblick über die Funktionen des Dienstes. Öffnen Sie AppCommissioningService in java/commissioning, um mitzumachen.

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.homesampleapp.chip.ChipClient

Schließlich enthält 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, mit dem wir Google Play-Dienste darüber 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 für das Entwicklungs-Fabric der App in Betrieb zu nehmen:

  1. Öffnen Sie AppCommissioningService in java/commissioning.
  2. Suchen Sie die Funktion onCommissioningRequested(). Wir haben eine Log-Nachricht bereitgestellt, in der die CommissioningRequestMetadata ausgegeben wird. Ersetzen Sie den Kommentar // CODELAB: onCommissioningRequested(), um die serviceScope-Coroutine zu starten und die deviceId abzurufen.
    // Perform commissioning on custom fabric for the sample app.
serviceScope.launch {
  val deviceId = devicesRepository.incrementAndReturnLastDeviceId()
  3. Führen Sie die Inbetriebnahme durch. Für diesen Schritt können wir die Geräteinformationen übergeben, die im CommissioningRequestMetadata-Objekt zurückgegeben werden. Die ChipClient verwendet diese Metadaten, um einen sicheren Kanal zwischen der GHSA for 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. Verwenden Sie commissioningServiceDelegate, um den Google Play-Diensten mitzuteilen, dass die Inbetriebnahme abgeschlossen ist. Übergeben Sie in .sendCommissioningComplete() die 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

Nachdem der gesamte erforderliche Code für die Inbetriebnahme in unserem lokalen Netzwerk vorhanden ist, können wir ihn 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 folgen Sie der Anleitung, um Ihr Gerät in Betrieb zu nehmen.

Nach Abschluss der Inbetriebnahme ist Ihr Gerät nun Teil von zwei Fabrics: dem lokalen Android-Fabric und Ihrem lokalen Entwicklungs-Fabric. Jedes Fabric hat eigene Anmeldedaten und eine eindeutige 64‑Bit-Fabric-ID.

6. Geräte steuern

Durch die Inbetriebnahme in einem Entwicklungs-Fabric können Sie die Bibliotheken aus dem Matter-Repository (connectedhomeip) verwenden, um 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 finden Sie unter ClustersHelper in java/clusters. Dieser Singleton-Helfer importiert die folgenden Bibliotheken, um auf Geräteinformationen zuzugreifen:

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

Wir können diese Klasse verwenden, um den On/Off-Cluster für ein Gerät abzurufen und dann .toggle aufzurufen:

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- oder ausschalten

Nachdem Sie ein Gerät in Betrieb genommen haben, wird die in CommissioningResult zurückgegebene Nutzlast dem DataStore 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 Cluster-Dienste auf eingehende Nachrichten. Nachdem ein Gerät in Betrieb genommen wurde, senden Matter-Clients Befehle über den sicheren Betriebskanal, der während der Inbetriebnahme des Geräts eingerichtet wurde.

Auf dem Gerät werden Pakete validiert, entschlüsselt und dann mit einem Callback gesendet. Callback-Funktionen enthalten die EndpointId, ClusterId und 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 verwenden Sie das Matter SDK und ClustersHelper, um ein Gerät ein- und auszuschalten.

  1. Rufen Sie DeviceViewModel in java/screens/device auf.
  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äterepository:
    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 von DeviceScreen aufgerufen:

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

Anwendung ausführen

Starten Sie die App, um Ihre Änderungen neu zu laden. Schalte dein Gerät auf dem Startbildschirm ein und aus.

7. Geräte für andere Ökosysteme freigeben

Die gemeinsame Nutzung eines Geräts wird in der Matter-Spezifikation als Multi-Admin-Ablauf bezeichnet.

In den vorherigen Schritten haben wir gelernt, dass mit dem Home Mobile SDK Geräte für das lokale Android-Netzwerk und für ein Entwicklernetzwerk für die Beispiel-App in Betrieb genommen werden können. Dies ist ein Beispiel für den Multi-Admin-Ablauf, bei dem Geräte für mehr als ein Netzwerk in Betrieb genommen werden können.

Möglicherweise möchten Sie Geräte jetzt für noch mehr Nutzer freigeben, insbesondere wenn in einem Haushalt jeder seine eigenen Vorlieben in Bezug auf Anwendungen und Plattformen hat.

Das Home Mobile SDK bietet diese Funktion in der ShareDeviceRequest API. Damit können Sie:

  1. Öffnen Sie ein temporäres Fenster für die Inbetriebnahme von Geräten.
  2. Ändern Sie den Status Ihrer Geräte, damit sie in einem anderen Fabric in Betrieb genommen werden können.
  3. Geräte über andere Apps und Ökosysteme steuern

In den nächsten Schritten verwenden Sie das Home Mobile SDK, um Geräte freizugeben.

Schritt 1: GPS-Aktivitäts-Launcher erstellen

Ähnlich wie beim Commissioning Activity Launcher, den wir beim Einrichten eines Entwicklungsstoffes erstellt haben, haben wir einen Share Device Activity Launcher erstellt, um die IntentSender aus der CommissioningClient API zu verarbeiten.

  1. Öffnen Sie DeviceScreen im Ordner java/com/google/homesampleapp/screens/device/.
  2. Ersetzen Sie den Kommentar // CODELAB: shareDeviceLauncher definition durch den folgenden Code, um das .shareDevice()-Aktivitätsergebnis 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 freigeben“ aus, indem er auf dem Gerätebildschirm auf die Schaltfläche „Freigeben“ klickt. Anschließend wird deviceViewModel aufgerufen, um ein Kopplungsfenster für die Gerätefreigabe zu öffnen.

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

Nachdem das Pairing-Fenster erfolgreich geöffnet wurde, teilt das deviceViewModel dies der Benutzeroberfläche mit. Die Kommunikation zwischen dem 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 DeviceScreen die Änderung am StateFlow-Objekt erkannt hat, wird der folgende Aufruf ausgeführt:

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

Schritt 3: API aufrufen

Jetzt können Sie die Aufgabe „Gerät freigeben“ starten.

  1. Öffnen Sie DeviceScreen.kt im Ordner java/com/google/homesampleapp/screens/device/.
  2. Suchen Sie die Funktion shareDevice(). Ersetzen Sie den // CODELAB: shareDevice-Kommentar durch ShareDeviceRequest. Das DeviceDescriptor enthält spezifische Informationen zum Gerät, z. B. die Hersteller‑ID, die Produkt‑ID und den Gerätetyp. In diesem Beispiel werden die Werte fest codiert.
    val shareDeviceRequest =
  ShareDeviceRequest.builder()
    .setDeviceDescriptor(DeviceDescriptor.builder().build())
    .setDeviceName("GHSAFM temp device name")
  3. Legen Sie CommissioningWindow und die 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() auf, verwenden Sie diesmal aber die .shareDevice() API.
    Matter.getCommissioningClient(context)
    .shareDevice(shareDeviceRequest)

Der Erfolgs-Callback der commissioningClient.shareDevice() API stellt den IntentSender bereit, der zum Starten der Geräteaktivität freigeben in den Google Play-Diensten verwendet werden soll.

  1. Fügen Sie ein addOnSuccessListener und ein addOnFailureListener hinzu, um die Funktion shareDevice zu vervollständigen. Bei Erfolg wird launch auf 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 mit anderen Ökosystemen teilen möchten, muss auf Ihrem Android-Gerät eine andere Plattform installiert sein. Wir haben eine weitere Instanz der Beispiel-App erstellt, die Sie als Ziel-Commissioner verwenden können.

Wenn Sie den Ziel-Commissioner auf Ihrem Android-Gerät installiert haben, prüfen Sie, ob Sie Ihr Matter-Gerät freigeben können. Die Ziel-Commissioning-App ist mit GHSAFM-TC gekennzeichnet.

Ihre Geräte können jetzt in drei Fabrics eingebunden werden:

  1. The Local Android fabric.
  2. Ihre Entwicklungsumgebung (diese App).
  3. Das ist der dritte Haushalt, mit dem du das Gerät gerade geteilt hast.

8. Nächste Schritte

Glückwunsch

Sie haben dieses Codelab erfolgreich abgeschlossen und gelernt, wie Sie Geräte mit dem Home Mobile SDK in Betrieb nehmen und freigeben.

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

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

Wenn Sie offizielle Informationen von Google zu technischen Fragen erhalten möchten, nutzen Sie das Smart Home Developer Forum:

Wenn Sie technischen Support von der Community erhalten möchten, verwenden Sie das Tag google-smart-home auf Stack Overflow: