Déboguer les intégrations Matter

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 coulisses. Le dépannage de systèmes comme ceux-ci peut souvent être intimidant pour les nouveaux développeurs. Nous avons donc 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 aborde 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 résoudre 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 les tendances des problèmes pour les appareils sur le terrain de manière agrégée et les résoudre par le biais de mises à jour logicielles. Cet atelier de programmation présente les techniques que vous pouvez utiliser à ces deux fins.

Prérequis

• Avoir terminé le guide Premiers pas avec Matter avec un projet Matter fonctionnel et un appareil configuré
• Disposer d'un téléphone Android que vous pouvez connecter à votre poste de travail (pour les journaux ADB)

Points abordés

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

2. Afficher les données analytiques Google Home

Il est essentiel de surveiller les performances pour réussir l'intégration à l'écosystème Google Home. Nous fournissons un ensemble d'outils de surveillance aux développeurs pour la maison connectée sur la plate-forme Google Cloud. Vous pouvez utiliser ces outils pour mesurer les performances de votre projet.

Accéder 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.

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 du préfixe "Google Home Analytics".

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 et d'un projet fonctionnel qui répond aux demandes.

Lorsque vous ouvrez l'un de ces tableaux de bord, une série de graphiques semblables à ceux ci-dessous s'affiche :

Les tableaux de bord Google Home contiennent différents graphiques qui affichent des informations sur les événements associés à votre projet. Chaque tableau de bord d'intégration comporte 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 indiquant les types et les caractéristiques des appareils concernés. De plus, avec Matter, vous disposez d'un ensemble de graphiques qui suivent le succès 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 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ê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 d'utiliser les journaux d'événements générés dans un projet. Pour y accéder, accédez à Google Cloud Console, puis à Opérations > Journalisation > Explorateur de journaux.

Une fois l'explorateur de journaux ouvert, vous obtenez une vue semblable à celle-ci :

La fenêtre de l'explorateur contient différents 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 sur le débogage.

3. Résoudre 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 à un utilisateur pour configurer 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 le réseau Matter. L'image suivante illustre certains de ces événements :

Pour en savoir plus sur chacune de ces étapes, consultez la page sur la mise en service du guide Matter. Dans cette section, nous allons aborder 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 aider à examiner les problèmes de mise en service en suivant les événements et en identifiant l'étape à laquelle les erreurs peuvent se produire. Vous les trouverez dans le tableau de bord d'intégration Matter, comme indiqué 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ç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 dans l'un de ces états, elle est également enregistrée dans le graphique de répartition des erreurs.

États de la 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 mise en service, vous pouvez rechercher "clientUpdateLog" associé à "severity>=ERROR" dans le champ de requête.

Voici un exemple de 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 des codes temporels pour l'erreur capturée, ainsi que l'ID 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 partagent un sessionId.

Les métriques de Google Home Analytics vous donnent une première idée de l'étape à laquelle le problème peut se produire. Pour identifier la cause première des erreurs de mise en service des appareils, vous devrez peut-être effectuer un débogage supplémentaire à l'aide des journaux générés par l'appareil mobile utilisé lors de la mise en service. Pour cela, vous avez besoin d'Android Debug Bridge.

Utiliser Android Debug Bridge (ADB)

Vous pouvez également utiliser l'outil de ligne de commande Android Debug Bridge (ADB) pour résoudre les problèmes de mise en service. Étant donné que la mise en service est 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 plate-forme

ADB fait partie des outils de plate-forme du SDK Android, qui peuvent être installés avec Android Studio ou à l'aide de 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 consultant 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é doit s'afficher sans erreur.

Activer le débogage USB

Ensuite, activez le débogage USB sur votre appareil Android.

Commencez par suivre la procédure pour 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 avec la commande suivante :

$ adb start-server

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

Un message d'avertissement peut s'afficher sur votre téléphone concernant le débogage USB. Il vous demande 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. Exécutez une commande list devices depuis le terminal 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 manière unique.

