Fehler bei Matter-Integrationen beheben

1. Hinweis

Matter bietet Endnutzern eine nahtlose, plattformübergreifende Geräteeinrichtung und -steuerung. Dies ist hauptsächlich durch die zahlreichen Komponenten des Systems möglich, die im Hintergrund zusammenwirken. Für neue Entwickler sind solche Systeme zur Fehlerbehebung oft eine echte Herausforderung. Deshalb haben wir eine Reihe von Tools und Techniken entwickelt, die das Leben als Matter-Entwickler mit Google Home 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 zur Verfügung, die über Smartphones und Hubs erfasst werden:

Inbetriebnahme, Ausführung, OTA-Update

Als Entwickler ist es für Sie von entscheidender Bedeutung, dass Sie Probleme, die während des gesamten Geräteentwicklungszyklus auftreten, minimieren können. Sobald Sie Ihr Projekt gestartet haben, müssen Sie Problemtrends für Geräte im Außeneinsatz zusammenfassen und durch Software-Updates beheben. In diesem Codelab werden Techniken für beide Zwecke behandelt.

Voraussetzungen

  • Schließe den Startleitfaden für Matter mit einem funktionierenden Matter-Projekt und einer funktionierenden Geräteeinrichtung ab.
  • ein Android-Smartphone haben, das sich mit Ihrer Workstation verbinden kann (für ADB-Protokolle)

Lerninhalte

  • Analysetools für Smart Home verwenden, um Matter-Probleme in großem Umfang im Blick zu behalten
  • Erfahren Sie, wie Sie Fehler durch Zugriff auf Fehlerprotokolle und das Erfassen von Informationen erkennen.
  • Hier erfahren Sie, wie Sie auf die Matter-Dokumentation und Supportressourcen zugreifen, um Hilfe zu erhalten.

2. Google Home-Analysedaten aufrufen

Die Leistungsüberwachung ist entscheidend für eine erfolgreiche Integration mit Google Home. 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, sich die Google Home-Dashboards anzusehen. Melden Sie sich dazu in der Google Cloud Console an und rufen Sie Vorgänge > Monitoring > Dashboards auf.

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

Dashboards für die Google Home-Analyse

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 funktionsfähiges Projekt haben, das Anfragen erfüllt.

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

Aufschlüsselungen der Erfolgsquote, Latenz und Gerätetypen

Dashboards auf der Google-Startseite enthalten verschiedene Diagramme mit Details zu den Ereignissen in Ihrem Projekt. Für jedes Integrations-Dashboard sehen Sie ein Diagramm mit der Gesamtzahl der Anfragen, die von Ihrem Projekt bearbeitet wurden, ein Diagramm mit der Erfolgsquote für diesen Integrationstyp und mehrere Diagramme mit den betroffenen Gerätetypen und -merkmalen. Darüber hinaus gibt es bei Matter eine Reihe von Diagrammen, die die erfolgreiche Inbetriebnahme sowie Updates auf Ihren Geräten verfolgen.

Hinweis: Die Standardansicht mit den Diagrammen in den Google Analytics-Dashboards ist nur eine Ansicht, die wir anhand von Smart-Home-Messwertdaten 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 darauf zugreifen.

Nach dem Öffnen des Log-Explorers sehen Sie eine Ansicht, die in etwa so aussieht:

Log-Explorer

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 der Protokolle, die außerhalb von Smart Home generiert werden. Daher ist es wichtig, diese Protokolle zu verwenden, indem Sie nach Ereignissen filtern, die Sie debuggen möchten. Wir werden in den Abschnitten zur Fehlerbehebung näher darauf eingehen.

3. Inbetriebnahmeprobleme beheben

Bei der ersten Art von Messwert geht es um Matter-Inbetriebnahmeereignisse. „Inbetriebnahme“ bezieht sich auf die Schritte, die Nutzer bei der Ersteinrichtung eines Matter-Geräts benötigen.

Bei der Inbetriebnahme des Geräts finden zwischen dem Matter-Gerät, der Google Home App und der Matter-Struktur eine Reihe von Interaktionen statt. In der folgenden Abbildung sind einige dieser Ereignisse dargestellt:

Ereignisse zur Matter-Provision

Weitere Informationen zu den einzelnen Schritten finden Sie auf der Inbetriebnahmeseite der Matter Primer App. In diesem Abschnitt werden die Tools und Techniken zur Behebung von Problemen bei der Inbetriebnahme behandelt.

Google Home Analytics verwenden

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

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

Messwerte zur Geräteinbetriebnahme

Das Diagramm zur Geräteanzahl zeigt die Anzahl der Inbetriebnahmeversuche der Nutzer an einem bestimmten Datum. Die Erfolgsquote zeigt die wahrgenommene Erfolgsquote für diese Ereignisse bei Google an. Bei jedem Inbetriebnahmeversuch wird eine Reihe von Ereignissen mit zugehörigen Status generiert. Wenn ein Fehler in einem dieser Status 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. Um nach Provisionsfehlern zu filtern, können Sie im Abfragefeld nach „clientUpdateLog“ und „severity>=ERROR“ suchen.

