Cette page a été traduite par l'API Cloud Translation.

Déboguer la page d'accueil locale

1. Avant de commencer

Lorsque l'Assistant Google est intégré à la maison connectée, il peut contrôler les appareils dont les utilisateurs sont équipés. Pour créer une action de maison connectée, vous devez fournir un point de terminaison de webhook cloud capable de gérer les intents de maison connectée. Par exemple, lorsqu'un utilisateur dit "Hey Google, allume la lumière", l'Assistant envoie la commande à votre traitement cloud pour actualiser l'état de l'appareil.

Le SDK Local Home améliore l'intégration en vous permettant d'ajouter un chemin d'accès local qui route ces intents directement vers Google Home. Le traitement des commandes des utilisateurs est ainsi plus fiable et plus rapide. Il permet de créer et de déployer une application de traitement local en TypeScript ou JavaScript, capable d'identifier les appareils et d'exécuter des commandes sur n'importe quels enceinte intelligente Google Home ou écran connecté Google Nest. Votre application communique ensuite directement avec les appareils connectés des utilisateurs, via le réseau local, en utilisant les protocoles standards existants pour traiter les commandes.

Le débogage des actions pour la maison connectée est une étape essentielle pour créer des actions de qualité de production, mais il s'agit d'un processus difficile et chronophage qui nécessite des outils d'information et de dépannage et de test faciles à utiliser. Pour faciliter le débogage des actions de maison connectée, les métriques, la journalisation et la suite de test pour la maison connectée de Google Cloud Platform (GCP) vous aident à identifier et à résoudre les problèmes liés à vos actions.

Conditions préalables

Guide du développeur Créer une action de maison connectée
Exécuter l'atelier de programmation Activer le traitement en local pour les actions de maison connectée

Objectifs de l'atelier

Dans cet atelier de programmation, vous allez créer un fulfillment local pour les actions de maison connectée et le connecter à l'Assistant, puis déboguer l'application Local Home via la suite de tests pour la maison connectée et les métriques Google Cloud Platform (GCP).

Points abordés

Utiliser les métriques et la journalisation GCP pour identifier et résoudre les problèmes de production
Utiliser la suite de tests pour identifier les problèmes fonctionnels et liés aux API
Utiliser les outils pour les développeurs Chrome lors du développement de votre application Local Home

Ce dont vous avez besoin

La dernière version de Google Chrome
Appareil iOS ou Android avec l'application Google Home
Enceinte intelligente Google Home ou écran connecté Google Nest
Node.js version 10.16 ou ultérieure
Un compte Google.
Un compte de facturation Google Cloud

2. Exécuter l'application du lave-linge

Obtenir le code source

Cliquez sur le lien suivant pour télécharger l'exemple utilisé dans cet atelier de programmation sur votre ordinateur de développement :

Vous pouvez également cloner le dépôt GitHub à partir de la ligne de commande :

$ git clone https://github.com/googlecodelabs/smarthome-debug-local.git

À propos du projet

L'application de démarrage contient des sous-répertoires et des fonctions cloud similaires à ceux de l'atelier de programmation Activer le fulfillment local pour les actions de maison connectée. Mais au lieu de app-start, nous avons app-faulty ici. Nous allons commencer avec une application de maison connectée locale qui fonctionne, mais pas bien.

Se connecter à Firebase

Nous utiliserons le projet que vous avez créé dans l'atelier de programmation Activer le traitement en local pour les actions de maison connectée, mais nous déploierons les fichiers téléchargés dans cet atelier de programmation.

Accédez au répertoire app-faulty, puis configurez la CLI Firebase avec votre projet Actions créé dans l'atelier de programmation Activer le fulfillment local pour les actions de maison connectée:

$ cd app-faulty
$ firebase use <project-id>

Déployer sur Firebase

Accédez au dossier app-faulty/functions et installez toutes les dépendances nécessaires à l'aide de npm :

$ cd functions
$ npm install

Remarque:Si le message ci-dessous s'affiche, vous pouvez ignorer cette étape et continuer. Cet avertissement est dû à des dépendances plus anciennes. Pour en savoir plus, cliquez ici.

found 5 high severity vulnerabilities
  run `npm audit fix` to fix them, or `npm audit` for details

