Fehler bei Matter-Integrationen beheben

1. Hinweis

Matter bietet Endnutzern eine nahtlose, plattformübergreifende Einrichtung und Steuerung von Geräten. Das ist vor allem durch die vielen Ökosystemkomponenten möglich, die im Hintergrund zusammenarbeiten. Die Fehlerbehebung bei solchen Systemen kann für neue Entwickler oft schwierig sein. Deshalb haben wir eine Reihe von Tools und Techniken entwickelt, um dir als Matter-Entwickler mit Google Home das Leben zu erleichtern.

In diesem Codelab werden drei Hauptkomponenten für Matter behandelt. Für jedes dieser Systeme stellt Google eine Reihe von Analysen zur Fehlerbehebung für Entwickler bereit, die von Smartphones und Hubs erhoben werden:

Als Entwickler ist es wichtig, dass Sie Probleme, die während des Geräteentwicklungszyklus auftreten, beheben können. Nachdem Sie Ihr Projekt gestartet haben, müssen Sie die Problemtrends für Geräte im Feld aggregiert überwachen und sie durch Softwareupdates beheben. In diesem Codelab werden Techniken behandelt, die Sie für beide Zwecke verwenden können.

Vorbereitung

• Führen Sie die Schritte im Startleitfaden für Matter aus. Sie benötigen ein funktionierendes Matter-Projekt und ein eingerichtetes Gerät.
• Sie haben ein Android-Smartphone, das Sie mit Ihrer Workstation verbinden können (für ADB-Logs).

Lerninhalte

• Analysetools für Smart Home verwenden, um Matter-Probleme im großen Maßstab zu beobachten
• So beheben Sie Fehler, indem Sie auf Fehlerlogs zugreifen und Informationen sammeln.
• So greifen Sie auf die Matter-Dokumentation und Supportressourcen zu, um Hilfe zu erhalten.

2. Google Home-Analysen aufrufen

Die Leistungsüberwachung ist entscheidend für eine erfolgreiche Integration in das Google Home-Ökosystem. Wir stellen Smart-Home-Entwicklern eine Reihe von Monitoring-Tools auf der Google Cloud Platform zur Verfügung. Mit diesen Tools können Sie die Leistung Ihres Projekts messen.

Auf Projektmesswerte zugreifen

• Der erste Schritt, um auf Ihre Daten zuzugreifen, besteht darin, die Google Home-Dashboards aufzurufen. Melden Sie sich dazu in der Google Cloud Console an und rufen Sie Vorgänge > Monitoring > Dashboards auf.

Für Ihr Projekt sind mehrere Dashboards verfügbar, darunter auch für andere GCP-Produkte. Die für das Smart Home bereitgestellten Dashboards haben das Präfix „Google Home Analytics“.

Derzeit gibt es ein allgemeines Dashboard für Ihr gesamtes Projekt sowie Dashboards für bestimmte Integrationen (Cloud, Lokal, Matter) oder Gerätetypen (Kameras). Diese Dashboards enthalten nur Daten, wenn Sie eine Integration des entsprechenden Typs haben und ein funktionierendes Projekt, das Anfragen erfüllt.

Wenn Sie eines dieser Dashboards öffnen, sehen Sie eine Reihe von Diagrammen, die so aussehen:

Google Home-Dashboards enthalten verschiedene Diagramme mit Details zu den Ereignissen, die mit Ihrem Projekt verknüpft sind. Auf jedem Integrationsdashboard sehen Sie ein Diagramm mit der Gesamtzahl der von Ihrem Projekt verarbeiteten Anfragen, ein Diagramm mit der Erfolgsrate für diesen Integrationstyp und mehrere Diagramme mit den beteiligten Gerätetypen und Eigenschaften. Außerdem stehen Ihnen mit Matter Diagramme zur Verfügung, in denen der Erfolg der Inbetriebnahme sowie die Einführung von Updates auf Ihren Geräten nachverfolgt werden.

Die Standardansicht mit den Diagrammen, die Sie in den Google Home Analytics-Dashboards sehen, ist nur eine Ansicht, die wir für Ihr Projekt mit Smart-Home-Messwertdaten erstellt haben. Sie können auch mit dem Metrics Explorer eigene Diagramme aus denselben zugrunde liegenden Messwerten erstellen und in Ihren benutzerdefinierten Dashboards speichern.

Auf Fehlerlogs zugreifen

Der Log-Explorer ist eine Sammlung von Tools zum Arbeiten mit Ereignislogs, die für ein Projekt generiert werden. Sie können darauf in der Google Cloud Console zugreifen, indem Sie zu Operations > Logging > Log-Explorer navigieren.

