Como depurar a casa inteligente

1. Antes de começar

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

a4657871181b5ad2.gif

Conhecer as ferramentas de depuração para ações de casa inteligente é uma etapa importante para integrar a qualidade da produção 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 casa inteligente estão disponíveis para ajudar você a identificar e resolver problemas das 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. Depois, vai depurar os defeitos da ação usando o pacote de testes para casa inteligente e métricas e Logging do Google Cloud Platform (GCP).

O que você vai aprender

  • Como usar as métricas e o Logging do GCP para identificar e resolver problemas de produção
  • Como usar o Pacote de testes de casa inteligente 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 sua máquina de desenvolvimento. Acesse 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, ignore e continue. O aviso se deve a algumas dependências mais antigas. Confira mais detalhes neste link.

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 seu projeto, está tudo pronto para implantar o app da lavadora com defeito.

$ firebase deploy

Esta é a resposta do console que você deverá ver:

...

✔ Deploy complete!

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

Atualizar o HomeGraph

Abra o URL de hospedagem no navegador (https://<project-id>.firebaseapp.com) para acessar o app da Web. Na IU da Web, clique no botão Atualizar ae8d3b25777a5e30.png para atualizar o HomeGraph pela sincronização de solicitações com os metadados mais recentes do dispositivo provenientes do app da lavadora com defeito:

6f2b1344179977cf.png

Abra o app Google Home e verifique se você vê o dispositivo de lavadora chamado Lavadora com defeito.

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 do valor ao tentar usar um dos seguintes comandos de voz pelo smartphone:

"Ok Google, ligar minha lavadora."

"Ok Google, iniciar minha lavadora."

"Ok Google, pausar minha lavadora."

"Ok Google, retomar minha lavadora."

"Ok Google, parar minha lavadora."

Quando você pausar / retomar a lavadora, vai perceber que o Google Assistente vai responder 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 do Smarthome Analytics, 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 o total de solicitações até o fulfillment.
  • As métricas de Integridade ajudam a monitorar a ocorrência de anomalias na ação de casa inteligente, abrangendo a latência da solicitação, a porcentagem de sucesso e o detalhamento de erros.

Para restringir 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 seu projeto de casa inteligente.
  3. Escolha a guia Análise e clique em Acessar 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 - Cloud Integration.

5edd3751323176dd.png

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

c468743c20a11c15.png

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

Acessar logs de eventos

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

Abra o menu de navegação no Google Cloud Platform e, em Operações, selecione Geração de registros > Análise de registros para acessar os logs de eventos do projeto. Também é possível buscar Análise de registros na caixa de pesquisa.

Na seção Consulta, digite 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 foi "retomar a lavadora" (actionType: "STARTSTOP_UNPAUSE"), que corresponde ao comando de voz que falhou recentemente.
  • 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 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 lida com a pausa / retomada na lavadora e veja se a string correspondente ao comando pausar / retomar 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 do comando de pausa / retomada:

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 sua correção

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

firebase deploy --only functions

Repita os comandos de voz abaixo. O Google Assistente vai responder corretamente quando você pausar / retomar a lavadora.

"Ok Google, pausar minha lavadora."

=&gt;

"Claro, pausando a lavadora."

"Ok Google, retomar minha lavadora."

=&gt;

"Entendi, retomando a lavadora."

Você também pode fazer perguntas para testar o estado atual da 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 do teste manual, você pode usar o Pacote de testes para casas inteligentes automatizado para validar casos de uso com base nos tipos de dispositivo e características associadas à sua Ação. O pacote de testes executa uma série de testes para detectar problemas na ação e mostra mensagens informativas em casos de teste com falha para acelerar a depuração antes de analisar os 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 Test Suite envie os comandos diretamente ao 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 Test Settings, você vai notar que 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 Test Suite for concluído, veja os resultados dos casos de teste. Você vai notar dois casos de teste com falha, capturados com a respectiva mensagem de erro:

5838d10631c98ed2.png

Para depurar a ação de casa inteligente para a falha, identifique a causa raiz do erro analisando a mensagem.

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.

Para o primeiro caso de teste com falha acima,

99e4e5d06965a8a7.png

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

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

fdb5124102e3a37.png

De acordo com as duas mensagens de erro, verifique se os relatórios de ação mostram o estado 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ê vai encontrar que ele não tem o estado isPaused, que é exatamente o que o Test Suite 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 functions/index.js adicionando o estado isPaused ao payload do estado 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 sua 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 e você verá que todos os casos de teste foram aprovados.

148837f85d377dd6.png

5. Parabéns

17d485868a6771bc.png

Parabéns! Agora você sabe como resolver problemas de ações de casa inteligente com o Pacote de testes para casas inteligentes e Métricas e geração de 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 revisão, incluindo o processo de certificação para publicá-la aos usuários.