Fulfillment local

O SDK do Local Home melhora a integração da sua casa inteligente com o Google Assistente ao adicionar um caminho de fulfillment local para rotear intents de casa inteligente.

O SDK do Google Home local oferece dois recursos: execução local e consulta local.

  • A execução local permite atender a comandos enviando intents EXEC pelo caminho de fulfillment local, em vez de fazer uma chamada de API do Cloud. Por exemplo, o pedido "Acender a luz" pode ser processado pela execução local.
  • A Consulta local permite processar consultas sobre o estado do dispositivo enviando intents QUERY pelo caminho de fulfillment local. Por exemplo, a consulta local atenderia à consulta "Minha luz está acesa?" sem fazer uma chamada de API do Cloud.

O SDK permite que você escreva um app de fulfillment local, usando TypeScript ou JavaScript, que contém sua lógica de negócios de casa inteligente. Os dispositivos Google Home ou Google Nest podem carregar e executar o app no dispositivo. O app se comunica diretamente com os dispositivos inteligentes por Wi-Fi em uma rede local (LAN) para atender aos comandos do usuário, usando protocolos atuais.

A integração do SDK oferece melhorias de desempenho para sua integração do Cloud-to-cloud, incluindo menor latência e maior confiabilidade. O fulfillment local é compatível com todos os tipos e traços de dispositivo, exceto aqueles que usam a verificação secundária do usuário.

Comece a criar Teste o exemplo

Entenda como funciona

Depois de receber uma resposta SYNC do fulfillment na nuvem, a plataforma do Google Home local verifica a rede de área local do usuário usando mDNS, transmissão UDP ou UPnP para descobrir dispositivos inteligentes conectados ao Google Assistente.

A plataforma envia uma intent IDENTIFY para determinar se o dispositivo é controlável localmente, comparando o ID do dispositivo na resposta IDENTIFY com os retornados pela resposta SYNC anterior. Se o dispositivo detectado for um hub ou uma ponte, a plataforma vai enviar uma intent REACHABLE_DEVICES e tratar o hub como o dispositivo proxy para comunicação local.

Quando recebe uma resposta confirmando um dispositivo local, a plataforma estabelece um caminho de fulfillment local para o dispositivo Google Home ou Google Nest do usuário e, em seguida, encaminha os comandos do usuário para o fulfillment local.

Quando um usuário aciona uma integração do Cloud-to-cloud que tem um caminho de fulfillment local, o Assistente envia a intent EXECUTE ou QUERY para o dispositivo Google Home ou Google Nest, em vez do fulfillment na nuvem. Em seguida, o dispositivo executa o app de fulfillment local para processar a intent.

Esta figura mostra o fluxo de execução do fulfillment local. O caminho de execução captura a intenção do usuário de um smartphone com o Google Assistente, que é processada pelo Google Cloud e executada localmente no dispositivo Google Home. O comando é emitido diretamente para o hub do dispositivo ou para o dispositivo. A nuvem de desenvolvedor está disponível como um substituto de nuvem.
Figura 1: como adicionar um caminho de fulfillment local para sua ação de casa inteligente.

A plataforma Local Home não é determinística ao escolher qual dispositivo Google Home ou dispositivo Google Nest vai acionar o comando. As intents EXECUTE e QUERY podem vir de qualquer dispositivo Google Home ou Google Nest definido na mesma estrutura do Home Graph que o dispositivo de destino.

App de fulfillment local

O app de fulfillment local contém a lógica de negócios para processar as intents enviadas pela plataforma de casa local e acessar seu dispositivo inteligente pela rede local. Não é necessário modificar o hardware para integrar o fulfillment local. O app atende às solicitações de integração de Cloud-to-cloud enviando comandos de controle para o dispositivo inteligente por protocolos da camada do aplicativo, incluindo HTTP, TCP ou UDP. Se o caminho de fulfillment local falhar, o fulfillment em nuvem será usado como um caminho de execução substituto.