Wenn Sie den Log-Explorer öffnen, sehen Sie eine Ansicht wie die folgende:

Das Explorer-Fenster enthält verschiedene Tools zum Ansehen, Filtern, Abfragen und Analysieren von Logs. Standardmäßig werden in dieser Ansicht Logs aus allen Systemen angezeigt, die für Ihr Projekt verfügbar sind, einschließlich Logs, die außerhalb von Smart Home generiert werden. Daher ist es wichtig, diese Logs zu verwenden und nach Ereignissen zu filtern, die Sie debuggen möchten. Darauf gehen wir in den Abschnitten zum Debugging noch genauer ein.

3. Probleme bei der Inbetriebnahme beheben

Die erste Art von Messwerten, die wir uns ansehen, bezieht sich auf Matter-Inbetriebnahmen. Die Inbetriebnahme umfasst die Schritte, die ein Nutzer ausführen muss, um ein Matter-Gerät zum ersten Mal einzurichten.

Bei der Inbetriebnahme eines Geräts findet eine Reihe von Interaktionen zwischen dem Matter-Gerät, der Google Home App und dem Matter-Netzwerk statt. Das folgende Bild zeigt einige dieser Ereignisse:

Weitere Informationen zu den einzelnen Schritten findest du auf der Seite zur Inbetriebnahme im Matter-Primer. In diesem Abschnitt werden die Tools und Techniken zur Fehlerbehebung bei der Inbetriebnahme behandelt.

Google Home Analytics verwenden

Wir haben eine Reihe von Messwerten erstellt, mit denen Sie Probleme bei der Inbetriebnahme untersuchen können. Dazu werden Ereignisse erfasst und es wird ermittelt, in welcher Phase die Fehler auftreten. Wie im vorherigen Abschnitt beschrieben, finden Sie diese im Matter Integration Dashboard.

Die Diagramme in diesem Dashboard enthalten Daten zur Geräteinbetriebnahme:

Im Diagramm zur Geräteanzahl sehen Sie die Anzahl der Inbetriebnahmen durch Nutzer an einem bestimmten Datum. Die Erfolgsrate gibt die wahrgenommene Erfolgsrate für diese Ereignisse auf Google-Seite an. Bei jedem Inbetriebnahmemanöver wird eine Reihe von Ereignissen mit zugehörigen Status generiert. Wenn in einem dieser Status ein Fehler auftritt, wird er auch im Diagramm zur Fehleraufschlüsselung erfasst.

Inbetriebnahmestatus:

• COMMISSIONING_STARTED
• ONBOARDING_PAYLOAD_GENERATED
• LOCAL_DISCOVERY_SUCCESSFUL
• PASE_CONNECTION_SUCCESSFUL
• NOC_ADDED_SUCCESSFULLY
• COMMISSIONING_COMPLETE

Eine detaillierte Version dieser Ereignisse finden Sie unter Vorgänge > Logging > Log-Explorer. Wenn Sie nach Inbetriebnahmefehlern filtern möchten, können Sie im Abfragefeld nach „clientUpdateLog“ in Kombination mit „severity>=ERROR“ suchen.

Ein Fehlerlog für die Matter-Inbetriebnahme sieht so aus:

{
  "insertId": "1a32ry0f6xpzzn",
  "jsonPayload": {
    "clientUpdateLog": {
      "MatterUpdate": {
        "reportedProductId": 55,
        "sessionId": "1584879052892229997",
        "reportedVendorId": 4800,
        "commissioningState": "GENERIC_COMMISSIONING_ERROR",
        "status": "GENERIC_ERROR"
      }
    }
  },
  "resource": {
    "type": "assistant_action_project",
    "labels": {
      "project_id": "<project-id>"
    }
  },
  "timestamp": "2023-03-01T07:09:55.216425297Z",
  "severity": "ERROR",
  "logName": "projects/<project-id>/logs/assistant_smarthome%2Fassistant_smarthome_logs",
  "receiveTimestamp": "2023-03-01T07:09:55.216425297Z"
}

Neben dem Inbetriebnahmezustand und einem Statuscode enthält ein Fehlerlog Zeitstempel für den erfassten Fehler sowie die Matter-Produkt-ID, mit der Sie ermitteln können, welches Ihrer Produkte den Fehler verursacht hat. Die Logs, die beim selben Inbetriebnahmemanöver generiert werden, haben dieselbe sessionId.

