Depurar integrações do Matter

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 oferece um conjunto de análises de solução de problemas para desenvolvedores coletadas de smartphones e hubs:

Como desenvolvedor, é crucial que você seja capaz de mitigar problemas que enfrentou durante todo o ciclo de desenvolvimento do dispositivo. Depois de lançar seu projeto, você precisa monitorar as tendências de problemas para dispositivos em campo de maneira agregada e corrigi-los por meio de 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 as ferramentas de análise de 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 as análises do Google Home

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 ter uma medida do desempenho do seu projeto.

Acessar as 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 cobre todo o projeto, além de painéis para integração específica (Cloud, Local, Matter) ou tipos de dispositivos (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ê verá uma série de gráficos como este:

Os painéis 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 as características envolvidas. 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

A Análise de registros é um conjunto de ferramentas para trabalhar com logs de eventos gerados em um projeto. Ele pode ser acessado no console do Google Cloud, em Operações > Geração de registros > Análise de registros.

Ao abrir o Logs Explorer, você vai encontrar uma visualização como 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, é essencial 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 comissionamento por 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 é capturado no gráfico de detalhamento de erros.

Estados de Comissão:

• 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 comissão, 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 a partir da 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 pode ser necessário fazer depuração adicional 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 o comissionamento é processado principalmente entre o dispositivo móvel e o dispositivo Matter, é possível usar a ferramenta adb para acessar 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 de plataforma no sistema, verifique o ADB verificando o número de versão no terminal com o seguinte comando:

$ adb -- version

Isso exibirá o número da versão do utilitário ADB instalado sem nenhum erro.

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 seu 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

1. Execute o servidor ADB com o seguinte comando:

$ adb start-server

2. 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:

3. Se você receber essa mensagem de aviso, clique em Permitir.
4. Emita um comando "list devices" no terminal para conferir 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 <phone-id> é uma string alfanumérica que identifica exclusivamente seu dispositivo.

5. Lembre-se do valor <phone-id> para usar nas próximas etapas.

Coletar informações do sistema

O próximo passo é verificar 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 conferir se você tem os módulos de controle Home / Matter pelo Google Play Services, faça o seguinte:

$ 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 solicitar 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.

1. Execute o seguinte comando 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 geração de registros. Um arquivo com o nome fornecido é criado, se ainda não existir, e os registros do telefone são adicionados ao arquivo após cada evento.

Siga as etapas de comissionamento com o dispositivo Matter.

2. Quando você chegar ao erro que quer depurar, interrompa o registro pressionando Control+C na 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.

1. Seguindo a principal estratégia usada ao analisar os erros de comissionamento, procure erros gerados pelo subsistema MatterCommissioner com o seguinte comando:

$ grep "MatterCommissioner" <file-name>

Isso gera uma saída que contém os eventos do processo de comissionamento.

2. 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.

3. Procure uma mensagem de falha de comissionamento com o seguinte comando:

$ grep "SetupDevice" $phonelog | grep -A 20 "Commissioning failed"

4. Depurar problemas de controle do dispositivo

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. Independentemente disso, também fornecemos métricas e registros para que você depure esses tipos de problemas.

Usar métricas

No painel de integração do Matter, várias métricas relacionadas ao controle de dispositivos são mostradas. Existem três gráficos essenciais para avaliar o desempenho dos seus dispositivos em 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. Para filtrar esses erros na Análise de registros, pesquise "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 em que você pode usar nossas técnicas recomendadas para garantir uma integração de boa qualidade.

Rastrear atualizações OTA

Para acompanhar os lançamentos de atualizações OTA para dispositivos Matter emitidos pelo Google Home, oferecemos um conjunto de métricas que mostram as versões de hardware e software dos dispositivos em campo.

Depois de emitir uma atualização pelo console, fique de olho nas seguintes métricas:

Nos dias seguintes ao lançamento, cada vez mais dispositivos em campo recebem a nova versão do software associada ao lançamento do seu software OTA.

6. Receber suporte

O Google fornece ferramentas e documentação para você depurar 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 suporte.

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 do Google e da comunidade, entre em contato pelo Fórum de Desenvolvedores do Nest. Este fórum é o melhor lugar para receber orientações oficiais sobre desenvolvimento.

Inscreva-se na newsletter para desenvolvedores

Além de visitar os canais para desenvolvedores para tirar dúvidas, também lançamos um boletim informativo trimestral que destaca novos recursos e traz notícias sobre o estado do ecossistema do Google Smart Home.

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.