Como depurar integrações do Matter

1. Antes de começar

O Matter oferece uma experiência integrada de controle e configuração em dispositivos multiplataforma para os usuários finais. Isso é possível principalmente devido aos vários componentes do ecossistema que funcionam em conjunto nos bastidores. A solução de problemas desses sistemas pode ser assustadora para novos desenvolvedores. Por isso, desenvolvemos uma série de ferramentas e técnicas para facilitar sua vida como desenvolvedor Matter com o Google Home.

Este codelab inclui três componentes principais do Matter. Para cada um desses sistemas, o Google oferece um conjunto de análises de solução de problemas para desenvolvedores coletados de telefones e hubs:

Como desenvolvedor, é fundamental que você consiga mitigar os problemas encontrados ao longo do ciclo de desenvolvimento do dispositivo. Depois de lançar o projeto, é necessário monitorar as tendências de problemas dos dispositivos no campo de forma agregada e corrigi-las por meio de atualizações de software. Este codelab aborda técnicas que você pode usar para essas duas finalidades.

Pré-requisitos

• Concluir o guia Primeiros passos com o Matter com um projeto funcional e uma configuração de dispositivo
• ter um smartphone Android que possa ser conectado à estação de trabalho (para registros ADB);

O que você vai aprender

• Como usar ferramentas de análise para a casa inteligente para monitorar problemas do Matter em grande escala.
• Como fazer a triagem de erros acessando registros de erro e coletando informações.
• Como acessar a documentação do Matter e recursos de suporte para receber ajuda.

2. Ver o Google Home Analytics

O monitoramento do desempenho é fundamental para uma integração bem-sucedida com o ecossistema do Google Home. Fornecemos um conjunto de ferramentas de monitoramento para desenvolvedores de casas inteligentes no Google Cloud Platform. Você pode usar essas ferramentas para ver o desempenho do seu projeto.

Acessar métricas de projetos

• O primeiro passo 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 casa inteligente vêm com um prefixo do Google Home Analytics.

No momento, temos um painel geral que abrange todo o projeto, bem como painéis para integração específica (Cloud, Local, Matter) ou tipos de dispositivo (Câmeras). Esses painéis só conterão dados se você tiver uma integração do tipo correspondente e um projeto em funcionamento que atenda às solicitações.

Ao abrir um desses painéis, você verá uma série de gráficos com a seguinte aparência:

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ê vê um gráfico que mostra o número total de solicitações processadas pelo seu projeto, um gráfico da taxa de sucesso desse tipo de integração e vários gráficos que mostram os tipos e as características do dispositivo envolvido. Além disso, com o Matter, você tem um conjunto de gráficos que acompanham o sucesso da ativação e as atualizações nos dispositivos.

A visualização padrão com os gráficos exibidos nos painéis do Google Home Analytics é 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 a partir das mesmas métricas subjacentes e salvá-los nos painéis personalizados.

Acessar registros de erros

O Explorador de registros é uma coleção de ferramentas para trabalhar com os logs de eventos gerados em um projeto. Acesse o Console do Google Cloud em Operações > Geração de registros > Explorador de registros.

Depois de abrir o Explorador de registros, você verá 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 de todos os sistemas disponíveis para o projeto, incluindo aqueles gerados fora da casa inteligente. É por isso que é fundamental usar esses registros filtrando por eventos que você quer depurar. Falaremos mais sobre isso nas seções de depuração.

3. Problemas de depuração de comissionamento

O primeiro tipo de métrica que vamos conhecer é sobre os eventos de comissionamento do Matter. O comissionamento é o conjunto de etapas necessárias para um usuário configurar um dispositivo Matter pela primeira vez.

Durante a ativação do dispositivo, um conjunto de interações ocorre entre o dispositivo Matter, o app Google Home e o tecido Matter. A imagem a seguir demonstra alguns desses eventos:

Consulte a página de comissão do Matter Primer para saber mais. Nesta seção, abordaremos as ferramentas e técnicas para depurar problemas de comissionamento.

Usar o Google Analytics

Criamos um conjunto de métricas para que você investigue problemas de ativação, acompanhando eventos e entendendo em que estágio os erros podem ocorrer. Você pode encontrá-los no Painel de integração do Matter, conforme abordado na seção anterior.

Os gráficos neste painel mostram dados sobre a ativação do dispositivo:

