1. Prima di iniziare
Matter offre un'esperienza fluida e multipiattaforma su come configurare e controllare i dispositivi degli utenti finali. Ciò è possibile principalmente a causa dei molteplici componenti dell'ecosistema che lavorano in sinergia tra loro dietro le quinte. I sistemi di risoluzione di problemi come questi possono essere scoraggianti per i nuovi sviluppatori, quindi abbiamo sviluppato una serie di strumenti e tecniche per semplificare la vita di uno sviluppatore Matter in Google Home.
In questo codelab sono trattati tre componenti principali della tecnologia Matter. Per ognuno di questi sistemi, Google fornisce una serie di dati e analisi per la risoluzione dei problemi per gli sviluppatori raccolti da telefoni e hub:
In qualità di sviluppatore, è fondamentale che tu sia in grado di mitigare i problemi che riscontri durante il ciclo di sviluppo dei dispositivi. Dopo aver avviato il progetto, devi monitorare le tendenze dei problemi per i dispositivi sul campo in forma aggregata 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 un telefono Android che puoi 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 accedendo ai log degli errori e raccogliendo informazioni.
- Come accedere alla documentazione e alle risorse di supporto di Matter per richiedere aiuto.
2. Visualizza Google Home Analytics
Il monitoraggio del rendimento è fondamentale per un'integrazione di successo con l'ecosistema Google Home. Offriamo una serie di strumenti di monitoraggio agli sviluppatori di smart home su Google Cloud Platform. Puoi utilizzare questi strumenti per misurare le prestazioni 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.
Sono disponibili diverse dashboard per il tuo progetto (inclusi altri prodotti GCP). Le dashboard fornite per la smart home hanno un prefisso Google Analytics.
Attualmente disponiamo di una dashboard generale che copre l'intero progetto, nonché dashboard per un'integrazione specifica (Cloud, Local, Matter) o tipi di dispositivi (Videocamere). Queste dashboard contengono dati solo se hai un'integrazione del tipo corrispondente, insieme a un progetto funzionante che soddisfa le richieste.
Quando apri una di queste dashboard, visualizzi una serie di grafici simili al seguente:
Le dashboard di Google Home contengono vari grafici che mostrano i dettagli degli eventi associati al tuo progetto. In ogni dashboard di integrazione, visualizzi 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 indicano i tipi di dispositivi e le caratteristiche richieste. Inoltre, con Matter hai a disposizione un insieme di grafici che tracciano i risultati relativi alle commissioni e le implementazioni degli aggiornamenti sui tuoi dispositivi.
Tieni presente che la visualizzazione predefinita con i grafici visualizzati nelle dashboard di Google Home Analytics è solo una vista che abbiamo creato per il tuo progetto utilizzando i dati delle metriche per la smart home. Inoltre, puoi utilizzare Metrics Explorer per creare i tuoi grafici dalle stesse metriche sottostanti e salvarli nelle tue dashboard personalizzate.
Accedi ai log degli errori
Esplora log è una raccolta di strumenti con cui lavorare con i log degli eventi generati su un progetto. Per accedere a Google Cloud Console, vai a Operazioni > Logging > Esplora log.
Una volta aperto Esplora log, viene visualizzata una vista 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 in base agli eventi di cui vuoi eseguire il debug. Ne discuteremo più a fondo nelle sezioni di debug.
3. Debug dei problemi relativi alle commissioni
Il primo tipo di metrica che esamineremo è relativo agli eventi di commissione di Matter. La messa in servizio si riferisce all'insieme di passaggi necessari a un utente per configurare un dispositivo Matter per la prima volta.
Durante la messa in servizio del dispositivo, viene eseguita 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, consulta la pagina dedicata a commissioni del Matter Primer. In questa sezione tratteremo gli strumenti e le tecniche per eseguire il debug dei problemi.
Utilizzare Google Home Analytics
Abbiamo creato una serie di metriche per consentirti di esaminare i problemi relativi alle commissioni monitorando gli eventi e comprendendo in quale fase potrebbero verificarsi gli errori. Sono disponibili nella dashboard di integrazione 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 esecuzione degli utenti in una data specificata. La percentuale di successo percepita mostra la percentuale di successo percepita per questi eventi da parte di Google. Ogni tentativo di messa in servizio genera un insieme di eventi con gli stati associati. Quando si verifica un errore in uno di questi stati, viene rilevato anche nel grafico di suddivisione degli errori.
Stati per la commissione:
- COMMISSIONING_STARTED
- ONBOARDING_PAYLOAD_GENERATED
- LOCAL_DISCOVERY_SUCCESSFUL
- PASE_CONNECTION_SUCCESSFUL
- NOC_ADDED_SUCCESSFULLY
- COMMISSIONE_COMPLETA
Per visualizzare una versione dettagliata di questi eventi, vai a Operazioni > Logging > Esplora log. Per filtrare in base agli errori delle commissioni, puoi cercare "clientUpdateLog" insieme a "severity>=ERROR" nel campo della query.
Un log degli errori di commissione 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 per la messa in servizio e a un codice di stato, un log degli errori contiene i timestamp per l'errore acquisito e l'ID prodotto Matter, che ti consente di identificare quali dei tuoi prodotti hanno causato l'errore. L'insieme di log generati dallo stesso tentativo di commissione condivide un valore sessionId.
L'utilizzo delle metriche di Google Home Analytics ti dà un'idea iniziale sulla fase in cui potrebbe verificarsi il problema. Per trovare la causa principale degli errori di commissione dei dispositivi, a volte potresti dover eseguire un debug aggiuntivo utilizzando i log generati dal dispositivo mobile utilizzato durante il processo di messa in servizio. Per questi casi ti serve Android Debug Bridge.
Utilizzare Android Debug Bridge (ADB)
Un altro modo per risolvere i problemi relativi alle commissioni è utilizzare lo strumento a riga di comando Android Debug Bridge (ADB). Dal momento che le commissioni vengono gestite principalmente tra il dispositivo mobile e il dispositivo Matter, è possibile utilizzare lo strumento ADB per accedere ai log generati dall'app Google Home durante tutta la procedura.
Installa strumenti della piattaforma
ADB fa parte degli Android SDK Platform Tools, che possono essere installati con Android Studio o tramite lo strumento a riga di comando sdkmanager.
Dopo aver installato correttamente gli strumenti della piattaforma sul tuo sistema, verifica ADB controllando il numero di versione nel terminale con questo comando:
$ adb -- version
Dovrebbe essere visualizzato il numero di versione dell'utilità ADB installata senza errori.
Attiva debug USB
A questo punto, 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.
Recupera ID dispositivo
- Esegui il server ADB con il comando seguente:
$ adb start-server
- Connetti il telefono al computer su cui è in esecuzione il server ADB.
Sul telefono potresti ricevere un messaggio di avviso relativo al debug USB, che chiede se vuoi consentire al computer di accedere alle informazioni del telefono:
- Se viene visualizzato il messaggio di avviso, fai clic su Consenti.
- Esegui un comando dell'elenco dei dispositivi dal terminale per verificare se il tuo computer può accedere al telefono tramite ADB, utilizzando il seguente comando:
$ adb devices
La risposta dovrebbe essere 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.
Raccogli informazioni sul sistema
Successivamente, controlla le informazioni sulla versione delle app e del 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 verificare 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 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 contatti il team per chiedere assistenza per gli errori relativi alle commissioni, includi sempre le informazioni di sistema nei ticket di assistenza.
Raccogli i log degli errori
Avvia quindi il processo di raccolta dei log e segui i passaggi per la messa in servizio per generare gli eventi di errore che vuoi sottoporre a debug.
- Esegui questo comando fornendo il tuo
<phone-id>e un<file-name>in cui i log verranno salvati sul computer (ad esempio,debug_file.txt)
$ adb -s <phone-id> logcat > <file-name>
Questa operazione avvia immediatamente il processo di logging. Se non esiste già, viene creato un file con il nome fornito e i log del telefono vengono aggiunti al file dopo ogni evento.
Procedi con i passaggi per la messa in servizio del tuo dispositivo Matter.
- Quando raggiungi l'errore di cui vuoi eseguire il debug, interrompi il logging premendo
Control+Cnella finestra del terminale in esecuzione.
Ora i tuoi log dovrebbero essere archiviati nel file di log <file-name>. Poiché questo processo registra i log di ogni processo in esecuzione monitorato nel dispositivo, il file contiene molti log. Ecco perché dovresti sempre usare questi log cercando le voci di cui hai bisogno.
Analizzare i log degli errori
I processi di messa in servizio vengono gestiti tramite un sottosistema chiamato MatterCommissioner all'interno di GHA.
- Seguendo la strategia principale utilizzata durante l'analisi degli errori di commissione, cerca gli errori generati dal sottosistema MatterCommissioner con il seguente comando:
$ grep "MatterCommissioner" <file-name>
Questa operazione genera un output contenente gli eventi dal processo di commissione.
- Se il tuo dispositivo Matter utilizza Thread, puoi anche cercare gli errori generati dal sottosistema Thread utilizzando il seguente comando:
$ grep -E "(ThreadNetworkManager|BorderAgentScannerImpl|ThreadBrSynchronizer)" <file-name>
Mentre analizzi il file di log generato dal processo di debug ADB, cerca anche determinati pattern. Tra gli errori di commissione figurano la stringa "commissioning failure" nel messaggio di errore.
- Cerca un messaggio di errore relativo alla commissione con il seguente comando:
$ grep "SetupDevice" $phonelog | grep -A 20 "Commissioning failed"
4. Debug di problemi relativi al controllo del dispositivo
Dopo aver configurato e commissionato i dispositivi Matter nell'ecosistema Google Home, questi possono emettere comandi vocali tramite l'Assistente Google (ad esempio, "Hey Google, accendi le luci in salotto") o utilizzando l'interfaccia utente nell'app Home o sui display Google Nest.
Poiché le specifiche di controllo tra i dispositivi finali e i Google Hub sono mediate da Matter, dovrebbero essere presenti meno errori sul controllo del dispositivo. Indipendentemente da questo, forniamo anche metriche e log per 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, generalmente registri una tendenza negativa nella percentuale di successo e un aumento nel grafico di suddivisione degli errori. Il grafico di suddivisione degli errori mostra gli errori acquisiti dai Google Nest Hub che spiegano perché il tentativo di controllo del dispositivo non è andato a buon fine.
Utilizza 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 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 un externalDebugString, un breve messaggio di errore che spiega di cosa si tratta.
5. Esegui il debug di altre funzionalità
Finora hai imparato a gestire i problemi di commissione sui dispositivi e di controllo dei dispositivi per Matter. Esistono anche altre funzionalità all'interno dell'ecosistema che possono essere utilizzate 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 emessi da Google Home, forniamo una serie di metriche che mostrano le versioni hardware e software dei dispositivi sul campo.
Dopo aver effettuato 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 OTA.
6. Cerca assistenza
Google fornisce strumenti e documentazione per il debug dei problemi Matter, ma poiché l'ecosistema Matter è nuovo, si verificheranno problemi che queste risorse non sono coperte. In questi casi, puoi sempre contattarci o richiedere un supporto alla comunità.
Visita i canali per gli sviluppatori
Esistono tre canali sviluppatore attivamente monitorati all'interno di Google:
Sebbene ognuno di questi canali sia monitorato dallo stesso team in modo periodico, esistono alcune differenze chiave su quando utilizzare quale canale.
- Overflow dello stack:puoi contattarci e la community di sviluppatori di 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: è il sistema ufficiale di monitoraggio dei problemi gestito da Google, che consente a segmenti di pubblico esterni di segnalare errori sull'ecosistema. Fornisce strumenti web per allegare file e condividere informazioni sensibili quando necessario. Issue Tracker è la soluzione migliore per segnalare problemi dell'ecosistema o condividere richieste di funzionalità.
- Forum degli sviluppatori:per ricevere indicazioni dall'Assistenza Google e dagli esperti delle community ufficiali, puoi contattare il Forum per gli sviluppatori Nest. Questo forum è ideale per ricevere indicazioni ufficiali per lo sviluppo.
Iscriviti alla newsletter per gli sviluppatori
Oltre a visitare i canali degli sviluppatori per eventuali domande, rilasciamo anche una newsletter trimestrale che evidenzia le nuove funzionalità e fornisce le notizie sullo stato dell'ecosistema delle smart home Google.
Puoi utilizzare il modulo di registrazione per ricevere la newsletter per gli sviluppatori.
7. Congratulazioni
Complimenti. Hai imparato a eseguire il debug delle integrazioni Matter utilizzando gli strumenti e le tecniche che consigliamo. Ti auguriamo un buon momento per la creazione di 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 utilizzare anche Test Suite per testare la tua integrazione con potenziali problemi.
- Quando l'integrazione è pronta per essere condivisa con tutti, il passaggio successivo consiste nella certificazione del progetto WWGH. Per farlo, puoi seguire i passaggi descritti nella pagina Certificazione.