Ein Fehlerprotokoll zur 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"
}

Neben dem Status der Inbetriebnahme und einem Statuscode enthält ein Fehlerprotokoll Zeitstempel für den erfassten Fehler sowie die Matter-Produkt-ID, anhand derer Sie ermitteln können, welches Ihrer Produkte den Fehler verursacht hat. Die Logs, die für denselben Inbetriebnahmeversuch generiert werden, verwenden ein sessionId.

Anhand der Messwerte von 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 mithilfe der Protokolle, die von dem bei der Inbetriebnahme verwendeten Mobilgerät generiert wurden, eine zusätzliche Fehlerbehebung durchführen. Dafür benötigen Sie die Android Debug Bridge.

Android Debug Bridge (ADB) verwenden

Eine weitere Möglichkeit zur Behebung von Inbetriebnahmeproblemen ist das Befehlszeilentool Android Debug Bridge (ADB). Da die Inbetriebnahme hauptsächlich zwischen dem Mobilgerät und dem Matter-Gerät erfolgt, ist es möglich, während der Inbetriebnahme mit dem ADB-Tool auf Protokolle zuzugreifen, 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, überprüfen Sie ADB, indem Sie mit dem folgenden Befehl die Versionsnummer im Terminal prüfen:

$ adb -- version

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

USB-Debugging aktivieren

Aktiviere als Nächstes USB-Debugging auf deinem Android-Gerät.

Folgen Sie zuerst der Anleitung zum Aktivieren der Entwickleroptionen auf Ihrem Gerät und aktivieren Sie dann das USB-Debugging.

Dadurch kann ADB auf Protokolle zugreifen, die von Apps generiert wurden, die aktuell 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
  1. Verbinden Sie das Telefon mit dem Computer, auf dem der ADB-Server ausgeführt wird.

Möglicherweise wird auf Ihrem Telefon eine Warnmeldung zum USB-Debugging angezeigt, in der Sie gefragt werden, ob der Computer auf Informationen von Ihrem Telefon zugreifen darf:

USB-Debugging-Aufforderung

  1. Wenn diese Warnmeldung angezeigt wird, klicken Sie auf Zulassen.
  2. Geben Sie über das Terminal einen Befehl zum Auflisten von Geräten aus, um zu sehen, ob Ihr Computer über ADB auf das Smartphone 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 <Telefon-ID> ist eine alphanumerische Zeichenfolge, die dein Gerät eindeutig identifiziert.

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

Systeminformationen erfassen

Überprü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 Smart-Home- bzw. Matter-Steuermodule über 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 den Support wenden, geben Sie in Ihren Support-Tickets immer Systeminformationen an.

Fehlerlogs erfassen

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

  1. Führen Sie den folgenden Befehl aus. Geben Sie dazu <phone-id> sowie eine <file-name> an, unter der die Protokolle auf Ihrem Computer gespeichert werden (z. B. debug_file.txt).
$ adb -s <phone-id> logcat > <file-name>

Dadurch wird sofort der Logging-Prozess gestartet. Sofern noch nicht vorhanden, wird eine Datei mit dem angegebenen Namen erstellt. Nach jedem Ereignis werden Protokolle vom Telefon zur Datei hinzugefügt.

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

  1. Wenn Sie zu dem Fehler kommen, den Sie debuggen möchten, beenden Sie die Protokollierung, indem Sie im laufenden Terminalfenster Control+C drücken.

Ihre Logs sollten jetzt in der Logging-Datei <file-name> gespeichert sein. Da bei diesem Prozess Protokolle aller laufenden Prozesse aufgezeichnet werden, die auf dem Gerät erfasst werden, befinden sich in dieser Datei viele Protokolle. Daher sollten Sie diese Protokolle immer verwenden, indem Sie nach den Einträgen suchen, die Sie benötigen.

Fehlerlogs analysieren

Die Inbetriebnahme erfolgt über ein Subsystem namens MatterCommissioner innerhalb der GHA.

  1. Suchen Sie gemäß der Hauptstrategie, die bei der Analyse von Inbetriebnahmefehlern angewendet wird, mit dem folgenden Befehl nach Fehlern, die vom MatterCommissioner-Subsystem generiert werden:
$ grep "MatterCommissioner" <file-name>

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

  1. 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>

Suchen Sie bei der Analyse der vom ADB-Fehlerbehebungsprozess generierten Protokolldatei auch nach bestimmten Mustern. Viele Fehler bei der Inbetriebnahme enthalten den String „commissioning failure“ in der Fehlermeldung.

  1. Mit dem folgenden Befehl können Sie nach einer Fehlermeldung bei der Inbetriebnahme suchen:
$ 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 genommen haben, können sie Google Assistant per Sprachbefehl (z. B. „Hey Google, schalte das Licht in meinem Wohnzimmer“) oder die Benutzeroberfläche der Home App oder eines Google Nest-Displays über die Benutzeroberfläche verwenden.

