Déboguer les intégrations Matter

1. Avant de commencer

Matter offre aux utilisateurs finaux une expérience de configuration et de contrôle simple 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 comprend 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 de téléphones et de hubs:

Mise en service, exécution, mise à jour OTA

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 pour les appareils sur le terrain et les résoudre par le biais de mises à jour logicielles. Cet atelier de programmation présente des techniques que vous pouvez utiliser à ces deux fins.

Prérequis

  • Suivez le guide Premiers pas avec Matter en veillant à ce que votre projet et votre appareil Matter fonctionnent correctement.
  • disposer d'un téléphone Android que vous pouvez connecter à votre station 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 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

La surveillance des performances est essentielle pour une intégration réussie dans l'écosystème Google Home. Nous mettons un ensemble d'outils de surveillance à la disposition des développeurs pour la maison connectée sur Google Cloud Platform. Vous pouvez utiliser ces outils pour obtenir une mesure des performances 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 cela, connectez-vous à la console Google Cloud et 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 sont précédés de Google Analytics pour la maison.

Tableaux de bord Analytics sur Google Home

Nous disposons actuellement d'un tableau de bord général qui couvre l'ensemble de votre projet, ainsi que de tableaux de bord pour des intégrations spécifiques (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, ainsi qu'un projet fonctionnel répondant aux 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:

Répartition du taux de réussite, de la latence et des types d'appareils

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 propose un ensemble de graphiques qui suivent la réussite de la mise en service, ainsi que les déploiements des mises à jour sur vos appareils.

Notez que la vue par défaut qui s'affiche dans les tableaux de bord Analytics de Google Home correspond simplement à une vue que nous avons créée pour votre projet à l'aide des métriques de la 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 qui permet d'exploiter les journaux d'événements générés sur un projet. Il est accessible dans la console Google Cloud en sélectionnant Opérations > Journalisation > Explorateur de journaux.

Lorsque vous ouvrez l'explorateur de journaux, la vue qui s'affiche ressemble à celle-ci:

Explorateur de journaux

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 à partir de 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 parlerons plus en détail dans les sections sur le débogage.

3. Résoudre les problèmes de mise en service

La première métrique que nous allons étudier concerne les événements de mise en service avec 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 des appareils, 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:

Événements de mise en service d'un litige

Vous pouvez consulter la page de mise en service de Matter Prime pour en savoir plus sur chacune de ces étapes. Dans cette section, nous allons aborder les outils et techniques permettant de résoudre 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 des 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:

Métriques de 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 de 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 > Journalisation > Explorateur de journaux : Pour filtrer les erreurs de commission, vous pouvez rechercher "clientUpdateLog" associé à "severity>=ERROR" dans le champ de requête.

Un journal des erreurs de mise en service pour Matter se présente comme suit:

{
  "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 de journaux générés à partir de la même tentative de mise en service partagent un sessionId.

Les métriques de Google Home Analytics vous permettent de savoir à quel moment le problème peut survenir. Pour identifier la cause des erreurs de mise en service de l'appareil, vous devrez parfois 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 celles-ci, 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). La mise en service étant principalement gérée 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 ADB en vérifiant le numéro de version à partir du 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 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 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
  1. Connectez votre téléphone à l'ordinateur exécutant 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:

Invite de débogage USB

  1. Si ce message d'avertissement s'affiche, cliquez sur Autoriser.
  2. 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 votre appareil de façon unique.

  1. Mémorisez la valeur <phone-id> pour l'utiliser lors des prochaines étapes.

Collecter les informations système

Ensuite, vérifiez les informations sur la version des applications et du système sur votre appareil.

  • Pour connaître la version de la plate-forme 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 soutenues par notre écosystème. Lorsque vous demandez de l'aide concernant un échec de mise en service, veuillez toujours inclure les informations système dans vos demandes d'assistance.

Collecter les journaux d'erreurs

Ensuite, lancez 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 <file-name> dans lequel 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 fourni est créé s'il n'existe pas encore. Les journaux du téléphone sont ajoutés au fichier après chaque événement.

Effectuez les étapes de mise en service avec votre appareil Matter.

  1. Lorsque vous arrivez à l'erreur que vous souhaitez 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>. Étant donné que ce processus enregistre les journaux de chaque processus en cours d'exécution suivi dans 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 au sein de GHA.

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

Une sortie contenant les événements du processus de mise en service est alors générée.

  1. 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 "commissioning failure" dans son message d'erreur.

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

Étant donné que la spécification de contrôle entre les appareils finaux et les hubs Google Hub fait l'objet d'une médiation Matter, il devrait y avoir moins d'erreurs du côté des commandes de contrôle 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

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

Graphiques de réussite, de latence et de répartition des erreurs

Lors des problèmes de contrôle, vous constatez généralement une évolution à la baisse du pourcentage de réussite et une hausse dans le graphique de répartition des erreurs. Le graphique de répartition des erreurs indique les erreurs enregistrées par Google Nest Hub concernant les raisons de l'échec de la tentative de contrôle de l'appareil.

Utiliser les journaux

Chaque problème de contrôle d'appareil 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 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 court message d'erreur expliquant la nature 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 pour Matter. D'autres fonctionnalités de l'écosystème sont également disponibles. Vous pouvez utiliser les techniques que nous recommandons pour assurer une intégration de bonne qualité.

Suivre les mises à jour OTA

Pour suivre les versions 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, gardez un œil sur les métriques suivantes:

Pannes logicielles et matérielles

Dans les jours qui suivent, de plus en plus d'appareils sur le terrain reçoivent la nouvelle version associée à la version du logiciel OTA.

6. Rechercher de l'aide

Google vous fournit des outils et de la documentation pour résoudre les problèmes liés à Matter, mais comme l'écosystème Matter est nouveau, certains problèmes ne seront pas couverts par ces ressources. Dans ce cas, vous pouvez toujours demander de l'aide à nous ou à la communauté.

Accéder aux canaux pour les développeurs

Il existe trois canaux pour les développeurs activement surveillés au sein de Google:

Stack Overflow, outil de suivi des problèmes, forum des développeurs

Bien que chacun de ces canaux soit surveillé régulièrement par la même équipe, il existe des différences majeures quant au moment où l'utiliser.

  • 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 les erreurs survenues dans 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:si vous souhaitez obtenir des conseils auprès de l'assistance Google officielle et des experts de la communauté, vous pouvez nous contacter via le forum des développeurs Nest. Ce forum est idéal pour obtenir des conseils officiels pour le développement.

S'inscrire à la newsletter pour les développeurs

En plus de consulter les chaînes destinées aux développeurs pour toute question, nous publions également une newsletter trimestrielle présentant les nouvelles fonctionnalités et les actualités sur l'état de l'écosystème de la maison connectée Google.

Pour recevoir la newsletter pour les développeurs, vous pouvez utiliser le formulaire d'inscription.

7. Félicitations

Google Home

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 découvrez des ressources supplémentaires:

  • 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 afin de détecter d'éventuels problèmes.
  • Une fois que votre intégration est prête à être diffusée dans le monde entier, vous devez obtenir la certification Fonctionne avec Google Home. Pour ce faire, suivez les étapes indiquées sur la page Certification.