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. Fehlerbehebungssysteme wie diese können für neue Entwickler oft einschüchternd sein. Deshalb haben wir eine Reihe von Tools und Techniken entwickelt, die dir das Leben als Matter-Entwickler mit Google Home erleichtern.

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

Als Entwickler ist es für Sie von entscheidender Bedeutung, Probleme während des gesamten Geräteentwicklungszyklus zu minimieren. Sobald Sie Ihr Projekt starten, müssen Sie die Problemtrends für Geräte, die im Einsatz sind, aggregiert beobachten und durch Softwareupdates beheben. In diesem Codelab werden Methoden beschrieben, die Sie für beide Zwecke verwenden können.

Voraussetzungen

• Schließe den Leitfaden Erste Schritte mit Matter mit einem funktionierenden Matter-Projekt und der Geräteeinrichtung ab.
• Du benötigst ein Android-Smartphone, das du mit deiner Workstation verbinden kannst (für ADB-Protokolle).

Aufgaben in diesem Lab

• Mit Analysetools für Smart Homes Matter-Probleme im großen Maßstab im Blick behalten
• Anleitung zum Erkennen von Fehlern durch Zugreifen auf Fehlerprotokolle und Erfassen von Informationen.
• Matter-Dokumentation und Supportressourcen aufrufen, um Hilfe zu erhalten

2. Google Home Analytics aufrufen

Die Leistungsüberwachung ist entscheidend für eine erfolgreiche Integration in die Google Home-Plattform. 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

• Der erste Schritt für den Zugriff auf Ihre Daten besteht darin, die Google Home-Dashboards zu prüfen. Melden Sie sich dazu in der Google Cloud Console an und rufen Sie Operations > Monitoring > Dashboards:

Für Ihr Projekt (einschließlich anderer GCP-Produkte) stehen mehrere Dashboards zur Verfügung. Die Dashboards für Smart Homes sind mit dem Präfix „Google Home Analytics“ versehen.

Wir haben derzeit ein allgemeines Dashboard, das Ihr gesamtes Projekt abdeckt, sowie Dashboards für bestimmte Integrationen (Cloud, Local, 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 wie folgt 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. Darüber hinaus gibt es mit Matter eine Reihe von Diagrammen, die die erfolgreiche Inbetriebnahme und die Einführung von Updates auf Ihren Geräten verfolgen.

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

Zugriffsfehlerlogs

Der Log-Explorer ist eine Sammlung von Tools für die Arbeit mit Ereignisprotokollen, die für ein Projekt generiert wurden. Sie können in der Google Cloud Console unter Vorgänge > Logging > Log-Explorer

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, indem Sie nach Ereignissen filtern, für die Sie eine Fehlerbehebung durchführen möchten. In den Debugging-Abschnitten werden wir näher darauf eingehen.

3. Inbetriebnahmeprobleme beheben

Der erste Messwerttyp, den wir uns ansehen werden, bezieht sich auf Ereignisse zur Inbetriebnahme von Matter. 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. In der folgenden Abbildung sind einige dieser Ereignisse dargestellt:

Auf der Seite für die Inbetriebnahme in der Matter-Primer App finden Sie weitere Informationen zu den einzelnen Schritten. In diesem Abschnitt behandeln wir die Tools und Techniken zur Behebung von Problemen bei der Inbetriebnahme.

Google Home Analytics verwenden

Wir haben eine Reihe von Messwerten erstellt, mit denen Sie Probleme bei der Inbetriebnahme untersuchen können, indem Sie Ereignisse verfolgen und nachvollziehen, in welcher Phase die Fehler auftreten können. Sie finden sie im Dashboard für die Integration von Rechtsangelegenheiten, wie im vorherigen Abschnitt beschrieben.

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

Das Diagramm mit der Geräteanzahl zeigt die Anzahl der Inbetriebnahmeversuche von Nutzern an einem bestimmten Datum. Die Erfolgsquote zeigt die wahrgenommene Erfolgsquote für diese Ereignisse auf Google-Seite an. Jeder Inbetriebnahmeversuch generiert eine Reihe von Ereignissen mit zugehörigen Status. Wenn bei 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 nach „clientUpdateLog“ suchen gekoppelt mit "severity>=ERROR" in das Abfragefeld ein.

Ein Fehlerprotokoll bei der Inbetriebnahme für 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"
}

Neben dem Inbetriebnahmestatus und einem Statuscode enthält ein Fehlerprotokoll 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 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, Probleme bei der Inbetriebnahme zu beheben, 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 während der Inbetriebnahme über das ADB-Tool auf Protokolle zugreifen, die 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, indem Sie die Versionsnummer im Terminal mit dem folgenden Befehl prüfen:

$ adb -- version

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

USB-Debugging aktivieren

Als Nächstes aktivieren Sie USB-Debugging auf Ihrem Android-Gerät.

Führen Sie zuerst die Schritte zum Aktivieren der Entwickleroptionen auf Ihrem Gerät aus und dann aktivieren Sie das USB-Debugging.

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

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. Wenn diese Warnmeldung angezeigt wird, klicken Sie 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

Die Antwort sollte in etwa so aussehen:

List of devices attached
<phone-id>    device

Deine <phone-id> ist eine alphanumerische Zeichenfolge, die dein Gerät eindeutig identifiziert.

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

Systeminformationen erfassen

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 Smart-Home-/Matter-Steuerungsmodule über die Play-Dienste installiert 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.

Fehlerlogs erfassen

