Debug delle integrazioni di Matter

1. Prima di iniziare

Matter offre agli utenti finali un'esperienza di configurazione e controllo dei dispositivi fluida e multipiattaforma. Ciò è possibile principalmente grazie ai vari componenti dell'ecosistema che lavorano insieme dietro le quinte. La risoluzione dei problemi di sistemi come questi può spesso scoraggiare i nuovi sviluppatori, quindi abbiamo sviluppato una serie di strumenti e tecniche per semplificare la vita degli sviluppatori Matter con Google Home.

I tre componenti principali di Matter sono trattati in questo codelab. Per ciascuno di questi sistemi, Google fornisce agli sviluppatori un insieme di dati e analisi per la risoluzione dei problemi raccolti da smartphone e hub:

In qualità di sviluppatore, è fondamentale per te essere in grado di mitigare i problemi riscontrati durante il ciclo di sviluppo del dispositivo. Dopo aver lanciato il progetto, devi monitorare le tendenze relative ai problemi dei dispositivi sul campo in modo aggregato e risolverli tramite gli aggiornamenti software. Questo codelab illustra le tecniche che puoi utilizzare per entrambi gli scopi.

Prerequisiti

• Completa la guida Iniziare a utilizzare Matter con un progetto Matter funzionante e la configurazione del dispositivo
• Avere uno smartphone Android che puoi collegare alla tua workstation (per i log ADB)

Cosa imparerai a fare

• Come utilizzare gli strumenti di analisi per la smart home per monitorare i problemi di Matter su larga scala.
• Come eseguire la triage degli errori accedendo ai log degli errori e raccogliendo informazioni.
• Come accedere alla documentazione e alle risorse di assistenza di Matter per chiedere aiuto.

2. Visualizzare i dati e le analisi di Google Home

Il monitoraggio delle prestazioni è fondamentale per un'integrazione efficace con l'ecosistema Google Home. Mettiamo a disposizione degli sviluppatori di smart home una serie di strumenti di monitoraggio sulla piattaforma Google Cloud. Puoi utilizzare questi strumenti per misurare il rendimento del tuo progetto.

Accedere alle metriche del progetto

• Il primo passaggio per accedere ai dati è controllare le dashboard di Google Home, accedendo alla console Google Cloud e andando a Operazioni > Monitoraggio > Dashboard.

Per il tuo progetto sono disponibili diverse dashboard (inclusi altri prodotti Google Cloud). Le dashboard fornite per la smart home hanno un prefisso di Google Home Analytics.

Al momento abbiamo una dashboard generale che copre l'intero progetto, oltre a dashboard per integrazioni specifiche (Cloud, locale, Matter) o tipi di dispositivi (videocamere). Queste dashboard contengono dati solo se hai un'integrazione del tipo corrispondente e un progetto funzionante che soddisfa le richieste.

Quando apri una di queste dashboard, viene visualizzata una serie di grafici come il seguente:

Le dashboard di Google Home contengono vari grafici che mostrano i dettagli degli eventi associati al progetto. In ogni dashboard di integrazione viene visualizzato un grafico che mostra il numero totale di richieste gestite dal progetto, un grafico che mostra il tasso di successo per quel tipo di integrazione e diversi grafici che mostrano i tipi di dispositivi e le caratteristiche coinvolti. Inoltre, con Matter hai a disposizione una serie di grafici che monitorano l'esito della messa in servizio, nonché l'implementazione degli aggiornamenti sui tuoi dispositivi.

Tieni presente che la visualizzazione predefinita con i grafici visualizzati nelle dashboard di Google Home Analytics è solo una visualizzazione che abbiamo creato per il tuo progetto utilizzando i dati delle metriche per la smart home. Puoi anche utilizzare Esplora metriche per creare i tuoi grafici in base alle stesse metriche di base e salvarli nelle dashboard personalizzate.

Accedi ai log degli errori

Logs Explorer è una raccolta di strumenti per lavorare con i log eventi generati in un progetto. Puoi accedervi nella console Google Cloud andando a Operazioni > Logging > Esplora log.

Una volta aperto Esplora log, viene visualizzata una visualizzazione simile alla seguente:

La finestra di Esplora contiene vari strumenti per visualizzare, filtrare, eseguire query e analizzare i log. Per impostazione predefinita, questa visualizzazione mostra i log generati da tutti i sistemi disponibili per il progetto, inclusi quelli generati al di fuori di Smart Home. Ecco perché è fondamentale utilizzare questi log filtrando gli eventi di cui vuoi eseguire il debug. Ne parleremo più nelle sezioni di debug.

