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épendancesindex.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.