Bienvenue dans le Centre des développeurs Google Home, la nouvelle destination pour apprendre à développer des actions pour la maison connectée. Remarque : Vous continuerez à créer des actions dans la console Actions.

Déboguer la page d'accueil locale

Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

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.

72ffb320986092c.png

Déboguer les actions de maison connectée est une étape cruciale de la qualité de production, mais elle est difficile et prend du temps sans outils informatifs, faciles à utiliser pour le dépannage et les tests. Pour faciliter le débogage des actions de maison connectée, les métriques et la journalisation Google Cloud Platform (GCP) ainsi que la suite de test pour la maison connectée sont disponibles pour vous aider à identifier et à résoudre les problèmes liés à vos actions.

Conditions préalables

Objectifs de l'atelier

Dans cet atelier de programmation, vous allez créer un traitement en local pour les actions de maison connectée, 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) et Logging.

Points abordés

  • Utiliser les métriques et la journalisation GCP pour identifier et résoudre les problèmes de production
  • Identifier les problèmes fonctionnels et liés à l'API à l'aide de la suite Test
  • Utiliser les outils pour les développeurs Chrome lors du développement de votre application Local Home

Ce dont vous avez besoin

2. Exécuter l'application de 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 semblables à ceux de l'atelier de programmation Activer le traitement en local pour les actions de maison connectée. Mais au lieu de app-start, nous avons app-faulty ici. Nous allons commencer par une application locale qui fonctionne, mais pas bien.

Se connecter à Firebase

Nous utiliserons le projet que vous avez créé dans l'atelier de programmation Activer le fulfillment 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 traitement en 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 ae8d3b25777a5e30.png 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:

fa3c47f293cfe0b7.png

Ouvrez l'application Google Home et vérifiez que votre lave-linge porte un nouveau nom. N'oubliez pas d'associer l'appareil à une pièce contenant un appareil Nest.

2a082ee11d47ad1a.png

3. Démarrer le lave-linge connecté

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

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 Google Home par commande vocale, par exemple:

"Hey Google, allume mon lave-linge."

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

"Hey Google, force locale ;

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

Vous remarquerez que l'Assistant Google répond par "Désolé, il semble que le lave-linge défectueux" n'est pas disponible pour le moment lorsque vous essayez de contrôler le lave-linge après avoir forcé le lave-linge en local.

Cela signifie que l'appareil n'est pas accessible par un chemin d'accès local. Cela fonctionnait avant d'émettre l'instruction "Hey Google, force local", car nous utiliserons l'accès au chemin du cloud lorsque l'appareil n'est pas accessible via un chemin d'accès local. Toutefois, après la "force locale", l'option de retour au cloud est désactivée.

Pour connaître le problème, utilisons les outils à notre disposition: Métriques et journalisation sur Google Cloud Platform (GCP) 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éterminer pourquoi l'appareil n'est pas accessible par 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 pour être informé des principales erreurs détectées dans l'application Local Home.

Connecter les Outils pour les développeurs Chrome

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

  1. Assurez-vous d'avoir associé votre appareil Google Home à un utilisateur autorisé à accéder au projet de la console Actions.
  2. 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.
  3. Lancez Chrome sur votre ordinateur de développement.
  4. 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.

567f97789a7d8846.png

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.

774c460c59f9f84a.png

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

Ajouter des journaux personnalisés

Bien qu'une erreur DEVICE_VERIFICATION_FAILED soit imprimée par le SDK Local Home, celle-ci ne vous aidera pas vraiment à en déterminer la cause. 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 de l'application Home locale, 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 mise à jour. Vous pouvez voir si l'appareil Google Home utilise la version souhaitée en consultant les journaux de la console dans les outils pour les développeurs Chrome.

ecc56508ebcf9ab.png

Accéder à Cloud Logging

Voyons comment utiliser Cloud Logging pour identifier les erreurs. Pour accéder à Cloud Logging pour votre projet:

  1. Dans la console Cloud Platform, accédez à la page Projets.
  2. Sélectionnez votre projet de maison connectée.
  3. Sous Opérations, sélectionnez Journalisation &gt ; 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é. Toutefois, comme nous souhaitons connaître précisément le problème, nous allons d'abord filtrer les erreurs qui se produisent dans le gestionnaire IDENTIFY.

