1. Antes de começar
Como desenvolvedor da Internet das Coisas (IoT), é possível criar integrações entre nuvens que permitem aos usuários controlar os dispositivos por meio dos controles por toque no app Google Home e nos comandos de voz com o Google Assistente.
Aprender as ferramentas de depuração para integrações entre nuvens é uma etapa importante para criar integrações de qualidade de produção com o Google Assistente. Para facilitar o monitoramento e a depuração, as Métricas do Google Cloud Platform (GCP), o Registro e o Test Suite para casa inteligente estão disponíveis para ajudar você a identificar e resolver problemas nas integrações.
Pré-requisitos
- Leia o guia para desenvolvedores Criar uma integração entre nuvens.
- Execute o codelab Conectar dispositivos de casa inteligente ao Google Assistente.
O que você vai criar
Neste codelab, você vai implantar uma integração entre nuvens com dois defeitos e conectá-la ao Google Assistente. Em seguida, vai depurar os defeitos da integração usando o Test Suite para métricas e geração de registros de casa inteligente e do Google Cloud Platform (GCP).
O que você vai aprender
- Como usar as métricas e o registro do GCP para identificar e resolver problemas de produção
- Como usar o Test Suite para casa inteligente para identificar problemas funcionais e de API
O que é necessário
- Um navegador da Web, como o Google Chrome
- Um dispositivo iOS ou Android com o app Google Home instalado
- Node.js versão 10.16 ou mais recente
- Uma conta de faturamento do Google Cloud
2. Executar o app com falha
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:
public: uma interface de front-end para controlar e monitorar o estado da lavadora inteligente.functions: um serviço de nuvem totalmente implementado que gerencia a lavadora inteligente com o Cloud Functions para Firebase e o Firebase Realtime Database.
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 de integração criado no codelab Conectar dispositivos de casa inteligente ao Google Assistente:
$ cd washer-faulty $ firebase use <firebase-project-id>
Implantar no Firebase
Acesse 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 é devido a algumas dependências mais antigas. Saiba mais 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 o projeto, está tudo pronto para implantar o app de lavagem com defeito.
$ firebase deploy
Esta é a resposta do console que você deverá ver:
... ✔ Deploy complete! Project Console: https://console.firebase.google.com/project/<Firebase-project-id>/overview Hosting URL: https://<Firebase-project-id>.firebaseapp.com
Atualizar o HomeGraph
Abra o URL de hospedagem no navegador (https://<firebase-project-id>.firebaseapp.com) para acessar o app da Web. Na IU da Web, clique no botão Atualizar 
para atualizar o HomeGraph usando a solicitação de sincronização com os metadados mais recentes do dispositivo do app de lavagem com defeito:
Abra o app Google Home e verifique se o dispositivo da lavadora chamado Faulty Washer aparece.
3. Testar a integração
Depois de implantar o projeto, teste se a integração controla a lavadora.
Testar a lavadora
Confira a mudança no valor ao tentar usar um dos seguintes comandos de voz no seu smartphone:
"Ok Google, ligar minha lavadora."
"Ok Google, iniciar minha lavadora."
"Ok Google, pausar minha lavadora."
"Ok Google, retomar a lavagem."
"Ok Google, parar minha lavadora."
O Google Assistente vai responder que algo está errado por voz quando você pausar / retomar a lavadora:
"Desculpe, não consegui 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álises do Smarthome
Um bom lugar para inspecionar erros é o painel de Análises da casa inteligente, que agrega gráficos de métricas de uso e integridade para a execução na nuvem:
- As métricas de uso refletem a tendência de uso da integração entre nuvens, 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 integração entre nuvens, cobrindo a latência da solicitação, a porcentagem de sucesso e a divisão de erros.
Para determinar a causa do erro, siga as etapas abaixo para acessar o painel do projeto.
- No console do desenvolvedor, acesse a página "Projetos".
- Selecione o projeto da casa inteligente.
- Clique na guia Analytics no menu à esquerda.
- Isso vai levar você a uma lista de painéis para seu projeto no Google Cloud. Selecione o painel Google Home Analytics – Integração com a nuvem.
- Role para baixo até o gráfico Erros de fulfillment da nuvem: detalhamento do status para conferir os códigos de erro do intervalo de tempo destacado.
O código de erro PARTNER_RESPONSE_MISSING_DEVICE fornece uma dica sobre a causa raiz. Em seguida, extraia os registros de eventos com base no código de erro para conferir mais detalhes.
Acessar registros de eventos
Para saber mais detalhes sobre o erro, acesse os registros de eventos da integração entre nuvens 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 registros de eventos do projeto. Você também pode pesquisar Logs Explorer na caixa de pesquisa.
No campo de entrada Pesquisar todos os campos, digite a consulta PARTNER_RESPONSE_MISSING_DEVICE e clique em Executar consulta. Os registros que correspondem à consulta são exibidos na seção Resultados.
O registro de erros mostra um evento da casa inteligente com detalhes do erro indicando:
- A ação do usuário é "retornar à 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 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)));
}
}
}
Verifique como a função updateDevice lida com a pausa / retomada na lavadora e encontre a string correspondente para o comando de pausa / retomada incorreto:
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, é possível corrigir 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 a correção
Implante o código atualizado usando a CLI do Firebase:
firebase deploy --only functions
Tente novamente os comandos de voz a seguir. O Google Assistente vai responder corretamente quando você pausar / retomar a lavadora.
"Ok Google, pausar minha lavadora."
=>
"Claro, vou pausar a lavadora."
"Ok Google, retomar a lavagem."
=>
"Entendido, retomando a lavagem."
Também é possível 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. Testar sua integração com o Test Suite
Além de testar manualmente, você pode usar o pacote de testes automatizados para casa inteligente para validar casos de uso com base nos tipos de dispositivo e nas características associadas à sua integração. O pacote de testes executa uma série de testes para detectar problemas na integração e mostra mensagens informativas para casos de teste com falha para agilizar a depuração antes de mergulhar nos registros de eventos.
Executar o Test Suite para casa inteligente
Siga estas instruções para testar a integração entre nuvens usando o Test Suite:
- No navegador da Web, abra o Pacote de testes para casa inteligente.
- 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.
- No campo ID do projeto, insira o ID do projeto da integração entre nuvens. Em seguida, clique em PRÓXIMA para continuar.
- Na etapa Configurações de teste, o pacote de teste lista o tipo de dispositivo e as características da lavadora.
- Desative a opção Test Request Sync, já que o app de lavagem de exemplo não tem uma interface para adicionar / remover / mudar o nome da lavadora. Em um sistema de produção, é necessário acionar a sincronização de solicitações sempre que o usuário adicionar / remover / renomear dispositivos.
- Clique em PRÓXIMO para iniciar o teste.
Depois que o pacote de testes for concluído, confira os resultados dos casos de teste. Você vai notar dois casos de teste com falhas detectados com a respectiva mensagem de erro:
Para depurar a integração entre nuvens para corrigir a falha, você precisa identificar a causa raiz do erro analisando primeiro a mensagem de erro.
Analisar a 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 que indicam o motivo da falha.
Para o primeiro caso de teste com falha acima,
A mensagem de erro indica que o Test Suite espera "isPause": true nos estados informados da integração entre nuvens, 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 QUERY da integração entre nuvens incluem "isPause": true, que difere de "isPause": false nos estados informados da integração entre nuvens:
De acordo com as duas mensagens de erro, verifique se os relatórios de integraçã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 usando o estado do relatório. Inspecione o payload do estado do relatório e você vai descobrir que ele não tem o estado isPaused, que é exatamente o que o conjunto 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 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 a correção
Implante o código atualizado usando a CLI do Firebase:
$ firebase deploy --only functions
Execute o pacote de testes para casa inteligente novamente e verifique se todos os casos de teste foram aprovados.
5. Parabéns
Parabéns! Você aprendeu a resolver problemas de integração entre nuvens usando o Test Suite para casa inteligente e métricas e registros do GCP.
Saiba mais
Com base neste codelab, faça os exercícios a seguir e explore outros recursos:
- Adicione mais traços compatíveis ao seu dispositivo e teste-os com o pacote de testes.
- Crie painéis, configure alertas e acesse dados de métricas de forma programática para ter métricas de uso úteis sobre sua integração.
- Conheça o fulfillment local para casa inteligente.
- Confira nosso exemplo do GitHub para saber mais.
Você também pode saber mais sobre como testar e enviar uma integração para análise, incluindo o processo de certificação para publicar a integração aos usuários.