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.
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
- Leia o guia para desenvolvedores sobre Criar uma ação de casa inteligente
- Executar o codelab Conectar dispositivos de casa inteligente ao Google Assistente.
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
- 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 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:
public
: uma interface de front-end para controlar e monitorar facilmente 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 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 para atualizar o HomeGraph via Request Sync com os metadados mais recentes do dispositivo referentes ao app com falha da lavadora:
Abra o app Google Home e confira se o dispositivo de lavagem Com falha é exibido.
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.
- No Console do Actions, acesse a página "Projetos".
- Selecione o projeto de casa inteligente.
- Escolha a guia Análise e clique em Ir para o Google Cloud Platform.
- 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.
- Role para baixo até o gráfico Cloud Fulfillment Errors: detalhamento de status para ver os códigos de erro do período destacado.
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.
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:
- 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 para o Google Assistente.
- No campo ID do projeto, insira o ID do projeto da ação de casa inteligente. Clique em PRÓXIMA para continuar.
- Na etapa Configurações de teste, o Test Suite lista o tipo de dispositivo e as características da lavadora.
- 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.
- 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:
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,
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:
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.
5. Parabéns
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:
- Adicione mais características compatíveis ao dispositivo e teste-as com o pacote de testes.
- Crie painéis, configure alertas e acesse dados de métricas de forma programática para conferir métricas de uso úteis sobre a Ação.
- Conheça o fulfillment local para casas inteligentes.
- Confira nosso exemplo do GitHub para saber mais.
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.