Da die Vorgaben für die Steuerung zwischen Endgeräten und Google-Hubs durch Matter übertragen werden, ist davon auszugehen, dass bei der Gerätesteuerung weniger Fehler auftreten. Unabhängig davon stellen wir Ihnen auch Messwerte und Protokolle zur Verfügung, mit denen Sie diese Art von Problemen beheben können.

Messwerte verwenden

Im Dashboard für die Matter-Integration findest du verschiedene Messwerte zur Gerätesteuerung. Für die Leistungsbewertung Ihrer Geräte im Einsatz sind drei Diagramme wichtig:

Erfolgs-, Latenz- und Fehleraufschlüsselungsdiagramme

Bei Kontrollproblemen sehen Sie häufig Abwärtstrends im Erfolgsprozentsatz und einen Aufwärtstrend im Fehleraufschlüsselungsdiagramm. In der Fehleraufschlüsselung sehen Sie, welche Fehler von Google Nest Hubs erfasst wurden und warum der Versuch, das Gerät zu steuern, fehlgeschlagen ist.

Protokolle verwenden

Bei jedem Problem mit der Matter-Gerätesteuerung wird im System auch ein Fehlerprotokoll generiert. Diese Fehler können im Log-Explorer gefiltert 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 eine Eigenschaft sowie den Fehler, der mit der Kontrollanfrage im statusType verknüpft ist. Viele Kontrollfehler enthalten auch eine externalDebugString, eine kurze Fehlermeldung zur Erläuterung des Fehlers.

5. Fehler in anderen Funktionen beheben

Bisher hast du gelernt, wie du mit der Geräteinbetriebnahme und der Steuerung von Matter umgehen kannst. Es gibt auch noch andere Funktionen, die Sie mit unseren empfohlenen Methoden für eine gute Integration nutzen können.

OTA-Updates verfolgen

Um die von Google Home herausgegebenen OTA-Updates (Over The Air) für Matter-Geräte zu verfolgen, stellen wir eine Reihe von Messwerten zur Verfügung, die die Hardware- und Softwareversionen für die Geräte im Einsatz zeigen.

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

Software- und Hardwareprobleme

Du wirst feststellen, dass in den Tagen nach der Veröffentlichung immer mehr Geräte im Außendienst die neue Softwareversion erhalten, die mit deinem OTA-Software-Release verknüpft ist.

6. Support kontaktieren

Google stellt Ihnen Tools und Dokumentationen zur Verfügung, mit denen Sie Probleme mit Matter beheben können. Da das Matter-Ökosystem jedoch neu ist, wird es Probleme geben, die in diesen Ressourcen nicht behandelt werden. In solchen Fällen können Sie sich jederzeit an uns oder die Community wenden.

Entwicklerkanäle aufrufen

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

Stack Overflow, Problemverfolgung, Entwicklerforum

Obwohl jeder dieser Kanäle regelmäßig von demselben Team überwacht wird, gibt es einige wichtige Unterschiede, wann Sie welchen verwenden sollten.

  • 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 eignet sich am besten, wenn Sie hier Informationen zur Fehlerbehebung oder Implementierung einer bestimmten Funktion finden möchten.
  • Problemverfolgung:Das offizielle Issue Tracker-System von Google, mit dem externe Zielgruppen Fehler im System melden können. Es bietet Webtools, mit denen Sie Dateien anhängen und vertrauliche Informationen bei Bedarf teilen können. Der Issue Tracker eignet sich am besten, um Probleme mit dem System zu melden oder Funktionsanfragen zu senden.
  • Entwicklerforum:Im Nest-Entwicklerforum können Sie sich an den offiziellen Google-Support und Community-Experten wenden. Dieses Forum ist am besten geeignet, um offizielle Anleitungen für die Entwicklung zu erhalten.

Entwickler-Newsletter abonnieren

Neben Fragen in den Entwicklerkanälen veröffentlichen wir auch einen vierteljährlichen Newsletter, in dem neue Funktionen und Neuigkeiten zum Google Smart Home-System vorgestellt werden.

Sie können das Anmeldeformular verwenden, um den Newsletter für Entwickler zu erhalten.

7. Glückwunsch

Google Home

Glückwunsch! Du hast jetzt gelernt, wie du mit den von uns empfohlenen Tools und Techniken Fehler in Matter-Integrationen beheben kannst. Wir wünschen dir viel Spaß beim Erstellen von Matter-Integrationen mit Google Home.

Weiteres Vorgehen

Probieren Sie die folgenden Übungen aus und sehen Sie sich zusätzliche Ressourcen an:

  • Mit der Test-Suite kannst du deine Integration nicht nur mithilfe von Analysefunktionen beheben, sondern auch auf potenzielle Probleme testen.
  • Sobald Ihre Integration fertig ist, können Sie Ihr Projekt für „Funktioniert mit Google Home“ zertifizieren lassen. Folgen Sie dazu der Anleitung auf der Zertifizierungsseite.