1. Hinweis
Matter bietet Endnutzern eine nahtlose, plattformübergreifende Geräteeinrichtung und -steuerung. Dies ist vor allem auf die verschiedenen Komponenten des Ökosystems zurückzuführen, die 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 müssen Sie in der Lage sein, Probleme während des gesamten Geräteentwicklungszyklus zu beheben. 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.
Vorbereitung
- 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)
Lerninhalte
- 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.
- So greifen Sie auf die Matter-Dokumentation und Supportressourcen zu, um Hilfe zu erhalten.
2. Google Home Analytics aufrufen
Die Leistungsüberwachung ist für eine erfolgreiche Integration in das Google Home-System entscheidend. 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
- 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 und ein funktionierendes Projekt haben, das Anfragen erfüllt.
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. Auf jedem Integrationsdashboard sehen Sie ein Diagramm mit der Gesamtzahl der Anfragen, die von Ihrem Projekt verarbeitet wurden, 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. Sie können mit dem Metrics Explorer 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 ihn in der Google Cloud Console unter Verwaltung > Logging > Log-Explorer aufrufen.
Wenn Sie den Log-Explorer öffnen, sehen Sie eine Ansicht, die in etwa so aussieht:
Das Explorer-Fenster enthält verschiedene Tools zum Ansehen, Filtern, Abfragen und Analysieren von Protokollen. Standardmäßig werden in dieser Ansicht Logs von allen Systemen angezeigt, die für Ihr Projekt verfügbar sind, einschließlich Logs, die außerhalb von Smart Home generiert werden. Deshalb ist es wichtig, diese Protokolle zu verwenden und nach Ereignissen zu filtern, die Sie beheben möchten. Darauf gehen wir in den Abschnitten zum Debuggen noch genauer ein.
3. Probleme bei der Inbetriebnahme beheben
Der erste Messwert, den wir uns ansehen, bezieht sich auf Matter-Inbetriebnahmeereignisse. Die Inbetriebnahme bezieht sich auf die Schritte, die ein Nutzer ausführen muss, um ein Matter-Gerät zum ersten Mal einzurichten.
Während der Geräteinbetriebnahme finden mehrere Interaktionen zwischen dem Matter-Gerät, der Google Home App und der Matter-Fabric 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 gibt die wahrgenommene Erfolgsquote für diese Ereignisse bei Google an. Bei jedem Versuch der Inbetriebnahme werden 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 Inbetriebnahmefehlern filtern möchten, können Sie im Suchfeld 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 Protokolle, die aus demselben Einrichtungsversuch generiert wurden, haben dieselbe sessionId.
Anhand der Messwerte aus Google Home Analytics können Sie sich einen ersten Überblick darüber verschaffen, 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 ausführen, die vom Mobilgerät generiert wurden, das bei der Inbetriebnahme verwendet wurde. Dazu 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, kannst du 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 Befehlszeilentool sdkmanager installiert werden können.
Nachdem Sie die Plattformtools auf Ihrem System installiert haben, prüfen Sie ADB. Rufen Sie dazu die Versionsnummer im Terminal 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 das USB-Debugging 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
- Führen Sie den ADB-Server mit dem folgenden Befehl aus:
$ adb start-server
- Verbinden Sie Ihr Smartphone mit dem Computer, auf dem der ADB-Server ausgeführt wird.
Möglicherweise erhalten Sie auf Ihrem Smartphone eine Warnung zum USB-Debugging, in der Sie gefragt werden, ob Sie Ihrem Computer erlauben möchten, auf Informationen auf Ihrem Smartphone zuzugreifen:
- Klicken Sie in diesem Fall auf Zulassen.
- Geben Sie über das 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
<phone-id> ist ein alphanumerischer String, der Ihr Gerät eindeutig identifiziert.
- Notieren Sie sich den Wert für
<phone-id>für die nächsten Schritte.
Systeminformationen erheben
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 Home-/Matter-Steuermodule ü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 Problemen bei der Inbetriebnahme an den Support wenden, geben Sie in Ihren Support-Tickets immer Systeminformationen an.
Fehlerprotokolle erfassen
Starten Sie als Nächstes die Protokollerhebung und führen Sie dann die Schritte zur Inbetriebnahme aus, um die Fehlerereignisse zu generieren, die Sie beheben möchten.
- 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. Wenn die Datei noch nicht vorhanden ist, wird eine Datei mit dem angegebenen Namen erstellt. Nach jedem Ereignis werden Protokolle vom Smartphone hinzugefügt.
Fahren Sie mit der Inbetriebnahme Ihres Matter-Geräts fort.
- Wenn Sie den Fehler gefunden haben, den Sie beheben möchten, beenden Sie die Protokollierung, indem Sie im geöffneten Terminalfenster die Taste
Control+Cdrü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.
Fehlerprotokolle analysieren
Die Inbetriebnahmeprozesse werden in GHA über ein Untersystem namens MatterCommissioner verwaltet.
- 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.
- 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.
- 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 Steuerspezifikation zwischen Endgeräten und Google-Hubs über Matter vermittelt wird, wird es voraussichtlich weniger Fehler bei der Gerätesteuerung geben. Wir stellen Ihnen jedoch auch Messwerte und Protokolle zur Verfügung, mit denen Sie diese Art 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 Fehleraufschlüsselungsdiagramm sehen Sie die von Google Nest Hubs erfassten Fehler, die zum Fehlschlagen des Gerätesteuerungsversuchs geführt haben.
Protokolle verwenden
Bei jedem Problem mit der Matter-Gerätesteuerung wird außerdem ein Fehlerprotokoll im System generiert. Diese Fehler können im 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 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. Andere 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, die Sie verwenden können, oder empfohlene Methoden, um eine gute Qualität der Integration zu gewährleisten.
Over-the-air-Updates im Blick behalten
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.
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 Einsatz die neue Softwareversion, die mit Ihrer OTA-Softwareversion verknüpft ist.
6. Support anfordern
Google stellt Tools und Dokumentationen zur Fehlerbehebung bei Matter-Problemen bereit. Da das Matter-System jedoch neu ist, gibt es Probleme, die in diesen Ressourcen nicht behandelt werden. In diesen Fällen kannst du dich jederzeit an uns oder die Community wenden, um Hilfe zu erhalten.
Entwicklerkanäle besuchen
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:Sie können sich an uns und die Smart-Home-Entwickler-Community wenden, wenn Sie Fragen zur Implementierung haben oder Hilfe benötigen. 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. Der Issue Tracker eignet sich am besten, um Probleme mit dem Werbesystem zu melden oder Funktionsanfragen zu 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.
Für den Newsletter für Entwickler registrieren
Neben den Entwicklerkanälen, in denen Sie Fragen stellen können, veröffentlichen wir vierteljährlich einen Newsletter mit Informationen zu neuen Funktionen und dem aktuellen Stand des Google Smart Home-Ökosystems.
Über das Anmeldeformular können Sie den Entwickler-Newsletter abonnieren.
7. Glückwunsch
Glückwunsch! Sie haben gelernt, wie Sie mit den von uns empfohlenen Tools und Techniken Fehler in Matter-Integrationen beheben. Wir wünschen Ihnen viel Erfolg beim Erstellen von Matter-Integrationen mit Google Home.
Nächste Schritte
Probieren Sie die folgenden Übungen aus und sehen Sie sich die zusätzlichen Ressourcen an:
- 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.