Solução de problemas

App de exemplo

Se você tiver problemas ao usar as APIs Home, colete registros para mais depuração. Para coletar registros do dispositivo móvel, é necessário o Android Debug Bridge (adb). Se você precisar de ajuda do Google, colete os registros dos dispositivos Android e do hub e abra um tíquete no rastreador de problemas com as informações e os registros relevantes associados a ele.

Coletar registros do Android

O dispositivo móvel precisa estar conectado à máquina local em todas as etapas que envolvem adb.

Instalar o adb

Se ainda não fez isso, configure o Android Debug Bridge na sua máquina local:

  1. Instale o "adb" no seu computador.
  2. Ative as opções do desenvolvedor e a depuração USB no smartphone Android.

Plug-in do Google Home para o Android Studio

O Google Home Plugin for Android Studio é uma ferramenta útil para coletar e analisar registros, e foi criado especificamente para desenvolvedores do Google Home platform. Esse plug-in dá acesso ao Google Assistant Simulator, ao Cloud Logging e a outras ferramentas para simplificar o processo de desenvolvimento do smart home.

Use essa ferramenta com adb para analisar ainda mais os registros de dispositivos Matter.

Para saber mais e acessar a ferramenta, consulte Google Home Plugin for Android Studio.

Informações da versão

Recomendamos que você reúna todas as informações de versão relacionadas à sua configuração sempre que decidir coletar registros. Isso é necessário se você precisar compartilhar problemas com o Google.

  1. Encontre o ID do seu dispositivo móvel: 
    adb devices
     
    List of devices attached
device-id    device
  2. Armazene esse valor em uma variável chamada phoneid: 
    phoneid=device-id
  3. Salve várias informações do dispositivo em variáveis: 
    containerinfo=$(adb -s $phoneid shell dumpsys package com.google.android.gms | grep "versionName" || true);
homemoduleinfo=$(adb -s $phoneid shell dumpsys activity provider com.google.android.gms.chimera.container.GmsModuleProvider | grep "com.google.android.gms.home " || true);
optionalhomemoduleinfo=$(adb -s $phoneid  shell dumpsys activity provider com.google.android.gms.chimera.container.GmsModuleProvider | grep "com.google.android.gms.optional_home " || true);
policyhomemoduleinfo=$(adb -s $phoneid  shell dumpsys activity provider com.google.android.gms.chimera.container.GmsModuleProvider | grep "com.google.android.gms.policy_home" || true);
threadinfo=$(adb -s $phoneid shell dumpsys activity provider com.google.android.gms.chimera.container.GmsModuleProvider | grep "com.google.android.gms.threadnetwork" || true);
ghainfo=$(adb -s $phoneid shell dumpsys package com.google.android.apps.chromecast.app | grep versionName || true);
enabledfeatures=$((adb -s $phoneid shell dumpsys activity provider com.google.android.gms.chimera.container.GmsModuleProvider | grep "Enabled features" | grep -i "home") || true);
androidversion=$(adb -s $phoneid shell getprop ro.build.version.release || true);
androidapiversion=$(adb -s $phoneid shell getprop ro.build.version.sdk || true)
  4. Salve todas as variáveis em um arquivo chamado _versions.txt:

    Expandir para mostrar comandos para salvar variáveis em um arquivo

    Todo o bloco pode ser copiado e colado em um terminal de uma só vez.

    versionfile=$logtimestamp"_versions.txt"
echo "Saving version info to $versionfile"

echo "Container version:" >> $versionfile
echo $containerinfo >> $versionfile
echo "" >> $versionfile

echo "Home Module version:" >> $versionfile
echo $homemoduleinfo >> $versionfile
echo "" >> $versionfile

echo "Optional Home Module version:" >> $versionfile
echo $optionalhomemoduleinfo >> $versionfile
echo "" >> $versionfile

echo "Policy Home Module version:" >> $versionfile
echo $policyhomemoduleinfo >> $versionfile
echo "" >> $versionfile

echo "Thread Module version:" >> $versionfile
echo $threadinfo >> $versionfile
echo "" >> $versionfile

echo "GHA version:" >> $versionfile
echo $ghainfo >> $versionfile
echo "" >> $versionfile

echo "Android version: " >> $versionfile
echo $androidversion >> $versionfile
echo "" >> $versionfile

echo "Android API version: " >> $versionfile
echo $androidapiversion >> $versionfile
echo "" >> $versionfile

echo "Found enabled features (blank if missing):" >> $versionfile
echo $enabledfeatures >> $versionfile
echo "" >> $versionfile
  5. Verifique o conteúdo de _versions.txt: 
    cat _versions.txt

    Abrir para mostrar a saída do arquivo de amostra

    Container version:
