1) Hinweis
Matter bietet Endnutzern eine nahtlose, plattformübergreifende Einrichtung und Steuerung. Dies ist hauptsächlich deshalb möglich, weil die verschiedenen Systemkomponenten im Hintergrund zusammenwirken. Solche Systeme zur Fehlerbehebung können für neue Entwickler oft eine Herausforderung darstellen. Deshalb haben wir eine Reihe von Tools und Techniken entwickelt, die dir als Matter-Entwickler mit Google Home das Leben leichter machen.
In diesem Codelab werden drei Hauptkomponenten auf Matter behandelt. Für jedes dieser Systeme bietet Google eine Reihe von Analysen zur Fehlerbehebung für Entwickler, die von Smartphones und Hubs erfasst werden:
Als Entwickler ist es für Sie wichtig, Probleme während des Geräteentwicklungszyklus zu minimieren. Nachdem Sie Ihr Projekt gestartet haben, müssen Sie Problemtrends für Geräte in der Praxis beobachten und Probleme mit Softwareupdates beheben. In diesem Codelab werden Verfahren beschrieben, die du für beide Zwecke verwenden kannst.
Voraussetzungen
- Schließen Sie den Leitfaden Erste Schritte mit Matter mit einem funktionierenden Matter-Projekt und der Einrichtung des Geräts ab.
- ein Android-Smartphone haben, das Sie mit Ihrer Workstation verbinden können (für ADB-Logs)
Lerninhalte
- Hier erfahren Sie, wie Sie Analysetools für Smart Home verwenden, um Matter-Probleme in großem Umfang zu beobachten.
- Fehler anhand von Fehlerlogs und Informationen erfassen.
- Informationen darüber, wie du auf die Matter-Dokumentation und die Supportressourcen zugreifen kannst, um Hilfe zu erhalten
2. Google Home Analytics ansehen
Die Leistungsüberwachung ist für eine erfolgreiche Integration in die Google Home-Umgebung von entscheidender Bedeutung. Smart-Home-Entwicklern stehen auf der Google Cloud Platform eine Reihe von Überwachungstools zur Verfügung. Mit diesen Tools können Sie die Leistung Ihres Projekts messen.
Auf Projektmesswerte zugreifen
- Zuerst müssen Sie auf die Google Home-Dashboards prüfen. Melden Sie sich dazu in der Google Cloud Console an und gehen Sie zu Vorgänge > Monitoring > Dashboards.
Für Ihr Projekt sind eine Reihe von Dashboards verfügbar, einschließlich anderer GCP-Produkte. Die Smart-Home-Dashboards haben ein Präfix von 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 den entsprechenden Typ in Kombination mit einem funktionierenden Projekt haben, das Anfragen ausführt.
Wenn Sie eines dieser Dashboards öffnen, sehen Sie eine Reihe von Diagrammen in etwa so:
Google Home-Dashboards enthalten verschiedene Diagramme mit Details zu den Ereignissen, die mit Ihrem Projekt verknüpft sind. Für jedes Integrationsdashboard gibt es ein Diagramm mit der Gesamtzahl der von Ihrem Projekt verarbeiteten Anfragen, ein Diagramm mit der Erfolgsquote für diesen Integrationstyp und mehrere Diagramme mit den jeweiligen Gerätetypen und Merkmalen. Darüber hinaus gibt es in Matter eine Reihe von Diagrammen, die den Erfolg der Inbetriebnahme sowie die Einführung von Updates auf Ihren Geräten verfolgen.
Die Standardansicht mit den Diagrammen, die in den Google Home Analytics-Dashboards angezeigt werden, ist eine Ansicht, die wir für Ihr Projekt mit Smart-Home-Messwertdaten erstellt haben. Sie können mit dem Metrics Explorer auch eigene Diagramme aus denselben zugrunde liegenden Messwerten erstellen und in benutzerdefinierten Dashboards speichern.
Zugriff auf Fehlerlogs
Der Log-Explorer ist eine Sammlung von Tools, mit denen Sie in einem Projekt generierten Ereignislogs arbeiten können. Sie können ihn in der Google Cloud Console unter Vorgänge > Logging > Log-Explorer aufrufen.
Nach dem Öffnen des Log-Explorers erhalten Sie eine Ansicht, die in etwa so aussieht:
Das Explorer-Fenster enthält verschiedene Tools zum Ansehen, Filtern, Abfragen und Analysieren von Logs. Standardmäßig zeigt diese Ansicht Logs aus allen Systemen, die für Ihr Projekt verfügbar sind, einschließlich Logs, die außerhalb von Smart Home generiert werden. Deshalb ist es wichtig, diese Logs zu verwenden, indem Sie nach Ereignissen suchen, die Sie debuggen möchten. Wir werden in den Abschnitten zur Fehlerbehebung noch näher darauf eingehen.
3. Inspektionsprobleme beheben
Der erste Messwert, den wir uns ansehen werden, bezieht sich auf Matter-Inbetriebnahmeereignisse. Mit der Inbetriebnahme ist die erstmalige Einrichtung eines Matter-Geräts durch den Nutzer gemeint.
Bei der Inbetriebnahme eines Geräts werden zwischen dem Matter-Gerät, der Google Home App und dem Matter-Gewebe einige Interaktionen durchgeführt. Das folgende Bild veranschaulicht einige dieser Ereignisse:
Auf der Seite zur Inbetriebnahme der Matter Primer App finden Sie weitere Informationen zu den einzelnen Schritten. In diesem Abschnitt werden die Tools und Techniken zur Behebung von Problemen bei der Inbetriebnahme behandelt.
Verwende Google Home Analytics.
Wir haben eine Reihe von Messwerten erstellt, mit denen Sie Inbetriebnahmeprobleme untersuchen, indem Ereignisse erfasst und ermittelt werden können, in welcher Phase die Fehler auftreten können. Sie finden diese im Matter Integration Dashboard, wie wir im vorherigen Abschnitt behandelt haben.
Diagramme in diesem Dashboard enthalten Daten zur Geräteinbetriebnahme:
Im Diagramm zur Geräteanzahl sehen Sie die Anzahl der Provisionsversuche von Nutzern an einem bestimmten Datum. Die Erfolgsquote zeigt die wahrgenommene Erfolgsquote für diese Ereignisse auf Seiten von Google. Jeder Provisionsversuch versucht, eine Reihe von Ereignissen mit zugehörigen Status zu generieren. Wenn ein Fehler in einem dieser Status auftritt, wird er auch im Diagramm zur Fehleraufschlüsselung erfasst.
Zuständigkeitsstaaten:
- COMMISIONING_STARTED
- ONBOARDING_PAYLOAD_GENERATED
- LOKAL_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 Provisionsfehlerprotokoll 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 Provisionsstatus und einem Statuscode enthält ein Fehlerprotokoll Zeitstempel für den erfassten Fehler sowie die Matter-Produkt-ID, anhand derer Sie feststellen können, durch welche Ihrer Produkte der Fehler verursacht wurde. Die Logs, die durch denselben Provisionsversuch generiert wurden, teilen sich ein sessionId.
Die Messwerte von Google Home Analytics geben Aufschluss darüber, in welcher Phase das Problem auftreten könnte. Um die Ursache der Geräte-Inbetriebnahmesfehler zu finden, müssen Sie unter Umständen mit den Protokollen des Mobilgeräts, das bei der Inbetriebnahme verwendet wird, zusätzliche Debugging-Methoden ausführen. Dazu benötigen Sie die Android Debug Bridge.
Android Debug Bridge (ADB) verwenden
Eine weitere Möglichkeit zur Behebung von Provisionsproblemen 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, das ADB-Tool zu verwenden, um während der Inbetriebnahme 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, prü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
Als Nächstes aktivieren Sie das USB-Debugging auf Ihrem Android-Gerät.
Folgen Sie zuerst den Schritten zur Aktivierung von Entwickleroptionen auf Ihrem Gerät und dann zur Aktivierung von 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
- Führen Sie den ADB-Server mit dem folgenden Befehl aus:
$ adb start-server
- Verbinden Sie Ihr Telefon mit dem Computer, auf dem der ADB-Server ausgeführt wird.
Möglicherweise wird auf Ihrem Smartphone eine Warnmeldung zu USB-Debugging angezeigt, in der Sie gefragt werden, ob Sie dem Computer Zugriff auf Informationen von Ihrem Smartphone gewähren möchten:
- Wenn diese Warnmeldung angezeigt wird, klicken Sie auf Zulassen.
- Führen Sie mit dem folgenden Befehl über das Terminal einen Befehl für „list devices“ aus, um zu prüfen, ob Ihr Computer über ADB auf das Smartphone zugreifen kann:
$ adb devices
Die Antwort sollte in etwa so aussehen:
List of devices attached <phone-id> device
Die <phone-id> ist ein alphanumerischer String, der dein Gerät eindeutig identifiziert.
- Merken Sie sich den
<phone-id>-Wert 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 überprüfen Sie die Android-Version:
$ adb -s <phone-id> shell getprop ro.build.version.release
- So überprüfen Sie die Version der Google Home App:
$ adb -s <phone-id> shell dumpsys package com.google.android.apps.chromecast.app | grep versionName
- So überprüfen Sie die Version der Google Play-Dienste:
$ adb -s <phone-id> shell dumpsys package com.google.android.gms | grep "versionName"
- So kannst du nachsehen, ob du die Steuermodule für Home und Matter über die Play-Dienste installiert hast:
$ adb -s <phone-id> shell dumpsys activity provider com.google.android.gms.chimera.container.GmsModuleProvider | grep "com.google.android.gms.home"
Diese Rückgabewerte müssen von unserem System unterstützt werden. Wenn Sie Hilfe bei der Inbetriebnahme von Fehlern benötigen, geben Sie in Ihren Support-Tickets immer Systeminformationen an.
Fehlerlogs erfassen
Starten Sie als Nächstes den Prozess der Logerfassung und führen Sie die Inbetriebnahmeschritte aus, um die Fehlerereignisse zu generieren, die Sie beheben möchten.
- Führen Sie den folgenden Befehl aus, indem Sie
<phone-id>und<file-name>angeben. Die Protokolle werden auf dem Computer gespeichert (z. B.debug_file.txt) verwenden.
$ adb -s <phone-id> logcat > <file-name>
Damit wird sofort der Logging-Prozess gestartet. Eine Datei mit dem angegebenen Namen wird erstellt, falls noch nicht vorhanden. Nach jedem Ereignis werden der Datei Protokolle vom Telefon hinzugefügt.
Folgen Sie der Inbetriebnahme auf Ihrem Matter-Gerät.
- Sobald Sie zu dem Fehler gelangen, den Sie beheben möchten, beenden Sie das Logging. Dazu drücken Sie im laufenden Terminalfenster
Control+C.
Ihre Logs sollten jetzt in der Logging-Datei <file-name> gespeichert sein. Da bei diesem Prozess Protokolle aus allen auf dem Gerät aufgezeichneten laufenden Prozessen aufgezeichnet werden, enthält diese Datei viele Protokolle. Daher sollten Sie diese Logs immer verwenden, indem Sie nach den Einträgen suchen, die Sie benötigen.
Fehlerlogs analysieren
Die Inbetriebnahme wird über ein Subsystem namens MatterCommissioner innerhalb der GHA abgewickelt.
- Folgen Sie der Hauptstrategie zur Analyse von Provisionsfehlern und suchen Sie mit dem folgenden Befehl nach Fehlern, die vom Subsystem von MatterCommissioner generiert wurden:
$ grep "MatterCommissioner" <file-name>
Dadurch wird eine Ausgabe mit den Ereignissen aus dem Inbetriebnahmevorgang generiert.
- 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 beim Analysieren der Protokolldatei, die durch den ADB-Fehlerbehebungsprozess generiert wird, auf bestimmte Muster. In vielen Fällen enthält die Fehlermeldung den String „commissioning failure“.
- Suchen Sie mit dem folgenden Befehl nach einer Provisionsfehlermeldung:
$ grep "SetupDevice" $phonelog | grep -A 20 "Commissioning failed"
4. Probleme mit der Gerätesteuerung beheben
Nachdem Nutzer Matter-Geräte in der Google Home-Umgebung eingerichtet und in Betrieb genommen haben, können sie Sprachbefehle per Sprachbefehl über Google Assistant erteilen (z. B. „Ok Google, schalte das Licht in meinem Wohnzimmer ein“) oder über die Benutzeroberfläche in der Home App oder auf den Google Nest-Display-Geräten.
Da die Steuerspezifikation zwischen Endgeräten und Google Hubs von Matter vermittelt wird, sollte es auf der Gerätesteuerungsseite weniger Fehler geben. In jedem Fall stellen wir Ihnen Messwerte und Protokolle zur Verfügung, damit Sie diese Art 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 entscheidend für die Leistungsbewertung von Geräten im Außendienst sind:
Bei Kontrollproblemen gibt es häufig Trends in der Erfolgsquote und einen Anstieg im Fehleraufschlüsselungsdiagramm. Im Diagramm sehen Sie die Fehler, die von Google Nest Hubs im Hinblick auf die Fehler bei der Gerätesteuerung erfasst wurden.
Logs verwenden
Jedes Problem mit der Matter-Gerätesteuerung generiert ebenfalls ein Fehlerprotokoll im System. Sie können diese Fehler aus dem Log-Explorer filtern, indem Sie nach „executionLog“ suchen.
Logs zu Matter-Gerätesteuerungsfehlern 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 Steuerungsanfrage in statusType verknüpft ist. Zu vielen Kontrollfehlern gehört auch eine externalDebugString-Fehlermeldung, in der der Fehler erläutert wird.
5. Fehler in anderen Funktionen beheben
Bisher haben Sie gelernt, wie Sie Probleme mit der Inbetriebnahme und Steuerung von Geräten in Matter beheben. Außerdem gibt es weitere Funktionen, mit denen du unsere empfohlenen Techniken nutzen kannst, um eine gute Qualität zu gewährleisten.
OTA-Updates verfolgen
Damit Sie die Releases für OTA-Updates (Over The Air) für Matter-Geräte verfolgen können, die über Google Home bereitgestellt wurden, stellen wir Ihnen eine Reihe von Messwerten zur Verfügung, die die Hardware- und Softwareversionen für die Außengeräte zeigen.
Nachdem Sie ein Update über die Konsole durchgeführt haben, sollten Sie die folgenden Messwerte im Auge behalten:
In den Tagen nach der Veröffentlichung erhalten immer mehr Geräte im Feld die neue Softwareversion, die mit Ihrer OTA-Software-Version verknüpft ist.
6. Unterstützung suchen
Google stellt Tools und Dokumentationen zur Behebung von Matter-Problemen zur Verfügung, doch da die Matter-Umgebung neu ist, gibt es Probleme, die durch diese Ressourcen nicht abgedeckt werden. In solchen Fällen kannst du dich natürlich auch jederzeit an uns oder die Community wenden.
Entwicklerkanäle aufrufen
Bei Google werden drei Entwicklerkanäle aktiv überwacht:
Jeder dieser Kanäle wird regelmäßig vom selben Team überwacht. Es gibt aber einige wichtige Unterschiede bei der Auswahl des Kanals.
- Stack Overflow:Sie können sich an uns und die Smart Home-Entwickler-Community wenden, wenn Sie Fragen zur Implementierung haben oder Unterstützung bei der Einrichtung benötigen. Über diesen Kanal kannst du am besten fragen, wie du Probleme beheben oder eine bestimmte Funktion implementieren kannst.
- Problemverfolgung:Dies ist das offizielle von Google verwaltete Problemverfolgungssystem, mit dem externe Zielgruppen Fehler in der Umgebung melden können. Sie bietet Webtools zum Anhängen von Dateien und zum Teilen vertraulicher Informationen bei Bedarf. Die Problemverfolgung ist am besten geeignet, um Probleme mit der Plattform zu melden oder Funktionsanfragen zu teilen.
- Entwicklerforum:Wenn Sie sich vom offiziellen Google-Support und Community-Experten beraten lassen möchten, können Sie sich über das Nest-Entwicklerforum an uns wenden. Dieses Forum eignet sich am besten, um offizielle Informationen zur Entwicklung zu erhalten.
Für den Newsletter für Entwickler anmelden
Wir stellen nicht nur die Entwicklerkanäle für Fragen zur Verfügung, sondern veröffentlichen auch einen vierteljährlichen Newsletter, in dem neue Funktionen vorgestellt und Informationen zum Status der Google-Smart-Home-Plattform bereitgestellt werden.
Verwenden Sie das Anmeldeformular, um den Entwickler-Newsletter zu erhalten.
7. Glückwunsch
Glückwunsch! Sie haben erfolgreich gelernt, wie Sie Matter-Integrationen mit den von uns empfohlenen Tools und Techniken debuggen können. Wir wünschen dir viel Spaß beim Erstellen von Matter-Integrationen in Google Home.
Weiteres Vorgehen
Probiere die folgenden Übungen aus und entdecke weitere Ressourcen:
- Neben der Verwendung von Analysen zur Fehlerbehebung können Sie die Testsuite verwenden, um die Integration auf mögliche Probleme zu testen.
- Wenn die Integration für die Welt freigegeben werden kann, besteht der nächste Schritt darin, für Ihr Projekt „WWGH-zertifiziert“ zu erhalten. Folgen Sie dazu der Anleitung auf der Seite Zertifizierung.