1. Prima di iniziare
Matter offre agli utenti finali un'esperienza di configurazione e controllo dei dispositivi multipiattaforma e senza interruzioni. Ciò è possibile principalmente grazie ai numerosi componenti dell'ecosistema che lavorano insieme 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 semplificarti la vita come sviluppatore Matter con Google Home.
Questo codelab tratta tre componenti principali di Matter. Per ciascuno di questi sistemi, Google fornisce un insieme di analisi per la risoluzione dei problemi per gli sviluppatori, raccolte da smartphone e hub:
In qualità di sviluppatore, è fondamentale che tu sia in grado di mitigare i problemi riscontrati durante il ciclo di sviluppo del dispositivo. Una volta avviato il progetto, devi monitorare le tendenze dei problemi per i dispositivi sul campo in modo aggregato e risolverli 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
- Avere uno smartphone Android che puoi connettere alla tua workstation (per i log ADB)
Obiettivi didattici
- Come utilizzare gli strumenti di analisi per Smart Home per monitorare i problemi di Matter su larga scala.
- Come eseguire il triage degli errori accedendo ai log degli errori e raccogliendo informazioni.
- Come accedere alla documentazione e alle risorse di assistenza di Matter per ricevere aiuto.
2. Visualizzare Google Home Analytics
Il monitoraggio delle prestazioni è fondamentale per un'integrazione riuscita con l'ecosistema Google Home. Forniamo una serie di strumenti di monitoraggio agli sviluppatori di smart home sulla piattaforma Google Cloud. Puoi utilizzare questi strumenti per ottenere una misurazione del rendimento del tuo progetto.
Accedere alle metriche del progetto
- Il primo passo per accedere ai tuoi dati è controllare le dashboard di Google Home. Per farlo, accedi alla console Google Cloud e vai a Operazioni > Monitoring > Dashboard.
Sono disponibili diverse dashboard per il tuo progetto (inclusi altri prodotti Google Cloud). Le dashboard fornite per la smart home hanno il prefisso Google Home Analytics.
Al momento disponiamo di una dashboard generale che copre l'intero progetto, nonché di dashboard per integrazioni specifiche (cloud, locale, Matter) o tipi di dispositivi (videocamere). Queste dashboard contengono dati solo se hai un'integrazione del tipo corrispondente, oltre a un progetto funzionante che soddisfi le richieste.
Quando apri una di queste dashboard, vedrai una serie di grafici simili a questi:
I dashboard di Google Home contengono vari grafici che mostrano i dettagli degli eventi associati al tuo progetto. In ogni dashboard di integrazione, vedrai un grafico che mostra il numero totale di richieste gestite dal tuo progetto, un grafico che mostra il tasso di successo per quel tipo di integrazione e diversi grafici che mostrano i tipi e le caratteristiche dei dispositivi coinvolti. Inoltre, con Matter hai a disposizione una serie di grafici che monitorano la riuscita del provisioning, nonché l'implementazione degli aggiornamenti sui tuoi dispositivi.
Tieni presente che la visualizzazione predefinita con i grafici che vedi 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 grafici personalizzati a partire dalle stesse metriche sottostanti e salvarli nelle dashboard personalizzate.
Accedere ai log degli errori
Esplora log è una raccolta di strumenti per lavorare con i log eventi generati in un progetto. È accessibile nella console Google Cloud andando a Operations > Logging > Esplora log.
Una volta aperto Esplora log, visualizzi una schermata simile alla seguente:
La finestra dell'explorer contiene vari strumenti per visualizzare, filtrare, interrogare 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 di Smart Home. Per questo motivo, è fondamentale utilizzare questi log filtrando gli eventi di cui vuoi eseguire il debug. Ne parleremo più nel dettaglio nelle sezioni sul debug.
3. Eseguire il debug dei problemi di commissioning
Il primo tipo di metrica che esamineremo riguarda gli eventi di commissioning di Matter. Il commissioning si riferisce all'insieme di passaggi necessari a un utente per configurare un dispositivo Matter per la prima volta.
Durante il provisioning del dispositivo, si verifica una serie di interazioni tra il dispositivo Matter, l'app Google Home e la rete Matter. La seguente immagine mostra alcuni di questi eventi:
Per saperne di più su ciascuno di questi passaggi, puoi consultare la pagina di commissioning della guida introduttiva a Matter. In questa sezione tratteremo gli strumenti e le tecniche per eseguire il debug dei problemi di commissioning.
Utilizzare Google Home Analytics
Abbiamo creato un insieme di metriche per consentirti di esaminare i problemi di commissione monitorando gli eventi e comprendendo in quale fase potrebbero verificarsi gli errori. Puoi trovarli nella dashboard di integrazione delle pratiche, come abbiamo visto nella sezione precedente.
I grafici in questa dashboard forniscono dati sul provisioning dei dispositivi:
Il grafico del conteggio dei dispositivi mostra il numero di tentativi di provisioning da parte degli utenti in una determinata data. La percentuale di successo mostra la percentuale di successo percepita per questi eventi da parte di Google. Ogni tentativo di provisioning genera un insieme di eventi con stati associati. Quando si verifica un errore in uno di questi stati, viene acquisito anche nel grafico di distribuzione degli errori.
Stati di 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 gli errori di commissione, puoi cercare "clientUpdateLog" insieme a "severity>=ERROR" nel campo della query.
Un log degli errori di commissioning 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 commissioning e a un codice di stato, un log degli errori contiene timestamp per l'errore acquisito, nonché l'ID prodotto Matter che consente di identificare quale dei tuoi prodotti ha causato l'errore. L'insieme di log generati dallo stesso tentativo di provisioning 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 provisioning dei dispositivi, a volte potrebbe essere necessario eseguire un debug aggiuntivo utilizzando i log generati dal dispositivo mobile utilizzato nel processo di provisioning. Per questi, è necessario Android Debug Bridge.
Utilizzare Android Debug Bridge (ADB)
Un altro modo per risolvere i problemi di provisioning è utilizzare lo strumento a riga di comando Android Debug Bridge (ADB). Poiché il provisioning viene gestito principalmente tra il dispositivo mobile e il dispositivo Matter, è possibile utilizzare lo strumento ADB per accedere ai log generati dall'app Google Home durante il provisioning.
Installa gli 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.
Una volta installati 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.
Attiva debug USB
Il passaggio successivo consiste nell'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.
In questo modo, ADB può accedere ai log generati dalle app attualmente in esecuzione sul dispositivo.
Recuperare l'ID dispositivo
- Esegui il server ADB con questo comando:
$ adb start-server
- Collega lo smartphone al computer su cui è in esecuzione il server ADB.
Potresti ricevere un messaggio di avviso sullo smartphone relativo al debug USB, che ti chiede se vuoi consentire al computer di accedere alle informazioni dello smartphone:
- Se ricevi questo messaggio di avviso, fai clic su Consenti.
- Esegui un comando di elenco dei dispositivi dal terminale per verificare se il computer può accedere allo smartphone tramite ADB, utilizzando il seguente comando:
$ adb devices
Dovresti ricevere una risposta simile a questa:
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 di
<phone-id>da utilizzare nei passaggi successivi.
Raccogliere informazioni sul sistema
Il passaggio successivo consiste nel controllare le informazioni sulla versione delle app e del sistema 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 della casa / 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 in caso di errori di commissioning, includi sempre le informazioni di sistema nei tuoi ticket di assistenza.
Raccogliere i log degli errori
Successivamente, avvia la procedura di raccolta dei log, quindi segui i passaggi di commissioning per generare gli eventi di errore di cui vuoi eseguire il debug.
- Esegui questo comando fornendo il tuo
<phone-id>, nonché un<file-name>in cui verranno salvati i log sul tuo computer (ad es.debug_file.txt).
$ adb -s <phone-id> logcat > <file-name>
In questo modo, il processo di registrazione inizia 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.
Procedi con i passaggi di commissioning con il tuo dispositivo Matter.
- Una volta raggiunto l'errore che 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, il file conterrà molti log. Per questo motivo, devi sempre utilizzare questi log cercando le voci di cui hai bisogno.
Analizzare i log degli errori
Le procedure di messa in servizio vengono gestite tramite un sottosistema chiamato MatterCommissioner all'interno di GHA.
- Seguendo la strategia principale utilizzata per analizzare gli errori di commissioning, cerca gli errori generati dal sottosistema MatterCommissioner con il seguente comando:
$ grep "MatterCommissioner" <file-name>
In questo modo viene generato un output contenente gli eventi della procedura di messa in servizio.
- Se il tuo dispositivo Matter utilizza Thread, puoi anche cercare 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 ADB, cerca anche determinati pattern. Molti errori di commissioning includono la stringa "commissioning failure" nel messaggio di errore.
- Cerca un messaggio di errore di provisioning con il seguente comando:
$ grep "SetupDevice" $phonelog | grep -A 20 "Commissioning failed"
4. Eseguire il debug dei problemi di controllo dei dispositivi
Una volta configurati e attivati i dispositivi Matter nell'ecosistema Google Home, gli utenti possono impartire comandi vocali utilizzando l'Assistente Google (ad esempio, "Ok Google, accendi le luci del soggiorno") o utilizzando la UI nell'app Home o sui dispositivi di visualizzazione Google Nest.
Poiché la specifica di controllo tra i dispositivi finali e i Google Hub è mediata da Matter, si prevede un numero inferiore di errori sul lato del controllo dei dispositivi. In ogni caso, forniamo metriche e log per eseguire il debug anche 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 il rendimento dei tuoi dispositivi sul campo:
Durante i problemi di controllo, in genere si osservano tendenze al ribasso nella percentuale di successo e una tendenza al rialzo nel grafico di distribuzione degli errori. Il grafico della distribuzione degli errori mostra gli errori acquisiti dai Google Nest Hub in merito al motivo per cui il tentativo di controllo del dispositivo non è riuscito.
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 hanno un aspetto simile 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, il tipo di dispositivo e la caratteristica, nonché l'errore associato alla richiesta di controllo in statusType. Molti errori di controllo includono anche un externalDebugString, un breve messaggio di errore che spiega di cosa si tratta.
5. Debug di altre funzionalità
Finora hai imparato a gestire i problemi di controllo e commissioning dei dispositivi per Matter. Esistono anche altre funzionalità all'interno dell'ecosistema che puoi utilizzare o tecniche consigliate per garantire un'integrazione di buona qualità.
Monitorare gli aggiornamenti OTA
Per monitorare le release degli aggiornamenti over-the-air (OTA) ai dispositivi Matter emessi 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:
Nei giorni successivi al rilascio, sempre più dispositivi sul campo riceveranno la nuova versione software associata al rilascio software OTA.
6. Richiedere assistenza
Google fornisce strumenti e documentazione per eseguire il debug dei problemi di Matter, ma poiché l'ecosistema Matter è nuovo, ci saranno problemi che queste risorse non coprono. Per questi casi, puoi sempre contattarci o rivolgerti alla community per ricevere assistenza.
Visita i canali per gli sviluppatori
Esistono tre canali per sviluppatori monitorati attivamente in Google:
Sebbene ciascuno di questi canali sia monitorato periodicamente dallo stesso team, esistono alcune differenze fondamentali per quanto riguarda il momento in cui utilizzarli.
- Stack Overflow:puoi contattarci e la community di sviluppatori di smart home per domande sull'implementazione o per chiedere indicazioni. Questo canale è ideale per chiedere come risolvere i problemi o implementare una determinata funzionalità.
- Issue Tracker:questo è il sistema di monitoraggio dei problemi ufficiale gestito da Google, in cui il pubblico esterno può segnalare errori nell'ecosistema. Fornisce strumenti web per allegare file e condividere informazioni sensibili quando necessario. L'utilizzo di Issue Tracker è la soluzione migliore per segnalare 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 contattarci tramite il forum per gli sviluppatori Nest. Questo forum è ideale per \ ricevere indicazioni ufficiali per lo sviluppo.
Iscriviti alla newsletter per sviluppatori
Oltre a visitare i canali per sviluppatori per porre domande, pubblichiamo anche una newsletter trimestrale che mette in evidenza le nuove funzionalità e fornisce informazioni 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 di divertirti a creare integrazioni Matter con Google Home.
Passaggi successivi
Prova i seguenti esercizi ed esplora le risorse aggiuntive:
- Oltre a utilizzare Analytics per risolvere i problemi, puoi anche utilizzare Test Suite per testare l'integrazione e verificare la presenza di potenziali problemi.
- Una volta che l'integrazione è pronta per essere condivisa con il mondo, il passaggio successivo è ottenere la certificazione WWGH per il tuo progetto. A questo scopo, puoi seguire i passaggi descritti nella pagina Certificazione.