versionName=23.19.12 (190400-530524295) versionName=22.46.17 (190408-491726958)

Home Module version:
com.google.android.gms.home [v230508900]

Optional Home Module version:


Policy Home Module version:
com.google.android.gms.policy_home [230508900] [230508900065.505615668.505615668] [Download:000003be/dl-Home.integ_230508900100400.apk] [download:/Home.integ/230508900100400:Home.integ:230508900100400]

Thread Module version:
com.google.android.gms.threadnetwork [v231912000]

GHA version:
versionName=3.2.32.1

Android version:
13

Android API version:
33

Found enabled features (blank if missing):
    Esse arquivo pode ser fornecido ao Google conforme necessário para a solução de problemas.

Coletar registros

Para coletar registros, feche todos os apps em execução no dispositivo móvel. Em seguida:

  1. Abra uma janela de terminal e limpe os registros de dispositivo atuais: 
    adb logcat -b all -c
  2. Inicie o processo de coleta de registros: 
    adb logcat >> _logs.txt
     Deixe esse terminal aberto. Isso vai coletar registros do seu dispositivo enquanto o processo estiver em execução.
  3. Execute o app de exemplo e capture todas as ações da interface do usuário. Quando terminar, pressione Ctrl+C (ou Cmd+C no Mac) para interromper o processo logcat em execução no terminal.
  4. Os registros dessa sessão são salvos em um arquivo chamado _logs.txt.

É possível analisar as informações desse arquivo de várias maneiras, incluindo a pesquisa de palavras-chave como error, exception ou crash.

Scripts de registro

Para sua conveniência, o app de exemplo fornece scripts para extrair os registros relevantes e compilá-los em um arquivo de texto. Para oferecer a melhor experiência de depuração, esses registros precisam ser anexados a todos os bugs informados para facilitar a análise da causa raiz pelo Google.

Esses registros estão localizados no diretório scripts na árvore de origem do app de exemplo. Execute as seguintes etapas no diretório raiz do projeto:

  1. Encontre o ID do seu dispositivo móvel: 
    adb devices -l
     
    List of devices attached
device-id device
  2. Execute o script get_logs.sh: 
     ./scripts/get_logs.sh device-id
     
    Cleared previous logs from device.
Saving version information to home_api_sample_logs_20240605233243.txt...
Saving logs to home_api_sample_logs_20240605233243.txt...
(Press CTRL+C to stop the script)
  3. Reproduza o problema.
  4. Pressione CTRL+C para interromper o script.

O script vai gerar um arquivo de registro com carimbo de data/hora que contém todas as informações relevantes. Anexe esses arquivos aos relatórios de bugs que você encontrar.

Registros de dispositivos do hub do Cast

É possível conferir os registros do dispositivo no Google Nest Hub usando este método, que é compatível com os seguintes modelos:

  • Google Home
  • Google Nest Audio
  • Google Nest Hub
  • Google Nest Mini

Para ativar um hub do Google Cast para recuperação de registros locais:

  1. Configure o Android Debug Bridge.

  2. Consiga o endereço IP do hub:

    • No hub, se ele tiver uma tela:
      1. Deslize de cima para baixo na tela.
      2. Toque no ícone Configurações
      3. Encontre o endereço IP do dispositivo: em um Nest Hub (2nd gen), acesse Informações do dispositivo > Informações técnicas > Endereço IP
    • Em GHA no seu smartphone:
      1. Toque no dispositivo para abrir a página de detalhes.
      2. Toque no ícone Configurações para abrir a página de configurações.
      3. Encontre o endereço IP do dispositivo: acesse Informações do dispositivo > Informações técnicas > Endereço IP

  3. Em um computador na mesma rede Wi-Fi do dispositivo: 

      adb connect ip-address
  adb logcat

  4. Para fornecer registros a alguém, execute a operação com falha e envie a saída para um arquivo de texto: 

      adb logcat -d > platform-logs.txt

Automações

Detecção de bordas

As automações no ecossistema Google Home têm detecção de borda, que é uma lógica que verifica se um gatilho só é ativado quando há uma mudança de estado real, e não uma atualização que apenas repete o estado anterior do dispositivo.

Por exemplo, se acender uma luz for um gatilho, a detecção de borda vai verificar se o gatilho só é ativado se o dispositivo de iluminação passar de desligado para ligado, e não de ligado para ligado (sem mudança).

A automação não se comporta como esperado