O gráfico de contagem de dispositivos mostra o número de tentativas de comissionamento feitas por usuários em uma determinada data. A taxa de sucesso mostra a taxa de sucesso percebida desses eventos no Google. Cada tentativa de comissionamento gera um conjunto de eventos com estados associados. Quando ocorre um erro em qualquer um desses estados, ele também é capturado no gráfico de detalhamento de erros.

Estados de comissionamento:

• COMMISIONING_INÍCIO
• ONBOARDING_PAYLOAD_GENERATED
• LOCAL_DISCOVERY_SUCCESSFUL
• PASE_CONNECTION_SUCCESSFUL
• NOC_ADDED_SUCCESSFULLY
• COMMISSIONING_COMPLETE

Para ver uma versão detalhada desses eventos, acesse Operações > Geração de registros > Explorador de registros. Para filtrar por erros de comissão, pesquise "clientUpdateLog" por "severity>=ERROR" no campo de consulta.

Um registro de erros de comissionamento para o Matter tem a seguinte 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 quais dos seus produtos causaram o erro. O conjunto de registros gerados a partir da mesma tentativa de comissionamento compartilham um sessionId.

O uso de métricas do Google Home Analytics dá uma ideia inicial da etapa do problema. Para encontrar a causa de erros de comissionamento do dispositivo, às vezes pode ser necessário fazer uma depuração adicional usando os registros gerados pelo dispositivo móvel usado no processo de comissionamento. Para isso, você precisa do Android Debug Bridge.

Usar o Android Debug Bridge (adb)

Outra forma de solucionar problemas de comissionamento é usar a ferramenta de linha de comando do Android Debug Bridge (adb). Como a ativação de comissões é realizada 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 a ativação.

Instalar ferramentas da plataforma

O adb vem como parte das Android SDK Platform Tools, 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 deverá exibir o número da versão do utilitário adb instalado sem nenhum erro.

Ativar 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 ativar a depuração USB.

Isso permite que o adb acesse registros gerados por apps em execução no dispositivo.

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

Você pode receber uma mensagem de aviso no telefone sobre a depuração USB, perguntando se deseja permitir que seu computador acesse informações do seu telefone:

3. Se você receber essa mensagem de aviso, clique em Permitir.
4. Execute um comando de lista de dispositivos no terminal para ver se o computador pode acessar o smartphone pelo adb usando o seguinte comando:

$ adb devices

O resultado será semelhante a este:

List of devices attached
<phone-id>    device

Seu <phone-id> é uma string alfanumérica que identifica seu dispositivo de forma exclusiva.

5. 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 conferir se você tem os módulos de controle Home / Matter no 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 entrar em contato para receber suporte sobre falhas de comissionamento, sempre inclua informações do sistema nos tíquetes de suporte.

Coletar registros de erros

Em seguida, inicie o processo de coleta de registros e siga as etapas de ativação para gerar os eventos de erro que você quer depurar.

1. Execute o comando a seguir, fornecendo seu <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 é criado, caso ainda não exista, e os registros do telefone são adicionados ao arquivo após cada evento.

Siga as etapas de comissionamento com seu dispositivo Matter.

2. Quando chegar ao erro que você quer depurar, pressione Control+C na janela de terminal em execução para interromper a geração de registros.

Seus registros agora serão armazenados no arquivo de registros <file-name>. Como esse processo grava registros de todos os processos em execução rastreados no dispositivo, haverá muitos registros neste arquivo. É por isso que você sempre deve usar esses registros pesquisando as entradas necessárias.

Analisar registros de erros

Os processos de comissionamento são manipulados por meio de um subsistema chamado MatterCommissioner no GHA.

1. Seguindo a estratégia principal 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 contendo os eventos do processo de comissionamento.

2. Se o dispositivo Matter estiver usando o Thread, também será possível procurar erros gerados pelo subsistema do Thread por meio do seguinte comando:

$ grep -E "(ThreadNetworkManager|BorderAgentScannerImpl|ThreadBrSynchronizer)" <file-name>

Ao analisar o arquivo de registros gerado pelo processo de depuração do ADB, procure também por determinados padrões. Muitos erros de comissionamento incluem a string "commissioning failure" na mensagem de erro.

