1. Avant de commencer
Matter offre aux utilisateurs finaux une expérience de configuration et de contrôle des appareils fluide et multiplate-forme. Cela est principalement possible grâce aux nombreux composants de l'écosystème qui fonctionnent ensemble en arrière-plan. Les systèmes de dépannage de ce type peuvent souvent être intimidants pour les nouveaux développeurs. C'est pourquoi nous avons développé une série d'outils et de techniques pour vous faciliter la vie en tant que développeur Matter avec Google Home.
Cet atelier de programmation présente trois composants principaux de Matter. Pour chacun de ces systèmes, Google fournit aux développeurs un ensemble d'analyses de dépannage collectées à partir des téléphones et des hubs :
En tant que développeur, il est essentiel que vous puissiez atténuer les problèmes que vous rencontrez tout au long du cycle de développement de l'appareil. Une fois votre projet lancé, vous devez surveiller de manière globale les tendances des problèmes sur les appareils sur le terrain et les résoudre via des mises à jour logicielles. Cet atelier de programmation présente les techniques que vous pouvez utiliser dans ces deux cas.
Prérequis
- Suivez le guide Premiers pas avec Matter avec un projet Matter fonctionnel et la configuration de l'appareil
- disposer d'un téléphone Android que vous pouvez connecter à votre station de travail (pour les journaux ADB) ;
Points abordés
- Utiliser des outils d'analyse pour la maison connectée afin de surveiller les problèmes Matter à grande échelle
- Comment trier les erreurs en accédant aux journaux d'erreurs et en collectant des informations
- Accéder à la documentation Matter et aux ressources d'assistance pour obtenir de l'aide
2. Afficher les données analytiques de Google Home
Surveiller les performances est essentiel pour une intégration réussie à l'écosystème Google Home. Nous fournissons un ensemble d'outils de surveillance aux développeurs de maisons connectées sur Google Cloud Platform. Vous pouvez utiliser ces outils pour évaluer les performances de votre projet.
Accès aux métriques du projet
- Pour accéder à vos données, commencez par consulter les tableaux de bord Google Home. Pour ce faire, connectez-vous à la console Google Cloud, puis accédez à Opérations > Surveillance > Tableaux de bord.
Votre projet dispose de plusieurs tableaux de bord (y compris d'autres produits GCP). Les tableaux de bord fournis pour la maison connectée sont précédés du préfixe "Google Home Analytics".
Nous proposons actuellement un tableau de bord général qui couvre l'ensemble de votre projet, ainsi que des tableaux de bord pour une intégration spécifique (Cloud, Local, Matter) ou des types d'appareils (caméras). Ces tableaux de bord ne contiennent des données que si vous disposez d'une intégration du type correspondant et d'un projet opérationnel répondant aux requêtes.
Lorsque vous ouvrez l'un de ces tableaux de bord, une série de graphiques s'affiche, comme suit :
Les tableaux de bord Google Home contiennent divers graphiques qui présentent des détails sur les événements associés à votre projet. Chaque tableau de bord d'intégration affiche un graphique indiquant le nombre total de requêtes traitées par votre projet, un graphique indiquant le taux de réussite pour ce type d'intégration, ainsi que plusieurs graphiques montrant les types d'appareils et les caractéristiques impliqués. De plus, Matter vous fournit un ensemble de graphiques qui permettent de suivre la réussite de la mise en service, ainsi que le déploiement des mises à jour sur vos appareils.
Notez que la vue par défaut avec les graphiques que vous voyez dans les tableaux de bord Google Home Analytics n'est qu'une vue que nous avons créée pour votre projet à l'aide de données de métriques de maison connectée. Vous pouvez également utiliser l'explorateur de métriques pour créer vos propres graphiques à partir des mêmes métriques sous-jacentes et les enregistrer dans vos tableaux de bord personnalisés.
Accéder aux journaux d'erreurs
L'explorateur de journaux est un ensemble d'outils permettant de travailler avec les journaux d'événements générés dans un projet. Pour y accéder dans la console Google Cloud, accédez à Operations > Logging > Logs Explorer (Opérations > Journalisation > Explorateur de journaux).
Lorsque vous ouvrez l'explorateur de journaux, la vue qui s'affiche ressemble à celle-ci:
La fenêtre de l'explorateur contient divers outils permettant d'afficher, de filtrer, d'interroger et d'analyser les journaux. Par défaut, cette vue affiche les journaux générés par tous les systèmes disponibles pour votre projet, y compris ceux générés en dehors de la maison connectée. C'est pourquoi il est essentiel d'utiliser ces journaux en filtrant les événements que vous souhaitez déboguer. Nous en reparlerons dans les sections de débogage.
3. Déboguer les problèmes de mise en service
Le premier type de métrique que nous allons examiner concerne les événements de mise en service Matter. La mise en service désigne l'ensemble d'étapes nécessaires à un utilisateur pour configurer un appareil Matter pour la première fois.
Lors de la mise en service de l'appareil, un ensemble d'interactions a lieu entre l'appareil Matter, l'application Google Home et le tissu Matter. L'image suivante illustre certains de ces événements :
Pour en savoir plus sur chacune de ces étapes, consultez la page de mise en service du guide de démarrage de Matter. Dans cette section, nous allons présenter les outils et les techniques permettant de déboguer les problèmes de mise en service.
Utiliser Google Home Analytics
Nous avons créé un ensemble de métriques vous permettant d'analyser les problèmes de mise en service en suivant les événements et en comprenant à quelle étape les erreurs peuvent se produire. Vous les trouverez dans le tableau de bord d'intégration de Matter, comme nous l'avons vu dans la section précédente.
Les graphiques de ce tableau de bord fournissent des données sur la mise en service des appareils :
Le graphique sur le nombre d'appareils indique le nombre de tentatives de mise en service par les utilisateurs à une date donnée. Le taux de réussite indique le taux de réussite perçu pour ces événements du côté de Google. Chaque tentative de mise en service génère un ensemble d'événements avec des états associés. Lorsqu'une erreur se produit à l'un de ces états, elle est également enregistrée dans le graphique de répartition des erreurs.
États de mise en service :
- COMMISSIONING_STARTED
- ONBOARDING_PAYLOAD_GENERATED
- LOCAL_DISCOVERY_SUCCESSFUL
- PASE_CONNECTION_SUCCESSFUL
- NOC_ADDED_SUCCESSFULLY
- COMMISSIONING_COMPLETE
Pour afficher une version détaillée de ces événements, accédez à Opérations > Journaux > Explorateur de journaux. Pour filtrer les erreurs de commissionnement, vous pouvez rechercher "clientUpdateLog" associé à "severity>=ERROR" dans le champ de requête.
Voici un exemple de journal des erreurs de mise en service pour Matter :
{
"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"
}
En plus de l'état de mise en service et d'un code d'état, un journal des erreurs contient des codes temporels pour l'erreur capturée, ainsi que l'ID de produit Matter qui vous permet d'identifier le produit à l'origine de l'erreur. L'ensemble des journaux générés à partir de la même tentative de mise en service partage un sessionId.
Les métriques de Google Home Analytics vous donnent une idée initiale de l'étape à laquelle le problème peut se produire. Pour déterminer l'origine des erreurs de mise en service de l'appareil, vous devrez peut-être effectuer un débogage supplémentaire à l'aide des journaux générés par l'appareil mobile utilisé lors du processus de mise en service. Pour cela, vous avez besoin d'Android Debug Bridge.
Utiliser Android Debug Bridge (ADB)
Vous pouvez également résoudre les problèmes de mise en service à l'aide de l'outil de ligne de commande Android Debug Bridge (ADB). Étant donné que la mise en service est principalement gérée entre l'appareil mobile et l'appareil Matter, vous pouvez utiliser l'outil ADB pour accéder aux journaux générés par l'application Google Home tout au long de la mise en service.
Installer les outils de la plate-forme
ADB est fourni avec les outils de plate-forme du SDK Android, qui peuvent être installés avec Android Studio ou via l'outil de ligne de commande sdkmanager.
Une fois que vous avez installé les outils de plate-forme sur votre système, vérifiez ADB en vérifiant le numéro de version dans le terminal à l'aide de la commande suivante :
$ adb -- version
Le numéro de version de l'utilitaire ADB installé devrait s'afficher sans erreur.
Activer le débogage USB
Activez ensuite le débogage USB sur votre appareil Android.
Commencez par activer les options pour les développeurs sur votre appareil, puis activez le débogage USB.
Cela permet à ADB d'accéder aux journaux générés par les applications actuellement exécutées sur l'appareil.
Récupérer l'ID de l'appareil
- Exécutez le serveur ADB à l'aide de la commande suivante :
$ adb start-server
- Connectez votre téléphone à l'ordinateur exécutant le serveur ADB.
Vous pouvez recevoir un message d'avertissement sur votre téléphone concernant le débogage USB, vous demandant si vous souhaitez autoriser votre ordinateur à accéder aux informations de votre téléphone :
- Si ce message s'affiche, cliquez sur Autoriser.
- Exécutez une commande permettant de lister les appareils à partir du terminal pour voir si votre ordinateur peut accéder au téléphone via ADB, à l'aide de la commande suivante:
$ adb devices
Vous devriez obtenir un résultat semblable à celui-ci:
List of devices attached <phone-id> device
Votre <phone-id> est une chaîne alphanumérique qui identifie de manière unique votre appareil.
- Mémorisez la valeur
<phone-id>, car vous l'utiliserez dans les étapes suivantes.
Collecter les informations système
Vérifiez ensuite les informations de version des applications et du système sur votre appareil.
- Pour vérifier la version du système d'exploitation Android :
$ adb -s <phone-id> shell getprop ro.build.version.release
- Pour connaître la version de l'application Google Home:
$ adb -s <phone-id> shell dumpsys package com.google.android.apps.chromecast.app | grep versionName
- Pour connaître la version des services Google Play :
$ adb -s <phone-id> shell dumpsys package com.google.android.gms | grep "versionName"
- Pour vérifier si vous disposez des modules de contrôle Home / Matter via les services Play:
$ adb -s <phone-id> shell dumpsys activity provider com.google.android.gms.chimera.container.GmsModuleProvider | grep "com.google.android.gms.home"
Assurez-vous que ces valeurs de retour sont compatibles avec notre écosystème. Lorsque vous contactez l'assistance pour des échecs de mise en service, veuillez toujours inclure des informations sur le système dans vos demandes d'assistance.
Collecter les journaux d'erreurs
Ensuite, démarrez le processus de collecte des journaux, puis suivez la procédure de mise en service pour générer les événements d'erreur que vous souhaitez déboguer.
- Exécutez la commande suivante en fournissant votre
<phone-id>, ainsi qu'un<file-name>où les journaux seront enregistrés sur votre ordinateur (par exemple,debug_file.txt).
$ adb -s <phone-id> logcat > <file-name>
Le processus de journalisation démarre immédiatement. Si ce n'est pas déjà le cas, un fichier portant le nom fourni est créé, et les journaux du téléphone y sont ajoutés après chaque événement.
Effectuez les étapes de mise en service avec votre appareil Matter.
- Une fois que vous avez atteint l'erreur que vous souhaitez déboguer, arrêtez la journalisation en appuyant sur
Control+Cdans la fenêtre du terminal en cours d'exécution.
Vos journaux devraient désormais être stockés dans le fichier de journalisation <file-name>. Étant donné que ce processus enregistre les journaux de chaque processus en cours d'exécution suivi sur l'appareil, ce fichier contient de nombreux journaux. C'est pourquoi vous devez toujours utiliser ces journaux en recherchant les entrées dont vous avez besoin.
Analyser les journaux d'erreur
Les processus de mise en service sont gérés par un sous-système appelé MatterCommissioner dans GHA.
- En suivant la stratégie principale utilisée lors de l'analyse des erreurs de mise en service, recherchez les erreurs générées par le sous-système MatterCommissioner à l'aide de la commande suivante:
$ grep "MatterCommissioner" <file-name>
Cela génère une sortie contenant les événements du processus de mise en service.
- Si votre appareil Matter utilise Thread, vous pouvez également rechercher les erreurs générées par le sous-système Thread à l'aide de la commande suivante :
$ grep -E "(ThreadNetworkManager|BorderAgentScannerImpl|ThreadBrSynchronizer)" <file-name>
Lorsque vous analysez le fichier journal généré par le processus de débogage ADB, recherchez également certains modèles. De nombreuses erreurs de mise en service incluent la chaîne "commissioning failure" dans son message d'erreur.
- Recherchez un message d'échec de mise en service à l'aide de la commande suivante:
$ grep "SetupDevice" $phonelog | grep -A 20 "Commissioning failed"
4. Déboguer les problèmes de contrôle des appareils
Une fois que les utilisateurs ont configuré et mis en service des appareils Matter dans l'écosystème Google Home, ils peuvent émettre des commandes vocales à l'aide de l'Assistant Google (par exemple, "Ok Google, allume la lumière dans le salon") ou via l'UI de l'application Home ou des écrans Google Nest.
Comme la spécification de contrôle entre les appareils finaux et les hubs Google est gérée par Matter, on devrait constater moins d'erreurs du côté de la commande des appareils. Dans tous les cas, nous vous fournissons des métriques et des journaux pour vous aider à déboguer ces types de problèmes.
Utiliser des métriques
Le tableau de bord d'intégration Matter affiche plusieurs métriques concernant le contrôle des appareils. Trois graphiques sont essentiels pour évaluer les performances de vos appareils sur le terrain :
En cas de problème de contrôle, le pourcentage de réussite est généralement à la baisse et le graphique de répartition des erreurs à la hausse. Le graphique de répartition des erreurs indique les erreurs capturées par les Google Nest Hub concernant l'échec de la tentative de contrôle de l'appareil.
Utiliser les journaux
Chaque problème de contrôle des appareils Matter génère également un journal des erreurs dans le système. Vous pouvez filtrer ces erreurs dans l'explorateur de journaux en recherchant "executionLog".
Les journaux d'erreurs de contrôle des appareils Matter se présentent comme suit :
{
"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"
}
Chaque journal d'erreurs contient un code temporel, un type d'appareil et une caractéristique, ainsi que l'erreur associée à la requête de contrôle dans statusType. De nombreuses erreurs de contrôle incluent également un externalDebugString, un bref message d'erreur qui explique en quoi consiste l'erreur.
5. Déboguer d'autres fonctionnalités
Jusqu'à présent, vous avez appris à gérer les problèmes de mise en service et de contrôle des appareils pour Matter. Vous pouvez également utiliser nos techniques recommandées pour assurer une intégration de qualité dans d'autres fonctionnalités de l'écosystème.
Suivre les mises à jour OTA
Pour suivre les versions des mises à jour Over The Air (OTA) des appareils Matter publiées par Google Home, nous fournissons un ensemble de métriques qui indiquent les versions matérielles et logicielles des appareils sur le terrain.
Une fois que vous avez publié une mise à jour depuis la console, surveillez les métriques suivantes :
Vous constaterez que dans les jours qui suivent la publication, de plus en plus d'appareils sur le terrain reçoivent la nouvelle version logicielle associée à votre version logicielle OTA.
6. Demander de l'aide
Google fournit des outils et de la documentation pour vous aider à déboguer vos problèmes liés à Matter. Toutefois, comme l'écosystème Matter est nouveau, il existe des problèmes que ces ressources ne couvrent pas. Dans ce cas, n'hésitez pas à nous contacter ou à solliciter l'aide de la communauté.
Accéder aux canaux pour les développeurs
Google surveille activement trois canaux pour les développeurs :
Bien que chaque canal soit surveillé régulièrement par la même équipe, il existe des différences clés quant au moment où utiliser l'un ou l'autre.
- Stack Overflow:si vous avez des questions sur l'implémentation ou si vous avez besoin d'aide, n'hésitez pas à nous contacter ou à contacter la communauté des développeurs pour la maison connectée. Ce canal est idéal pour demander comment résoudre des problèmes ou implémenter une fonctionnalité spécifique.
- Issue Tracker:il s'agit du système officiel de suivi des problèmes géré par Google. Les audiences externes peuvent signaler des erreurs sur l'écosystème. Il fournit des outils Web pour joindre des fichiers et partager des informations sensibles si nécessaire. L'outil Issue Tracker est le meilleur moyen de signaler des problèmes liés à l'écosystème ou de partager des demandes de fonctionnalités.
- Forum des développeurs : pour obtenir des conseils de la part de l'assistance Google officielle et des experts de la communauté, vous pouvez contacter le forum des développeurs Nest. Ce forum est le meilleur endroit pour obtenir des conseils officiels sur le développement.
S'inscrire à la newsletter pour les développeurs
En plus de consulter les canaux des développeurs pour poser vos questions, vous pouvez également recevoir une newsletter trimestrielle qui présente les nouvelles fonctionnalités et les dernières informations sur l'état de l'écosystème Google Home.
Vous pouvez utiliser le formulaire d'inscription pour recevoir la newsletter destinée aux développeurs.
7. Félicitations
Félicitations ! Vous avez appris à déboguer les intégrations Matter à l'aide des outils et techniques que nous recommandons. Nous vous souhaitons de passer de bons moments à créer des intégrations Matter avec Google Home.
Étapes suivantes
Essayez les exercices suivants et explorez d'autres ressources :
- En plus d'utiliser les données analytiques pour résoudre les problèmes, vous pouvez également utiliser la suite de test pour tester votre intégration afin de détecter d'éventuels problèmes.
- Une fois votre intégration prête à être partagée avec le monde entier, la prochaine étape consiste à obtenir la certification WWGH pour votre projet. Pour ce faire, suivez les étapes indiquées sur la page Certification.