Depurar integrações do Matter

1. Antes de começar

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

Este codelab aborda três componentes principais do Matter. Para cada um desses sistemas, o Google fornece um conjunto de análises de solução de problemas para desenvolvedores coletadas em smartphones e hubs:

Comissão, execução, atualização OTA

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 essas duas finalidades.

Pré-requisitos

  • Concluir o guia Começar a usar o Matter com um projeto prático do Matter e a configuração do dispositivo
  • 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 de dados de casa inteligente para monitorar problemas do Matter em grande escala.
  • Como fazer a triagem de erros acessando registros de erros e coletando informações.
  • Como acessar a documentação e os recursos de suporte do Matter para procurar ajuda.

2. Acessar as análises do Google Home

O monitoramento da 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. 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 o projeto, inclusive outros produtos do GCP. Os painéis fornecidos para a casa inteligente têm um prefixo do Google Home Analytics.

Painéis do 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ó vão conter dados se você tiver uma integração do tipo correspondente, além de um projeto em funcionamento que atenda às solicitações.

Ao abrir um desses painéis, você verá uma série de gráficos como este:

Detalhamento da taxa de sucesso, da latência e do tipo de dispositivo

Os painéis do Google Home contêm vários gráficos que mostram detalhes dos eventos associados ao seu projeto. Com 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 que mostra a taxa de sucesso desse tipo de integração e vários gráficos que mostram os tipos de dispositivos e as características envolvidas. Além disso, o Matter tem um conjunto de gráficos que monitora o sucesso do comissionamento, bem como o lançamento de atualizações nos seus dispositivos.

A visualização padrão com os gráficos 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 com as mesmas métricas subjacentes 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.

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

Explorador de registros

A janela do explorador contém várias ferramentas para visualizar, filtrar, consultar e analisar registros. Por padrão, essa visualização mostra registros gerados por todos os sistemas disponíveis para seu projeto, incluindo registros gerados fora da casa inteligente. Por isso, é essencial usar esses registros filtrando os eventos que você quer depurar. Falaremos mais sobre isso nas seções de depuração.

3. Depurar problemas de comissionamento

O primeiro tipo de métrica que vamos conferir é 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 o comissionamento do dispositivo, ocorre um conjunto de interações entre o dispositivo Matter, o app Google Home e o tecido Matter. A imagem a seguir demonstra alguns desses eventos:

Eventos de comissionamento do Matter

Confira a página de comissionamento do Matter Primer 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 estágio os erros podem ocorrer. Eles podem ser encontrados 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:

Métricas de comissionamento 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 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 Comissão:

  • COMMISSIONING_STARTED
  • ONBOARDING_PAYLOAD_GENERATED
  • LOCAL_DISCOVERY_SUCCESSFUL
  • PASE_CONNECTION_SUCCESSFUL
  • NOC_ADDED_SUCCESSFULLY
  • COMMISSIONING_COMPLETE

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

O 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 um código de status, um registro de erro contém carimbos de data/hora do erro capturado, bem como o ID do produto do 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.

Com as métricas do Google Home Analytics, você tem uma ideia inicial de em que 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 do Android Debug Bridge.

Usar o Android Debug Bridge (adb)

Outra maneira de solucionar 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 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 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

Agora, 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 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
  1. 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:

Solicitação de depuração USB

  1. Se você receber essa mensagem de aviso, clique em Permitir.
  2. Emita um comando "list devices" no terminal para conferir se o computador pode acessar o smartphone pelo ADB usando o seguinte comando:
$ adb devices

A resposta será semelhante a esta:

List of devices attached
<phone-id>    device

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

  1. 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 entrar em contato com o suporte sobre falhas no 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 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.

  1. Quando chegar ao erro que você quer depurar, interrompa a geração de registros pressionando Control+C na janela do terminal em execução.

Seus registros agora estão armazenados no arquivo de geração de registros <file-name>. Como esse processo registra registros de todos os processos em execução monitorados 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 gerenciados por um subsistema chamado MatterCommissioner na 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 que contém os eventos do processo de comissionamento.

  1. Se o dispositivo Matter estiver usando o Thread, você também vai 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 certos padrões. Muitos erros de comissionamento incluem "commissioning failure" na mensagem de erro.

  1. 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 de configurar e comissionar os dispositivos Matter no ecossistema Google Home, os usuários podem emitir comandos por voz usando o Google Assistente (por exemplo, "Ok Google, acenda as luzes da sala de estar") ou usando a interface no app Home ou nos dispositivos de tela Google Nest.

Como a especificação de controle entre os dispositivos finais e os hubs do Google é mediada pelo Matter, é esperado 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:

Gráficos de detalhamento de sucesso, latência e erros

Durante as questões de controle, você pode observar tendências de redução na porcentagem de sucesso e de aumento no gráfico de detalhamento de erros. O gráfico de detalhamento de erros mostra os erros detectados pelos Google Nest Hubs sobre o motivo da falha na tentativa de controle do dispositivo.

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 do 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 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 breve mensagem de erro que explica do que se trata.

5. Depurar outros recursos

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

Rastrear atualizações OTA

Para acompanhar os lançamentos de atualizações over the air (OTA) para 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 pelo console, fique de olho nas seguintes métricas:

Detalhamento de software e hardware

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. Procurar suporte

O Google oferece ferramentas e documentação para você depurar problemas do Matter, mas como o ecossistema dele é novo, esses recursos não cobrem as questões. Nesses casos, entre em contato com nossa equipe ou com a comunidade para buscar suporte.

Acessar canais para desenvolvedores

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

Stack Overflow, Issue Tracker, fórum de desenvolvedores

Embora cada um desses canais seja monitorado periodicamente pela mesma equipe, existem algumas diferenças importantes em relação a quando usar cada um.

  • Stack Overflow: entre em contato com nossa equipe e a comunidade de desenvolvedores de casas inteligentes para fazer perguntas sobre implementação ou receber orientações. Use esse canal para saber 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 informar problemas do 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, entre em contato pelo Fórum de desenvolvedores do Nest. Este fórum é o melhor para receber orientações oficiais para desenvolvimento.

Inscreva-se na newsletter para desenvolvedores

Além de acessar os canais para desenvolvedores em caso de dúvidas, também lançamos um boletim trimestral que destaca novos recursos e traz notícias sobre o estado do ecossistema de casa inteligente do Google.

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

7. Parabéns

Google Home

Parabéns! Você aprendeu a depurar integrações do Matter usando as ferramentas e técnicas recomendadas. Esperamos que se divirta criando integrações do Matter com o Google Home.

Próximas etapas

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

  • Além de usar análises para solucionar problemas, você também pode usar o Pacote de testes para testar sua integração e encontrar possíveis problemas.
  • Quando sua integração estiver pronta para ser compartilhada com o mundo, a próxima etapa será tornar seu projeto Certificado em Compatível com o Google Home. Para isso, siga as etapas na página Certificação.