1. Prima di iniziare
Matter offre agli utenti finali un'esperienza di configurazione e controllo dei dispositivi multipiattaforma senza interruzioni. Ciò è possibile principalmente grazie ai molteplici componenti dell'ecosistema che operano in sinergia dietro le quinte. Sistemi di risoluzione dei problemi come questi possono spesso essere scoraggianti per 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 ognuno di questi sistemi, Google fornisce agli sviluppatori una serie di analisi dei problemi, raccolte da telefoni e hub:
In qualità di sviluppatore, è fondamentale che tu sia in grado di ridurre i problemi riscontrati durante il ciclo di sviluppo del dispositivo. Una volta lanciato il progetto, devi monitorare le tendenze dei problemi per i dispositivi sul campo in modo aggregato e risolverle tramite aggiornamenti software. Questo codelab illustra le tecniche che puoi utilizzare per entrambi gli scopi.
Prerequisiti
- Completa la guida Inizia a utilizzare Matter con un progetto Matter funzionante e la configurazione del dispositivo
- Disporre di uno smartphone Android da connettere alla 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 classificare gli errori mediante l'accesso ai log degli errori e la raccolta di 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 del rendimento è 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 usare questi strumenti per misurare il rendimento del tuo progetto.
Accedi alle metriche di progetto
- Il primo passaggio per accedere ai dati consiste nel controllare le dashboard di Google Home, accedendo alla console Google Cloud e andando a Operazioni > Monitoraggio > Dashboard.
Sono disponibili diverse dashboard per il tuo progetto (inclusi altri prodotti Google Cloud). Le dashboard fornite per la smart home hanno un prefisso di dati e analisi di Google Home.
Attualmente disponiamo di una dashboard generale che copre l'intero progetto, nonché di dashboard per integrazioni specifiche (cloud, locali, Matter) o tipi di dispositivi (videocamere). Queste dashboard contengono dati solo se disponi di un'integrazione del tipo corrispondente, insieme a un progetto funzionante che soddisfa le richieste.
Quando apri una di queste dashboard, viene visualizzata una serie di grafici simili ai seguenti:
Le dashboard di Google Home contengono vari grafici che mostrano i dettagli degli eventi associati al progetto. Con ogni dashboard di integrazione, vedrai un grafico che mostra il numero totale di richieste gestite dal tuo progetto, un grafico che mostra la percentuale di successo per quel tipo di integrazione e diversi grafici che mostrano i tipi e i trait di dispositivi coinvolti. Inoltre, con Matter hai a disposizione una serie di grafici che tracciano il successo della messa in servizio e le implementazioni degli aggiornamenti sui tuoi dispositivi.
Tieni presente che la vista predefinita con i grafici presenti nelle dashboard di analisi di Google Home è solo una vista che abbiamo creato per il tuo progetto utilizzando i dati delle metriche della smart home. Puoi anche utilizzare Esplora metriche per creare i tuoi grafici in base alle stesse metriche di base e salvarli nelle dashboard personalizzate.
Accedere ai log degli errori
Esplora log è una raccolta di strumenti che puoi utilizzare con i log eventi generati in un progetto. Puoi accedervi nella console Google Cloud andando su Operazioni > Logging > Esplora log.
Una volta aperto Esplora log, ottieni una visualizzazione simile alla seguente:
La finestra Explorer 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 tuo progetto, inclusi quelli generati al di fuori della smart home. Ecco perché è fondamentale utilizzare questi log filtrando gli eventi di cui vuoi eseguire il debug. Approfondiremo questo aspetto nelle sezioni di debug.
3. Debug dei problemi di messa in servizio
Il primo tipo di metrica che esamineremo riguarda gli eventi di messa in servizio di Matter. Per messa in servizio si intende l'insieme di passaggi necessari a un utente per 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 saperne 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 individuando in quale fase possono 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 del 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 un errore si verifica in uno di questi stati, viene acquisito anche nel grafico di analisi 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 > Logging > Esplora log. Per filtrare gli errori di commissione, puoi cercare "clientUpdateLog" abbinato 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 di messa in servizio e a un codice di stato, un log degli errori contiene i timestamp relativi all'errore acquisito e l'ID prodotto Matter che ti consente di identificare i prodotti che hanno causato l'errore. Il set di log generati dallo stesso tentativo di messa in servizio condivide un sessionId.
L'utilizzo delle metriche di Google Home Analytics ti dà un'idea iniziale della fase in cui potrebbe verificarsi il problema. Per trovare la causa principale degli errori di messa in servizio del dispositivo, a volte potresti dover eseguire ulteriori debug utilizzando i log generati dal dispositivo mobile utilizzato durante la procedura di messa in servizio. Per farlo, è necessario 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 di Android Debug Bridge (ADB). Poiché la messa in servizio avviene 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 strumenti della piattaforma
ADB fa parte degli strumenti della piattaforma SDK Android, che possono essere installati con Android Studio o tramite lo strumento a riga di comando sdkmanager.
Dopo aver installato correttamente gli strumenti della piattaforma nel sistema, verifica ADB controllando il numero di versione sul terminale con il seguente comando:
$ adb -- version
Dovrebbe essere visualizzato il numero di versione dell'utilità ADB installata, senza errori.
Attiva debug USB
Ora attiva il debug USB sul tuo dispositivo Android.
Innanzitutto, segui i passaggi per attivare le Opzioni sviluppatore sul 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
- Esegui il server ADB con il seguente comando:
$ adb start-server
- Collega lo smartphone al computer su cui è installato il server ADB.
Sul telefono potrebbe essere visualizzato un messaggio di avviso relativo al debug USB, che ti chiede se desideri consentire al tuo computer di accedere alle informazioni del tuo telefono.
- Se viene visualizzato questo messaggio di avviso, fai clic su Consenti.
- 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
Il tuo <phone-id> è una stringa alfanumerica che identifica in modo univoco il dispositivo.
- 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 controllare la versione di Google Play Services:
$ adb -s <phone-id> shell dumpsys package com.google.android.gms | grep "versionName"
- Per verificare se disponi dei moduli di controllo della home page o di 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 di reso siano supportati dal nostro ecosistema. Quando richiedi assistenza in caso di errori di messa in servizio, includi sempre le informazioni sul sistema nei ticket di assistenza.
Raccolta dei log degli errori
Avvia il processo di raccolta dei log, quindi svolgi i passaggi della messa in servizio per generare gli eventi di errore di cui vuoi eseguire il debug.
- Esegui il comando seguente fornendo il tuo
<phone-id>, nonché un<file-name>in cui i log verranno salvati nel tuo computer (ad esempio:debug_file.txt).
$ adb -s <phone-id> logcat > <file-name>
In questo modo il processo di logging viene avviato immediatamente. 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.
- Una volta visualizzato l'errore di cui vuoi eseguire il debug, interrompi la registrazione premendo
Control+Cnella finestra del terminale in esecuzione.
Ora i log dovrebbero essere archiviati nel file di logging <file-name>. Poiché questo processo registra i log di ogni processo in esecuzione monitorato nel dispositivo, il file conterrà molti log. Ecco perché dovresti sempre utilizzare questi log cercando le voci che ti servono.
Analizzare i log degli errori
I processi di messa in servizio sono gestiti attraverso un sottosistema chiamato MatterCommissioner all'interno di GHA.
- 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>
Questo genera un output contenente gli eventi del processo di messa in servizio.
- Se il tuo dispositivo Matter utilizza Thread, puoi anche cercare gli errori generati dal sottosistema Thread con il seguente comando:
$ grep -E "(ThreadNetworkManager|BorderAgentScannerImpl|ThreadBrSynchronizer)" <file-name>
Quando analizzi il file di log generato dal processo di debug ADB, cerca anche determinati pattern. Molti errori di messa in servizio includono "commissioning failure" nel suo messaggio di errore.
- Cerca un messaggio di errore di messa in servizio con il seguente comando:
$ grep "SetupDevice" $phonelog | grep -A 20 "Commissioning failed"
4. Esegui il debug dei problemi di controllo dei dispositivi
Dopo aver configurato e messo in servizio i dispositivi Matter nell'ecosistema Google Home, gli utenti possono impartire comandi vocali usando l'Assistente Google (ad esempio "Hey Google, accendi le luci nel salotto") oppure utilizzando la UI dell'app Home o i display Google Nest.
Poiché le specifiche di controllo tra i dispositivi finali e gli Hub Google sono mediate da Matter, si prevede che ci saranno meno errori sul lato del controllo dei dispositivi. Indipendentemente da ciò, forniamo metriche e log per consentirti di eseguire anche il debug di questi tipi di problemi.
Utilizzare le metriche
Nella dashboard di integrazione Matter vedrai diverse metriche relative al controllo dei dispositivi. Esistono tre grafici fondamentali per valutare le prestazioni dei dispositivi sul campo:
Durante i problemi di controllo, solitamente si notano tendenze diminuite nella percentuale di successo e una tendenza al rialzo nel grafico di analisi degli errori. Il grafico di analisi degli errori mostra gli errori rilevati da Google Nest Hub riguardo al motivo per cui il tentativo di controllo del dispositivo non è riuscito.
Utilizza i log
Per ogni problema relativo al controllo dei dispositivi Matter viene generato anche un log di errore nel sistema. Questi errori possono essere filtrati da Esplora log cercando "executionLog".
I log degli errori del controllo del dispositivo Matter hanno il seguente aspetto:
{
"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. Esegui il debug di altre funzionalità
Finora hai imparato a gestire i problemi di messa in servizio e controllo 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 per gli 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 sul campo.
Dopo aver eseguito un aggiornamento dalla console, tieni d'occhio le seguenti metriche:
Vedrai che nei giorni successivi al rilascio, sempre più dispositivi sul campo riceveranno la nuova versione software associata alla release software OTA.
6. Richiedi assistenza
Google fornisce strumenti e documentazione per eseguire il debug dei problemi relativi a Matter, ma poiché l'ecosistema Matter è nuovo, ci saranno dei problemi che queste risorse non trattano. In questi casi, puoi sempre contattare noi o la community per richiedere assistenza.
Visita i canali per gli sviluppatori
Google prevede tre canali per sviluppatori attivamente monitorati:
Sebbene ciascuno di questi canali sia monitorato dallo stesso team periodicamente, esistono alcune differenze fondamentali in merito a quando utilizzare quale opzione.
- Stack Overflow: puoi contattare noi e la community di sviluppatori per la smart home per domande sull'implementazione o per ricevere assistenza. Questo canale è ideale per chiedere come risolvere i problemi o implementare una determinata funzionalità.
- Issue Tracker:si tratta del sistema di monitoraggio dei problemi ufficiale gestito da Google, in cui i segmenti di pubblico esterni possono segnalare errori relativi all'ecosistema. Fornisce strumenti web per allegare file e condividere informazioni sensibili quando necessario. Utilizzare Issue Tracker è l'ideale per segnalare problemi dell'ecosistema o condividere richieste di funzionalità.
- Forum per gli sviluppatori:per ottenere aiuto dall'Assistenza Google ufficiale e dagli esperti della community, puoi rivolgerti al Nest Developer Forum. Questo forum è ideale per \ ottenere una guida ufficiale per lo sviluppo.
Iscriviti alla newsletter per gli sviluppatori
Oltre a visitare i canali degli sviluppatori per le domande, pubblichiamo anche una newsletter trimestrale che evidenzia le nuove funzionalità e fornisce le notizie sullo stato dell'ecosistema della smart home di Google.
Puoi utilizzare il modulo di registrazione per ricevere la newsletter per gli sviluppatori.
7. Complimenti
Complimenti! Hai imparato a eseguire il debug delle integrazioni di Matter utilizzando gli strumenti e le tecniche che ti consigliamo. Ti auguriamo un buon proseguimento con le integrazioni Matter con Google Home.
Passaggi successivi
Prova i seguenti esercizi ed esplora risorse aggiuntive:
- Oltre a utilizzare dati e analisi per risolvere i problemi, puoi anche utilizzare la Test Suite per testare l'integrazione su eventuali problemi potenziali.
- Quando l'integrazione è pronta per essere condivisa con il mondo, il passo successivo è ottenere la certificazione FCGH per il tuo progetto. Per farlo, puoi seguire i passaggi nella pagina Certificazione.