A migração para a Central para desenvolvedores do Google Home foi concluída.

Como depurar a casa local

1. Antes de começar

As integrações de casa inteligente permitem que o Google Assistente controle os dispositivos conectados nas casas dos usuários. Para criar uma integração de nuvem para nuvem, você precisa fornecer um endpoint de webhook na nuvem capaz de processar intents de casa inteligente. Por exemplo, quando o usuário diz "Ok Google, acenda as luzes", o Google Assistente envia o comando ao fulfillment da nuvem para atualizar o estado do dispositivo.

Para integrar sua integração de casa inteligente, o SDK local do Google Home adiciona um caminho local para encaminhar as intents de casa inteligente diretamente para um dispositivo Google Home. Isso aumenta a confiabilidade e reduz a latência no processamento dos comandos dos usuários. Assim, é possível criar e implantar um app fulfillment local no TypeScript ou JavaScript que identifique dispositivos e execute comandos em qualquer alto-falante inteligente do Google Home ou smart display do Google Nest. O app se comunica diretamente com os dispositivos inteligentes dos usuários na rede local usando protocolos padrão para executar comandos.

A depuração de integrações de nuvem para nuvem é uma etapa essencial para criar integrações com qualidade de produção. No entanto, ela é desafiadora e demorada sem ferramentas informativas e fáceis de usar para teste e solução de problemas. Para facilitar a depuração de integrações de nuvem para nuvem, as métricas e o Logging do Google Cloud Platform (GCP) e o Test Suite para casa inteligente estão disponíveis para ajudar você a identificar e resolver problemas nas suas integrações.

Pré-requisitos

Guia para desenvolvedores Criar uma integração de nuvem para nuvem
Execute o codelab Ativar atendimento local para integrações de nuvem para nuvem.

O que você vai criar

Neste codelab, você vai criar um atendimento local para integrações de nuvem para nuvem e conectá-lo ao Google Assistente. Em seguida, vai depurar o app Google Home usando o pacote de testes para casa inteligente e métricas e geração de registros 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 para identificar problemas funcionais e de API.
Como usar o Chrome DevTools ao desenvolver o app Local Home.

O que é necessário

A versão mais recente do Google Chrome
Um dispositivo iOS ou Android com o app Google Home
Um alto-falante inteligente do Google Home ou smart display do Google Nest
Node.js versão 10.16 ou mais recente
Uma Conta do Google
Uma conta de faturamento do Google Cloud

2. Executar o app da lavadora

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-local.git

Sobre o projeto

O app inicial tem subdiretórios e funções do Cloud semelhantes ao codelab Ativar o atendimento local para integrações de nuvem para nuvem. Em vez de app-start, temos app-faulty aqui. Vamos começar com um app de casa inteligente local que funciona, mas não tão bem.

Conectar-se ao Firebase

Vamos usar o mesmo projeto que você criou no codelab Ativar o atendimento local para integrações de nuvem para nuvem, mas vamos implantar os arquivos baixados neste codelab.

Acesse o diretório app-faulty e configure a CLI do Firebase com seu projeto de integração criado no codelab Ativar o fulfillment local para integrações de nuvem para nuvem:

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

Implantar no Firebase

Acesse a pasta app-faulty/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 aqui.

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

Acesse o diretório app-faulty/local/ e execute os seguintes comandos para fazer o download do compilador TypeScript e compilar o app:

$ cd ../local
$ npm install
$ npm run build

Isso compila a origem index.ts (TypeScript) e coloca o seguinte conteúdo no diretório app-faulty/public/local-home/:

bundle.js: saída de JavaScript compilada que contém o app local e as dependências.
index.html: página de hospedagem local usada para veicular o app para testes no dispositivo.

Após instalar as dependências e configurar o projeto, você já pode executar o app pela primeira vez.

$ 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://<projectcd -id>.web.app

O comando implanta um app da Web, além de várias Cloud Functions para Firebase.