Anhand von Messwerten aus Google Home Analytics können Sie sich ein Bild davon machen, in welcher Phase das Problem auftreten könnte. Um die Ursache für Fehler bei der Geräteinbetriebnahme zu finden, müssen Sie manchmal zusätzliche Fehlerbehebungen mithilfe der Protokolle durchführen, die vom Mobilgerät generiert werden, das bei der Inbetriebnahme verwendet wird. Dafür benötigen Sie die Android Debug Bridge.

Android Debug Bridge (ADB) verwenden

Eine weitere Möglichkeit zur Fehlerbehebung bei der Inbetriebnahme ist die Verwendung des Befehlszeilentools Android Debug Bridge (ADB). Da die Inbetriebnahme hauptsächlich zwischen dem Mobilgerät und dem Matter-Gerät erfolgt, können Sie mit dem ADB-Tool auf Protokolle zugreifen, die während der Inbetriebnahme von der Google Home App generiert werden.

Plattformtools installieren

ADB ist Teil der Android SDK-Plattformtools, die mit Android Studio oder über das Befehlszeilentool sdkmanager installiert werden können.

Nachdem Sie die Plattformtools auf Ihrem System installiert haben, prüfen Sie ADB, indem Sie die Versionsnummer über das Terminal mit dem folgenden Befehl aufrufen:

$ adb -- version

Die Versionsnummer des installierten ADB-Tools sollte ohne Fehler angezeigt werden.

USB-Debugging aktivieren

Als Nächstes müssen Sie das USB‑Debugging auf Ihrem Android-Gerät aktivieren.

Folge zuerst der Anleitung zum Aktivieren der Entwickleroptionen auf deinem Gerät und aktiviere dann das USB‑Debugging.

Dadurch kann ADB auf Logs zugreifen, die von Apps generiert werden, die derzeit auf dem Gerät ausgeführt werden.

Geräte-ID abrufen

1. Führen Sie den ADB-Server mit dem folgenden Befehl aus:

$ adb start-server

2. Verbinden Sie Ihr Smartphone mit dem Computer, auf dem der ADB-Server ausgeführt wird.

Möglicherweise erhalten Sie auf Ihrem Smartphone eine Warnmeldung zum USB-Debugging, in der Sie gefragt werden, ob Sie Ihrem Computer den Zugriff auf Informationen von Ihrem Smartphone erlauben möchten:

3. Wenn Sie diese Warnmeldung erhalten, klicken Sie auf Zulassen.
4. Geben Sie im Terminal den Befehl „list devices“ ein, um zu prüfen, ob Ihr Computer über ADB auf das Smartphone zugreifen kann:

$ adb devices

Sie sollten eine Antwort ähnlich der folgenden erhalten:

List of devices attached
<phone-id>    device

Ihre <phone-id> ist ein alphanumerischer String, der Ihr Gerät eindeutig identifiziert.

5. Merken Sie sich den Wert <phone-id> für die nächsten Schritte.

Systeminformationen erfassen

Prüfen Sie als Nächstes die Versionsinformationen der Apps und des Systems auf Ihrem Gerät.

• So prüfen Sie die Android-Version:

$ adb -s <phone-id> shell getprop ro.build.version.release

• So prüfen Sie die Version der Google Home App:

$ adb -s <phone-id> shell dumpsys package com.google.android.apps.chromecast.app | grep versionName

• So prüfen Sie die Version der Google Play-Dienste:

$ adb -s <phone-id> shell dumpsys package com.google.android.gms | grep "versionName"

• So prüfen Sie, ob Sie die Module für die Steuerung von Smart-Home-Geräten und Matter-Geräten über die Play-Dienste haben:

$ adb -s <phone-id> shell dumpsys activity provider com.google.android.gms.chimera.container.GmsModuleProvider | grep "com.google.android.gms.home"

Achten Sie darauf, dass diese Rückgabewerte von unserem Ökosystem unterstützt werden. Wenn Sie sich wegen Fehlern bei der Inbetriebnahme an den Support wenden, geben Sie in Ihren Supporttickets bitte immer Systeminformationen an.

Fehlerprotokolle erfassen

Starten Sie als Nächstes die Protokollerfassung und führen Sie dann die Inbetriebnahmeschritte aus, um die Fehlerereignisse zu generieren, die Sie debuggen möchten.

1. Führen Sie den folgenden Befehl aus und geben Sie Ihre <phone-id> sowie einen <file-name> an, in dem die Logs auf Ihrem Computer gespeichert werden (z. B. debug_file.txt) verwenden.

$ adb -s <phone-id> logcat > <file-name>

Dadurch wird der Protokollierungsvorgang sofort gestartet. Wenn noch keine Datei mit dem angegebenen Namen vorhanden ist, wird eine solche Datei erstellt. Nach jedem Ereignis werden der Datei Logs vom Smartphone hinzugefügt.

