1. Antes de começar
O Matter oferece uma experiência de configuração e controle de dispositivos perfeita e multiplataforma para os usuários finais. Isso é possível principalmente devido aos vários componentes do ecossistema que trabalham em conjunto nos bastidores. A solução de problemas de sistemas como esses pode ser assustadora para novos desenvolvedores. Por isso, desenvolvemos uma série de ferramentas e técnicas para facilitar sua vida como desenvolvedor do Matter com o Google Home.
Há três componentes principais do Matter abordados neste codelab. Para cada um desses sistemas, o Google fornece um conjunto de análises de solução de problemas para desenvolvedores coletadas de smartphones e hubs:
Como desenvolvedor, é fundamental que você consiga mitigar os problemas que encontrar ao longo do ciclo de desenvolvimento do dispositivo. Depois de lançar o projeto, você precisa monitorar as tendências de problemas dos dispositivos no campo de forma agregada e corrigi-los com atualizações de software. Este codelab aborda técnicas que podem ser usadas para os dois propósitos.
Pré-requisitos
- Conclua o guia Começar a usar o Matter com um projeto do Matter e uma configuração de dispositivo funcionando
- Ter um smartphone Android que possa ser conectado à estação de trabalho (para registros do ADB)
O que você vai aprender
- Como usar ferramentas de análise para casa inteligente para monitorar problemas do Matter em grande escala.
- Como classificar erros acessando registros de erros e coletando informações.
- Como acessar a documentação e os recursos de suporte do Matter para receber ajuda.
2. Acessar o Google Home Analytics
Monitorar a performance é fundamental para uma integração bem-sucedida com o ecossistema do Google Home. Oferecemos um conjunto de ferramentas de monitoramento para desenvolvedores de casas inteligentes no Google Cloud Platform. Você pode usar essas ferramentas para medir o desempenho do seu projeto.
Acessar métricas do projeto
- A primeira etapa para acessar seus dados é verificar os painéis do Google Home fazendo login no console do Google Cloud e navegando até Operações > Monitoramento > Painéis.
Há vários painéis disponíveis para seu projeto (incluindo outros produtos do GCP). Os painéis fornecidos para a casa inteligente têm o prefixo "Google Home Analytics".
No momento, temos um painel geral que abrange todo o projeto, além de painéis para integração específica (Cloud, Local, Matter) ou tipos de dispositivo (câmeras). Esses painéis só contêm dados se você tiver uma integração do tipo correspondente e um projeto funcional que atenda às solicitações.
Ao abrir um desses painéis, você vai encontrar uma série de gráficos parecidos com este:
Os painéis iniciais do Google Home contêm vários gráficos que mostram detalhes dos eventos associados ao seu projeto. Em cada painel de integração, você encontra um gráfico mostrando o número total de solicitações processadas pelo projeto, um gráfico mostrando a taxa de sucesso desse tipo de integração e vários gráficos mostrando os tipos de dispositivo e os atributos envolvidos. Além disso, com o Matter, você tem um conjunto de gráficos que rastreiam o sucesso da ativação, bem como os lançamentos de atualizações nos seus dispositivos.
A visualização padrão com os gráficos que você vê nos painéis de análise do Google Home é apenas uma visualização que criamos para seu projeto usando dados de métricas de casa inteligente. Também é possível usar o Metrics Explorer para criar seus próprios gráficos com as mesmas métricas e salvá-los nos painéis personalizados.
Acessar registros de erros
O Logs Explorer é um conjunto de ferramentas para trabalhar com registros de eventos gerados em um projeto. Para acessar o recurso no console do Google Cloud, navegue até Operações > Geração de registros > Análise de registros.
Ao abrir o Logs Explorer, você vai ter uma visualização semelhante a esta:
A janela do explorador contém várias ferramentas para visualizar, filtrar, consultar e analisar registros. Por padrão, essa visualização mostra os registros gerados por todos os sistemas disponíveis para o projeto, incluindo os gerados fora da casa inteligente. Por isso, é fundamental usar esses registros filtrando os eventos que você quer depurar. Vamos falar mais sobre isso nas seções de depuração.
3. Depurar problemas de comissionamento
O primeiro tipo de métrica que vamos analisar é sobre eventos de comissionamento do Matter. O comissionamento se refere ao conjunto de etapas necessárias para que um usuário configure um dispositivo Matter pela primeira vez.
Durante a comissionamento do dispositivo, um conjunto de interações ocorre entre o dispositivo Matter, o app Google Home e o fabric do Matter. A imagem a seguir demonstra alguns desses eventos:
Confira a página de comissionamento do guia introdutório do Matter para saber mais sobre cada uma dessas etapas. Nesta seção, vamos abordar as ferramentas e técnicas para depurar problemas de comissionamento.
Usar o Google Home Analytics
Criamos um conjunto de métricas para você investigar problemas de comissionamento rastreando eventos e entendendo em qual fase os erros podem ocorrer. Elas podem ser encontradas no Painel de integração do Matter, conforme abordamos na seção anterior.
Os gráficos neste painel fornecem dados sobre a ativação do dispositivo:
O gráfico de contagem de dispositivos mostra o número de tentativas de ativação feitas pelos usuários em uma determinada data. A taxa de sucesso mostra a taxa de sucesso percebida para esses eventos no Google. Cada tentativa de comissionamento gera um conjunto de eventos com estados associados. Quando um erro ocorre em qualquer um desses estados, ele também é registrado no gráfico de detalhamento de erros.
Estados de comissionamento:
- COMMISSIONING_STARTED
- ONBOARDING_PAYLOAD_GENERATED
- LOCAL_DISCOVERY_SUCCESSFUL
- PASE_CONNECTION_SUCCESSFUL
- NOC_ADDED_SUCCESSFULLY
- COMMISSIONING_COMPLETE
Para conferir uma versão detalhada desses eventos, acesse Operações > Geração de registros > Análise de registros. Para filtrar erros de comissionamento, pesquise "clientUpdateLog" com "severity>=ERROR" no campo de consulta.
Um registro de erros de comissionamento do Matter tem esta aparência:
{
"insertId": "1a32ry0f6xpzzn",
"jsonPayload": {
"clientUpdateLog": {
"MatterUpdate": {
"reportedProductId": 55,
"sessionId": "1584879052892229997",
"reportedVendorId": 4800,
"commissioningState": "GENERIC_COMMISSIONING_ERROR",
"status": "GENERIC_ERROR"
}
}
},
"resource": {
"type": "assistant_action_project",
"labels": {
"project_id": "<project-id>"
}
},
"timestamp": "2023-03-01T07:09:55.216425297Z",
"severity": "ERROR",
"logName": "projects/<project-id>/logs/assistant_smarthome%2Fassistant_smarthome_logs",
"receiveTimestamp": "2023-03-01T07:09:55.216425297Z"
}
Além do estado de comissionamento e de um código de status, um registro de erros contém carimbos de data/hora para o erro capturado, bem como o ID do produto Matter, que permite identificar qual dos seus produtos causou o erro. O conjunto de registros gerados na mesma tentativa de comissionamento compartilha um sessionId.
O uso de métricas do Google Home Analytics dá uma ideia inicial de em qual estágio o problema pode ocorrer. Para encontrar a causa raiz dos erros de comissionamento do dispositivo, às vezes é necessário fazer mais depuração usando os registros gerados pelo dispositivo móvel usado no processo de comissionamento. Para isso, você precisa da Android Debug Bridge.
Usar o Android Debug Bridge (adb)
Outra maneira de resolver problemas de comissionamento é usar a ferramenta de linha de comando do Android Debug Bridge (ADB). Como a comissionamento é gerenciada principalmente entre o dispositivo móvel e o dispositivo Matter, é possível usar a ferramenta ADB para acessar os registros gerados pelo app Google Home durante o comissionamento.
Instalar ferramentas de plataforma
O adb faz parte das Ferramentas da plataforma do SDK do Android, que podem ser instaladas com o Android Studio ou pela ferramenta de linha de comando sdkmanager.
Depois de instalar as ferramentas da plataforma no sistema, verifique o ADB verificando o número da versão no terminal com o seguinte comando:
$ adb -- version
Isso vai mostrar o número da versão do utilitário ADB instalado sem erros.
Ativar a depuração USB
Em seguida, ative a depuração USB no dispositivo Android.
Primeiro, siga as etapas para ativar as opções do desenvolvedor no dispositivo e, em seguida, ative a depuração USB.
Isso permite que o adb acesse os registros gerados por apps que estão em execução no dispositivo.
Extrair o ID do dispositivo
- Execute o servidor do ADB com o seguinte comando:
$ adb start-server
- Conecte o smartphone ao computador que executa o servidor ADB.
Talvez você receba uma mensagem de aviso no smartphone sobre a depuração USB, perguntando se você quer permitir que o computador acesse as informações do smartphone:
- Se você receber essa mensagem de aviso, clique em Permitir.
- Emita um comando de lista de dispositivos no terminal para saber se o computador pode acessar o smartphone pelo ADB usando o seguinte comando:
$ adb devices
Isso vai gerar uma resposta semelhante a esta:
List of devices attached <phone-id> device
O <id-do-telefone> é uma string alfanumérica que identifica exclusivamente o dispositivo.
- Lembre-se do valor
<phone-id>para usar nas próximas etapas.
Coletar informações do sistema
Em seguida, verifique as informações de versão dos apps e do sistema no seu dispositivo.
- Para verificar a versão do SO Android:
$ adb -s <phone-id> shell getprop ro.build.version.release
- Para verificar a versão do app Google Home:
$ adb -s <phone-id> shell dumpsys package com.google.android.apps.chromecast.app | grep versionName
- Para verificar a versão do Google Play Services:
$ adb -s <phone-id> shell dumpsys package com.google.android.gms | grep "versionName"
- Para verificar se você tem os módulos de controle da Casa / Matter pelos Serviços do Google Play:
$ adb -s <phone-id> shell dumpsys activity provider com.google.android.gms.chimera.container.GmsModuleProvider | grep "com.google.android.gms.home"
Verifique se esses valores de retorno são compatíveis com nosso ecossistema. Ao pedir suporte para falhas de comissionamento, sempre inclua informações do sistema nos seus tíquetes de suporte.
Coletar registros de erros
Em seguida, inicie o processo de coleta de registros e siga as etapas de comissionamento para gerar os eventos de erro que você quer depurar.
- Execute o comando a seguir fornecendo o
<phone-id>e um<file-name>em que os registros serão salvos no computador (por exemplo,debug_file.txt).
$ adb -s <phone-id> logcat > <file-name>
Isso inicia imediatamente o processo de registro. Um arquivo com o nome fornecido será criado se ainda não existir, e os registros do smartphone serão adicionados ao arquivo após cada evento.
Siga as etapas de comissionamento com o dispositivo Matter.
- Quando você chegar ao erro que quer depurar, interrompa o registro pressionando
Control+Cna janela do terminal em execução.
Seus registros agora serão armazenados no arquivo de registro <file-name>. Como esse processo registra registros de todos os processos em execução rastreados no dispositivo, haverá muitos registros nesse arquivo. Por isso, sempre use esses registros pesquisando as entradas necessárias.
Analisar registros de erros
Os processos de comissionamento são processados por um subsistema chamado MatterCommissioner no GHA.
- Seguindo a estratégia principal usada ao analisar erros de comissionamento, procure erros gerados pelo subsistema MatterCommissioner com o seguinte comando:
$ grep "MatterCommissioner" <file-name>
Isso gera uma saída com os eventos do processo de comissionamento.
- Se o dispositivo Matter estiver usando o Thread, você também poderá procurar erros gerados pelo subsistema Thread com o seguinte comando:
$ grep -E "(ThreadNetworkManager|BorderAgentScannerImpl|ThreadBrSynchronizer)" <file-name>
Ao analisar o arquivo de registro gerado pelo processo de depuração do ADB, procure também determinados padrões. Muitos erros de comissionamento incluem a string "commissioning failure" na mensagem de erro.
- Procure uma mensagem de falha de comissionamento com o seguinte comando:
$ grep "SetupDevice" $phonelog | grep -A 20 "Commissioning failed"
4. Depurar problemas de controle de dispositivos
Depois que os usuários configuram e ativam os dispositivos Matter no ecossistema do Google Home, eles podem emitir comandos por voz usando o Google Assistente (por exemplo, "Ok Google, ligue as luzes da minha sala de estar") ou usando a interface do app Home ou dos dispositivos de tela Google Nest.
Como a especificação de controle entre os dispositivos finais e os hubs do Google é mediada pelo Matter, espera-se que haja menos erros no controle do dispositivo. De qualquer forma, também oferecemos métricas e registros para você depurar esses tipos de problemas.
Usar métricas
No Painel de integração do Matter, você vai encontrar várias métricas relacionadas ao controle do dispositivo. Há três gráficos essenciais para avaliar a performance dos seus dispositivos no campo:
Durante problemas de controle, é comum observar tendências de queda na porcentagem de sucesso e uma tendência de aumento no gráfico de detalhamento de erros. O gráfico de detalhamento de erros mostra os erros capturados pelos Google Nest Hubs sobre por que a tentativa de controle do dispositivo falhou.
Usar registros
Cada problema de controle do dispositivo Matter também gera um registro de erros no sistema. Esses erros podem ser filtrados na Análise de registros pesquisando "executionLog".
Os registros de erros de controle do dispositivo Matter são parecidos com este:
{
"insertId": "1a32ry0f6xpzzn",
"jsonPayload": {
"executionLog": {
"executionResults": [
{
"executionType": "MATTER",
"latencyMsec": "6000",
"actionResults": [
{
"action": {
"actionType": "ONOFF_OFF",
"trait": "TRAIT_ON_OFF"
},
"status": {
"externalDebugString": "No message was received before the deadline.",
"statusType": "RESPONSE_TIMEOUT",
"fallbackToCloud": false,
"isSuccess": false
},
"device": {
"deviceType": "OUTLET"
}
}
],
"requestId": "1487232799486580805"
}
]
},
"locale": "en-US"
},
"resource": {
"type": "assistant_action_project",
"labels": {
"project_id": "<project-id>"
}
},
"timestamp": "2023-03-01T15:47:27.311673018Z",
"severity": "ERROR",
"logName": "projects/<project-id>/logs/assistant_smarthome%2Fassistant_smarthome_logs",
"receiveTimestamp": "2023-03-01T15:47:27.311673018Z"
}
Cada registro de erro contém um carimbo de data/hora, tipo de dispositivo e atributo, além do erro associado à solicitação de controle no statusType. Muitos erros de controle também incluem um externalDebugString, uma mensagem de erro curta que explica o que está acontecendo.
5. Depurar outros recursos
Até agora, você aprendeu a lidar com problemas de comissionamento e controle de dispositivos para o Matter. Também há outros recursos no ecossistema que você pode usar ou técnicas recomendadas para garantir uma integração de boa qualidade.
Monitorar atualizações OTA
Para acompanhar os lançamentos de atualizações OTA para dispositivos Matter emitidos pelo Google Home, disponibilizamos um conjunto de métricas que mostram as versões de hardware e software dos dispositivos em campo.
Depois de emitir uma atualização no console, fique de olho nas seguintes métricas:
Nos dias seguintes ao lançamento, mais e mais dispositivos no campo vão receber a nova versão do software associada à versão OTA.
6. Receber suporte
O Google fornece ferramentas e documentação para você depurar os problemas do Matter, mas, como o ecossistema do Matter é novo, haverá problemas que esses recursos não abrangem. Nesses casos, você pode entrar em contato com nossa equipe ou com a comunidade para receber ajuda.
Acessar canais de desenvolvedores
Há três canais de desenvolvedor monitorados ativamente no Google:
Embora cada um desses canais seja monitorado pela mesma equipe de forma periódica, há algumas diferenças importantes sobre quando usar cada um deles.
- Stack Overflow:entre em contato com nossa equipe e a comunidade de desenvolvedores de casas inteligentes para tirar dúvidas sobre implementação ou pedir orientações. Esse canal é o melhor para perguntar como resolver problemas ou implementar um determinado recurso.
- Rastreador de problemas:é o sistema oficial de rastreamento de problemas do Google, em que o público externo pode informar erros no ecossistema. Ele oferece ferramentas da Web para anexar arquivos e compartilhar informações sensíveis quando necessário. O Issue Tracker é a melhor opção para relatar problemas do ecossistema ou compartilhar solicitações de recursos.
- Fórum de desenvolvedores:para receber orientação de especialistas oficiais de suporte e da comunidade do Google, entre em contato pelo Fórum de Desenvolvedores do Nest. Este fórum é o melhor para receber orientações oficiais sobre desenvolvimento.
Inscreva-se na newsletter para desenvolvedores
Além de visitar os canais para desenvolvedores e tirar dúvidas, também lançamos um boletim informativo trimestral que destaca novos recursos e traz notícias sobre o estado do ecossistema de casas inteligentes do Google.
Use o formulário de inscrição para receber a newsletter para desenvolvedores.
7. Parabéns
Parabéns! Você aprendeu a depurar integrações do Matter usando as ferramentas e técnicas recomendadas. Esperamos que você se divirta criando integrações do Matter com o Google Home.
Próximas etapas
Faça os exercícios a seguir e confira outros recursos:
- Além de usar a análise para resolver problemas, você também pode usar o pacote de testes para testar a integração em relação a possíveis problemas.
- Quando a integração estiver pronta para ser compartilhada com o mundo, a próxima etapa é obter a certificação WWGH do seu projeto. Para isso, siga as etapas na página Certificação.