Développez la zone Query preview (Aperçu de la requête), qui devrait devenir un Query builder (Générateur de requêtes). Saisissez jsonPayload.intent="IDENTIFY" dans le champ Query builder (Générateur de requêtes), puis cliquez sur le bouton Run query (Exécuter la requête).

4c0b9d2828ee2447.png

Par conséquent, vous obtenez tous les journaux d'erreurs 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 lorsque vous refusez la promesse dans le gestionnaire IDENTIFY.

71f2f156c6887496.png

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 ici, 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 sont reçues sous forme de chaîne hexadécimale. Vous pouvez donc transmettre hex comme encodage de 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 de l'application Home locale, 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-la 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 locale mise à jour. Assurez-vous que sa version est 1.0.2. Cette fois, aucune erreur ne devrait s'afficher dans la console des outils pour les développeurs Chrome.

C8456f7b5f77f894.png

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 Test pour la maison connectée

Après avoir validé votre appareil à l'aide des commandes tactiles de l'application Google Home ou à l'aide de commandes vocales, vous pouvez utiliser la suite Test pour maison connectée 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 d'événements.

Exécuter la suite Test pour la maison connectée

Suivez ces instructions pour tester votre Action Home par Test Suite:

  1. Dans votre navigateur Web, ouvrez la suite Test pour la maison connectée.
  2. Connectez-vous à Google à l'aide du bouton situé en haut à droite. La suite Test peut ainsi envoyer les commandes directement à l'Assistant Google.
  3. Dans le champ ID du projet, saisissez l'ID de votre action de maison connectée. Ensuite, cliquez sur SUIVANT pour continuer.
  4. À l'étape Paramètres de test, vous devriez voir votre laveuse défectueuse dans la section Appareils et trains.
  5. Désactivez l'option Test Request Sync (Tester la synchronisation des requêtes), car l'exemple d'application de lave-linge ne comporte pas d'interface utilisateur pour ajouter / supprimer / 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.
  6. Laissez l'option SDK Local Home activée, car nous allons tester à la fois les chemins d'accès locaux et cloud.
  7. Cliquez sur SUIVANT pour commencer à exécuter le test.

67433d9190fa770e.png

Une fois les tests terminés, vous constaterez que les tests de mise en veille/de reprise du chemin d'accès local échouent.

d1ebd5cfae2a2a47.png

Analyser le message d'erreur

Examinez les messages d'erreur dans les scénarios de test ayant échoué. Ils indiquent l'état attendu de ce test et son état réel. Dans le cas présent, l'état attendu pour la fonction "Pause the Washer" est la suivante : isPaused: true. En revanche, l'état réel est isPaused: false. De même, pour la fonction "Pause the Washer", l'état attendu est isPaused: true, mais dans l'état réel, nous obtenons isPaused: false.

6bfd3acef9c16b84.png

À partir des messages d'erreur, il semble que le chemin d'accès local soit défini de manière inverse à l'état isPaused.

Identifier et corriger l'erreur

Déterminons le code source via 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 bien isPause à l'état inverse. Il devrait être défini sur true lorsque params.pause est défini sur true et false dans le cas contraire. Nous allons donc résoudre 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 locale de l'application Home pour nous permettre de 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, exécutez à nouveau la suite Test pour la maison connectée avec les mêmes configurations. Vous constaterez que tous les scénarios de test sont concluants.

b7fc8c5d3c727d8d.png

7. Félicitations

764dbc83b95782a.png

Félicitations ! Vous avez appris à résoudre les problèmes liés à une application Local Home via la suite de tests pour la maison connectée et Cloud Logging.

En savoir plus

Voici quelques pistes à explorer :

Vous pouvez également en apprendre davantage sur le test et l'envoi d'une Action pour examen, y compris le processus de certification permettant de publier votre Action auprès des utilisateurs.