Depurar integrações do Matter

1. Antes de começar

O Matter oferece uma experiência de configuração e controle de dispositivos integrada e multiplataforma para usuários finais. Isso é possível principalmente devido aos vários componentes do ecossistema que trabalham em conjunto nos bastidores. Sistemas de solução de problemas como esses podem ser assustadores 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, é fundamental que você consiga reduzir os problemas que surgem durante o ciclo de desenvolvimento do dispositivo. Depois de lançar o projeto, é necessário monitorar as tendências de problemas dos dispositivos em campo de forma agregada e corrigi-los com atualizações de software. Este codelab aborda técnicas que podem ser usadas para os dois fins.

Pré-requisitos

• Conclua o guia Começar a usar o Matter com um projeto e uma configuração de dispositivo do Matter em funcionamento.
• 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 e 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. Use 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. Para isso, faça login no console do Google Cloud e navegue 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 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 dispositivos (câmeras). Esses painéis só contêm dados se você tiver uma integração do tipo correspondente, além de 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 estes:

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 para esse tipo de integração e vários gráficos mostrando os tipos e características de dispositivos envolvidos. Além disso, com o Matter, você tem um conjunto de gráficos que acompanham o sucesso do provisionamento e os lançamentos de atualizações nos seus dispositivos.

A visualização padrão com os gráficos que aparecem nos painéis do Google Home Analytics é apenas uma visualização criada para seu projeto usando dados de métricas de casa inteligente. Você também pode usar o Metrics Explorer para criar seus próprios gráficos com base nas mesmas métricas e salvá-los em painéis personalizados.

Acessar registros de erros

A Análise de registros é um conjunto de ferramentas para trabalhar com registros de eventos gerados em um projeto. Para acessar, navegue até Operações > Geração de registros > Análise de registros no console do Google Cloud.

Depois de abrir a Análise de registros, você vai ter uma visualização como esta:

A janela do Explorer 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 seu projeto, incluindo os gerados fora da casa inteligente. Por isso, é importante 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 provisionamento se refere ao conjunto de etapas necessárias para que um usuário configure um dispositivo Matter pela primeira vez.

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

Confira a página de comissionamento do guia básico do Matter para saber mais sobre cada uma dessas etapas. Nesta seção, vamos abordar as ferramentas e técnicas para depurar problemas de provisionamento.

Usar o Google Home Analytics

Criamos um conjunto de métricas para você investigar problemas de comissionamento rastreando eventos e entendendo em qual etapa os erros podem ocorrer. Você pode encontrar essas informações no painel de integração do Matter, conforme abordado na seção anterior.

Os gráficos neste painel fornecem dados sobre o provisionamento de dispositivos:

O gráfico de contagem de dispositivos mostra o número de tentativas de inclusão feitas pelos 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 um erro ocorre em qualquer um desses estados, ele também é capturado 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" e "severity>=ERROR" no campo de consulta.

Um registro de erros de provisionamento 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 ativação e de um código de status, um registro de erros contém carimbos de data/hora do 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 inclusão compartilha um sessionId.

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

Usar o Android Debug Bridge (ADB)

Outra maneira de resolver problemas de provisionamento é usar a ferramenta de linha de comando Android Debug Bridge (ADB). Como o provisionamento é feito 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 provisionamento.

Instalar ferramentas da plataforma

O ADB faz parte das ferramentas da plataforma 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 seu sistema, verifique o ADB conferindo 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 de desenvolvedor no seu dispositivo e, em seguida, ative a depuração USB.

Isso permite que o adb acesse os registros gerados pelos 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.

Talvez você receba uma mensagem de aviso no smartphone sobre a depuração USB, perguntando se quer permitir que o computador acesse informações do smartphone:

3. Se você receber essa mensagem de aviso, clique em Permitir.
4. Emita um comando de lista de dispositivos no terminal para verificar 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 seu dispositivo de maneira 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 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 do Home / Matter pelo Google Play Services:

$ 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 com o suporte sobre 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 comando a seguir fornecendo seu <phone-id> e um <file-name> em que os registros serão salvos no seu 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 será criado se ele ainda não existir, e os registros do smartphone serão adicionados a ele 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 do terminal em execução para interromper o registro.

Seus registros agora estão armazenados no arquivo de registro <file-name>. Como esse processo registra logs de todos os processos em execução rastreados no dispositivo, haverá muitos logs nesse arquivo. Por isso, sempre use esses registros pesquisando as entradas necessárias.

Analisar registros de erros

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

1. Seguindo a principal estratégia 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.

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 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, acenda as luzes da minha sala de estar") ou usando a interface do usuário no app Home ou nos dispositivos de tela Google Nest.

Como a especificação de controle entre dispositivos finais e Google Hubs é mediada pelo Matter, espera-se que haja menos erros no controle de dispositivos. De qualquer forma, fornecemos métricas e registros para você depurar esses tipos de problemas também.

Usar métricas

No painel de integração do Matter, você vai encontrar várias métricas sobre o controle de dispositivos. Há três gráficos importantes para avaliar a performance dos seus dispositivos em campo:

Durante problemas de controle, é comum ver tendências de queda na porcentagem de sucesso e de alta no gráfico de detalhamento de erros. O gráfico de detalhamento de erros mostra os erros capturados pelos Google Nest Hubs sobre o motivo da falha na tentativa de controle do dispositivo.

Usar registros

Cada problema de controle de 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 de dispositivos Matter têm esta 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 erro contém um carimbo de data/hora, tipo de dispositivo e característica, 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 aconteceu.

5. Depurar outros recursos

Até agora, você aprendeu a lidar com problemas de controle e comissionamento de dispositivos para o Matter. Há também 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 emitidas pelo Google Home, fornecemos um conjunto de métricas que mostram as versões de hardware e software dos dispositivos em uso.

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

Nos dias após o lançamento, cada vez mais dispositivos no campo recebem a nova versão de software associada ao lançamento de software OTA.

6. Pedir ajuda

O Google oferece ferramentas e documentação para depurar problemas do Matter, mas como o ecossistema é novo, haverá problemas que esses recursos não abrangem. Nesses casos, entre em contato com nossa equipe ou a comunidade para receber ajuda.

Acessar canais de desenvolvedores

Há três canais de desenvolvedores 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 (link em inglês): entre em contato com a gente e com a comunidade de desenvolvedores de casas inteligentes para tirar dúvidas sobre implementação ou pedir orientação. Esse canal é ideal para perguntar como resolver problemas ou implementar um determinado recurso.
• Issue Tracker:é o sistema oficial de rastreamento de problemas do Google, em que públicos externos podem 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 para desenvolvedores:para receber orientação do suporte oficial do Google e de especialistas da comunidade, entre em contato pelo fórum para desenvolvedores do Nest. Esse fórum é ideal 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 uma newsletter trimestral que destaca novos recursos e fornece 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. Desejamos 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 Test Suite para testar sua integração e verificar possíveis problemas.
• Quando a integração estiver pronta para ser compartilhada com o mundo, a próxima etapa será certificar seu projeto pelo WWGH. Para isso, siga as etapas na página Certificação.