Fehler bei Matter-Integrationen beheben

1. Hinweis

Matter ermöglicht eine nahtlose, plattformübergreifende Geräteeinrichtung und -steuerung für Endnutzer. Dies ist vor allem möglich, da mehrere Systemkomponenten im Hintergrund zusammenarbeiten. Die Fehlerbehebung bei solchen Systemen kann für neue Entwickler oft entmutigend sein. Deshalb haben wir eine Reihe von Tools und Techniken entwickelt, die Ihnen als Matter-Entwickler mit Google Home die Arbeit erleichtern.

In diesem Codelab werden drei Hauptkomponenten von Matter behandelt. Für jedes dieser Systeme stellt Google Entwicklern eine Reihe von Analysetools zur Fehlerbehebung zur Verfügung, die von Smartphones und Hubs erfasst werden:

Als Entwickler ist es für Sie von entscheidender Bedeutung, Probleme während des gesamten Geräteentwicklungszyklus zu minimieren. Nach der Einführung Ihres Projekts müssen Sie die Problemtrends für Geräte im Einsatz zusammenfassen und durch Softwareupdates beheben. In diesem Codelab werden Techniken behandelt, die Sie für beide Zwecke verwenden können.

Voraussetzungen

• Führen Sie den Leitfaden „Erste Schritte mit Matter“ mit einem funktionierenden Matter-Projekt und einer Geräteeinrichtung durch.
• Ein Android-Smartphone, das Sie mit Ihrer Workstation verbinden können (für ADB-Protokolle)

Aufgaben in diesem Lab

• So verwenden Sie Analysetools für Smart Home, um Matter-Probleme im großen Maßstab zu überwachen.
• So triagieren Sie Fehler, indem Sie auf Fehlerprotokolle zugreifen und Informationen erfassen.
• Matter-Dokumentation und Supportressourcen aufrufen, um Hilfe zu erhalten

2. Google Home Analytics aufrufen

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

Auf Projektmesswerte zugreifen

• Rufen Sie zuerst die Google Home-Dashboards auf, um auf Ihre Daten zuzugreifen. Melden Sie sich dazu in der Google Cloud Console an und gehen Sie zu Verwaltung > Monitoring > Dashboards.

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

Derzeit gibt es ein allgemeines Dashboard, das Ihr gesamtes Projekt abdeckt, 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 sowie ein funktionierendes Projekt, das Anfragen erfüllt, haben.

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

Google Home-Dashboards enthalten verschiedene Diagramme mit Details zu den Ereignissen, die mit Ihrem Projekt verknüpft sind. Für jedes Integrations-Dashboard sehen Sie ein Diagramm mit der Gesamtzahl der von Ihrem Projekt bearbeiteten Anfragen, ein Diagramm mit der Erfolgsquote für diesen Integrationstyp und mehrere Diagramme mit den beteiligten Gerätetypen und Merkmalen. Außerdem haben Sie mit Matter eine Reihe von Diagrammen, mit denen Sie den Erfolg der Inbetriebnahme sowie die Einführung von Updates auf Ihren Geräten verfolgen können.

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

Auf Fehlerprotokolle zugreifen

Der Log-Explorer ist eine Sammlung von Tools zum Arbeiten mit Ereignisprotokollen, die in einem Projekt generiert wurden. Sie können in der Google Cloud Console unter Vorgänge > Logging > Log-Explorer darauf zugreifen.

Nachdem Sie den Log-Explorer geöffnet haben, sieht die Ansicht so aus:

Das Explorer-Fenster enthält verschiedene Tools zum Anzeigen, Filtern, Abfragen und Analysieren von Logs. Standardmäßig werden in dieser Ansicht Protokolle von allen Systemen angezeigt, die für Ihr Projekt verfügbar sind, auch solche, die außerhalb von Smart Home generiert wurden. Deshalb ist es wichtig, diese Protokolle zu verwenden und nach Ereignissen zu filtern, die Sie beheben möchten. In den Abschnitten zur Fehlerbehebung werden wir näher darauf eingehen.

3. Probleme bei der Inbetriebnahme beheben

Der erste Messwerttyp, den wir uns ansehen, bezieht sich auf Matter-Inbetriebnahmeereignisse. Inbetriebnahme bezieht sich auf die Schritte, die Nutzer ausführen müssen, um ein Matter-Gerät zum ersten Mal einzurichten.

Bei der Inbetriebnahme des Geräts finden eine Reihe von Interaktionen zwischen dem Matter-Gerät, der Google Home App und dem Matter-Gewebe statt. Die folgende Abbildung zeigt einige dieser Ereignisse:

Weitere Informationen zu den einzelnen Schritten finden Sie auf der Seite zur Inbetriebnahme im Matter-Leitfaden. In diesem Abschnitt werden die Tools und Techniken zur Behebung von Problemen bei der Inbetriebnahme beschrieben.

Google Home Analytics verwenden