3. Eseguire il debug dei problemi di messa in servizio

Il primo tipo di metrica che esamineremo riguarda gli eventi di messa in servizio Matter. La messa in servizio si riferisce all'insieme di passaggi necessari per consentire a un utente di configurare un dispositivo Matter per la prima volta.

Durante la messa in servizio del dispositivo, ha luogo una serie di interazioni tra il dispositivo Matter, l'app Google Home e il tessuto Matter. L'immagine seguente mostra alcuni di questi eventi:

Per scoprire di più su ciascuno di questi passaggi, puoi consultare la pagina relativa alle commissioni di Matter Primer. In questa sezione illustreremo gli strumenti e le tecniche per eseguire il debug dei problemi di messa in servizio.

Utilizzare Google Home Analytics

Abbiamo creato un insieme di metriche per consentirti di esaminare i problemi di messa in servizio monitorando gli eventi e comprendendo in quale fase potrebbero verificarsi gli errori. Le puoi trovare nella dashboard di integrazione di Matter, come abbiamo visto nella sezione precedente.

I grafici in questa dashboard forniscono dati sulla messa in servizio dei dispositivi:

Il grafico sul conteggio dei dispositivi mostra il numero di tentativi di messa in servizio da parte degli utenti in una determinata data. La percentuale di successo indica la percentuale di successo percepita di questi eventi lato Google. Ogni tentativo di messa in servizio genera una serie di eventi con stati associati. Quando si verifica un errore in uno di questi stati, viene rilevato anche nel grafico di distribuzione degli errori.

Stati in cui è in servizio:

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

Per visualizzare una versione dettagliata di questi eventi, vai a Operazioni > Log > Esplora log. Per filtrare gli errori di commissione, puoi cercare "clientUpdateLog" associato a "severity>=ERROR" nel campo della query.

Un log degli errori di messa in servizio per Matter ha il seguente aspetto:

{
  "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"
}

Oltre allo stato della messa in servizio e a un codice di stato, un log degli errori contiene i timestamp dell'errore rilevato, nonché l'ID prodotto Matter che ti consente di identificare quale dei tuoi prodotti ha causato l'errore. L'insieme di log generati dallo stesso tentativo di messa in servizio condivide un sessionId.

L'utilizzo delle metriche di Google Home Analytics ti offre un'idea iniziale di quale potrebbe essere la fase in cui si verifica il problema. Per trovare la causa principale degli errori di messa in servizio del dispositivo, a volte potrebbe essere necessario eseguire un ulteriore debug utilizzando i log generati dal dispositivo mobile utilizzato nella procedura di messa in servizio. Per questi, hai bisogno di Android Debug Bridge.

Utilizzare Android Debug Bridge (ADB)

Un altro modo per risolvere i problemi di messa in servizio è utilizzare lo strumento a riga di comando Android Debug Bridge (ADB). Poiché la messa in servizio viene gestita principalmente tra il dispositivo mobile e il dispositivo Matter, è possibile utilizzare lo strumento ADB per accedere ai log generati dall'app Google Home durante la messa in servizio.

Installa gli strumenti della piattaforma

ADB è incluso in Android SDK Platform Tools, che può essere installato con Android Studio o tramite lo strumento a riga di comando sdkmanager.

Dopo aver installato correttamente gli strumenti della piattaforma sul sistema, verifica ADB controllando il numero di versione dal terminale con il seguente comando:

$ adb -- version

Dovrebbe essere visualizzato il numero di versione dell'utilità ADB installata senza errori.

Attivare il debug USB

A questo punto, devi attivare il debug USB sul tuo dispositivo Android.

Innanzitutto, segui i passaggi per attivare le opzioni sviluppatore sul tuo dispositivo, quindi attiva il debug USB.

Ciò consente ad ADB di accedere ai log generati dalle app attualmente in esecuzione sul dispositivo.

Recuperare l'ID dispositivo

1. Esegui il server ADB con il seguente comando:

$ adb start-server

2. Collega lo smartphone al computer su cui è in esecuzione il server ADB.

Sullo smartphone potresti visualizzare un messaggio di avviso relativo al debug USB che ti chiede se vuoi consentire al computer di accedere alle informazioni dello smartphone:

