Déboguer les intégrations Matter

1. Avant de commencer

Matter offre aux utilisateurs finaux une expérience fluide de configuration et de contrôle multiplate-forme des appareils. Cela est principalement dû aux multiples composants de l'écosystème qui fonctionnent en coulisse. Résoudre les problèmes liés à ce type de système peut être intimidant 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 pour Matter. Pour chacun de ces systèmes, Google fournit aux développeurs un ensemble d'analyses de dépannage collectées à partir de téléphones et de hubs:

En tant que développeur, il est essentiel que vous soyez en mesure de limiter les problèmes que vous rencontrez tout au long du cycle de développement de l'appareil. Une fois que vous avez lancé votre projet, vous devez surveiller de manière globale les tendances des problèmes rencontrés par les appareils sur le terrain, et les résoudre grâce à des mises à jour logicielles. Cet atelier de programmation présente des techniques que vous pouvez utiliser à ces deux fins.

Conditions préalables

• Suivez le guide Premiers pas avec Matter avec un projet Matter et une configuration d'appareil opérationnels.
• disposer d'un téléphone Android que vous pouvez connecter à votre poste de travail (pour les journaux ADB) ;

Points abordés

• Comment utiliser les outils d'analyse pour la maison connectée afin de surveiller les problèmes liés à Matter à grande échelle
• Comment trier les erreurs en accédant aux journaux d'erreurs et en collectant des informations ?
• Comment accéder à la documentation et aux ressources d'assistance Matter pour obtenir de l'aide

2. Afficher les données analytiques de Google Home

Surveiller les performances est essentiel à une intégration réussie dans l'écosystème Google Home. Nous fournissons aux développeurs un ensemble d'outils de surveillance sur Google Cloud Platform. Vous pouvez utiliser ces outils pour obtenir une mesure de la performance de votre projet.

Accéder aux métriques du projet

• Pour accéder à vos données, la première étape consiste à 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.