Fahre mit der Einrichtung deines Matter-Geräts fort.

2. Wenn Sie den Fehler gefunden haben, den Sie debuggen möchten, beenden Sie das Logging, indem Sie im ausgeführten Terminalfenster Control+C drücken.

Ihre Logs sollten jetzt in der Logdatei <file-name> gespeichert werden. Da bei diesem Vorgang Logs von jedem laufenden Prozess aufgezeichnet werden, der auf dem Gerät verfolgt wird, enthält diese Datei viele Logs. Daher sollten Sie diese Protokolle immer nutzen, indem Sie nach den benötigten Einträgen suchen.

Fehlerlogs analysieren

Inbetriebnahmeprozesse werden über ein Subsystem namens „MatterCommissioner“ in GHA abgewickelt.

1. Suchen Sie mit dem folgenden Befehl nach Fehlern, die vom MatterCommissioner-Subsystem generiert wurden. Gehen Sie dabei nach der Hauptstrategie vor, die bei der Analyse von Inbetriebnahmefehlern verwendet wird:

$ grep "MatterCommissioner" <file-name>

Dadurch wird eine Ausgabe mit den Ereignissen aus dem Inbetriebnahmevorgang generiert.

2. Wenn Ihr Matter-Gerät Thread verwendet, können Sie auch mit dem folgenden Befehl nach Fehlern suchen, die vom Thread-Subsystem generiert wurden:

$ grep -E "(ThreadNetworkManager|BorderAgentScannerImpl|ThreadBrSynchronizer)" <file-name>

Achten Sie bei der Analyse der vom ADB-Debuggingprozess generierten Protokolldatei auch auf bestimmte Muster. Viele Fehler bei der Inbetriebnahme enthalten den String „commissioning failure“ in der Fehlermeldung.

3. Suchen Sie mit dem folgenden Befehl nach einer Fehlermeldung zur Inbetriebnahme:

$ grep "SetupDevice" $phonelog | grep -A 20 "Commissioning failed"

4. Probleme mit der Gerätesteuerung beheben

Nachdem Nutzer Matter-Geräte im Google Home-Ökosystem eingerichtet und in Betrieb genommen haben, können sie Befehle per Sprachbefehl über Google Assistant (z. B. „Hey Google, schalte das Licht in meinem Wohnzimmer ein“) oder über die Benutzeroberfläche in der Home App oder auf Google Nest-Displays ausführen.

Da die Steuerungsspezifikation zwischen Endgeräten und Google-Hubs über Matter erfolgt, sind weniger Fehler bei der Gerätesteuerung zu erwarten. Wir stellen Ihnen jedoch Messwerte und Logs zur Verfügung, mit denen Sie auch diese Art von Problemen beheben können.

Messwerte verwenden

Im Matter-Integrations-Dashboard sehen Sie verschiedene Messwerte zur Gerätesteuerung. Es gibt drei Diagramme, die für die Bewertung der Leistung Ihrer Geräte im Feld entscheidend sind:

Bei Problemen mit der Kontrollgruppe sehen Sie in der Regel einen Abwärtstrend beim Prozentsatz der erfolgreichen Aktionen und einen Aufwärtstrend im Diagramm zur Fehleraufschlüsselung. Im Diagramm zur Fehleraufschlüsselung sehen Sie die von Google Nest Hubs erfassten Fehler, die dazu geführt haben, dass der Versuch zur Gerätesteuerung fehlgeschlagen ist.

Logs verwenden

Bei jedem Problem mit der Matter-Gerätesteuerung wird auch ein Fehlerlog im System generiert. Diese Fehler können im Log-Explorer herausgefiltert werden, indem Sie nach „executionLog“ suchen.

Fehlerlogs für die Matter-Gerätesteuerung sehen so aus:

{
  "insertId": "1a32ry0f6xpzzn",
  "jsonPayload": {
    "executionLog": {
      "executionResults": [
        {
          "executionType": "MATTER",
          "latencyMsec": "6000",
          "actionResults": [
            {
              "action": {
                "actionType": "ONOFF_OFF",
                "trait": "TRAIT_ON_OFF"
              },
              "status": {
                "externalDebugString": "No message was received before the deadline.",
                "statusType": "RESPONSE_TIMEOUT",
                "fallbackToCloud": false,
                "isSuccess": false
              },
              "device": {
                "deviceType": "OUTLET"
              }
            }
          ],
          "requestId": "1487232799486580805"
        }
      ]
    },
    "locale": "en-US"
  },
  "resource": {
    "type": "assistant_action_project",
    "labels": {
      "project_id": "<project-id>"
    }
  },
  "timestamp": "2023-03-01T15:47:27.311673018Z",
  "severity": "ERROR",
  "logName": "projects/<project-id>/logs/assistant_smarthome%2Fassistant_smarthome_logs",
  "receiveTimestamp": "2023-03-01T15:47:27.311673018Z"
}

