Risoluzione dei problemi

App di esempio

Se riscontri problemi durante l'utilizzo delle API Home, puoi raccogliere i log per ulteriori operazioni di debug. La raccolta dei log dal dispositivo mobile richiede Android Debug Bridge (adb). Se hai bisogno dell'assistenza di Google, raccogli i log sia dai dispositivi Android sia dall'hub e apri un ticket nel tracker dei problemi con le informazioni e i log pertinenti associati.

Raccogliere i log di Android

Il dispositivo mobile deve essere connesso alla macchina locale per tutti i passaggi che coinvolgono adb.

Installare adb

Se non l'hai ancora fatto, configura Android Debug Bridge sulla tua macchina locale:

  1. Installa "adb" sul computer.
  2. Attiva le Opzioni sviluppatore e il debug USB sullo smartphone Android.

Plugin Google Home per Android Studio

Google Home Plugin for Android Studio è uno strumento utile per raccogliere e analizzare i log ed è stato creato appositamente per gli sviluppatori Google Home platform. Questo plug-in ti consente di accedere a Google Assistant Simulator, Cloud Logging e altri strumenti per semplificare il processo di sviluppo di smart home.

Utilizza questo strumento insieme a adb per analizzare ulteriormente Matter i log del dispositivo.

Per saperne di più e scaricare lo strumento, visita Google Home Plugin for Android Studio.

Informazioni sulla versione

Ti consigliamo di raccogliere tutte le informazioni sulla versione relative alla configurazione ogni volta che decidi di raccogliere i log. Questa operazione è necessaria se devi condividere problemi con Google.

  1. Recupera l'ID del tuo dispositivo mobile: 
    adb devices
     
    List of devices attached
device-id    device
  2. Memorizza questo valore in una variabile denominata phoneid: 
    phoneid=device-id
  3. Salva varie informazioni sul dispositivo nelle variabili: 
    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. Salva tutte le variabili in un file denominato _versions.txt:

    Espandi per mostrare i comandi per salvare le variabili in un file

    L'intero blocco può essere copiato e incollato in un terminale contemporaneamente.

    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. Verifica i contenuti di _versions.txt: 
    cat _versions.txt

    Espandi per mostrare l'output del file di esempio

    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):
    Ora questo file può essere fornito a Google in caso di necessità per la risoluzione dei problemi.

Raccogliere i log

Per raccogliere i log, chiudi tutte le app in esecuzione sul dispositivo mobile. Quindi:

  1. Apri una finestra del terminale e cancella i log del dispositivo esistenti: 
    adb logcat -b all -c
  2. Avvia la procedura di raccolta dei log: 
    adb logcat >> _logs.txt
     Lascia aperto questo terminale. Verranno raccolti i log dal tuo dispositivo finché la procedura è in esecuzione.
  3. Esegui l'app di esempio e acquisisci tutte le azioni dell'interfaccia utente. Al termine, interrompi il processo logcat in esecuzione sul terminale premendo Ctrl+C (o Cmd+C su Mac).
  4. I log di questa sessione vengono salvati in un file denominato _logs.txt.

Puoi analizzare le informazioni contenute in questo file in vari modi, ad esempio cercando parole chiave come error, exception o crash.

Script di log

Per comodità, l'app di esempio fornisce script per ottenere i log pertinenti e li compila in un file di testo. Per fornire la migliore esperienza di debug, questi log devono essere allegati a eventuali bug segnalati per facilitare l'analisi della causa principale da parte di Google.

Questi log si trovano nella directory scripts nell'albero delle origini dell'app di esempio. Esegui i seguenti passaggi dalla directory principale del progetto:

  1. Recupera l'ID del tuo dispositivo mobile: 
    adb devices -l
     
    List of devices attached
device-id device
  2. Esegui lo 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. Riproduci il problema.
  4. Premi CTRL+C per interrompere lo script.

Lo script genererà un file di log con timestamp contenente tutte le informazioni pertinenti. Allega questi dati a eventuali segnalazioni di bug che riscontri.

Log del dispositivo hub di trasmissione

Puoi visualizzare i log del dispositivo per Google Nest Hub utilizzando questo metodo, che è supportato per i seguenti modelli:

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

Per attivare un hub Cast per il recupero dei log locali:

  1. Configura Android Debug Bridge.

  2. Ottieni l'indirizzo IP dell'hub:

    • Dall'hub, se ha uno schermo:
      1. Scorri verso il basso dalla parte superiore dello schermo.
      2. Tocca l'icona Impostazioni .
      3. Trova l'indirizzo IP del dispositivo: su Nest Hub (2nd gen), vai a Informazioni sul dispositivo > Informazioni tecniche > Indirizzo IP
    • Da GHA sullo smartphone:
      1. Tocca il dispositivo per visualizzare la pagina dei dettagli
      2. Tocca l'icona Impostazioni per visualizzare la pagina delle impostazioni.
      3. Trova l'indirizzo IP del dispositivo: vai a Informazioni sul dispositivo > Informazioni tecniche > Indirizzo IP

  3. Su un computer connesso alla stessa rete Wi-Fi del dispositivo: 

      adb connect ip-address
  adb logcat

  4. Per fornire i log a qualcuno, esegui l'operazione che non va a buon fine e reindirizza l'output a un file di testo: 

      adb logcat -d > platform-logs.txt