5. Mémorisez la valeur <phone-id>, vous en aurez besoin à l'étape suivante.

Collecter des informations système

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

• Pour vérifier la version de l'OS Android :

$ adb -s <phone-id> shell getprop ro.build.version.release

• Pour vérifier la version de l'application Google Home :

$ adb -s <phone-id> shell dumpsys package com.google.android.apps.chromecast.app | grep versionName

• Pour vérifier 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 acceptées par notre écosystème. Lorsque vous demandez de l'aide en cas d'échec de la mise en service, veuillez toujours inclure des informations sur le 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> 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. Un fichier portant le nom fourni est créé s'il n'existe pas déjà, et les journaux du téléphone y sont ajoutés après chaque événement.

Suivez les étapes de mise en service de votre appareil Matter.

2. Une fois que vous avez trouvé 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 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.

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>

Cela génère un résultat 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 schémas. De nombreuses erreurs de mise en service incluent la chaîne "commissioning failure" dans leur 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 les lumières du salon") ou en utilisant l'interface utilisateur 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 est assurée par Matter, le nombre d'erreurs devrait être moins élevé du côté du contrôle des appareils. Dans tous les cas, nous vous fournissons des métriques et des journaux pour vous aider à résoudre ces types de problèmes.

Utiliser des métriques

Dans le tableau de bord d'intégration Matter, vous trouverez 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èmes de contrôle, vous constaterez généralement une tendance à la baisse du pourcentage de réussite et une tendance à la hausse dans le graphique de répartition des erreurs. Le graphique de répartition des erreurs vous montre les erreurs détectées par les Google Nest Hubs 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 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, le type d'appareil et le trait, 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 qui explique le problème.

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. L'écosystème propose également d'autres fonctionnalités et techniques recommandées pour garantir une intégration de 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 qui indiquent les versions matérielles et logicielles des appareils sur le terrain.

Une fois que vous avez effectué 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 mise à jour logicielle OTA.

6. Demander de l'aide

Google fournit des outils et de la documentation pour vous aider à résoudre vos problèmes liés à Matter. Toutefois, comme l'écosystème Matter est nouveau, il est possible que ces ressources ne couvrent pas tous les problèmes. Dans ce cas, vous pouvez toujours nous contacter ou solliciter la communauté pour obtenir de l'aide.

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

Chez Google, trois canaux de développeurs sont activement surveillés :

Bien que chacun de ces canaux soit surveillé périodiquement par la même équipe, il existe des différences essentielles quant à leur utilisation.

• Stack Overflow : vous pouvez nous contacter, ainsi que la communauté des développeurs pour la maison connectée, si vous avez des questions sur l'implémentation ou si vous avez besoin de conseils. Ce canal est idéal pour demander comment résoudre des problèmes ou implémenter une fonctionnalité spécifique.
• Outil de suivi des problèmes : il s'agit du système officiel de suivi des problèmes géré par Google, où les audiences externes peuvent signaler les erreurs de l'écosystème. Il fournit des outils Web permettant de joindre des fichiers et de 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 de l'aide auprès de l'assistance Google officielle et des experts de la communauté, vous pouvez contacter le forum des développeurs Nest. Ce forum est idéal pour obtenir des conseils officiels sur le développement.

S'inscrire à la newsletter pour les développeurs

En plus de pouvoir poser vos questions sur les canaux pour les développeurs, nous publions également une newsletter trimestrielle qui présente les nouvelles fonctionnalités et l'état de l'écosystème Google pour la maison connectée.

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 un bon moment à créer des intégrations Matter avec Google Home.

Étapes suivantes

Faites 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 et détecter d'éventuels problèmes.
• Une fois votre intégration prête à être partagée avec le monde entier, l'étape suivante consiste à obtenir la certification WWGH pour votre projet. Pour ce faire, suivez les étapes décrites sur la page Certification.