3. Se ricevi questo messaggio di avviso, fai clic su Consenti.
4. Esegui un comando per elencare i dispositivi dal terminale per verificare se il computer può accedere al telefono tramite ADB, utilizzando questo comando:

$ adb devices

Dovrebbe essere visualizzata una risposta simile alla seguente:

List of devices attached
<phone-id>    device

<phone-id> è una stringa alfanumerica che identifica in modo univoco il tuo dispositivo.

5. Ricorda il valore <phone-id> da utilizzare nei passaggi successivi.

Raccogli informazioni sul sistema

Il prossimo passaggio consiste nel controllare le informazioni sulla versione delle app e del sistema presenti sul dispositivo.

• Per controllare la versione del sistema operativo Android:

$ adb -s <phone-id> shell getprop ro.build.version.release

• Per controllare la versione dell'app Google Home:

$ adb -s <phone-id> shell dumpsys package com.google.android.apps.chromecast.app | grep versionName

• Per verificare la versione di Google Play Services:

$ adb -s <phone-id> shell dumpsys package com.google.android.gms | grep "versionName"

• Per verificare se hai i moduli di controllo Home/Matter tramite Play Services:

$ adb -s <phone-id> shell dumpsys activity provider com.google.android.gms.chimera.container.GmsModuleProvider | grep "com.google.android.gms.home"

Assicurati che questi valori restituiti siano supportati dal nostro ecosistema. Quando richiedi assistenza per errori di messa in servizio, includi sempre le informazioni di sistema nei ticket di assistenza.

Raccogliere i log degli errori

Quindi, avvia la procedura di raccolta dei log, poi segui i passaggi di messa in servizio per generare gli eventi di errore che vuoi eseguire il debug.

1. Esegui questo comando fornendo il <phone-id>, nonché un <file-name> in cui i log verranno salvati nel tuo computer (ad es. debug_file.txt).

$ adb -s <phone-id> logcat > <file-name>

Viene avviata immediatamente la procedura di registrazione. Se non esiste già, viene creato un file con il nome fornito e i log dello smartphone vengono aggiunti al file dopo ogni evento.

Puoi procedere con la procedura di messa in servizio con il tuo dispositivo Matter.

2. Una volta raggiunto l'errore che vuoi eseguire il debug, interrompi la registrazione premendo Control+C nella finestra del terminale in esecuzione.

I log ora dovrebbero essere archiviati nel file di log <file-name>. Poiché questo processo registra i log di ogni processo in esecuzione monitorato nel dispositivo, questo file conterrà molti log. Ecco perché devi sempre utilizzare questi log cercando le voci di cui hai bisogno.

Analizzare i log degli errori

I processi di messa in servizio sono gestiti attraverso un sottosistema chiamato MatterCommissioner all'interno di GHA.

1. Seguendo la strategia principale utilizzata per analizzare gli errori di messa in servizio, cerca gli errori generati dal sottosistema MatterCommissioner con il seguente comando:

$ grep "MatterCommissioner" <file-name>

Viene generato un output contenente gli eventi della procedura di messa in servizio.

2. Se il tuo dispositivo Matter utilizza Thread, puoi anche cercare gli errori generati dal sottosistema Thread tramite il seguente comando:

$ grep -E "(ThreadNetworkManager|BorderAgentScannerImpl|ThreadBrSynchronizer)" <file-name>

Mentre analizzi il file di log generato dalla procedura di debug ADB, cerca anche determinati pattern. Molti errori di messa in servizio includono la stringa "commissioning failure" nel messaggio.

3. Cerca un messaggio di errore di messa in servizio con il seguente comando:

$ grep "SetupDevice" $phonelog | grep -A 20 "Commissioning failed"

4. Risolvere i problemi di controllo dei dispositivi

Una volta che gli utenti hanno configurato e messo in servizio i dispositivi Matter nell'ecosistema Google Home, possono impartire comandi tramite comandi vocali utilizzando l'Assistente Google (ad esempio, "Hey Google, accendi le luci in soggiorno") o utilizzando l'interfaccia utente nell'app Home o sui display Google Nest.

Poiché la specifica di controllo tra i dispositivi finali e gli hub Google è mediata da Matter, si prevede di avere meno errori sul lato del controllo del dispositivo. Tuttavia, forniamo metriche e log per consentirti di eseguire il debug anche di questi tipi di problemi.

Utilizzare le metriche