Automazioni

Rilevamento dei bordi

Le automazioni nell'ecosistema Google Home sono dotate di rilevamento dei bordi, ovvero una logica che verifica che un comando iniziale si attivi solo quando si verifica un'effettiva modifica dello stato, anziché un aggiornamento dello stato che ripete semplicemente lo stato precedente del dispositivo.

Ad esempio, se l'accensione di una luce è un punto di partenza, il rilevamento dei bordi verifica che il punto di partenza si attivi solo se la luce passa da spenta ad accesa, non da accesa ad accesa (nessuna modifica).

L'automazione non si comporta come previsto

Dopo aver tenuto conto del rilevamento dei bordi, se un'automazione non si comporta come previsto:

  1. Controlla ogni dispositivo per assicurarti che funzioni correttamente indipendentemente dall'automazione.

  2. Dai un'occhiata al grafico dell'automazione, confrontandolo con il DSL dell'automazione, per rivelare eventuali ipotesi potenzialmente errate da parte tua.

  3. Osserva lo stato del dispositivo nell'app Google Home durante l'esecuzione dell'automazione.

  4. Controlla che tutti i dispositivi a cui fa riferimento l'automazione siano presenti nella struttura in cui ti aspetti che si trovino. L'eliminazione di un dispositivo da cui dipende un'automazione può avere conseguenze indesiderate. Consulta Impatto dell'eliminazione del dispositivo sulle automazioni.

L'automazione viene eseguita quando non dovrebbe

Se l'automazione viene eseguita quando non dovrebbe, esamina i criteri del comando iniziale. Potrebbe essere necessario aggiungere una logica aggiuntiva per assicurarsi che una modifica dello stato venga acquisita una sola volta e attivi l'automazione una sola volta.

L'automazione non viene compilata

Assicurati che la tua app contenga tutte le importazioni necessarie, inclusa ogni classe corrispondente ai diversi tipi di nodi, nonché i tratti a cui fai riferimento.

La creazione dell'automazione non supera la convalida

Se la creazione dell'automazione non supera la convalida, un messaggio di avviso o di errore fornisce informazioni sul problema. Per saperne di più, consulta il riferimento ValidationIssueType.

La funzione List genera eccezioni

Quando chiami la funzione List dell'API Automation, i gestori di lettura potrebbero generare eccezioni a causa della mancanza di funzionalità API. Per risolvere il problema, elimina l'automazione interessata.

Per:

  1. Verifica che adb sia installato. Consulta Installare adb.

  2. Recupera l'ID dell'automazione dai log di Android richiamando:

    adb logcat -s GhpNative

    Log di esempio:

    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 è necessario eliminare più ID automazione, puoi utilizzare il pager del terminale per controllare l'output:

    adb logcat -s GhpNative level:debug | less

  3. Elimina l'automazione utilizzando il relativo ID:

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

L'API Discovery registra un avviso quando una caratteristica viene annullata

Se l'API Discovery registra un avviso per Trait not found, significa che l'API sta tentando di utilizzare il tratto per i candidati di Discovery, ma non riuscirà perché il tratto non è stato registrato durante l'inizializzazione. Ad esempio:

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

L'identificatore del tratto è home.matter.6006.clusters.fc43, che corrisponde a RelativeHumidityControl. Per determinare il nome del tratto da un ID, consulta l'indice dei tratti.

Da questo esempio, RelativeHumidityControl deve essere registrato durante l'inizializzazione dell'app. Consulta la sezione Registrazione delle caratteristiche per aggiungere la tua caratteristica al registro.

OAuth

Se hai un client OAuth esistente

Se hai già un client OAuth verificato per un'app pubblicata, puoi utilizzare il client OAuth esistente per testare le API per la casa.

La registrazione Google Home Developer Console non è necessaria per testare e utilizzare le API Home. Tuttavia, per pubblicare la tua app avrai comunque bisogno di una registrazione Developer Console approvata, anche se hai un client OAuth verificato da un'altra integrazione.

Si applicano le seguenti considerazioni:

  • Esiste un limite di 100 utenti quando si utilizza un client OAuth esistente. Per informazioni sull'aggiunta di utenti di test, consulta la sezione Configura la schermata per il consenso OAuth. Indipendentemente dalla verifica OAuth, le API Home impongono un limite di 100 utenti che possono concedere autorizzazioni alla tua applicazione. Questa limitazione viene rimossa al termine della registrazione di Developer Console.

  • La registrazioneDeveloper Console deve essere inviata per l'approvazione quando sei pronto a limitare le concessioni di tipo di dispositivo tramite OAuth in preparazione dell'aggiornamento dell'app con le API Home.

Per le app Google Cloud per cui la verifica OAuth è ancora in attesa, gli utenti non possono completare il flusso OAuth finché la verifica non è completata. I tentativi di concedere le autorizzazioni non andranno a buon fine e verrà visualizzato il seguente errore:

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