Depurar integrações do Matter

1. Antes de começar

O Matter oferece uma experiência de controle e configuração de dispositivos multiplataforma para os usuários finais. Isso é possível principalmente devido aos vários componentes do ecossistema que funcionam em conjunto nos bastidores. Resolver problemas em sistemas como esse pode ser um desafio para os 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.

Existem três componentes principais para o Matter que são abordados neste codelab. Para cada um desses sistemas, o Google oferece um conjunto de análises de solução de problemas para desenvolvedores coletadas por meio de smartphones e hubs:

Comissionamento, execução, atualização OTA

Como desenvolvedor, é crucial que você possa mitigar problemas durante o ciclo de desenvolvimento do dispositivo. Depois de lançar seu projeto, você precisa monitorar as tendências de problemas dos dispositivos em campo de maneira agregada e corrigi-las com atualizações de software. Este codelab aborda técnicas que podem ser usadas para essas duas finalidades.

Pré-requisitos

  • Concluir o guia Introdução ao Matter com um projeto funcional e a configuração de dispositivos
  • 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 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 do Matter e os recursos de suporte para receber ajuda.

2. Acessar os dados de análise do Google Home

Monitorar o desempenho é essencial para uma integração 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 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 a casa inteligente vêm com o prefixo Google Home Analytics.

Painéis do Google Home Analytics

No momento, temos um painel geral que abrange todo o seu projeto, bem como 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, 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 estes:

Detalhamentos 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. Em cada painel de integração, há um gráfico com 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 com as características e os tipos de dispositivos envolvidos. Além disso, com o Matter você tem um conjunto de gráficos que rastreiam o sucesso do comissionamento, bem como os lançamentos de atualizações nos seus dispositivos.

A vista padrão com os gráficos mostrados 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 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. Ela pode ser acessada no Console do Google Cloud em Operações > Logging > Análise de registros.

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

Análise 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 o projeto, inclusive aqueles gerados fora da casa inteligente. É por isso que é 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 conhecer é sobre os eventos de comissionamento do Matter. O comissionamento se refere ao conjunto de etapas necessárias para que o usuário configure um dispositivo Matter pela primeira vez.

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

Eventos de comissionamento do Matter

Confira a página de encomenda do Matter Primer para saber mais sobre cada uma dessas etapas. Nesta seção, abordaremos as ferramentas e técnicas para depurar problemas de comissionamento.

Usar o Google Home Analytics

Criamos um conjunto de métricas para que você investigue problemas de comissionamento acompanhando eventos e entendendo em que estágio os erros podem ocorrer. Eles estão disponíveis no painel de integração do Matter, como abordamos na seção anterior.

Os gráficos neste painel oferecem dados sobre o comissionamento 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 ocorre um erro 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 > Logging > Análise de registros. Para filtrar erros de comissão, pesquise "clientUpdateLog" junto com "severity>=ERROR" no campo de consulta.

Um registro de erros de comissionamento do 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 do erro capturado e o ID do produto do Matter, que permite identificar qual dos produtos causou o erro. O conjunto de registros gerados da mesma tentativa de comissionamento compartilha um sessionId.

Ao usar as métricas do Google Home Analytics, você pode ter uma ideia inicial em que estágio o problema pode ocorrer. Para encontrar a causa raiz de erros de comissionamento do dispositivo, às vezes pode ser necessário fazer depuração adicional usando os registros gerados pelo dispositivo móvel utilizado 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 Android Debug Bridge (ADB). Como o comissionamento é feito principalmente entre o dispositivo móvel e o Matter, é possível usar a ferramenta ADB para acessar os registros gerados pelo app Google Home durante o comissionamento.

Instalar ferramentas da plataforma

O adb é parte do Android SDK Platform Tools, que pode ser instalado com o Android Studio ou com a ferramenta de linha de comando sdkmanager.

Após instalar as ferramentas da plataforma no seu sistema, verifique o ADB pelo número da versão no terminal com o seguinte comando:

$ adb -- version

Isso deve 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, depois, ativar a depuração USB.

Isso permite que o adb acesse registros gerados por apps atualmente 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 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

Você verá uma resposta 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

A seguir, é necessário 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 verificar se você tem os módulos de controle da casa / do 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 para falhas de comissionamento, sempre inclua informações do sistema em 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 informando o <phone-id> e um <file-name>, onde 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 será criado, se ainda não existir, e os registros do telefone serão adicionados a ele após cada evento.

Siga as etapas de comissionamento com o dispositivo Matter.

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

Os registros agora estão armazenados no arquivo de geração de registros <file-name>. Como esse processo grava registros de todos os processos em execução rastreados no dispositivo, haverá muitos registros nesse arquivo. É por isso que use sempre 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 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.

  1. Se o dispositivo Matter estiver usando o Thread, você também pode procurar erros gerados pelo subsistema Thread com este comando:
$ grep -E "(ThreadNetworkManager|BorderAgentScannerImpl|ThreadBrSynchronizer)" <file-name>

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

  1. Pesquise uma mensagem de falha de comissionamento com o seguinte comando:
$ grep "SetupDevice" $phonelog | grep -A 20 "Commissioning failed"

4. Depurar problemas no controle do dispositivo

Depois que os usuários configuram e comissionam 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 no app Home ou nos dispositivos de tela Google Nest.

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

Usar métricas

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

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

Durante os problemas de controle, é comum observar tendências de queda na porcentagem de sucesso e tendências no gráfico de detalhamento de erros. O gráfico de detalhamento de erros mostra os erros capturados pelos Google Nest Hubs relacionados ao 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. É possível filtrar esses erros do Buscador de registros pesquisando "executionLog".

Os registros de erros de controle do dispositivo Matter 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 um externalDebugString, uma breve mensagem de erro que explica do que se trata o erro.

5. Depurar outros recursos

Até agora, você aprendeu a lidar com problemas de comissionamento e controle do dispositivo no Matter. Existem também outros recursos dentro 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 os lançamentos de atualizações over the air (OTA) nos dispositivos Matter emitidas 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 do console, fique de olho nas seguintes métricas:

Detalhamentos de software e hardware

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

6. Procurar suporte

O Google oferece 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 abordam. Nesses casos, você pode entrar em contato com nossa equipe ou com a comunidade para receber ajuda.

Acessar canais do desenvolvedor

Há três canais de desenvolvedores monitorados ativamente no Google:

Stack Overflow, Issue Tracker, fórum de desenvolvedores

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

  • Stack Overflow:você pode entrar em contato com nossa equipe e com a comunidade de desenvolvedores de casa inteligente para tirar dúvidas sobre implementação ou buscar orientações. Esse canal é ideal para perguntar como resolver problemas ou implementar um recurso.
  • Issue Tracker:é o sistema oficial de rastreamento de problemas executado pelo Google em que públicos-alvo 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ções do Suporte oficial do Google e de especialistas da comunidade, entre em contato pelo Fórum de desenvolvedores do Nest. Este fórum é ideal para receber orientações oficiais para desenvolvimento.

Inscreva-se na newsletter para desenvolvedores

Além de visitar os canais dos desenvolvedores para tirar dúvidas, também lançamos uma newsletter trimestral que destaca os novos recursos e dá 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. Aproveite para criar integrações do Matter com o Google Home.

Próximas etapas

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

  • Além de usar o Analytics para resolver problemas, você também pode usar o Test Suite para testar sua integração e identificar possíveis problemas.
  • Quando a integração estiver pronta para ser compartilhada com o mundo, a próxima etapa será receber a certificação do WWGH. Para isso, siga as etapas na página Certificação.