Esta página foi traduzida pela API Cloud Translation.

Solução de problemas

App de exemplo

Se você tiver problemas ao usar as APIs Home, colete logs para depuração adicional. A coleta de registros do dispositivo móvel requer o Android Debug Bridge (adb). Se você precisar de assistência 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 para todas as etapas envolvendo adb.

Instalar o adb

Configure o Android Debug Bridge na sua máquina local, caso ainda não tenha feito isso:

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

Plug-in do Google Home para Android Studio

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

Use essa ferramenta com o adb para analisar melhor os registros do dispositivo Matter.

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

Informações da versão

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

Acesse o ID do seu dispositivo móvel:

adb devices

List of devices attached
device-id    device

Armazene esse valor em uma variável chamada phoneid:
```
phoneid=device-id
```

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)

Salve todas as variáveis em um arquivo chamado _versions.txt:

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

O bloco inteiro 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

Verifique o conteúdo de _versions.txt:

cat _versions.txt

Expanda para mostrar a saída de arquivo de exemplo

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):

Agora, esse arquivo pode ser enviado ao Google conforme necessário para resolver problemas.

Coletar registros

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

Abra uma janela do terminal e limpe os registros do dispositivo:
```
adb logcat -b all -c
```
Inicie o processo de coleta de registros:
```
adb logcat >> _logs.txt
```
Deixe este terminal aberto. Isso vai coletar registros do seu dispositivo enquanto o processo estiver em execução.
Execute o app de exemplo e capture todas as ações da interface do usuário. Quando terminar, interrompa o processo logcat em execução no terminal pressionando Ctrl + C (ou Cmd + C no Mac).
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 logs relevantes e os compilar 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. Para executá-los, siga as etapas abaixo no diretório raiz do projeto:

Acesse o ID do seu dispositivo móvel:

adb devices -l

List of devices attached
device-id device

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)

Reproduza o problema.
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 a todos os relatórios de bugs que você encontrar.

Registros de dispositivos do hub de transmissão

Para conferir os registros de dispositivo do seu hub do Google, faça o seguinte:

Configurar o Android Debug Bridge.
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 de 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.
- No GHA do smartphone:
  1. Toque no dispositivo para abrir a página de detalhes.
  2. Toque no ícone de 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.
Em um computador na mesma rede Wi-Fi do dispositivo:
```
  adb connect ip-address
  adb logcat
```
Para fornecer registros a alguém, execute a operação que está com falha e canalize a saída para um arquivo de texto:
```
  adb logcat -d > platform-logs.txt
```

Automações

Detecção de borda

As automações no ecossistema do Google Home têm a detecção de borda, que é uma lógica que garante que um ativador só seja ativado quando houver uma mudança de estado real, em vez de uma atualização de estado que apenas repete o estado anterior do dispositivo.

Por exemplo, se acender uma luz é um início, a detecção de bordas garante que o início só seja ativado se o dispositivo de luz passar de desligado para ligado, em vez 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:

Verifique se cada dispositivo está funcionando corretamente, independente da automação.
Analise o gráfico de automação e compare-o com o DSL de automação para revelar suposições incorretas.
Observe o estado do dispositivo no app Google Home durante a execução da automação.
Verifique se todos os dispositivos referenciados pela automação estão presentes na estrutura em que você espera que eles estejam. A exclusão de um dispositivo que depende de uma automação pode ter consequências inesperadas. 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. Pode ser necessário adicionar mais lógica para garantir que uma mudança de estado seja capturada apenas uma vez 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ó e aos traits que você está referenciando.

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

Se a criação de automação não passar na validação, uma mensagem de aviso ou de 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 isso:

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

Extraia o ID da automação dos 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 vários IDs de automação precisarem ser excluídos, use o pager do terminal para controlar a saída:

adb logcat -s GhpNative level:debug | less

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 recurso não está registrado

Se a API Discovery registrar um aviso para Trait not found, isso significa que ela está tentando usar o atributo para candidatos da Discovery, mas não vai conseguir porque o atributo não foi registrado 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 atributo é home.matter.6006.clusters.fc43, que corresponde a RelativeHumidityControl. Para determinar o nome do atributo de um ID, consulte o Índice de atributos.

Neste exemplo, RelativeHumidityControl precisa ser registrado durante a inicialização do app. Consulte Registrar atributos para adicionar o atributo ao registro.

OAuth

Se você já tiver 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.

O registro de Google Home Developer Console não é necessário para testar e usar as APIs Home. No entanto, você ainda vai precisar de um registro Developer Console aprovado para publicar o 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 existente. Para saber como adicionar usuários de teste, consulte Configurar a tela de consentimento OAuth. Independentemente da verificação do OAuth, há um limite de 100 usuários imposto pelas APIs Home que podem conceder permissões ao seu app. Essa limitação é suspensa após a conclusão do registro de Developer Console.
ODeveloper Console registration precisa ser enviado para aprovação quando você estiver pronto para restringir as permissões de tipo de dispositivo por meio do OAuth para preparar a atualização do app com as APIs Home.

Importante:o Google Home Developer Console ainda não está disponível para registro.

Para apps Google Cloud que ainda estão com a verificação OAuth pendente, os usuários não podem concluir o fluxo 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.

API Initialization and Permissions

API de comissionamento