1. Antes de começar
Como desenvolvedor da Internet das Coisas (IoT, na sigla em inglês), é possível criar integrações de nuvem para nuvem que permitem os 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 de nuvem para nuvem é uma etapa importante para criar uma integração 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) e o registro e o pacote de testes para casa inteligente estão disponíveis para ajudar a identificar e resolver problemas nas suas integrações.
Pré-requisitos
- Leia o guia do desenvolvedor Criar uma integração de nuvem para nuvem.
- Execute o codelab Conectar dispositivos de casa inteligente ao Google Assistente.
O que você vai criar
Neste codelab, você vai implantar uma integração de nuvem para nuvem com dois defeitos e conectá-la ao Google Assistente. Em seguida, você vai depurar os defeitos da integração usando o pacote de testes para casa inteligente e as métricas e o registro 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 pacote de testes 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 24 ou mais recente
- Uma conta de faturamento do Google Cloud
2. Executar o app com falha
Conseguir o 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 de 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 Cloud Functions para Firebase e Firebase Realtime Database
Conectar-se ao Firebase
Abra o terminal na máquina de desenvolvimento. Acesse o diretório washer-faulty e configure a CLI do Firebase com seu projeto de integração criado no Conectar dispositivos de casa inteligente ao Google Assistente codelab:
$ 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 você vir a mensagem abaixo, ignore e continue. O aviso é devido a algumas dependências mais antigas, e você pode encontrar mais detalhes aqui.
found 5 high severity vulnerabilities run `npm audit fix` to fix them, or `npm audit` for details
Depois de instalar as dependências e configurar o projeto, você já pode implantar o app de lavadora com falha.
$ firebase deploy
Esta é a resposta do console que deverá aparecer:
... ✔ 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 ver o app da Web. Na interface da Web, clique no botão Atualizar
para atualizar o HomeGraph com os metadados mais recentes do dispositivo do app de lavadora com falha usando a sincronização de solicitações.
Abra o app Google Home e verifique se o dispositivo da lavadora chamado Faulty Washer aparece.
3. Testar sua integração
Depois de implantar o projeto, teste se a integração controla a lavadora.
Testar a lavadora
Verifique a mudança de 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 minha lavadora."
"Ok Google, parar minha lavadora."
Você vai notar que o Google Assistente responde que algo está errado por voz quando você pausa / retoma a lavadora:
"Desculpe, não consegui acessar <project display name>."
Para depurar esse problema, primeiro você precisa de mais informações sobre o erro para restringir e identificar a causa raiz.
Painel do Analytics para casa inteligente
Um bom lugar para inspecionar erros é o painel do Analytics para casa inteligente, que agrega gráficos de métricas de uso e integridade do fulfillment de nuvem:
- As métricas de uso refletem a tendência de uso da integração de nuvem para nuvem, 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 de nuvem para nuvem, abrangendo a latência da solicitação, a porcentagem de sucesso e a detalhamento de erros.
Para restringir a causa do erro, siga as etapas abaixo para acessar o painel do projeto.
- No console do desenvolvedor, acesse a página "Projetos".
- Selecione seu projeto de casa inteligente.
- Clique na guia Analytics no menu à esquerda.
- Isso vai levar você a uma lista de painéis do seu projeto no Google Cloud. Selecione o painel Google Home Analytics - Cloud Integration.
- Role a tela para baixo até o gráfico Erros de fulfillment de nuvem - detalhamento de status para conferir os códigos de erro do período destacado.
O código de erro PARTNER_RESPONSE_MISSING_DEVICE fornece uma dica para a causa raiz. Em seguida, recupere os registros de eventos com base no código de erro para mais detalhes.
Acessar registros de eventos
Para ter mais detalhes sobre o erro, acesse os registros de eventos da integração de nuvem para nuvem usando o 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 seu projeto. Como alternativa, você pode pesquisar Análise de registros na caixa de pesquisa.
No campo de entrada Pesquisar todos os campos, insira 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 de casa inteligente com detalhes de erro indicando:
- A ação do usuário realizada é "retomar a lavadora" (
actionType:"STARTSTOP_UNPAUSE"), correspondente ao comando de voz com falha recente. - A mensagem de depuração associada é "
JSON response does not include device."
Com base na mensagem de depuração, verifique por que o app de 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 ainda mais como a função updateDevice processa a pausa / retomada na lavadora. Você vai encontrar a string a ser correspondida para o comando de pausa / retomada incorreta:
index.js
const updateDevice = async (execution, deviceId) => {
const {params, command} = execution;
let state; let ref;
switch (command) {
...
case 'action.devices.commands.PauseUnpausePause':
const data = await queryDevice(deviceId);
state = (data.isPaused === false && data.isRunning === false)
? {isRunning: false, isPaused: false}
: {isRunning: !params.pause, isPaused: params.pause};
ref = getFirebaseRef().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':
const data = await queryDevice(deviceId);
state = (data.isPaused === false && data.isRunning === false)
? {isRunning: false, isPaused: false}
: {isRunning: !params.pause, isPaused: params.pause};
ref = getFirebaseRef().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 os seguintes comandos de voz. O Google Assistente vai responder corretamente quando você pausar / retomar a lavadora.
"Ok Google, pausar minha lavadora."
=>
"Claro, pausando a lavadora."
"Ok Google, retomar minha lavadora."
=>
"Entendi, retomando a lavadora."
Também é possível 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. Testar sua integração com o pacote de testes
Além de testar manualmente, você pode usar o pacote de testes automatizado para casa inteligente para validar casos de uso com base nos tipos de dispositivos e 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 acelerar a depuração antes de analisar os registros de eventos.
Executar o pacote de testes para casa inteligente
Siga estas instruções para testar sua integração de nuvem para nuvem pelo pacote de testes:
- 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 pacote de testes envie os comandos diretamente ao Google Assistente.
- No campo ID do projeto, insira o ID do projeto da integração de nuvem para nuvem. Em seguida, clique em PRÓXIMA para continuar.
- Na etapa Configurações de teste, o pacote de testes vai listar o tipo de dispositivo e as características da lavadora.
- Desative a opção Sincronização de solicitações de teste , já que o exemplo de app de lavadora não tem uma interface para adicionar, remover ou renomear a lavadora. Em um sistema de produção, você precisa acionar a sincronização de solicitações sempre que o usuário adicionar, remover ou renomear dispositivos.
- Clique em PRÓXIMA para iniciar o teste.
Depois que o pacote de testes terminar a execução, confira os resultados dos casos de teste. Você vai notar dois casos de teste com falha detectados com a respectiva mensagem de erro:
Para depurar a integração de nuvem para nuvem em relação à falha, você precisará 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 pacote de testes mostra mensagens de erro para cada caso de teste com falha que indica o motivo da falha.
Para o primeiro caso de teste com falha acima,
a mensagem de erro indica que o pacote de testes espera "isPause": true nos estados informados pela integração de nuvem para nuvem, 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 de nuvem para nuvem incluem "isPause": true, que difere de "isPause": false nos estados informados pela integração de nuvem para nuvem:
De acordo com as duas mensagens de erro, verifique se a integração informa 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 posta mudanças de estado no Home Graph usando o estado do relatório. Inspecione o payload do estado do relatório. Você vai encontrar o payload sem 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: snapshot.online,
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: snapshot.online,
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 casa inteligente. Você vai descobrir que todos os casos de teste foram aprovados.
5. Parabéns
Parabéns! Você aprendeu a resolver problemas de integração de nuvem para nuvem usando o pacote de testes para casa inteligente e as métricas e o registro do GCP.
Saiba mais
Com base neste codelab, faça os exercícios a seguir e explore outros recursos:
- Adicione mais características compatíveis ao seu dispositivo e teste-as com o pacote de testes.
- Crie painéis, configure alertas e acesse dados de métricas de maneira programática para receber métricas de uso úteis sobre sua integração.
- Conheça o fulfillment local para casas inteligentes.
- Confira nosso exemplo do GitHub para ver mais informações.
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 sua integração aos usuários.