Como depurar a casa inteligente

1. Antes de começar

Como desenvolvedor de Internet das Coisas (IoT, na sigla em inglês), você pode criar ações de casa inteligente que oferecem aos usuários a capacidade de controlar os dispositivos com controles por toque no app Google Home e comandos de voz com o Google Assistente.

a4657871181b5ad2.gif

Aprender a usar as ferramentas de depuração das ações de casa inteligente é uma etapa importante para criar uma integração de qualidade com o Google Assistente. Para facilitar o monitoramento e a depuração, as métricas do Google Cloud Platform (GCP), o Logging e o Pacote de testes para casas inteligentes estão disponíveis para ajudar você a identificar e resolver problemas nas suas ações.

Pré-requisitos

O que você vai criar

Neste codelab, você vai implantar uma ação de casa inteligente com dois defeitos e conectá-la ao Google Assistente. Em seguida, você vai depurar os defeitos da ação usando o pacote de testes para casas inteligentes e métricas e registros do Google Cloud Platform (GCP).

O que você vai aprender

  • Como usar as métricas do GCP e o Logging para identificar e resolver problemas de produção
  • Como usar o Test Suite para casas inteligentes para identificar problemas funcionais e de API

O que é necessário

2. Executar o app com defeito

Faça o download do código-fonte

Clique neste link para fazer o download do exemplo deste codelab na máquina de desenvolvimento:

…ou clone o repositório do GitHub da linha de comando:

$ git clone https://github.com/google-home/smarthome-debug.git

Sobre o projeto

O app da lavadora contém os seguintes subdiretórios:

Conectar-se ao Firebase

Abra o terminal na máquina de desenvolvimento. Navegue até o diretório washer-faulty e configure a CLI do Firebase com seu projeto do Actions criado no codelab Conectar dispositivos de casa inteligente ao Google Assistente:

$ cd washer-faulty
$ firebase use <project-id>

Implantar no Firebase

Navegue até a pasta functions e instale todas as dependências necessárias usando npm..

$ cd functions
$ npm install

Observação: se a mensagem abaixo aparecer, você pode ignorar e continuar. O aviso se deve a algumas dependências mais antigas. Confira mais detalhes.

found 5 high severity vulnerabilities
  run `npm audit fix` to fix them, or `npm audit` for details

Agora que você instalou as dependências e configurou o projeto, está tudo pronto para implantar o app com falha.

$ firebase deploy

Esta é a resposta do console que deverá aparecer:

...

✔ Deploy complete!

Project Console: https://console.firebase.google.com/project/<project-id>/overview
Hosting URL: https://<project-id>.firebaseapp.com

Atualizar HomeGraph

