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 diversi componenti dell'ecosistema, che funzionano in sinergia tra loro dietro le quinte. Risolvere i problemi di sistemi come questi spesso può intimorire i nuovi sviluppatori, quindi abbiamo sviluppato una serie di strumenti e tecniche per semplificarti la vita come sviluppatore Matter con Google Home.
Questo codelab è dedicato ai tre componenti principali di Matter. Per ognuno di questi sistemi, Google fornisce agli sviluppatori una serie di dati e analisi per la risoluzione dei problemi raccolti da telefoni e hub:
In qualità di sviluppatore, è fondamentale per te essere in grado di mitigare i problemi riscontrati durante tutto il ciclo di sviluppo del dispositivo. Una volta avviato il progetto, devi monitorare in modo aggregato le tendenze dei problemi dei dispositivi sul campo e risolverli tramite aggiornamenti software. Questo codelab descrive le tecniche che puoi utilizzare per entrambi gli scopi.
Prerequisiti
- Completare la guida introduttiva all'utilizzo di Matter con un progetto Matter funzionante e la configurazione del dispositivo
- Avere uno smartphone Android da connettere alla tua workstation (per i log ADB)
Cosa imparerai a fare
- Come utilizzare gli strumenti di analisi per la smart home al fine di monitorare i problemi relativi a Matter su larga scala.
- Come classificare gli errori accedendo ai log degli errori e raccogliendo informazioni.
- Come accedere alla documentazione e alle risorse di assistenza di Matter per richiedere assistenza.
2. Visualizza dati e analisi di Google Home
Il monitoraggio delle prestazioni è fondamentale per una corretta integrazione con l'ecosistema Google Home. Forniamo agli 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 tuoi dati è controllare le dashboard di Google Home, accedendo a Google Cloud Console 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 disponiamo di una dashboard generale che copre l'intero progetto, nonché di dashboard per integrazioni specifiche (Cloud, Local, Matter) o per 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 simili ai seguenti:
Le dashboard della home page di Google contengono vari grafici che mostrano i dettagli degli eventi associati al progetto. Con ogni dashboard di integrazione, vedi 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 di dispositivi e i tratti interessati. Matter offre inoltre una serie di grafici che monitorano la riuscita delle operazioni di messa in servizio e l'implementazione degli aggiornamenti sui tuoi dispositivi.
Tieni presente che la vista predefinita con i grafici che vedi nelle dashboard di Analytics per Google Home è solo una vista che abbiamo creato per il tuo progetto utilizzando i dati delle metriche della smart home. Puoi anche utilizzare Metrics Explorer per creare i tuoi grafici dalle stesse metriche sottostanti e salvarli nelle tue dashboard personalizzate.
Accedere ai log degli errori
Esplora log è una raccolta di strumenti per lavorare con i log eventi generati in un progetto. Per accedervi nella console Google Cloud, vai a Operazioni > Logging > Esplora log.
Una volta aperto Esplora log, vedrai una visualizzazione simile alla seguente:
La finestra di esplorazione 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 della smart home. Ecco perché è fondamentale utilizzare questi log filtrando in base agli eventi di cui vuoi eseguire il debug. Approfondiremo questo aspetto nelle sezioni relative al debug.
3. Debug dei problemi di messa in servizio
Il primo tipo di metrica che analizzeremo riguarda gli eventi di messa in servizio 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, avviene una serie di interazioni tra il dispositivo Matter, l'app Google Home e il fabric Matter. La seguente immagine mostra alcuni di questi eventi:
Per saperne di più su ciascuno di questi passaggi, consulta la pagina relativa alla messa in servizio di Matter Primer. In questa sezione tratteremo gli strumenti e le tecniche per eseguire il debug dei problemi di messa in servizio.
Usare Google Home Analytics
Abbiamo creato una serie di metriche per consentirti di esaminare i problemi di messa in servizio monitorando gli eventi e comprendendo in quale fase potrebbero verificarsi gli errori. Sono disponibili nella dashboard di integrazione di Matter, come illustrato nella sezione precedente.
I grafici in questa dashboard forniscono dati sulla messa in servizio del dispositivo:
Il grafico del numero di 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 per questi eventi da parte di 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 registrato anche nel grafico di analisi degli errori.
Stati della messa 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 in base agli 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 dell'errore acquisito, nonché l'ID prodotto Matter, che consente di identificare i prodotti che hanno causato l'errore. L'insieme di log generati dallo stesso tentativo di messa in servizio condivide un valore sessionId.
L'utilizzo delle metriche di Analytics di Google Home ti dà un'idea iniziale in quale fase potrebbe verificarsi il problema. Per trovare la causa principale degli errori di messa in servizio del dispositivo, a volte potresti dover eseguire debug aggiuntivi utilizzando i log generati dal dispositivo mobile utilizzato nella procedura di messa in servizio. Per eseguire queste operazioni, è 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 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 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.
Attiva debug USB
Il passaggio successivo consiste nell'attivare il debug USB sul tuo dispositivo Android.
Innanzitutto segui la procedura per attivare le opzioni sviluppatore sul dispositivo, quindi attiva il debug USB.
In questo modo ADB può accedere ai log generati dalle app attualmente in esecuzione sul dispositivo.
Recupera l'ID dispositivo
- Esegui il server ADB con questo comando:
$ adb start-server
- Collega il telefono al computer su cui è in esecuzione il server ADB.
Sul tuo telefono potrebbe essere visualizzato un messaggio di avviso relativo al debug USB, in cui ti viene chiesto se vuoi consentire al computer di accedere alle informazioni del telefono:
- Se viene visualizzato questo messaggio di avviso, fai clic su Consenti.
- Esegui un comando list devices dal terminale per verificare se il tuo computer può accedere al telefono tramite ADB, utilizzando questo comando:
$ adb devices
Questo dovrebbe dare 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 tuo dispositivo.
- Ricorda il valore
<phone-id>da utilizzare nei passaggi successivi.
Raccogliere informazioni sul sistema
Il passaggio successivo consiste nel controllare le informazioni sulla versione delle app e il sistema sul dispositivo.
- Per verificare 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 sono presenti 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 di reso siano supportati dal nostro ecosistema. Quando contatti l'assistenza in caso di errori di messa in servizio, includi sempre informazioni sul sistema nei ticket di assistenza.
Raccogli i log degli errori
Successivamente, avvia la procedura di raccolta dei log e svolgi i passaggi di messa in servizio per generare gli eventi di errore di cui vuoi eseguire il debug.
- Esegui questo comando fornendo il tuo
<phone-id>e un<file-name>in cui verranno salvati i log sul tuo computer (ad es.debug_file.txt).
$ adb -s <phone-id> logcat > <file-name>
Il processo di logging viene avviato immediatamente. Se non esiste già, viene creato un file con il nome fornito e i registri del telefono vengono aggiunti al file dopo ogni evento.
Procedi con la procedura di messa in servizio del dispositivo Matter.
- Una volta raggiunto l'errore di cui vuoi eseguire il debug, interrompi la registrazione premendo
Control+Cnella finestra del terminale in esecuzione.
I log ora dovrebbero essere archiviati nel file di logging <file-name>. Poiché questo processo registra i log di ogni processo in esecuzione monitorato nel dispositivo, questo file conterrà molti log. Per questo motivo dovresti sempre utilizzare questi log eseguendo ricerche nelle voci necessarie.
Analizzare i log degli errori
I processi di messa in servizio sono gestiti tramite 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 tramite il seguente comando:
$ grep -E "(ThreadNetworkManager|BorderAgentScannerImpl|ThreadBrSynchronizer)" <file-name>
Durante l'analisi del file di log generato dal processo di debug di ADB, cerca anche determinati pattern. Molti errori di messa in servizio includono la stringa "commissioning failure" nel 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 del dispositivo
Dopo che gli utenti hanno configurato e messo in servizio i dispositivi Matter nell'ecosistema Google Home, potranno inviare comandi vocali usando l'Assistente Google (ad esempio "Hey Google, accendi le luci in salotto") oppure utilizzando l'UI 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 che ci saranno meno errori sul lato del controllo dei dispositivi. Indipendentemente da ciò, forniamo anche metriche e log per consentirti di eseguire il debug di questi tipi di problemi.
Utilizzare le metriche
Nella dashboard di integrazione di 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 noti una tendenza negativa 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 relativi al motivo per cui il tentativo di controllo dei dispositivi non è riuscito.
Utilizzare i log
Ogni problema di controllo dei dispositivi 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 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 un trait, nonché l'errore associato alla richiesta di controllo in statusType. Molti errori di controllo includono anche un externalDebugString, un breve messaggio che spiega l'argomento dell'errore.
5. Esegui il debug di altre funzionalità
Finora hai imparato a gestire la messa in servizio dei dispositivi e a controllare i problemi per Matter. L'ecosistema offre anche altre funzionalità a cui puoi utilizzare 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 emessi da Google Home, forniamo un insieme di metriche che mostrano le versioni hardware e software dei dispositivi sul campo.
Dopo aver inviato un aggiornamento dalla console, tieni d'occhio le seguenti metriche:
Noterai che nei giorni successivi al rilascio, sempre più dispositivi del settore ricevono la nuova versione del software associata alla release del software OTA.
6. Richiedi assistenza
Google fornisce gli strumenti e la documentazione per eseguire il debug dei problemi relativi a Matter, ma poiché l'ecosistema Matter è nuovo, esistono problemi non inclusi in queste risorse. In questi casi, puoi sempre contattare noi o la community per richiedere assistenza.
Visita i canali per gli sviluppatori
Esistono tre canali per gli sviluppatori monitorati attivamente all'interno di Google:
Sebbene ciascuno di questi canali sia monitorato regolarmente dallo stesso team, ci sono alcune differenze fondamentali in merito a quando utilizzarlo.
- Stack Overflow:puoi contattare noi e la community di sviluppatori di 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:è il sistema di monitoraggio dei problemi gestito da Google ufficiale, tramite cui il pubblico esterno può segnalare errori nell'ecosistema. Fornisce strumenti web per allegare file e condividere informazioni sensibili quando necessario. Utilizzare Issue Tracker è la soluzione migliore per segnalare i problemi dell'ecosistema o condividere richieste di funzionalità.
- Forum per gli sviluppatori: per ricevere indicazioni dall'Assistenza Google ufficiale e dagli esperti della community, puoi contattare il Nest Developer Forum. Questo forum è il luogo migliore per ottenere una guida ufficiale per lo sviluppo.
Iscriviti alla newsletter per sviluppatori
Oltre a visitare i canali per gli sviluppatori per eventuali domande, pubblichiamo anche una newsletter trimestrale che mette in evidenza le nuove funzionalità e fornisce 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 Matter utilizzando gli strumenti e le tecniche che consigliamo. Ti auguriamo un buon tempo per la creazione delle 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 utilizzare anche la Test Suite per testare l'integrazione rispetto a eventuali problemi.
- Quando l'integrazione è pronta per essere condivisa con il mondo, il passo successivo è ottenere la certificazione FCGH del tuo progetto. A questo scopo, puoi seguire la procedura descritta nella pagina Certificazione.