Wir haben eine Reihe von Messwerten erstellt, mit denen Sie Probleme bei der Inbetriebnahme untersuchen können, indem Sie Ereignisse erfassen und nachvollziehen, in welcher Phase die Fehler auftreten. Sie finden sie im Matter-Integrations-Dashboard, wie im vorherigen Abschnitt beschrieben.

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

Im Diagramm „Geräteanzahl“ sehen Sie die Anzahl der Inbetriebnahmeversuche von Nutzern an einem bestimmten Datum. Die Erfolgsquote zeigt die wahrgenommene Erfolgsquote für diese Ereignisse auf Google-Seite an. Bei jedem Inbetriebnahmeversuch wird eine Reihe von Ereignissen mit zugehörigen Status generiert. Wenn in einem dieser Status ein Fehler auftritt, wird er auch im Fehleraufschlüsselungsdiagramm 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 Provisionsfehlern filtern möchten, können Sie im Abfragefeld nach „clientUpdateLog“ und „severity>=ERROR“ suchen.

Ein Fehlerprotokoll für die Inbetriebnahme von Matter 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"
}

Ein Fehlerprotokoll enthält neben dem Status der Inbetriebnahme und einem Statuscode auch Zeitstempel für den aufgezeichneten Fehler sowie die Matter-Produkt-ID, anhand derer Sie ermitteln können, welches Ihrer Produkte den Fehler verursacht hat. Die Logs, die aus demselben Inbetriebnahmeversuch generiert wurden, haben eine gemeinsame sessionId.

Anhand der Messwerte von Google Home Analytics können Sie sich eine erste Vorstellung 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 in einigen Fällen zusätzliche Fehlerbehebungen anhand der Protokolle durchführen, die von dem für den Inbetriebnahmeprozess verwendeten Mobilgerät generiert wurden. Dafür benötigen Sie die Android Debug Bridge.

Android Debug Bridge (ADB) verwenden

Eine weitere Möglichkeit zur Behebung von Problemen bei der Inbetriebnahme ist das Befehlszeilentool „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 wurden.

Plattformtools installieren

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

Nachdem Sie die Plattformtools auf Ihrem System installiert haben, prüfen Sie ADB. Rufen Sie dazu im Terminal die Versionsnummer mit dem folgenden Befehl auf:

$ adb -- version

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

USB-Debugging aktivieren

Aktivieren Sie als Nächstes die USB-Fehlerbehebung auf Ihrem Android-Gerät.

Aktivieren Sie zuerst die Entwickleroptionen auf Ihrem Gerät und dann das USB-Debugging.

Dadurch kann ADB auf Protokolle 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. Verbinde dein Smartphone mit dem Computer, auf dem der ADB-Server ausgeführt wird.

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

3. Klicken Sie in diesem Fall auf Zulassen.
4. Führen Sie über das Terminal einen Befehl zum Auflisten von Geräten aus, um zu prüfen, ob Ihr Computer über ADB auf das Telefon zugreifen kann. Verwenden Sie dazu den folgenden Befehl:

$ adb devices

Sie sollten eine Antwort ähnlich der folgenden erhalten:

List of devices attached
<phone-id>    device

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

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

Systeminformationen erheben

Als Nächstes überprüfen Sie 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 Steuermodule für Smart Home/Matter ü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 System unterstützt werden. Wenn Sie sich bei Problemen mit der Inbetriebnahme an uns wenden, geben Sie bitte immer Systeminformationen in Ihren Support-Tickets an.

Fehlerprotokolle erfassen

Starten Sie als Nächstes die Protokollerstellung und führen Sie dann die Schritte zur Inbetriebnahme aus, um die Fehlerereignisse zu generieren, die Sie beheben möchten.

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

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

Dadurch wird sofort mit der Protokollierung begonnen. Eine Datei mit dem angegebenen Namen wird erstellt, sofern sie noch nicht vorhanden ist. Nach jedem Ereignis werden der Datei Protokolle vom Telefon hinzugefügt.

Fahren Sie mit den Schritten zur Inbetriebnahme Ihres Matter-Geräts fort.

2. Wenn Sie den Fehler gefunden haben, den Sie beheben möchten, beenden Sie die Protokollierung, indem Sie im geöffneten Terminalfenster die Taste Control+C drücken.

Ihre Protokolle sollten jetzt in der Protokolldatei <file-name> gespeichert sein. Da bei diesem Vorgang Protokolle von allen laufenden Prozessen auf dem Gerät aufgezeichnet werden, enthält diese Datei viele Protokolle. Daher sollten Sie diese Protokolle immer verwenden und nach den benötigten Einträgen suchen.

Fehlerlogs analysieren

In GHA läuft die Inbetriebnahme über ein Subsystem namens MatterCommissioner.

1. Suchen Sie mit dem folgenden Befehl nach Fehlern, die vom MatterCommissioner-Subsystem generiert wurden:

$ grep "MatterCommissioner" <file-name>

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

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

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

