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

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 vos actions avec un niveau de qualité de production. Toutefois, sans outils de dépannage et de test informatifs et faciles à utiliser, il s'agit d'un processus difficile et chronophage. Pour faciliter le débogage des actions de maison connectée, les outils Métriques, Journalisation et Suite de tests pour la maison connectée de Google Cloud Platform (GCP) vous aident à identifier et à résoudre les problèmes liés à vos actions.

Prérequis

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

Ce que vous allez faire

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

Points abordés

Utiliser les métriques GCP et Logging pour identifier et résoudre les problèmes de production
Identifier les problèmes fonctionnels et d'API avec la suite de tests
Utiliser les outils pour les développeurs Chrome tout en développant votre application Local Home.

Prérequis

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/google-home/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 ici app-faulty. Commençons par une application d'accueil locale qui fonctionne, mais qui n'est pas très performante.

Se connecter à Firebase

Nous utiliserons le même projet que celui 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 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 l'ignorer et continuer. Cet avertissement est dû à d'anciennes dépendances. 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 Demander la synchronisation avec les dernières métadonnées de l'appareil de l'application de lave-linge défectueuse:

Ouvrez l'application Google Home et vérifiez que votre lave-linge s'affiche sous le nouveau nom "Lave-linge défectueux". N'oubliez pas d'associer l'appareil à une pièce équipée d'un appareil Nest.

3. Démarrer le lave-linge connecté

Si vous avez exécuté l'atelier de programmation Activer le traitement en local pour les actions de maison connectée, vous devez déjà avoir démarré le lave-linge connecté virtuel. Si elle est arrêtée, 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 le biais de commandes vocales, par exemple:

"Hey Google, allume mon lave-linge."

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

"Hey Google, force le chargement local."

"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 n'est pas disponible pour le moment". lorsque vous essayez de contrôler le lave-linge après "forcer local".

Cela signifie que l'appareil n'est pas accessible via un chemin d'accès local. L'opération fonctionnait avant d'émettre le message "Hey Google, force la localisation". car nous reviendrons à utiliser le chemin d’accès cloud lorsque l’appareil n’est pas accessible via un chemin d’accès local. Toutefois, après l'option "Forcer l'accès local", l'option de retour au chemin d'accès au cloud est désactivée.

Pour identifier le problème, nous allons utiliser les outils à notre disposition: les métriques et Logging de Google Cloud Platform (GCP), ainsi que les outils pour les développeurs Chrome.

5. Déboguer l'application Local Home

Dans la section suivante, vous utiliserez les outils fournis par Google pour déterminer 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, afficher 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 vos 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 de votre HomeGraph. Ajoutons des journaux personnalisés pour en découvrir la raison.

Ajouter des journaux personnalisés

Bien qu'une erreur DEVICE_VERIFICATION_FAILED s'affiche par le SDK Local Home, elle ne permet pas vraiment d'en identifier 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 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 la version mise à jour de l'application Home locale. Pour savoir si l'appareil Google Home utilise la version attendue, consultez les journaux de la console dans les outils pour les développeurs Chrome.

Accéder à Cloud Logging

Voyons comment identifier vos 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 Journalisation > 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 n'a pas pu être identifié. Cependant, nous voulons savoir exactement quel est le problème. Commençons donc par filtrer les erreurs qui se produisent dans le gestionnaire IDENTIFY.

Développez la zone Aperçu de la requête. Elle doit se transformer en zone de texte Générateur de requêtes. Saisissez jsonPayload.intent="IDENTIFY" dans la zone de texte Générateur de requêtes, puis cliquez sur le bouton Exécuter la requête.

Vous obtenez alors tous les journaux d'erreurs générés dans le gestionnaire IDENTIFY. Ensuite, développez la dernière erreur. Vous trouverez les errorCode et debugString que vous venez de définir lors du rejet de la promesse dans le gestionnaire IDENTIFY.

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

Corriger l'erreur

Si nous revenons au code source dans lequel nous analysons l'ID de l'appareil local à partir des données d'analyse, nous remarquons 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 devez donc transmettre 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');

Après avoir corrigé l'erreur, 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 votre correction

Après le déploiement, redémarrez votre appareil Google Home pour qu'il puisse charger la nouvelle application d'accueil local. Assurez-vous que la version locale de l'application d'accueil 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 le chargement local."

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

"Hey Google, allume mon lave-linge."

…

"Hey Google, force la valeur par défaut."

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

Après avoir validé votre appareil à l'aide des commandes tactiles de l'application Google Home ou des commandes vocales, vous pouvez utiliser la suite de tests pour la maison connectée automatisée afin de valider des 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 informatifs en cas d'échec des scénarios de test afin d'accélérer le débogage avant de vous plonger dans les journaux d'événements.

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

Suivez ces instructions pour tester la suite Action by Test de votre maison connectée:

Dans votre navigateur Web, ouvrez Test Suite 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 de maison connectée. Cliquez ensuite sur SUIVANT pour continuer.
À l'étape Tester les paramètres, votre lave-linge défectueux devrait apparaître dans la section Appareils et carton.
Désactivez l'option Test Request Sync (Synchronisation des requêtes de test), car l'exemple d'application de lave-linge ne dispose d'aucune UI permettant d'ajouter, de supprimer ou de renommer le lave-linge. Dans un système de production, vous devez déclencher la synchronisation des requêtes chaque fois que l'utilisateur ajoute, supprime ou renomme des appareils.
Laissez l'option SDK Local Home activée, car nous allons tester les chemins d'accès locaux et cloud.
Cliquez sur SUIVANT pour lancer le test.

Une fois les tests terminés, vous remarquerez que les tests Mettre en pause/Reprendre dans le chemin d'accès local échouent alors que les tests de mise en pause/Reprendre dans le chemin d'accès cloud sont en cours de réussite.

Analyser le message d'erreur

Examinez de plus près les messages d'erreur dans les scénarios de test ayant échoué. Ils vous indiquent quel est l'état attendu pour ce test et quel était l'état réel. Dans le cas présent, l'état attendu pour "Mettre en pause le lave-linge" est isPaused: true. À l'état réel, nous obtenons isPaused: false. De même, pour "Mettre en pause le lave-linge", l'état attendu est isPaused: true. À l'état réel, nous obtenons isPaused: false.

À partir des messages d'erreur, il semble que dans le chemin d'accès local, nous définissons l'état isPaused à l'inverse.

Identifier et corriger l'erreur

Recherchons le code source où 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 isPause à l'état inverse : il doit être défini 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 {};
    }
}

Modifier 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.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 la version mise à jour de l'application Home locale. Assurez-vous que la version locale de l'application Home est 1.0.3.

Tester votre correction

À présent, réexécutez la suite Test pour la maison connectée avec les mêmes configurations. Vous constaterez que tous les scénarios de test ont réussi.

7. Félicitations

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 :

Ajoutez d'autres caractéristiques compatibles à votre appareil et testez-la avec Test Suite.
Ajoutez des journaux personnalisés à chacun des gestionnaires d'intent et affichez-les dans Cloud Logging.
Créez des tableaux de bord, configurez des alertes et accédez aux données des métriques de manière programmatique 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.