Jedes Fehlerlog enthält einen Zeitstempel, einen Gerätetyp und ein Attribut sowie den mit der Steuerungsanfrage verknüpften Fehler in der statusType. Viele Steuerungsfehler enthalten auch ein externalDebugString, eine kurze Fehlermeldung, die den Fehler beschreibt.

5. Fehlerbehebung bei anderen Funktionen

Bisher haben Sie gelernt, wie Sie Probleme bei der Inbetriebnahme und Steuerung von Matter-Geräten beheben. Es gibt auch andere Funktionen im Ökosystem, die Sie verwenden können, oder empfohlene Techniken, um eine hochwertige Integration zu gewährleisten.

OTA-Updates im Blick behalten

Um die von Google Home ausgegebenen Releases für Over-the-Air-Updates (OTA) für Matter-Geräte zu verfolgen, stellen wir eine Reihe von Messwerten bereit, die die Hardware- und Softwareversionen der Geräte im Feld zeigen.

Nachdem Sie ein Update über die Console veröffentlicht haben, sollten Sie die folgenden Messwerte im Blick behalten:

In den Tagen nach der Veröffentlichung erhalten immer mehr Geräte im Feld die neue Softwareversion, die mit Ihrer OTA-Softwareversion verknüpft ist.

6. Support kontaktieren

Google stellt Tools und Dokumentationen zur Verfügung, mit denen du Matter-Probleme beheben kannst. Da das Matter-Ökosystem jedoch neu ist, gibt es möglicherweise Probleme, die in diesen Ressourcen nicht behandelt werden. In diesen Fällen können Sie sich jederzeit an uns oder die Community wenden, um Unterstützung zu erhalten.

Entwicklerversionen verwenden

Bei Google werden drei Entwicklerkanäle aktiv überwacht:

Alle diese Kanäle werden regelmäßig vom selben Team überwacht. Es gibt jedoch einige wichtige Unterschiede, wann welcher Kanal verwendet werden sollte.

• Stack Overflow:Hier können Sie uns und die Smart Home-Entwickler-Community bei Fragen zur Implementierung kontaktieren oder um Rat fragen. Dieser Kanal ist am besten geeignet, um Fragen zur Fehlerbehebung oder zur Implementierung einer bestimmten Funktion zu stellen.
• Issue Tracker:Dies ist das offizielle von Google betriebene Issue-Tracker-System, in dem externe Nutzer Fehler im Ökosystem melden können. Sie bietet Weboberflächen, über die Sie bei Bedarf Dateien anhängen und vertrauliche Informationen teilen können. Die Problemverfolgung ist die beste Möglichkeit, Probleme im Ökosystem zu melden oder Feature Requests zu teilen.
• Entwicklerforum:Wenn Sie Unterstützung vom offiziellen Google-Support und von Community-Experten benötigen, können Sie sich über das Nest-Entwicklerforum an uns wenden. Dieses Forum eignet sich am besten, um offizielle Anleitungen für die Entwicklung zu erhalten.

Newsletter für Entwickler*innen abonnieren

Neben den Entwicklerkanälen, in denen Sie Fragen stellen können, veröffentlichen wir auch einen vierteljährlichen Newsletter, in dem wir neue Funktionen vorstellen und über den aktuellen Stand des Google Smart Home-Ökosystems informieren.

Hier können Sie sich für den Entwickler-Newsletter anmelden.

7. Glückwunsch

Glückwunsch! Sie haben erfolgreich gelernt, wie Sie Matter-Integrationen mit den von uns empfohlenen Tools und Techniken debuggen. Wir wünschen Ihnen viel Erfolg bei der Entwicklung von Matter-Integrationen mit Google Home.

Nächste Schritte

Hier finden Sie einige Übungen und zusätzliche Ressourcen:

• Neben der Verwendung von Analysen zur Fehlerbehebung können Sie auch die Test Suite verwenden, um Ihre Integration auf potenzielle Probleme zu testen.
• Wenn Ihre Integration bereit ist, mit der Welt geteilt zu werden, müssen Sie Ihr Projekt als NWWGH-zertifiziert kennzeichnen lassen. Folgen Sie dazu der Anleitung auf der Seite Zertifizierung.