Achten Sie beim Analysieren der Protokolldatei, die durch den ADB-Debugging-Prozess generiert wurde, 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 Meldung zu einem Fehler bei der Inbetriebnahme:

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

4. Probleme mit der Gerätesteuerung beheben

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

Da die Steuerungsspezifikation zwischen Endgeräten und Google-Hubs über Matter vermittelt wird, sollte es bei der Gerätesteuerung weniger Fehler geben. Unabhängig davon stellen wir Ihnen Messwerte und Protokolle zur Verfügung, mit denen Sie diese Arten von Problemen beheben können.

Messwerte verwenden

Im Matter-Integrations-Dashboard sehen Sie mehrere Messwerte zur Gerätesteuerung. Es gibt drei Diagramme, die für die Beurteilung der Leistung Ihrer Geräte vor Ort entscheidend sind:

Bei Problemen mit der Steuerung ist der Prozentsatz der erfolgreichen Zugriffe in der Regel rückläufig und der im Diagramm mit der Fehleraufschlüsselung zu sehende Aufwärtstrend ist typisch. Im Diagramm zur Fehleraufschlüsselung sehen Sie, warum die Gerätesteuerung fehlgeschlagen ist, die von Google Nest Hubs erfasst wurden.

Protokolle verwenden

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

Fehlerprotokolle 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 Fehlerprotokoll enthält einen Zeitstempel, einen Gerätetyp und ein Merkmal sowie den Fehler, der mit der Steueranfrage in der statusType verknüpft ist. Viele Steuerelementfehler enthalten auch eine externalDebugString, eine kurze Fehlermeldung, in der der Fehler erläutert wird.

5. Fehler in anderen Funktionen beheben

Bisher haben Sie gelernt, wie Sie Probleme bei der Geräteeinrichtung und -steuerung für Matter beheben. Es gibt auch andere Funktionen im System, bei denen Sie unsere empfohlenen Methoden anwenden können, um eine gute Qualität der Integration zu gewährleisten.

OTA-Updates verfolgen

Um die Veröffentlichungen von Over-the-Air-Updates (OTA) für Matter-Geräte von Google Home zu verfolgen, stellen wir eine Reihe von Messwerten bereit, die die Hardware- und Softwareversionen der Geräte in der Praxis anzeigen.

Wenn Sie ein Update über die Console ausführen, sollten Sie die folgenden Messwerte im Blick behalten:

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

6. Support anfordern

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

Entwicklerkanäle besuchen

Bei Google gibt es drei Entwicklerkanäle, die aktiv überwacht werden:

Jeder dieser Kanäle wird regelmäßig vom selben Team überwacht. Es gibt jedoch einige wichtige Unterschiede im Hinblick darauf, wann der jeweilige Kanal verwendet wird.

• Stack Overflow:Wenn Sie Fragen zur Implementierung haben oder Unterstützung benötigen, können Sie sich an uns und die Smart-Home-Entwickler-Community wenden. In diesem Kanal kannst du fragen, wie du Probleme beheben oder eine bestimmte Funktion implementieren kannst.
• Issue Tracker: Das offizielle Issue-Tracker-System von Google, über das externe Nutzer Fehler im System melden können. Es bietet Webtools, mit denen Sie bei Bedarf Dateien anhängen und vertrauliche Informationen freigeben können. Mit dem Issue Tracker können Sie am besten Probleme mit dem Werbesystem melden oder Funktionsanfragen stellen.
• Entwicklerforum: Wenn Sie Hilfe vom offiziellen Google-Support und von Community-Experten benötigen, können Sie sich über das Nest-Entwicklerforum an uns wenden. In diesem Forum erhalten Sie offizielle Informationen zur Entwicklung.

Newsletter für Entwickler abonnieren

Neben den Entwicklerkanälen, in denen Sie Fragen stellen können, veröffentlichen wir auch vierteljährlich einen Newsletter mit Informationen zu neuen Funktionen und dem aktuellen Stand des Google Smart Home-Ökosystems.

Sie können das Anmeldeformular verwenden, um den Entwicklernewsletter zu erhalten.

7. Glückwunsch

Glückwunsch! Du hast gelernt, wie du Matter-Integrationen mithilfe der von uns empfohlenen Tools und Techniken debuggen kannst. Wir wünschen Ihnen viel Erfolg beim Erstellen von Matter-Integrationen mit Google Home.

Weiteres Vorgehen

Probieren Sie die folgenden Übungen aus und nutzen Sie zusätzliche Ressourcen:

• Neben der Analyse zur Fehlerbehebung können Sie auch die Test Suite verwenden, um Ihre Integration auf potenzielle Probleme zu testen.
• Sobald Ihre Integration bereit ist, mit der Welt geteilt zu werden, ist der nächste Schritt die Zertifizierung Ihres Projekts für die weltweite Verfügbarkeit von Inhalten. Folgen Sie dazu der Anleitung auf der Seite Zertifizierung.