Accédez au répertoire app-faulty/local/ et exécutez les commandes suivantes pour télécharger le compilateur TypeScript et compiler l'application :

$ cd ../local
$ npm install
$ npm run build

Cette opération compile la source index.ts (TypeScript) et place le contenu suivant dans le répertoire app-faulty/public/local-home/ :

bundle.js : sortie JavaScript compilée contenant l'application locale et les dépendances
index.html : page d'hébergement local utilisée pour diffuser l'application en vue d'un test sur l'appareil

Maintenant que vous avez installé les dépendances et configuré votre projet, vous êtes prêt à exécuter l'application.

$ firebase deploy

La console doit afficher le résultat suivant :

...

✔ Deploy complete!

Project Console: https://console.firebase.google.com/project/<project-id>/overview
Hosting URL: https://<projectcd -id>.web.app

Cette commande déploie une application Web, ainsi que plusieurs fonctions Cloud Functions for Firebase.

Mettre à jour HomeGraph

Ouvrez l'URL d'hébergement dans votre navigateur (https://<project-id>.web.app) pour afficher l'application Web. Dans l'UI Web, cliquez sur le bouton Actualiser pour mettre à jour HomeGraph via Request Sync avec les dernières métadonnées de l'appareil provenant de l'application de lave-linge défectueux:

Ouvrez l'application Google Home et vérifiez que votre lave-linge porte un nouveau nom intitulé "Lave-linge défectueux". Pensez à associer l'appareil à une pièce équipée d'un appareil Nest.

3. Démarrer le lave-linge connecté

Si vous avez suivi l'atelier de programmation Activer le traitement en local pour les actions de maison connectée, vous devriez déjà avoir lancé le lave-linge connecté virtuel. S'il est arrêté, n'oubliez pas de le redémarrer.

Démarrer l'appareil

Accédez au répertoire virtual-device/ et exécutez le script de l'appareil en transmettant les paramètres de configuration en tant qu'arguments :

$ cd ../../virtual-device
$ npm install
$ npm start -- \
  --deviceId=deviceid123 --projectId=<project-id> \
  --discoveryPortOut=3311 --discoveryPacket=HelloLocalHomeSDK

Vérifiez que le script de l'appareil s'exécute avec les paramètres attendus :

(...): UDP Server listening on 3311
(...): Device listening on port 3388
(...): Report State successful

4. Tester l'application Local Home

Envoyez des commandes à votre appareil à l'aide de commandes vocales sur l'appareil Google Home. Par exemple:

"Hey Google, allume mon lave-linge."

"Hey Google, démarre mon lave-linge."

"Hey Google, force la langue locale."

"Hey Google, arrête mon lave-linge."

Vous remarquerez que l'Assistant Google répond "Désolé, il semble que le lave-linge défectueux ne soit pas disponible pour le moment" lorsque vous essayez de contrôler le lave-linge après avoir forcé la machine à laver.

Cela signifie que l'appareil n'est pas accessible via un chemin d'accès local. Elle fonctionnait avant d'émettre "Hey Google, force locale", car nous reviendrons au chemin cloud lorsque l'appareil n'est pas accessible via un chemin d'accès local. Cependant, après l'option "forcer localement", l'option permettant de revenir au chemin cloud est désactivée.

Pour connaître le problème, nous allons utiliser les outils dont nous disposons: Métriques Google Cloud Platform (GCP), Logging et les outils pour les développeurs Chrome.

5. Déboguer l'application Local Home

Dans la section suivante, vous allez utiliser les outils fournis par Google pour découvrir pourquoi l'appareil n'est pas accessible via le chemin d'accès local. Vous pouvez utiliser les outils pour les développeurs Google Chrome pour vous connecter à l'appareil Google Home, consulter les journaux de la console et déboguer l'application Local Home. Vous pouvez également envoyer des journaux personnalisés à Cloud Logging afin d'identifier les principales erreurs détectées par les utilisateurs dans votre application Local Home.

Connecter les Outils pour les développeurs Chrome

Pour connecter le débogueur à votre application de traitement en local :

Assurez-vous d'avoir associé votre appareil Google Home à un utilisateur autorisé à accéder au projet de la console Actions.
Redémarrez votre appareil Google Home pour lui permettre d'obtenir l'URL de votre code HTML, ainsi que la configuration de recherche définie dans la console Actions.
Lancez Chrome sur votre ordinateur de développement.
Ouvrez un nouvel onglet Chrome, puis saisissez chrome://inspect dans le champ d'adresse pour lancer l'outil d'inspection.

Une liste d'appareils devrait s'afficher sur la page, et l'URL de votre application devrait figurer sous le nom de votre appareil Google Home.

Lancer l'outil d'inspection

Cliquez sur Inspect (Inspecter) sous l'URL de votre application pour ouvrir les Outils pour les développeurs Chrome. Sélectionnez l'onglet Console et vérifiez que le contenu de l'intent IDENTIFY produit par votre application TypeScript apparaît correctement.

Ce résultat signifie que le gestionnaire IDENTIFY a bien été déclenché, mais que le verificationId renvoyé dans IdentifyResponse ne correspond à aucun des appareils dans votre HomeGraph. Ajoutons des journaux personnalisés pour comprendre pourquoi.

Ajouter des journaux personnalisés

Même si une erreur DEVICE_VERIFICATION_FAILED est générée par le SDK Local Home, cela n'aura aucun impact. Ajoutons des journaux personnalisés pour nous assurer que nous lisons et traitons correctement les données d'analyse. Notez que si nous rejetons la promesse avec une erreur, le message d'erreur est également envoyé à Cloud Logging.

local/index.ts

identifyHandler(request: IntentFlow.IdentifyRequest):
    Promise<IntentFlow.IdentifyResponse> {
  console.log("IDENTIFY intent: " + JSON.stringify(request, null, 2));

  const scanData = request.inputs[0].payload.device.udpScanData;
  if (!scanData) {
    const err = new IntentFlow.HandlerError(request.requestId,
        'invalid_request', 'Invalid scan data');
    return Promise.reject(err);
  }

  // In this codelab, the scan data contains only local device id.
  // Is there something wrong here?
  const localDeviceId = Buffer.from(scanData.data);
  console.log(`IDENTIFY handler: received local device id
      ${localDeviceId}`);

  // Add custom logs
  if (!localDeviceId.toString().match(/^deviceid[0-9]{3}$/gi)) {
    const err = new IntentFlow.HandlerError(request.requestId,
        'invalid_device', 'Invalid device id from scan data ' +
        localDeviceId);
    return Promise.reject(err);
  }

  const response: IntentFlow.IdentifyResponse = {
    intent: Intents.IDENTIFY,
    requestId: request.requestId,
    payload: {
      device: {
        id: 'washer',
        verificationId: localDeviceId.toString(),
      }
    }
  };
  console.log("IDENTIFY response: " + JSON.stringify(response, null, 2));

  return Promise.resolve(response);
}

Modifiez également la version locale de l'application Home, afin que nous puissions déterminer si nous utilisons la bonne version.

local/index.ts

const localHomeSdk = new App('1.0.1');

Après avoir ajouté les journaux personnalisés, vous devez compiler à nouveau l'application et la redéployer sur Firebase.

$ cd ../app-faulty/local
$ npm run build
$ firebase deploy --only hosting

Redémarrez maintenant votre appareil Google Home pour qu'il puisse charger l'application locale Google Home mise à jour. Pour savoir si c'est le cas, consultez les journaux de la console dans les outils pour les développeurs Chrome.

Accéder à Cloud Logging

Voyons comment identifier les erreurs à l'aide de Cloud Logging. Pour accéder à Cloud Logging pour votre projet:

Dans la console Cloud Platform, accédez à la page Projets.
Sélectionnez votre projet de maison connectée.
Sous Opérations, sélectionnez Logging > Explorateur de journaux.

L'accès aux données de journalisation est géré via Identity and Access Management (IAM) pour les utilisateurs de votre projet Actions. Pour en savoir plus sur les rôles et les autorisations pour la journalisation des données, consultez la page Contrôle des accès de Cloud Logging.

Utiliser des filtres avancés

Nous savons que des erreurs se produisent dans l'intent IDENTIFY, car le chemin d'accès local ne fonctionne pas, car l'appareil local ne parvient pas à être identifié. Cependant, nous souhaitons connaître précisément le problème. Filtrez donc d'abord les erreurs qui se produisent dans le gestionnaire IDENTIFY.

Développez la zone Query preview (Aperçu de la requête) pour qu'elle se transforme en Query builder (Générateur de requêtes). Saisissez jsonPayload.intent="IDENTIFY" dans le champ Générateur de requêtes, puis cliquez sur le bouton Exécuter la requête.

Par conséquent, vous obtenez tous les journaux d'erreur générés dans le gestionnaire IDENTIFY. Développez ensuite la dernière erreur. Vous trouverez les errorCode et les debugString que vous venez de définir lors du refus de la promesse dans le gestionnaire IDENTIFY.

Le debugString indique que l'ID d'appareil local n'est pas au format attendu. L'application Local Home s'attend à obtenir l'ID d'appareil local sous la forme d'une chaîne commençant par deviceid, suivie de trois chiffres, mais l'ID d'appareil local est une chaîne hexadécimale.

Corriger l'erreur

Si nous revenons au code source dans lequel nous analysons l'ID d'appareil local à partir des données d'analyse, nous constatons que nous n'avons pas fourni l'encodage lors de la conversion de la chaîne en octets. Les données d'analyse étant reçues sous forme de chaîne hexadécimale, transmettez hex comme encodage des caractères lorsque vous appelez Buffer.from().

local/index.ts

identifyHandler(request: IntentFlow.IdentifyRequest):
    Promise<IntentFlow.IdentifyResponse> {
  console.log("IDENTIFY intent: " + JSON.stringify(request, null, 2));

  const scanData = request.inputs[0].payload.device.udpScanData;
  if (!scanData) {
    const err = new IntentFlow.HandlerError(request.requestId,
        'invalid_request', 'Invalid scan data');
    return Promise.reject(err);
  }

  // In this codelab, the scan data contains only local device id.
  const localDeviceId = Buffer.from(scanData.data, 'hex');
  console.log(`IDENTIFY handler: received local device id
      ${localDeviceId}`);

  if (!localDeviceId.toString().match(/^deviceid[0-9]{3}$/gi)) {
    const err = new IntentFlow.HandlerError(request.requestId,
      'invalid_device', 'Invalid device id from scan data ' +
      localDeviceId);
    return Promise.reject(err);
  }

  const response: IntentFlow.IdentifyResponse = {
    intent: Intents.IDENTIFY,
    requestId: request.requestId,
    payload: {
      device: {
        id: 'washer',
        verificationId: localDeviceId.toString(),
      }
    }
  };
  console.log("IDENTIFY response: " + JSON.stringify(response, null, 2));

  return Promise.resolve(response);
}

Modifiez également la version locale de l'application Home, afin que nous puissions déterminer si nous utilisons la bonne version.

local/index.ts

const localHomeSdk = new App('1.0.2');

Une fois l'erreur corrigée, compilez l'application et redéployez l'application sur Firebase. Dans l'outil app-faulty/local, exécutez :

$ npm run build
$ firebase deploy --only hosting

Tester le correctif

Après le déploiement, redémarrez votre appareil Google Home pour qu'il puisse charger l'application Local Home mise à jour. Assurez-vous que sa version est 1.0.2. Cette fois-ci, aucune erreur ne devrait s'afficher dans la console des outils pour les développeurs Chrome.

Vous pouvez maintenant réessayer d'envoyer des commandes à votre appareil.

"Hey Google, force locale".

"Hey Google, arrête mon lave-linge."

"Hey Google, allume mon lave-linge."

…

"Hey Google, forcer l'utilisation par défaut."

6. Exécuter la suite de tests pour la maison connectée

Après avoir fait valider votre appareil à l'aide des commandes tactiles dans l'application Google Home ou par commande vocale, vous pouvez utiliser la suite de test pour la maison connectée, qui est automatisée pour valider les cas d'utilisation en fonction des types d'appareils et des caractéristiques associés à votre action. La suite de tests exécute une série de tests pour détecter les problèmes dans votre action et affiche des messages d'information pour les scénarios de test ayant échoué afin d'accélérer votre débogage avant de plonger dans les journaux des événements.

Exécuter la suite de tests pour la maison connectée

Suivez les instructions ci-dessous pour tester votre Action Home par Test Suite:

Dans votre navigateur Web, ouvrez la suite de test pour la maison connectée.
Connectez-vous à Google à l'aide du bouton situé dans l'angle supérieur droit. Cela permet à la suite de tests d'envoyer les commandes directement à l'Assistant Google.
Dans le champ ID du projet, saisissez l'ID de projet de votre action pour la maison connectée. Ensuite, cliquez sur SUIVANT pour continuer.
À l'étape Paramètres de test, vous devriez voir votre lave-linge défectueux dans la section Appareils et trains.
Désactivez l'option Tester la synchronisation, car l'exemple d'application de lave-linge ne dispose pas d'une interface utilisateur permettant d'ajouter, de supprimer ou de renommer le lave-linge. Dans un système de production, vous devez déclencher Request Sync chaque fois que l'utilisateur ajoute, supprime ou renomme des appareils.
Laissez l'option Local Home SDK activée, car nous testons les chemins d'accès locaux et cloud.
Cliquez sur SUIVANT pour commencer à exécuter le test.

Une fois les tests terminés, vous remarquerez que les tests de mise en pause et de reprise du chemin d'accès local échouent.

Analyser le message d'erreur

Examinez les messages d'erreur dans les scénarios de test ayant échoué. Ils vous indiquent l'état attendu de ce test et l'état réel. Dans cet exemple, l'état attendu pour "Pause le lave-linge" est isPaused: true, mais l'état réel est isPaused: false. De même, pour l'état "Pause du lave-linge", l'état attendu est isPaused: true, mais l'état réel correspond à isPaused: false.

D'après les messages d'erreur, il semble que le chemin d'accès local soit défini sur l'état isPaused à l'inverse.

Identifier et corriger l'erreur

Recherchons le code source sur lequel l'application Local Home envoie la commande d'exécution à l'appareil. getDataCommand() est la fonction appelée par executeHandler() pour définir payload dans la commande d'exécution envoyée à l'appareil.

local/index.ts

getDataForCommand(command: string, params: IWasherParams): unknown {
    switch (command) {
        case 'action.devices.commands.OnOff':
            return {
                on: params.on ? true : false
            };
        case 'action.devices.commands.StartStop':
            return {
                isRunning: params.start ? true : false
            };
        case 'action.devices.commands.PauseUnpause':
            return {
                // Is there something wrong here?
                isPaused: params.pause ? false : true
            };
        default:
            console.error('Unknown command', command);
            return {};
    }
}

Nous définissons en effet la valeur isPause à l'état inverse. Elle devrait être définie sur true lorsque params.pause est true et false dans le cas contraire. Résolvons à présent ce problème.

local/index.ts

getDataForCommand(command: string, params: IWasherParams): unknown {
    switch (command) {
        case 'action.devices.commands.OnOff':
            return {
                on: params.on ? true : false
            };
        case 'action.devices.commands.StartStop':
            return {
                isRunning: params.start ? true : false
            };
        case 'action.devices.commands.PauseUnpause':
            return {
                isPaused: params.pause ? true : false
            };
        default:
            console.error('Unknown command', command);
            return {};
    }
}

Modifiez la version de l'application Home locale pour que nous puissions déterminer si nous utilisons la bonne version.

local/index.ts

const localHomeSdk = new App('1.0.3');

N'oubliez pas de compiler à nouveau l'application et de la redéployer sur Firebase. Dans l'outil app-faulty/local, exécutez :

$ npm run build
$ firebase deploy --only hosting

Redémarrez maintenant votre appareil Google Home pour qu'il puisse charger l'application Local Home mise à jour. Assurez-vous que vous utilisez la version 1.0.3.

Tester le correctif

Maintenant, réexécutez la suite de tests pour maison connectée avec les mêmes configurations, et vous constaterez que tous les scénarios de test ont réussi.

7. Félicitations !

Félicitations ! Vous avez appris à dépanner une application Local Home via la suite de tests pour la maison connectée et Cloud Logging.

En savoir plus

Voici quelques pistes à explorer :

Ajoutez d'autres caractéristiques compatibles à votre appareil et effectuez des tests avec Test Suite.
Ajoutez des journaux personnalisés dans chacun des gestionnaires d'intents et affichez-les dans Cloud Logging.
Créez des tableaux de bord, configurez des alertes et consultez des données de métriques par programmation pour obtenir des métriques d'utilisation utiles concernant votre action.

Vous pouvez également découvrir comment tester et envoyer une action pour examen, y compris le processus de certification permettant de la publier auprès des utilisateurs.