Para ajudar na criação do app, o SDK do Local Home oferece estas duas classes principais:

  • DeviceManager: oferece métodos para se comunicar com dispositivos inteligentes usando soquetes TCP, UDP ou solicitações HTTP.
  • App: fornece métodos para anexar gerenciadores para intents que o Google envia depois de descobrir dispositivos controláveis localmente (IDENTIFY, REACHABLE_DEVICES). Essa classe também atende aos comandos do usuário (EXECUTE) e responde às consultas do usuário sobre o estado atual do dispositivo (QUERY).

Durante o desenvolvimento, é possível criar e testar o app carregando-o no seu próprio servidor de hospedagem ou na máquina de desenvolvimento local. Na produção, o Google hospeda seu app em um ambiente de sandbox seguro do JavaScript no dispositivo Google Home ou dispositivo Google Nest do usuário.

No momento, a API Report State não é compatível com o fulfillment local. O Google depende do seu fulfillment na nuvem para processar essas solicitações.

Ciclo de vida do aplicativo

O app de fulfillment local é carregado sob demanda quando a plataforma Local Home descobre novos dispositivos locais que correspondem à configuração de verificação do projeto ou tem intents pendentes para entregar relacionados a um dispositivo identificado anteriormente.

Os dispositivos Google Home ou Google Nest têm restrição de memória, e o app de fulfillment local pode ser encerrado a qualquer momento devido à pressão de memória no sistema. Isso pode acontecer se o app começar a consumir muita memória ou se o sistema precisar liberar espaço para outro app. A plataforma de casa local só reinicia o app quando há novas intents a serem entregues e recursos de memória suficientes para que o app seja executado.

A plataforma Local Home descarrega o app após um tempo limite de inatividade quando o usuário desvincula a conta ou não há mais dispositivos compatíveis com o fulfillment local associados ao agentUserId do usuário.

Dispositivos compatíveis

A plataforma de casa local executa o app de fulfillment local em dispositivos Google Home ou Google Nest compatíveis. A tabela a seguir descreve os dispositivos compatíveis e o ambiente de execução usado em cada um deles. Para saber mais sobre os requisitos de ambiente de execução, consulte Ambiente de execução.

Dispositivo Tipo Ambiente
Google Home Alto-falante Chrome
Google Home Mini Alto-falante Chrome
Google Home Max Alto-falante Chrome
Nest Mini Alto-falante Chrome
Nest Hub Display Chrome
Nest Hub Max Display Chrome
Nest Wifi Roteador Node.js
Ponto Chrome

Ambiente de execução

O ambiente de execução do app de fulfillment local depende do seu dispositivo. A plataforma de casa local é compatível com os seguintes ambientes de execução:

Estrutura do código-fonte

Recomendamos agrupar as dependências em um único arquivo JavaScript usando as configurações do bundler fornecidas pelo SDK do Local Home e empacotar o código-fonte como uma expressão de função imediatamente invocada (IIFE, na sigla em inglês).

Caminho de implementação

Para usar o SDK local do Google Home na sua integração de casa inteligente, é necessário realizar estas tarefas:

1 Configurar a verificação config Configure o Google Home Developer Console com os parâmetros necessários para que o Google Assistente descubra dispositivos controláveis localmente.
2 Atualizar a resposta de SYNC no fulfillment na nuvem No fulfillment na nuvem, modifique o gerenciador de solicitações SYNC para oferecer suporte ao campo otherDeviceIds que a plataforma usa para estabelecer um caminho de fulfillment local. Nesse campo, especifique os IDs dos dispositivos que podem ser controlados localmente.
3 Implementar o app de fulfillment local Use o SDK do Local Home para criar um app JavaScript que processe as intents IDENTIFY, EXECUTE e QUERY. Para dispositivos de proxy de hub ou ponte, você também precisa processar a intent REACHABLE_DEVICES.
4 Testar e depurar o app Teste sua integração (ou faça a autocertificação) usando o pacote de testes do Google Home.

Antes de começar

Avançar
Compatibilidade com descoberta de dispositivos