3. Procure uma mensagem de falha na ativação 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 comissionam dispositivos Matter no ecossistema do Google Home, eles podem emitir comandos por voz usando o Google Assistente (por exemplo, "Ok Google, acenda as luzes da minha sala de estar") ou usando a IU no app Google Home ou nos dispositivos de tela Google Nest.

Como a especificação de controle entre dispositivos finais e Google Hubs é mediada pela Matter, espera-se que ela tenha menos erros no controle de dispositivos. Independentemente disso, também fornecemos métricas e registros para você depurar esses tipos de problemas.

Usar métricas

No painel de integração do Matter, você verá várias métricas relacionadas ao controle de dispositivos. Existem três gráficos essenciais para avaliar o desempenho dos seus dispositivos em campo:

Durante os problemas de controle, você geralmente vê tendências na porcentagem de sucesso e um aumento no gráfico de detalhamento de erros. O gráfico de detalhamento de erros mostra os erros capturados pelo Google Nest Hubs que explicam por que a tentativa de controle do dispositivo falhou.

Usar registros

Cada problema de controle de dispositivo Matter também gera um registro de erro no sistema. Esses erros podem ser filtrados do Explorador de registros pesquisando por "executionLog".

Os registros de erro de controle de dispositivos têm a seguinte aparência:

{
  "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 erros contém um carimbo de data/hora, um tipo de dispositivo e uma característica, além do erro associado à solicitação de controle no statusType. Muitos erros de controle também incluem uma externalDebugString, uma mensagem de erro curta que explica o problema.

5. Depurar outros recursos

Até agora, você aprendeu a lidar com problemas de comissionamento e controle de dispositivos no Matter. Há também outros recursos do ecossistema que podem ser usados com nossas técnicas recomendadas para garantir uma integração de boa qualidade.

Rastrear atualizações OTA

Para rastrear as versões "over-the-air" (OTA) dos dispositivos Matter emitidos pelo Google Home, fornecemos um conjunto de métricas que mostram as versões de hardware e software dos dispositivos em campo.

Depois de emitir uma atualização a partir do console, fique atento às seguintes métricas:

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

6. Procurar suporte

O Google fornece ferramentas e documentos para você depurar os problemas do Matter. No entanto, como o ecossistema do Matter é novo, existem problemas que não são abordados por esses recursos. Nesses casos, entre em contato conosco ou com a comunidade para receber suporte.

Acessar canais para desenvolvedores

Existem três canais para desenvolvedores monitorados ativamente no Google:

Embora cada um desses canais seja monitorado periodicamente pela mesma equipe, há algumas diferenças importantes quanto ao uso de cada um.

• Stack Overflow: você pode entrar em contato com nossa comunidade de desenvolvedores de casas inteligentes para tirar dúvidas sobre a implementação ou receber orientações. Este canal é melhor para perguntar como resolver problemas ou implementar um determinado recurso.
• Issue Tracker: é o sistema oficial de acompanhamento de problemas executado pelo Google, em que públicos externos podem relatar erros no ecossistema. Ele oferece ferramentas da Web para anexar arquivos e compartilhar informações confidenciais quando necessário. Usar o Issue Tracker é a melhor opção para informar problemas no ecossistema ou compartilhar solicitações de recursos.
• Fórum de desenvolvedores: para receber orientação do suporte oficial do Google e de especialistas da comunidade, você pode falar com o Fórum de desenvolvedores da Nest. Este fórum é melhor para \ receber orientações oficiais para desenvolvimento.

Inscreva-se na newsletter para desenvolvedores

Além de visitar os canais para desenvolvedores, também lançamos um boletim informativo trimestral que destaca novos recursos e fornece notícias sobre o estado do ecossistema de casa inteligente do Google.

Use o formulário de inscrição para receber a newsletter do desenvolvedor.

7. Parabéns

Parabéns! Você aprendeu a depurar integrações do Matter usando as ferramentas e técnicas recomendadas. Desejamos a você um bom momento para criar integrações do Matter com o Google Home.

Próximas etapas

Faça os seguintes exercícios e explore outros recursos:

• Além de usar análises para resolver problemas, também é possível usar o Pacote de testes para testar a integração com possíveis problemas.
• Quando sua integração estiver pronta para ser compartilhada com o mundo todo, a próxima etapa é tornar seu projeto certificado pelo WWGH. Para isso, siga as etapas na página Certificação.