Abra o URL de hospedagem no navegador (https://<project-id>.firebaseapp.com) para abrir o app da Web. Na interface da Web, clique no botão Atualizar ae8d3b25777a5e30.png para atualizar o HomeGraph via Request Sync com os metadados mais recentes do dispositivo referentes ao app com falha da lavadora:

6f2b1344179977cf.png

Abra o app Google Home e confira se o dispositivo de lavagem Com falha é exibido.

e357de6a7faff925.png

3. Testar sua ação

Depois de implantar o projeto, teste se a ação controla a lavadora.

Testar a lavadora

Verifique a mudança no valor ao tentar qualquer um dos seguintes comandos de voz no smartphone:

"Ok Google, ligar minha lavadora."

"Ok Google, iniciar minha lavadora."

"Ok Google, pause minha lavadora."

"Ok Google, retome minha lavadora."

"Ok Google, parar minha lavadora."

Quando você pausar / retomar a lavadora, vai notar que o Google Assistente responde por voz:

"Não foi possível acessar <nome de exibição do projeto>"

Para depurar esse problema, primeiro você precisa de mais informações sobre o erro para restringir e identificar a causa raiz.

Painel de análise do Smarthome

Um bom lugar para inspecionar erros é o painel de análise do Smarthome, que agrega gráficos de métricas de uso e integridade para o fulfillment da nuvem:

  • As métricas de Uso refletem a tendência de uso da ação de casa inteligente, incluindo o número de usuários ativos por dia e a contagem total de solicitações para o fulfillment.
  • As métricas de Integridade ajudam a monitorar a ocorrência de anomalias na Ação de casa inteligente, incluindo a latência da solicitação, a porcentagem de sucesso e o detalhamento dos erros.

Para determinar a causa do erro, siga as etapas abaixo para acessar o painel do projeto.

  1. No Console do Actions, acesse a página "Projetos".
  2. Selecione o projeto de casa inteligente.
  3. Escolha a guia Análise e clique em Ir para o Google Cloud Platform.

b1735bbe11a7aff8.png

  1. Isso vai levar você a uma lista de painéis para seu projeto no Google Cloud. Selecione o painel Google Home Analytics: integração na nuvem.

5edd3751323176dd.png

  1. Role para baixo até o gráfico Cloud Fulfillment Errors: detalhamento de status para ver os códigos de erro do período destacado.

c468743c20a11c15.png

O código do erro PARTNER_RESPONSE_MISSING_DEVICE fornece uma dica para a causa raiz. Em seguida, recupere os logs de eventos com base no código de erro para saber mais detalhes.

Acessar logs de eventos

Para saber mais detalhes sobre o erro, acesse os registros de eventos das ações de casa inteligente pelo Cloud Logging.

Abra o Menu de navegação no Google Cloud Platform e, em Operações, selecione Logging > Análise de registros para acessar os logs de eventos do projeto. Outra opção é buscar a Análise de registros na caixa de pesquisa.

Na seção Consulta, insira a consulta PARTNER_RESPONSE_MISSING_DEVICE e clique em Executar consulta. Os registros correspondentes à consulta são exibidos na seção Resultados da consulta.

747cca0f1249a5a.png

O registro de erros mostra um evento de casa inteligente com detalhes do erro indicando:

  • A ação do usuário é "retomar lavadora" (actionType: "STARTSTOP_UNPAUSE"), correspondente ao comando de voz recente com falha.
  • A mensagem de depuração associada é "JSON response does not include device."

Com base na mensagem de depuração, verifique por que o app da lavadora não inclui o dispositivo correto na resposta de EXECUTE.

Identificar a causa raiz do erro

Em functions/index.js, encontre o gerenciador EXECUTE (na matriz onExecute) que retorna o status de cada comando e o novo estado do dispositivo. A inserção de IDs de dispositivos em uma resposta EXECUTE depende da resolução da função updateDevice:

index.js

app.onExecute(async (body) => {
 ...

 for (const command of intent.payload.commands) {
   for (const device of command.devices) {
     for (const execution of command.execution) {
       executePromises.push(
           updateDevice(execution, device.id)
               .then((data) => {
                 result.ids.push(device.id);
                 Object.assign(result.states, data);
               })
               .catch((e) =>
                 functions.logger.error('EXECUTE',
                     device.id, e.message)));
     }
   }
 }

Confira como a função updateDevice processa a pausa / retomada na lavadora. Você vai perceber que a string correspondente ao comando de pausa / retomada está incorreta:

index.js

const updateDevice = async (execution, deviceId) => {
 const {params, command} = execution;
 let state; let ref;
 switch (command) {
   ...
   case 'action.devices.commands.PauseUnpausePause':
     state = {isPaused: params.pause};
     if (params.pause) state.isRunning = false;
     ref = firebaseRef.child(deviceId).child('StartStop');
     break;
 }

 return ref.update(state)
     .then(() => state);
};

Corrigir o erro

Agora que você identificou a causa raiz do erro, corrija a string para o comando pausar / retomar:

index.js

const updateDevice = async (execution, deviceId) => {
 const {params, command} = execution;
 let state; let ref;
 switch (command) {
   ...
   case 'action.devices.commands.PauseUnpause':
     state = {isPaused: params.pause};
     if (params.pause) state.isRunning = false;
     ref = firebaseRef.child(deviceId).child('StartStop');
     break;
 }

 return ref.update(state)
     .then(() => state);
};

Testar a correção

Implante o código atualizado usando a CLI do Firebase:

firebase deploy --only functions

Quando você pausar / retomar a lavadora, repita os comandos de voz a seguir para conferir a resposta do Google Assistente.

"Ok Google, pausar minha lavadora."

=>

"Claro, pausando a lavadora."

"Ok Google, retome minha lavadora."

=>

"Entendi, retomando a lavadora."

Você também pode fazer perguntas para testar o estado atual da sua lavadora.

"Ok Google, minha lavadora está ligada?"

"Ok Google, minha lavadora está funcionando?"

"Ok Google, em que ciclo está a lavadora?"

4. Teste sua ação com o pacote de testes

Além de testar manualmente, você pode usar o Pacote de testes para casa inteligente automatizado para validar casos de uso com base nas características e tipos de dispositivo associados à sua Ação. O Test Suite executa uma série de testes para detectar problemas na sua Ação e mostra mensagens informativas sobre casos de teste com falha para acelerar a depuração antes de se aprofundar nos logs de eventos.

Executar o pacote de testes para casa inteligente

Siga estas instruções para testar a ação de casa inteligente do pacote de testes:

  1. No navegador da Web, abra o Pacote de testes para casa inteligente.
  2. Faça login no Google usando o botão no canto superior direito. Isso permite que o pacote de testes envie os comandos diretamente para o Google Assistente.
  3. No campo ID do projeto, insira o ID do projeto da ação de casa inteligente. Clique em PRÓXIMA para continuar.
  4. Na etapa Configurações de teste, o Test Suite lista o tipo de dispositivo e as características da lavadora.

78ed6a1ebdb581bf.png

  1. Desative a opção Test Request Sync, já que o app de exemplo da lavadora não tem interface para adicionar, remover ou renomear a lavadora. Em um sistema de produção, é preciso acionar a sincronização de solicitações sempre que o usuário adicionar / remover / renomear dispositivos.
  2. Clique em PRÓXIMA para começar a executar o teste.

Depois que o pacote de testes terminar a execução, confira os resultados dos casos de teste. Dois casos de teste com falha serão detectados com a respectiva mensagem de erro:

5838d10631c98ed2.png

Para depurar a ação de casa inteligente para a falha, analise a mensagem de erro para identificar a causa raiz.

Analisar mensagem de erro

Para ajudar os desenvolvedores a identificar a causa raiz, o Test Suite mostra mensagens de erro para cada caso de teste com falha indicando o motivo.

No primeiro caso de teste com falha acima,

99e4e5d06965a8a7.png

a mensagem de erro indica que o Pacote de testes espera "isPause": true nos estados informados da ação de casa inteligente, mas os estados reais incluem apenas "isPause": false.

Além disso, a mensagem de erro do segundo caso de teste com falha indica que os estados na resposta de QUERY da ação de casa inteligente incluem "isPause": true, que é diferente de "isPause": false nos estados informados da ação de casa inteligente:

fdb5124102e3a37.png

De acordo com as duas mensagens de erro, verifique se os relatórios de ação indicam isPaused com o valor correto.

Identificar a causa raiz do erro

Abra functions/index.js, que contém a função reportstate que publica mudanças de estado no Home Graph pelo estado do relatório. Inspecione o payload do estado do relatório. Você verá que ele não tem o estado isPaused, que é exatamente o que o pacote de testes verificou nos casos de teste com falha.

index.js

exports.reportstate = functions.database.ref('{deviceId}').onWrite(
    async (change, context) => {
      ...

      const requestBody = {
        requestId: 'ff36a3cc', /* Any unique ID */
        agentUserId: USER_ID,
        payload: {
          devices: {
            states: {
              /* Report the current state of our washer */
             [context.params.deviceId]: {
                online: true,
                on: snapshot.OnOff.on,
                isRunning: snapshot.StartStop.isRunning,
                currentRunCycle: [{
                  currentCycle: 'rinse',
                  nextCycle: 'spin',
                  lang: 'en',
                }],
                currentTotalRemainingTime: 1212,
                currentCycleRemainingTime: 301,
              },
            },
          },
        },
      };

      const res = await homegraph.devices.reportStateAndNotification({
        requestBody,
      });
      ...
    });

Corrigir o erro

Agora que você identificou a causa raiz do erro, revise o functions/index.js adicionando o estado isPaused ao payload do relatório:

index.js

exports.reportstate = functions.database.ref('{deviceId}').onWrite(
    async (change, context) => {
      ...

      const requestBody = {
        requestId: 'ff36a3cc', /* Any unique ID */
        agentUserId: USER_ID,
        payload: {
          devices: {
            states: {
              /* Report the current state of our washer */
             [context.params.deviceId]: {
                online: true,
                on: snapshot.OnOff.on,
                isPaused: snapshot.StartStop.isPaused,
                isRunning: snapshot.StartStop.isRunning,
                currentRunCycle: [{
                  currentCycle: 'rinse',
                  nextCycle: 'spin',
                  lang: 'en',
                }],
                currentTotalRemainingTime: 1212,
                currentCycleRemainingTime: 301,
              },
            },
          },
        },
      };
      ...
    });

Testar a correção

Implante o código atualizado usando a CLI do Firebase:

$ firebase deploy --only functions

Execute novamente o pacote de testes para casas inteligentes. Você verá que todos os casos de teste foram aprovados.

148837f85d377dd6.png

5. Parabéns

17d485868a6771bc.png

Parabéns! Você aprendeu a resolver problemas de ação de casa inteligente com o Test Suite para casas inteligentes e métricas e registros do GCP.

Saiba mais

Com base neste codelab, faça os exercícios a seguir e explore outros recursos:

Saiba mais sobre como testar e enviar uma ação para análise, incluindo o processo de certificação para publicar a ação aos usuários.