Plusieurs tableaux de bord sont disponibles pour votre projet (y compris d'autres produits GCP). Les tableaux de bord fournis pour la maison connectée affichent le 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 des intégrations spécifiques (Cloud, Local, Matter) ou des types d'appareils (Appareils photo). Ces tableaux de bord ne contiennent des données que si vous avez une intégration du type correspondant, ainsi qu'un projet fonctionnel qui traite les requêtes.

Lorsque vous ouvrez l'un de ces tableaux de bord, vous voyez une série de graphiques qui se présentent comme suit:

Les tableaux de bord Google Home contiennent divers graphiques qui détaillent les événements associés à votre projet. Chaque tableau de bord d'intégration comprend 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, et plusieurs graphiques présentant les types d'appareils et les caractéristiques impliqués. De plus, Matter vous permet de disposer d'un ensemble de graphiques qui suivent 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 Analytics de Google Home n'est qu'une vue que nous avons créée pour votre projet à l'aide des données de métriques pour la maison connectée. Vous pouvez également utiliser l'Explorateur de métriques pour créer vos propres graphiques à partir des 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 gérer les journaux d'événements générés pour un projet. Il est accessible dans la console Google Cloud en accédant à Opérations > Journaux > Explorateur de journaux.

Une fois l'explorateur de journaux ouvert, vous obtenez une vue semblable à 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 reviendrons sur ce point plus en détail dans les sections consacrées au 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 des étapes nécessaires pour qu'un utilisateur configure un appareil Matter pour la première fois.

Lors de la mise en service d'un appareil, un ensemble d'interactions a lieu entre l'appareil Matter, l'application Google Home et la structure Matter. L'image suivante illustre certains de ces événements:

Consultez la page de mise en service de Matter Primer pour en savoir plus sur chacune de ces étapes. Dans cette section, nous aborderons 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 pour vous permettre d'examiner les problèmes de mise en service en suivant les événements et en déterminant à quel moment les erreurs peuvent se produire. Vous pouvez les trouver 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 du 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çue 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 dans l'un de ces états, elle est également capturé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 commission, vous pouvez rechercher "clientUpdateLog" avec "severity>=ERROR" dans le champ de requête.

Voici à quoi ressemble un journal d'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 d'erreurs contient les codes temporels de l'erreur capturée, ainsi que l'ID produit Matter qui vous permet d'identifier les produits à l'origine de l'erreur. L'ensemble des journaux générés lors de la même tentative de mise en service partagent un sessionId.

Les métriques d'Analytics dans Google Home vous donnent une idée initiale à quel stade le problème peut survenir. Pour identifier l'origine des erreurs de mise en service d'un appareil, il est parfois nécessaire d'effectuer des opérations de débogage supplémentaires à l'aide des journaux générés par l'appareil mobile utilisé lors du processus de mise en service. Pour ces éléments, 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 se fait principalement entre l'appareil mobile et l'appareil Matter, il est possible d'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 Android SDK Platform Tools, qui peut être installé 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 le numéro de version d'ADB sur 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

Vous devez ensuite activer le débogage USB sur votre appareil Android.

Commencez par suivre la procédure d'activation des options pour les développeurs sur votre appareil, puis pour activer le débogage USB.

ADB peut ainsi accéder aux journaux générés par les applications en cours d'exécution sur l'appareil.

Récupérer l'ID de l'appareil

1. Exécutez le serveur ADB à l'aide de la commande suivante:

$ adb start-server

2. Connectez votre téléphone à l'ordinateur qui exécute le serveur ADB.

Il est possible qu'un message d'avertissement concernant le débogage USB s'affiche sur votre téléphone, vous demandant si vous souhaitez autoriser votre ordinateur à accéder aux informations de votre téléphone:

3. Si ce message d'avertissement s'affiche, cliquez sur Autoriser.
4. À partir du terminal, exécutez une commande permettant de lister les appareils pour vérifier si votre ordinateur peut accéder au téléphone via ADB à l'aide de la commande suivante:

$ adb devices

Vous devriez obtenir une réponse semblable à celle-ci:

List of devices attached
<phone-id>    device

Votre <phone-id> est une chaîne alphanumérique qui identifie votre appareil de façon unique.

5. Mémorisez la valeur <phone-id>, car vous en aurez besoin lors des prochaines étapes.

Collecter des informations système

Vous devez ensuite vérifier les informations de version des applications et du système de 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 renvoyées sont compatibles avec notre écosystème. Lorsque vous contactez l'assistance en cas d'échec de mise en service, veuillez toujours inclure les informations système dans vos demandes d'assistance.

Collecter les journaux d'erreurs

Ensuite, démarrez le processus de collecte des journaux, puis suivez les étapes de mise en service pour générer les événements d'erreur que vous souhaitez déboguer.

1. Exécutez la commande suivante en fournissant votre <phone-id>, ainsi qu'un fichier <file-name> où les journaux seront enregistrés sur votre ordinateur (par exemple, debug_file.txt).

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

Cela lance immédiatement le processus de journalisation. Un fichier portant le nom indiqué est créé s'il n'existe pas déjà, et les journaux du téléphone sont ajoutés au fichier après chaque événement.

Suivez la procédure de mise en service avec votre appareil Matter.

2. Une fois que vous avez trouvé l'erreur à déboguer, arrêtez la journalisation en appuyant sur Control+C dans la fenêtre de terminal en cours d'exécution.

Vos journaux devraient maintenant être stockés dans le fichier de journalisation <file-name>. Comme ce processus enregistre les journaux de chaque processus en cours d'exécution suivi sur l'appareil, ce fichier contiendra beaucoup de journaux. C'est pourquoi vous devez toujours utiliser ces journaux en recherchant les entrées dont vous avez besoin.

Analyser les journaux d'erreurs

Les processus de mise en service sont gérés via un sous-système appelé "MatterCommissioner" dans GHA.

1. En suivant la principale stratégie 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>

Cette commande génère une sortie contenant les événements du processus de mise en service.

2. 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 le message d'erreur.

3. Recherchez un message d'échec de la 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.

Étant donné que la spécification de contrôle entre les appareils finaux et les hubs Google repose sur la médiation Matter, il est probable qu'il y ait moins d'erreurs au niveau des commandes des appareils. Quoi qu'il en soit, nous fournissons des métriques et des journaux vous permettant de résoudre également ce type de problème.

Utiliser les métriques

Dans le tableau de bord d'intégration de Matter, vous verrez plusieurs métriques concernant le contrôle des appareils. Trois graphiques sont essentiels pour évaluer les performances de vos appareils sur le terrain:

Lors des problèmes de contrôle, vous voyez généralement des tendances à la baisse dans le pourcentage de réussite et une tendance à la hausse dans le graphique de répartition des erreurs. Le graphique de répartition des erreurs affiche les erreurs enregistrées par Google Nest Hub et explique pourquoi la tentative de contrôle de l'appareil a échoué.

Utiliser des journaux

Chaque problème de contrôle des appareils Matter génère également un journal d'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, une caractéristique, ainsi que l'erreur associée à la requête de contrôle dans le statusType. De nombreuses erreurs de contrôle incluent également un externalDebugString, un court message d'erreur qui explique la cause de 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 Matter. Il existe également d'autres fonctionnalités de l'écosystème pour lesquelles vous pouvez appliquer les techniques recommandées pour assurer une intégration de bonne qualité.

Suivre les mises à jour OTA

Pour suivre les mises à jour Over The Air (OTA) des appareils Matter émises par Google Home, nous fournissons un ensemble de métriques indiquant les versions matérielles et logicielles des appareils sur le terrain.

Lorsque vous publiez une mise à jour depuis la console, tenez compte des métriques suivantes:

Dans les jours qui suivent la sortie, de plus en plus d'appareils sur le terrain obtiennent la nouvelle version logicielle associée à votre version logicielle OTA.

6. Rechercher une assistance

Google vous fournit des outils et de la documentation pour vous aider à déboguer vos problèmes Matter. Cependant, comme l'écosystème Matter est nouveau, il y aura des problèmes que ces ressources ne couvriront pas. Dans ce cas, vous pouvez toujours contacter notre équipe ou contacter la communauté pour demander de l'aide.

Accéder aux chaînes pour les développeurs

Trois canaux pour les développeurs sont activement surveillés dans Google:

Bien que chacun de ces canaux soit surveillé régulièrement par la même équipe, il existe des différences importantes au moment de choisir lequel utiliser.

• Stack Overflow:n'hésitez pas à nous contacter ainsi qu'à la communauté des développeurs pour la maison connectée si vous avez des questions sur l'implémentation ou si vous avez besoin d'aide. Elle est idéale 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, qui permet aux audiences externes de signaler les 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 idéal pour signaler des problèmes liés à l'écosystème ou partager des demandes de fonctionnalités.
• Forum des développeurs:pour obtenir des conseils auprès de l'assistance Google officielle et des experts de la communauté, vous pouvez le contacter via le forum des développeurs Nest. Ce forum est idéal pour obtenir des recommandations officielles de développement.

Inscrivez-vous à la newsletter pour les développeurs

Outre la consultation des canaux des développeurs pour les questions, nous publions également une newsletter trimestrielle qui présente les nouvelles fonctionnalités et donne des informations sur l'état de l'écosystème Google pour la maison connectée.

Pour recevoir la newsletter pour les développeurs, utilisez le formulaire d'inscription.

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 un bon moment pour 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 tests pour tester votre intégration par rapport à d'éventuels problèmes.
• Une fois que votre intégration est prête à être partagée avec le monde entier, vous devez obtenir la certification Fonctionne avec Google pour votre projet. Pour ce faire, suivez les étapes de la page Certification.