Nella dashboard di integrazione Matter vengono visualizzate diverse metriche relative al controllo dei dispositivi. Esistono tre grafici fondamentali per valutare il rendimento dei dispositivi sul campo:

Durante i problemi di controllo, in genere si verificano tendenze al ribasso nella percentuale di successo e una tendenza al rialzo nel grafico di distribuzione degli errori. Il grafico di distribuzione degli errori mostra gli errori rilevati da Google Nest Hub relativi al motivo del fallimento del tentativo di controllo del dispositivo.

Utilizzare i log

Ogni problema di controllo del dispositivo Matter genera anche un log degli errori nel sistema. Questi errori possono essere filtrati da Esplora log cercando "executionLog".

I log degli errori di controllo dei dispositivi Matter sono simili al seguente:

{
  "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"
}

Ogni log degli errori contiene un timestamp, un tipo di dispositivo e una caratteristica, nonché l'errore associato alla richiesta di controllo in statusType. Molti errori di controllo includono anche il externalDebugString, un breve messaggio che spiega il motivo dell'errore.

5. Eseguire il debug di altre funzionalità

Finora hai imparato a gestire i problemi di controllo e messa in servizio dei dispositivi per Matter. Esistono anche altre funzionalità all'interno dell'ecosistema che puoi utilizzare con le nostre tecniche consigliate per garantire un'integrazione di buona qualità.

Monitorare gli aggiornamenti OTA

Per monitorare le release degli aggiornamenti over-the-air (OTA) dei dispositivi Matter rilasciati da Google Home, forniamo un insieme di metriche che mostrano le versioni hardware e software dei dispositivi in uso.

Dopo aver rilasciato un aggiornamento dalla console, tieni d'occhio le seguenti metriche:

Nei giorni successivi al rilascio, sempre più dispositivi sul campo riceveranno la nuova versione software associata al rilascio del software OTA.

6. Richiedere assistenza

Google fornisce strumenti e documentazione per eseguire il debug dei problemi relativi a Matter, ma poiché l'ecosistema Matter è nuovo, ci saranno problemi che queste risorse non coprono. In questi casi, puoi sempre contattarci o rivolgerti alla community per ricevere assistenza.

Visita i canali degli sviluppatori

Google monitora attivamente tre canali per sviluppatori:

Sebbene ciascuno di questi canali venga monitorato dallo stesso team in modo periodico, esistono alcune differenze fondamentali su quando utilizzarne uno.

• Stack Overflow: puoi contattarci e rivolgerti alla community di sviluppatori per la smart home per domande sull'implementazione o per ricevere indicazioni. Questo canale è ideale per chiedere come risolvere i problemi o implementare una determinata funzionalità.
• Issue Tracker: si tratta del sistema di issue tracker ufficiale gestito da Google, in cui i segmenti di pubblico esterni possono segnalare errori nell'ecosistema. Fornisce strumenti web per allegare file e condividere informazioni sensibili, se necessario. Lo strumento Issue Tracker è ideale per segnalare problemi dell'ecosistema o condividere richieste di funzionalità.
• Forum per sviluppatori: per ricevere indicazioni dall'assistenza ufficiale di Google e dagli esperti della community, puoi contattare il forum per sviluppatori Nest. Questo forum è ideale per ricevere indicazioni ufficiali per lo sviluppo.

Iscriviti alla newsletter per gli sviluppatori

Oltre a visitare i canali per sviluppatori per eventuali domande, pubblichiamo anche una newsletter trimestrale che mette in evidenza le nuove funzionalità e fornisce le notizie sullo stato dell'ecosistema Google Smart Home.

Puoi utilizzare il modulo di registrazione per ricevere la newsletter per gli sviluppatori.

7. Complimenti

Complimenti! Hai imparato a eseguire il debug delle integrazioni Matter utilizzando gli strumenti e le tecniche che consigliamo. Ti auguriamo buon lavoro per la creazione di integrazioni Matter con Google Home.

Passaggi successivi

Prova i seguenti esercizi ed esplora risorse aggiuntive:

• Oltre a utilizzare gli strumenti di analisi per risolvere i problemi, puoi anche utilizzare la Test Suite per verificare la presenza di eventuali problemi di integrazione.
• Una volta che l'integrazione è pronta per essere condivisa con il mondo, il passaggio successivo è ottenere la certificazione WWGH per il progetto. Per farlo, puoi seguire i passaggi descritti nella pagina Certificazione.