Depois de considerar a detecção de bordas, se uma automação não se comportar como esperado:

  1. Verifique cada dispositivo para garantir que ele esteja funcionando corretamente, independente da sua automação.

  2. Confira o gráfico de automação para comparar sua automação com a DSL e revelar possíveis suposições incorretas da sua parte.

  3. Observe o estado do dispositivo no app Google Home durante a execução da automação.

  4. Verifique se todos os dispositivos referenciados pela automação estão presentes na estrutura em que você espera que eles estejam. Excluir um dispositivo de que uma automação depende pode ter consequências indesejadas. Consulte Impacto da exclusão de dispositivos nas automações.

A automação é executada quando não deveria

Se a automação for executada quando não deveria, examine os critérios de ativação. Talvez seja necessário adicionar mais lógica para garantir que uma mudança de estado seja capturada e acione a automação apenas uma vez.

A automação não é compilada

Verifique se o app contém todas as importações necessárias, incluindo cada classe correspondente aos diferentes tipos de nós, bem como os traços a que você está fazendo referência.

A criação da automação falha na validação

Se a criação da automação não passar na validação, uma mensagem de aviso ou erro vai fornecer informações sobre o problema. Para mais informações, consulte a referência de ValidationIssueType.

A função de lista gera exceções

Ao chamar a função "List" da API Automation, os manipuladores de leitura podem gerar exceções devido à falta de recursos da API. Para evitar isso, exclua a automação afetada.

Para fazer isto:

  1. Verifique se o adb instalado está instalado. Consulte Instalar o adb.

  2. Recupere o ID da automação nos registros do Android invocando:

    adb logcat -s GhpNative

    Exemplos de registros:

    adb logcat -s GhpNative level:debug | grep -A 10 -B 10 AutomationManagerTrait\.ListResponse

INTERACTION RESPONSE -> SendCommandsResponse:
1 {
1: "automation@global"
3 {
  1: "home.internal.traits.automation.AutomationManagerTrait.ListResponse"
  2:
  5 {
    1: "type.googleapis.com/home.internal.traits.automation.AutomationManagerTrait.ListResponse"
    1 {
        1: "1111-2222-3333-44444-55555" // Automation ID to delete
        2: "structure@2222-3333-4444-5555-6666"
...

    Se for necessário excluir vários IDs de automação, use o pager do terminal para controlar a saída:

    adb logcat -s GhpNative level:debug | less

  3. Exclua a automação usando o ID dela:

    structure.deleteAutomation(new object : HasId(id = "1111-2222-3333-44444-55555"))

A API Discovery registra um aviso quando um traço é cancelado.

Se a API Discovery registrar um aviso para Trait not found, isso significa que a API está tentando usar a característica para candidatos da API Discovery, mas não vai conseguir porque a característica não foi registrada durante a inicialização. Exemplo:

09-03 17:45:20.578 10646 10646 W AutomationSdk: trait_id: "home.matter.6006.clusters.fc43" and Exception occurred com.google.home.HomeException: 18: Trait not found: home.matter.6006.clusters.fc43
09-03 17:45:20.578 10646 10646 W AutomationSdk: While converting candidate: # com.google.home.platform.traits.AutomationCandidateNode@76f0b582

O identificador de traço é home.matter.6006.clusters.fc43, que corresponde a RelativeHumidityControl. Para determinar o nome de um traço com base em um ID, consulte o Índice de traços.

Neste exemplo, RelativeHumidityControl precisa ser registrado durante a inicialização do app. Consulte Registrar características para adicionar sua característica ao registro.

OAuth

Se você já tem um cliente OAuth

Se você já tiver um cliente OAuth verificado para um app publicado, use o cliente OAuth atual para testar as APIs Home.

Não é necessário registrar o Google Home Developer Console para testar e usar as APIs Home. No entanto, você ainda vai precisar de um registro Developer Console aprovado para publicar seu app, mesmo que tenha um cliente OAuth verificado de outra integração.

As seguintes considerações se aplicam:

  • Há um limite de 100 usuários ao usar um cliente OAuth atual. Para informações sobre como adicionar usuários de teste, consulte Configure a tela de permissão OAuth. Independente da verificação do OAuth, há um limite imposto pelas APIs Home de 100 usuários que podem conceder permissões ao seu aplicativo. Essa limitação é removida após a conclusão do registro do Developer Console.

  • ODeveloper Console registro deve ser enviado para aprovação quando você estiver pronto para restringir as concessões de tipo de dispositivo pelo OAuth em preparação para atualizar o app com as APIs Home.

Para apps Google Cloud que ainda estão pendentes de verificação do OAuth, os usuários não podem concluir o fluxo do OAuth até que a verificação seja concluída. As tentativas de conceder permissões vão falhar com o seguinte erro:

Access blocked: <Project Name> has not completed the Google verification process.