Starten Sie als Nächstes die Protokollerfassung 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, indem Sie Ihre <phone-id> sowie einen <file-name> angeben, in dem die Protokolle auf Ihrem Computer gespeichert werden (z. B. debug_file.txt) verwenden.

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

Dadurch wird der Logging-Prozess sofort gestartet. 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 zu dem Fehler gelangen, den Sie beheben möchten, beenden Sie das Logging, indem Sie im laufenden Terminalfenster Control+C drücken.

Die Logs sollten jetzt in der Logging-Datei <file-name> gespeichert sein. Da bei diesem Prozess Protokolle von jedem laufenden Prozess aufgezeichnet werden, der auf dem Gerät erfasst wird, enthält diese Datei viele Protokolle. Aus diesem Grund sollten Sie diese Logs immer verwenden, indem Sie nach den gewünschten Einträgen suchen.

Fehlerlogs analysieren

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

1. Folgen Sie der Hauptstrategie, die bei der Analyse von Inbetriebnahmefehlern verwendet wird, und suchen Sie mit dem folgenden Befehl nach Fehlern, die vom MatterCommissioner-Subsystem generiert wurden:

$ grep "MatterCommissioner" <file-name>

Dadurch wird eine Ausgabe generiert, die die Ereignisse aus dem Inbetriebnahmeprozess enthält.

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

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

Suchen Sie bei der Analyse der durch den ADB-Debugging-Prozess generierten Logdatei auch nach bestimmten Mustern. Zu vielen Fehlern bei der Inbetriebnahme zählt der Fehler "commissioning failure" in der Fehlermeldung.

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

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

4. Probleme mit der Gerätesteuerung beheben

Sobald Nutzer Matter-Geräte für Google Home eingerichtet und in Betrieb nehmen, können sie per Sprachbefehl über Google Assistant (z. B. „Hey Google, schalte das Licht in meinem Wohnzimmer“) oder über die Benutzeroberfläche der Home App oder der Google Nest-Display-Geräte steuern.

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 Dashboard für die Matter-Integration findest du verschiedene Messwerte zur Gerätesteuerung. Es gibt drei Diagramme, die für die Leistungsbewertung Ihrer Geräte unterwegs entscheidend sind:

Bei Kontrollproblemen sehen Sie häufig Abwärtstrends beim Erfolgsprozentsatz und einen Aufwärtstrend im Fehleraufschlüsselungsdiagramm. Im Diagramm zur Fehleraufschlüsselung sehen Sie, warum die Gerätesteuerung fehlgeschlagen ist, die von Google Nest Hubs erfasst wurden.

Logs verwenden

Bei jedem Problem mit der Matter-Gerätesteuerung wird auch ein Fehlerprotokoll im System generiert. Diese Fehler können aus dem Log-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 Fehlerlog enthält einen Zeitstempel, einen Gerätetyp und ein Trait sowie den Fehler, der mit der Kontrollanfrage in statusType verknüpft ist. Viele Kontrollfehler enthalten auch ein externalDebugString, eine kurze Fehlermeldung, die den Grund des Fehlers erklärt.

5. Fehler in anderen Funktionen beheben

Bisher haben Sie gelernt, wie Sie bei der Inbetriebnahme von Geräten mit Matter umgehen und Probleme steuern können. Es gibt auch noch andere Funktionen, die du mit unseren empfohlenen Techniken umsetzen kannst, um eine gute Integration sicherzustellen.

OTA-Updates verfolgen

Um die Releases für Over-the-Air-Updates (OTA) für Matter-Geräte, die von Google Home ausgegeben werden, zu verfolgen, stellen wir eine Reihe von Messwerten zur Verfügung, die die Hardware- und Softwareversionen der Geräte zeigen, die draußen sind.

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 deinem OTA-Software-Release verknüpft ist.

6. Support kontaktieren

Google bietet Tools und Dokumentationen, mit denen du Matter-Probleme beheben kannst. Da das Matter-Ökosystem neu ist, wird es aber auch Probleme geben, 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 aufrufen

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. Dieser Kanal ist am besten geeignet, um zu fragen, wie Sie Probleme beheben oder eine bestimmte Funktion implementieren können.
• Issue Tracker:Dies ist das offizielle Issue Tracker-System von Google, über das externe Zielgruppen Fehler im System melden können. Sie bietet Webtools, mit denen Sie bei Bedarf Dateien anhängen und vertrauliche Daten teilen können. Der Issue Tracker eignet sich am besten, um Systemprobleme zu melden oder Funktionsanfragen zu teilen.
• Entwicklerforum:Im Nest Developer Forum können Sie sich an den offiziellen Google-Support und die Community-Experten wenden. Dieses Forum eignet sich am besten, um \offizielle Entwicklungshilfen zu erhalten.

Für den Entwickler-Newsletter anmelden

Wir rufen nicht nur die Entwicklerkanäle auf, um Fragen zu stellen, sondern veröffentlichen auch einen vierteljährlichen Newsletter, in dem neue Funktionen vorgestellt und Neuigkeiten zum Smart-Home-System von Google veröffentlicht werden.

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 dir viel Spaß beim Erstellen von Matter-Integrationen mit Google Home.

Weiteres Vorgehen

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

• Neben der Verwendung von Analysen zur Fehlerbehebung kannst du auch die Test Suite verwenden, um deine Integration auf mögliche Probleme zu testen.
• Sobald Ihre Integration bereit ist und der ganzen Welt zur Verfügung gestellt werden kann, besteht der nächste Schritt darin, Ihr Projekt für „Funktioniert mit Google Home“ zertifizieren zu lassen. Eine Anleitung dazu finden Sie hier.