Traitement en local

Le SDK Local Home améliore l'intégration de votre maison connectée à l'Assistant Google en ajoutant un chemin d'accès local pour router les intents de maison connectée.

Le SDK Local Home offre deux fonctionnalités : l'exécution en local et la requête en local.

  • L'exécution locale permet d'exécuter des commandes en envoyant des intents EXEC via le chemin de traitement local, au lieu d'effectuer un appel d'API Cloud. Par exemple, la requête "Allume la lumière" peut être traitée par l'exécution locale.
  • Local Query permet de gérer les requêtes concernant l'état des appareils en envoyant des intents QUERY via le chemin de traitement local. Par exemple, Local Query répondrait à la requête "Ma lumière est-elle allumée ?" sans effectuer d'appel d'API cloud.

Le SDK vous permet d'écrire une application de traitement en local, en TypeScript ou JavaScript, qui contient votre logique métier pour la maison connectée. Les appareils Google Home ou Google Nest peuvent charger et exécuter votre application sur l'appareil. Votre application communique directement avec vos appareils connectés existants via le Wi-Fi sur un réseau local (LAN) pour traiter les commandes des utilisateurs, à l'aide des protocoles existants.

L'intégration du SDK permet d'améliorer les performances de votre intégration Cloud-to-cloud, y compris en réduisant la latence et en augmentant la fiabilité. Le traitement local est compatible avec tous les types et traits d'appareils, à l'exception de ceux qui utilisent la validation secondaire de l'utilisateur.

Commencer à créer Essayer l'exemple

Comprendre le fonctionnement

Après avoir reçu une réponse SYNC de votre traitement cloud, la plate-forme Local Home analyse le réseau local de l'utilisateur à l'aide de mDNS, de la diffusion UDP ou d'UPnP pour détecter les appareils connectés à l'Assistant.

La plate-forme envoie un intent IDENTIFY pour déterminer si l'appareil est contrôlable localement, en comparant l'ID de l'appareil dans la réponse IDENTIFY à ceux renvoyés par la réponse SYNC précédente. Si l'appareil détecté est un hub ou un pont, la plate-forme envoie une intention REACHABLE_DEVICES et traite le hub comme appareil proxy pour la communication locale.

Lorsqu'elle reçoit une réponse confirmant un appareil local, la plate-forme établit un chemin de traitement en local vers l'appareil Google Home ou Google Nest de l'utilisateur, puis achemine les commandes de l'utilisateur pour le traitement en local.

Lorsqu'un utilisateur déclenche une intégration Cloud-to-cloud qui comporte un chemin d'exécution local, l'Assistant envoie l'intent EXECUTE ou l'intent QUERY à l'appareil Google Home ou Google Nest plutôt qu'à l'exécution cloud. L'appareil exécute ensuite l'application de traitement en local pour traiter l'intention.

Cette figure illustre le flux d'exécution du fulfillment local. Le chemin d'exécution capture l'intention d'un utilisateur à partir d'un téléphone avec l'Assistant Google. L'intention de l'utilisateur est ensuite traitée par Google Cloud, puis exécutée localement sur l'appareil Google Home. La commande est émise directement au hub de l'appareil ou directement à l'appareil. Le cloud pour les développeurs est disponible en tant que solution de repli cloud.
Figure 1 : Ajout d'un chemin d'accès local pour votre action de maison connectée.

La plate-forme Local Home n'est pas déterministe dans le choix de l'appareil Google Home ou Google Nest sur lequel déclencher la commande. Les intents EXECUTE et QUERY peuvent provenir de n'importe quel appareil Google Home ou Google Nest défini dans la même structure Home Graph que l'appareil cible.

Application de traitement en local

L'application de traitement en local contient la logique métier permettant de traiter les intents envoyés par la plate-forme Local Home et d'accéder à votre appareil connecté via le réseau local. Aucune modification de votre matériel n'est nécessaire pour intégrer l'exécution locale. L'application répond aux requêtes d'intégration Cloud-to-cloud en envoyant des commandes de contrôle à l'appareil connecté via des protocoles de couche application, y compris HTTP, TCP ou UDP. Si le chemin de traitement local échoue, votre traitement cloud est utilisé comme chemin d'exécution de secours.