Atualizar o HomeGraph

Abra o URL de hospedagem no navegador (https://<project-id>.web.app) 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 no app da máquina de lavar com falha usando Solicitar sincronização.

Abra o app Google Home e verifique se o dispositivo da lavadora aparece com o novo nome "Lavadora com defeito". Não se esqueça de atribuir o dispositivo a um ambiente que tenha um dispositivo Nest.

3. Iniciar a lavadora inteligente

Se você já executou o codelab Ativar o atendimento local para integrações de nuvem para nuvem, já deve ter iniciado a máquina de lavar inteligente virtual. Se ele estiver parado, reinicie o dispositivo virtual.

Iniciar o dispositivo

Acesse o diretório virtual-device/ e execute o script do dispositivo, transmitindo os parâmetros de configuração como argumentos:

$ cd ../../virtual-device
$ npm install
$ npm start -- \
  --deviceId=deviceid123 --projectId=<project-id> \
  --discoveryPortOut=3311 --discoveryPacket=HelloLocalHomeSDK

Verifique se o script de dispositivo é executado com os parâmetros esperados:

(...): UDP Server listening on 3311
(...): Device listening on port 3388
(...): Report State successful

4. Testar o app Local Home

Envie comandos para seu dispositivo usando comandos de voz para o dispositivo Google Home, como:

"Ok Google, ligue minha lavadora."

"Ok Google, ligar minha lavadora."

"Ok Google, forçar local."

"Ok Google, pare a lavadora."

O Google Assistente vai responder com "Desculpe, parece que a máquina de lavar com defeito não está disponível no momento" quando você tentar controlar a máquina depois de "force local".

Isso significa que o dispositivo não pode ser acessado por um caminho local. Ele funcionava antes de emitir "Ok Google, force local" porque vamos voltar a usar o caminho da nuvem quando o dispositivo não puder ser acessado por um caminho local. No entanto, depois de "forçar local", a opção de voltar ao caminho da nuvem é desativada.

Para descobrir qual é o problema, vamos usar as ferramentas que temos: métricas e registro em log do Google Cloud Platform (GCP) e as Ferramentas para desenvolvedores do Chrome.

5. Depurar o app Local Home

Na seção a seguir, você vai usar as ferramentas fornecidas pelo Google para descobrir por que o dispositivo não pode ser acessado pelo caminho local. Você pode usar as Ferramentas para desenvolvedores do Chrome para se conectar ao dispositivo Google Home, visualizar os registros do console e depurar o app Local Home. Também é possível enviar registros personalizados para o Cloud Logging para ficar por dentro dos principais erros que os usuários estão encontrando no app Local Home.

Conectar as ferramentas para desenvolvedores do Chrome

Para conectar o depurador ao seu app de fulfillment local, siga estas etapas:

Verifique se você vinculou seu dispositivo Google Home a um usuário com permissão para acessar o projeto do Play Console.
Reinicie o dispositivo Google Home para que ele receba o URL do HTML e a configuração de verificação colocada no Play Console.
Inicie o Chrome na sua máquina de desenvolvimento.
Abra uma nova guia do Chrome e digite chrome://inspect no campo de endereço para iniciar o inspetor.

Você verá uma lista de dispositivos na página e o URL do aplicativo aparecerá abaixo do nome do dispositivo Google Home.

Iniciar o inspetor

Clique em Inspecionar abaixo do URL do aplicativo para iniciar as Ferramentas para desenvolvedores do Chrome. Selecione a guia Console e confirme se aparece o conteúdo da intent IDENTIFY impresso pelo app do TypeScript.

Essa saída significa que o manipulador IDENTIFY foi acionado, mas o verificationId retornado no IdentifyResponse não corresponde a nenhum dos dispositivos no HomeGraph. Vamos adicionar alguns registros personalizados para descobrir o motivo.

Adicionar registros personalizados

Embora haja um erro DEVICE_VERIFICATION_FAILED impresso pelo SDK Local Home, ele não ajuda muito a encontrar a causa raiz. Vamos adicionar alguns registros personalizados para garantir que estamos lendo e processando os dados de verificação corretamente. Se rejeitarmos a promessa com um erro, a mensagem de erro também será enviada ao Cloud Logging.

local/index.ts

identifyHandler(request: IntentFlow.IdentifyRequest):
    Promise<IntentFlow.IdentifyResponse> {
  console.log("IDENTIFY intent: " + JSON.stringify(request, null, 2));

  const scanData = request.inputs[0].payload.device.udpScanData;
  if (!scanData) {
    const err = new IntentFlow.HandlerError(request.requestId,
        'invalid_request', 'Invalid scan data');
    return Promise.reject(err);
  }

  // In this codelab, the scan data contains only local device id.
  // Is there something wrong here?
  const localDeviceId = Buffer.from(scanData.data);
  console.log(`IDENTIFY handler: received local device id
      ${localDeviceId}`);

  // Add custom logs
  if (!localDeviceId.toString().match(/^deviceid[0-9]{3}$/gi)) {
    const err = new IntentFlow.HandlerError(request.requestId,
        'invalid_device', 'Invalid device id from scan data ' +
        localDeviceId);
    return Promise.reject(err);
  }

  const response: IntentFlow.IdentifyResponse = {
    intent: Intents.IDENTIFY,
    requestId: request.requestId,
    payload: {
      device: {
        id: 'washer',
        verificationId: localDeviceId.toString(),
      }
    }
  };
  console.log("IDENTIFY response: " + JSON.stringify(response, null, 2));

  return Promise.resolve(response);
}

Além disso, mude a versão local do app Google Home para que possamos identificar se estamos usando a versão correta.

local/index.ts

const localHomeSdk = new App('1.0.1');

Depois de adicionar os registros personalizados, compile o app novamente e faça uma nova implantação no Firebase.

$ cd ../app-faulty/local
$ npm run build
$ firebase deploy --only hosting

Agora, reinicie o dispositivo Google Home para que ele possa carregar o app local atualizado. Para saber se o dispositivo Google Home está usando a versão esperada, consulte os registros do Console nas Ferramentas para desenvolvedores do Chrome.

Acessar o Cloud Logging

Vamos conferir como usar o Cloud Logging para encontrar seus erros. Para acessar o Cloud Logging do seu projeto:

No console do Cloud Platform, acesse a página Projetos.
Selecione seu projeto de casa inteligente.
Em Operações, selecione Logging > Análise de registros.

O acesso aos dados de registro é gerenciado pelo Identity and Access Management (IAM) para usuários do projeto de integrações. Para mais detalhes sobre papéis e permissões para dados de registros, consulte o controle de acesso do Cloud Logging.

Usar filtros avançados

Sabemos que há erros na intent IDENTIFY porque o caminho local não está funcionando, já que o dispositivo local não é identificado. No entanto, queremos saber exatamente qual é o problema. Então, vamos filtrar primeiro os erros que acontecem no gerenciador IDENTIFY.

Clique no botão Mostrar consulta, que vai se transformar em uma caixa Criador de consultas. Insira jsonPayload.intent="IDENTIFY" na caixa Criador de consultas e clique no botão Executar consulta.

Como resultado, você recebe todos os registros de erros gerados no manipulador IDENTIFY. Em seguida, expanda o último erro. Você vai encontrar o errorCode e o debugString que acabou de definir ao rejeitar a promessa no manipulador IDENTIFY.

Pelo debugString, podemos dizer que o ID do dispositivo local não está no formato esperado. O app Local Home espera receber o ID do dispositivo local como uma string que começa com deviceid e é seguida por três dígitos, mas o ID do dispositivo local aqui é uma string hexadecimal.

Corrigir o erro

Voltando ao código-fonte em que analisamos o ID do dispositivo local dos dados de verificação, notamos que não fornecemos a codificação ao converter a string em bytes. Os dados de verificação são recebidos como uma string hexadecimal. Portanto, transmita hex como a codificação de caracteres ao chamar Buffer.from().

local/index.ts

identifyHandler(request: IntentFlow.IdentifyRequest):
    Promise<IntentFlow.IdentifyResponse> {
  console.log("IDENTIFY intent: " + JSON.stringify(request, null, 2));

  const scanData = request.inputs[0].payload.device.udpScanData;
  if (!scanData) {
    const err = new IntentFlow.HandlerError(request.requestId,
        'invalid_request', 'Invalid scan data');
    return Promise.reject(err);
  }

  // In this codelab, the scan data contains only local device id.
  const localDeviceId = Buffer.from(scanData.data, 'hex');
  console.log(`IDENTIFY handler: received local device id
      ${localDeviceId}`);

  if (!localDeviceId.toString().match(/^deviceid[0-9]{3}$/gi)) {
    const err = new IntentFlow.HandlerError(request.requestId,
      'invalid_device', 'Invalid device id from scan data ' +
      localDeviceId);
    return Promise.reject(err);
  }

  const response: IntentFlow.IdentifyResponse = {
    intent: Intents.IDENTIFY,
    requestId: request.requestId,
    payload: {
      device: {
        id: 'washer',
        verificationId: localDeviceId.toString(),
      }
    }
  };
  console.log("IDENTIFY response: " + JSON.stringify(response, null, 2));

  return Promise.resolve(response);
}

Além disso, mude a versão local do app Google Home para que possamos identificar se estamos usando a versão correta.

local/index.ts

const localHomeSdk = new App('1.0.2');

Depois de corrigir o erro, compile o app e faça uma nova implantação no Firebase. Em app-faulty/local, execute:

$ npm run build
$ firebase deploy --only hosting

Teste sua correção

Após a implantação, reinicie o dispositivo Google Home para que ele possa carregar o app Google Home local atualizado. Verifique se a versão do app Google Home local é 1.0.2. Desta vez, não deve haver erros no console das Ferramentas para desenvolvedores do Chrome.

Agora você pode tentar enviar comandos para o dispositivo de novo.

"Ok Google, forçar local."

"Ok Google, pare a lavadora."

"Ok Google, ligue minha lavadora."

…

"Ok Google, forçar padrão."

6. Executar o pacote de testes para casa inteligente

Depois de verificar seu dispositivo usando os controles por toque no app Google Home ou por comandos de voz, use o pacote de testes para casa inteligente automatizado para validar casos de uso com base nos tipos e traits de dispositivos associados à sua integração. O Test Suite executa uma série de testes para detectar problemas na sua integração e mostra mensagens informativas para casos de teste com falha, acelerando a depuração antes de analisar os registros de eventos.

Executar o pacote de teste para casa inteligente

Siga estas instruções para testar sua integração de nuvem para nuvem com o Test Suite:

No navegador da Web, abra o Test Suite para casa inteligente.
Faça login no Google usando o botão no canto superior direito. Isso permite que a Test Suite envie os comandos diretamente para o Google Assistente.
No campo ID do projeto, insira o ID do projeto da sua integração de nuvem para nuvem. Em seguida, clique em PRÓXIMA para continuar.
Na etapa Configurações de teste, você vai encontrar a lavadora com defeito na seção Dispositivos e características.
Desative a opção Test Request Sync porque o app de exemplo não tem uma interface para adicionar, remover ou renomear a máquina de lavar. 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.
Deixe a opção SDK Local Home ativada, já que vamos testar caminhos locais e na nuvem.
Clique em Próxima: ambiente de teste para começar a executar o teste.

Quando os testes forem concluídos, você vai notar que os testes de pausa/retomada no caminho local estão falhando, enquanto os testes de pausa/retomada no caminho da nuvem estão sendo aprovados.

Analisar a mensagem de erro

Analise as mensagens de erro nos casos de teste com falha. Eles informam qual é o estado esperado para esse teste e qual foi o estado real. Nesse caso, para "Pause the Washer", o estado esperado é isPaused: true, mas no estado real recebemos isPaused: false. Da mesma forma, para "Pause the Washer", o estado esperado é isPaused: true, mas no estado real recebemos isPaused: false.

Pelas mensagens de erro, parece que no caminho local estamos definindo o estado isPaused de forma inversa.

Identificar e corrigir o erro

Vamos encontrar o código-fonte em que o app Local Home envia o comando de execução para o dispositivo. getDataCommand() é a função chamada pelo executeHandler() para definir o payload no comando de execução enviado ao dispositivo.

local/index.ts

getDataForCommand(command: string, params: IWasherParams): unknown {
    switch (command) {
        case 'action.devices.commands.OnOff':
            return {
                on: params.on ? true : false
            };
        case 'action.devices.commands.StartStop':
            return {
                isRunning: params.start ? true : false
            };
        case 'action.devices.commands.PauseUnpause':
            return {
                // Is there something wrong here?
                isPaused: params.pause ? false : true
            };
        default:
            console.error('Unknown command', command);
            return {};
    }
}

Estamos definindo o isPause no estado inverso. Ele deve ser definido como true quando params.pause for true e false caso contrário. Vamos corrigir isso.

local/index.ts

getDataForCommand(command: string, params: IWasherParams): unknown {
    switch (command) {
        case 'action.devices.commands.OnOff':
            return {
                on: params.on ? true : false
            };
        case 'action.devices.commands.StartStop':
            return {
                isRunning: params.start ? true : false
            };
        case 'action.devices.commands.PauseUnpause':
            return {
                isPaused: params.pause ? true : false
            };
        default:
            console.error('Unknown command', command);
            return {};
    }
}

Mude a versão do app Google Home local para que possamos identificar se estamos usando a versão correta.

local/index.ts

const localHomeSdk = new App('1.0.3');

Não se esqueça de compilar o app novamente e fazer uma nova implantação no Firebase. Em app-faulty/local, execute:

$ npm run build
$ firebase deploy --only hosting

Agora, reinicie o dispositivo Google Home para que ele possa carregar o app Casa local atualizado. Verifique se a versão do app Casa local é 1.0.3.

Teste sua correção

Agora, execute novamente o conjunto de testes para casa inteligente com as mesmas configurações. Você vai notar que todos os casos de teste foram aprovados.

7. Parabéns

Parabéns! Você aprendeu a solucionar problemas de um app Local Home usando o pacote de testes para casa inteligente e o Cloud Logging.

Saiba mais

Veja o que mais você pode fazer:

Adicione mais traços compatíveis ao seu dispositivo e teste com o Test Suite.
Adicione mais registros personalizados em cada um dos gerenciadores de intent e confira no Cloud Logging.
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.

Você também pode saber mais sobre como testar e enviar uma integração para análise, incluindo o processo de certificação para publicá-la aos usuários.

Como depurar a casa local Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

1. Antes de começar

Pré-requisitos

O que você vai criar

O que você vai aprender

O que é necessário

2. Executar o app da lavadora

Faça o download do código-fonte

Sobre o projeto

Conectar-se ao Firebase

Implantar no Firebase

Atualizar o HomeGraph

3. Iniciar a lavadora inteligente

Iniciar o dispositivo

4. Testar o app Local Home

5. Depurar o app Local Home

Conectar as ferramentas para desenvolvedores do Chrome

Iniciar o inspetor

Adicionar registros personalizados

Acessar o Cloud Logging

Usar filtros avançados

Corrigir o erro

Teste sua correção

6. Executar o pacote de testes para casa inteligente

Executar o pacote de teste para casa inteligente

Analisar a mensagem de erro

Identificar e corrigir o erro

Teste sua correção

7. Parabéns

Saiba mais

Como depurar a casa local