Pour vous aider à créer l'application, le SDK Local Home fournit les deux classes principales suivantes :

  • DeviceManager : Fournit des méthodes pour communiquer avec les appareils connectés à l'aide de sockets TCP, UDP ou de requêtes HTTP.
  • App : Fournit des méthodes pour associer des gestionnaires aux intents que Google envoie après avoir détecté des appareils contrôlables localement (IDENTIFY, REACHABLE_DEVICES). Cette classe exécute également les commandes utilisateur (EXECUTE) et répond aux requêtes utilisateur sur l'état actuel de l'appareil (QUERY).

Pendant le développement, vous pouvez créer et tester l'application en la chargeant sur votre propre serveur d'hébergement ou sur votre machine de développement locale. En production, Google héberge votre application dans un environnement de bac à sable JavaScript sécurisé sur l'appareil Google Home ou Google Nest de l'utilisateur.

L'API Report State n'est actuellement pas compatible avec l'exécution locale. Google s'appuie sur votre traitement cloud pour traiter ces demandes.

Cycle de vie de l'application

Votre application de traitement en local est chargée à la demande lorsque la plate-forme Local Home détecte de nouveaux appareils locaux correspondant à la configuration de recherche du projet ou lorsqu'elle a des intents en attente à traiter concernant un appareil précédemment identifié.

Les appareils Google Home ou Google Nest ont une mémoire limitée. Votre application de traitement local peut être arrêtée à tout moment en raison d'une pression sur la mémoire du système. Cela peut se produire si votre application commence à consommer trop de mémoire ou si le système doit faire de la place pour une autre application. La plate-forme Local Home redémarre votre application uniquement lorsqu'il y a de nouvelles intentions à transmettre et suffisamment de ressources mémoire pour que l'application s'exécute.

La plate-forme Local Home décharge votre application après un délai d'inactivité lorsque l'utilisateur dissocie son compte ou qu'il n'y a plus d'appareils compatibles avec l'exécution locale associés à son agentUserId.

Appareils compatibles

La plate-forme Local Home exécute votre application de traitement en local sur les appareils Google Home ou Google Nest compatibles. Le tableau suivant décrit les appareils compatibles et le temps d'exécution utilisé sur chacun d'eux. Pour en savoir plus sur les exigences d'exécution, consultez Environnement d'exécution.

Appareil Type Environnement
Google Home Haut-parleur Chrome
Google Home Mini Haut-parleur Chrome
Google Home Max Haut-parleur Chrome
Nest Mini Haut-parleur Chrome
Nest Hub Écran Chrome
Nest Hub Max Écran Chrome
Nest Wifi Routeur Node.js
Point Chrome

Environnement d'exécution

L'environnement d'exécution de votre application de traitement en local dépend de votre appareil. La plate-forme Local Home est compatible avec les environnements d'exécution suivants :

  • Chrome : votre application d'exécution locale est exécutée dans le contexte d'un navigateur Chrome window exécutant Chrome M80 ou version ultérieure avec prise en charge d'ECMAScript version ES2018.
  • Node.js : votre application de traitement locale est exécutée en tant que script dans un processus Node.js exécutant Node v10.x LTS ou version ultérieure avec compatibilité pour ECMAScript version ES2018.

Structure du code source

Nous vous recommandons de regrouper vos dépendances dans un seul fichier JavaScript à l'aide des configurations de regroupement fournies par le SDK Local Home et d'empaqueter votre code source en tant qu'expression de fonction immédiatement invoquée (IIFE).

Chemin d'accès de l'exécution

Pour utiliser le SDK Local Home pour votre intégration de maison connectée, vous devez effectuer les tâches suivantes :

1 Configurer la configuration de l'analyse Configurez Google Home Developer Console avec les paramètres nécessaires pour que l'Assistant puisse détecter les appareils contrôlables en local.
2 Mettez à jour la réponse SYNC dans votre traitement cloud. Dans votre plate-forme d'exécution cloud, modifiez le gestionnaire de requêtes SYNC pour qu'il prenne en charge le champ otherDeviceIds que la plate-forme utilise pour établir un chemin d'exécution local. Dans ce champ, spécifiez les ID des appareils qui peuvent être contrôlés localement.
3 Implémenter l'application de traitement en local Utilisez le SDK Local Home pour créer une application JavaScript permettant de gérer les intents IDENTIFY, EXECUTE et QUERY. Pour les appareils proxy de hub ou de pont, vous devez également gérer l'intention REACHABLE_DEVICES.
4 Tester et déboguer votre application Testez votre intégration (ou autocertifiez-la) à l'aide de la suite de tests Google Home.

Avant de commencer