1. Antes de comenzar
Matter ofrece una experiencia fluida de control y configuración de dispositivos multiplataforma a los usuarios finales. Esto es posible principalmente debido a los múltiples componentes del ecosistema que funcionan en conjunto entre sí en segundo plano. Los sistemas de solución de problemas como estos a menudo pueden ser abrumadores para los desarrolladores nuevos. Por eso, con Google Home creamos una serie de herramientas y técnicas para facilitarte la vida como desarrollador de Matter.
Este codelab incluye tres componentes principales de Matter. Para cada uno de estos sistemas, Google brinda un conjunto de estadísticas de solución de problemas para desarrolladores que se recopilan desde teléfonos y concentradores:
Como desarrollador, es fundamental que puedas mitigar los problemas que experimentas durante el ciclo de desarrollo del dispositivo. Una vez que inicies tu proyecto, deberás supervisar las tendencias de problemas de los dispositivos fuera de la oficina y, luego, corregirlos mediante actualizaciones de software. En este codelab, se abordan técnicas que puedes usar para ambos propósitos.
Requisitos previos
- Completa la guía Cómo comenzar a usar Matter con un proyecto de Matter y la configuración de dispositivos.
- Tener un teléfono Android al que puedas conectarte a la estación de trabajo (para registros de ADB)
Qué aprenderás
- Cómo usar herramientas de estadísticas para la casa inteligente a fin de supervisar problemas de Matter a gran escala
- Cómo clasificar los errores accediendo a los registros de errores y recopilando información
- Cómo acceder a la documentación y los recursos de asistencia de Matter para obtener ayuda.
2. Ver Google Home Analytics
La supervisión del rendimiento es fundamental para lograr una integración exitosa con el ecosistema de Google Home. Proporcionamos un conjunto de herramientas de supervisión para desarrolladores de casas inteligentes en Google Cloud Platform. Puedes usar estas herramientas para medir el rendimiento de tu proyecto.
Accede a las métricas del proyecto
- El primer paso para ver tus datos es verificar los paneles de Google Home. Para ello, accede a Google Cloud Console y navega a Operaciones > Monitoring > Paneles.
Hay una serie de paneles disponibles para tu proyecto (incluidos otros productos de GCP). Los paneles proporcionados para el hogar inteligente vienen con un prefijo de Google Home Analytics.
Actualmente, contamos con un panel general que abarca todo su proyecto, así como paneles de integración específica (Cloud, Local, Matter) o tipos de dispositivos (Cámaras). Estos paneles solo contienen datos si tienes una integración del tipo correspondiente, junto con un proyecto en funcionamiento que cumpla con las solicitudes.
Cuando abra uno de estos paneles, verá una serie de gráficos que lucen de la siguiente manera:
Los paneles de Google Home contienen varios gráficos que muestran detalles de los eventos asociados con tu proyecto. Con cada panel de integración, verás un gráfico que muestra la cantidad total de solicitudes que maneja tu proyecto, un gráfico que muestra la tasa de éxito de ese tipo de integración y varios gráficos que muestran los tipos de dispositivos y las características implicadas. Además, con Matter, tiene un conjunto de gráficos que realizan un seguimiento del éxito de la asignación, así como del lanzamiento de actualizaciones en sus dispositivos.
Ten en cuenta que la vista predeterminada con los gráficos que ves en los paneles de control de Google Home es solo una vista que creamos para tu proyecto con los datos de las métricas de casa inteligente. También puede usar el Explorador de métricas para crear sus propios gráficos a partir de las mismas métricas subyacentes y guardarlos en sus paneles personalizados.
Accede a los registros de errores
El Explorador de registros es una colección de herramientas para trabajar con registros de eventos generados en un proyecto. Para acceder a ella en Google Cloud Console, navegue a Operaciones > Logging > Explorador de registros.
Una vez que abras el Explorador de registros, obtendrás una vista similar a la siguiente:
La ventana del explorador contiene varias herramientas para ver, filtrar, consultar y analizar registros. De forma predeterminada, esta vista muestra los registros generados de todos los sistemas disponibles para tu proyecto, incluidos los registros que se generan fuera de Smart Home. Por ello, es fundamental usar estos registros mediante el filtrado de los eventos que desea depurar. Hablaremos más sobre este tema en las secciones de depuración.
3. Depurar problemas de puesta en marcha
El primer tipo de métrica que analizaremos es el de los eventos de asignación de Matter. Las comisiones son el conjunto de pasos necesarios para que un usuario configure un dispositivo Matter por primera vez.
Durante la asignación de dispositivos, se realiza un conjunto de interacciones entre el dispositivo Matter, la app de Google Home y la estructura de Matter. En la siguiente imagen, se muestran algunos de estos eventos:
Puede consultar la página de comisiones del Matter Primer para obtener más información sobre cada uno de estos pasos. En esta sección, analizaremos las herramientas y técnicas para depurar problemas de puesta en marcha.
Usa Google Home Analytics.
Creamos un conjunto de métricas para que investigue los problemas de asignación mediante el seguimiento de eventos y la comprensión de en qué etapa pueden ocurrir los errores. Puedes encontrarlos en el panel de integración de Matter, como vimos en la sección anterior.
Los gráficos de este panel proporcionan datos sobre la asignación de dispositivos:
El gráfico de recuento de dispositivos muestra la cantidad de intentos de puesta en marcha que realizaron los usuarios en una fecha determinada. La tasa de éxito muestra la tasa percibida de éxito de estos eventos por parte de Google. Cada intento de puesta en marcha genera un conjunto de eventos con estados asociados. Cuando ocurre un error en cualquiera de estos estados, también se registra en el gráfico de desglose de errores.
Estados de comisión:
- COMPROMISO
- ONBOARDING_PAYLOAD_GENERATED
- LOCAL_DISCOVERY_SUCCESSFUL
- PASE_CONNECTION_SUCCESSFUL
- NOC_ADDED_SUCCESSFULLY
- COMPROMISO_COMPLETO
Para ver una versión detallada de estos eventos, ve a Operaciones > Logging > Explorador de registros. Para filtrar los errores de comisión, puedes buscar "clientUpdateLog" junto con "severity>=ERROR" en el campo de búsqueda.
Un registro de errores de comisiones de Matter se ve de la siguiente manera:
{
"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"
}
Además del estado de comisión y un código de estado, un registro de errores contiene marcas de tiempo para el error capturado, así como el ID del producto de Matter que te permite identificar cuál de tus productos causó el error. El conjunto de registros generados a partir del mismo intento de puesta en marcha comparte un sessionId.
Usar las métricas de las estadísticas de Google Home te brinda una idea inicial de la etapa en la que podría ocurrir el problema. A fin de encontrar la causa raíz de los errores de asignación de dispositivos, es posible que, en ocasiones, debas hacer una depuración adicional con los registros generados por el dispositivo móvil que se usó en el proceso de asignación. Para ello, necesitas Android Debug Bridge.
Cómo usar Android Debug Bridge (ADB)
Otra forma de solucionar problemas de asignación es usar la herramienta de línea de comandos Android Debug Bridge (ADB). Dado que la asignación de tareas se realiza principalmente entre el dispositivo móvil y el de Matter, es posible usar la herramienta de ADB para acceder a los registros generados por la app de Google Home durante la asignación.
Instala herramientas de la plataforma
ADB forma parte de las herramientas de la plataforma del SDK de Android, que se pueden instalar con Android Studio o mediante la herramienta de línea de comandos de sdkmanager.
Una vez que hayas instalado correctamente las herramientas de la plataforma en tu sistema, verifica el ADB mediante el número de versión desde la terminal con el siguiente comando:
$ adb -- version
Se debería mostrar el número de versión de la utilidad ADB instalada sin ningún error.
Habilita la depuración por USB
A continuación, habilita la depuración por USB en tu dispositivo Android.
Primero, sigue los pasos para habilitar las opciones para desarrolladores en tu dispositivo y, luego, habilita la depuración por USB.
Esto permite que ADB acceda a los registros generados por apps que se ejecutan actualmente en el dispositivo.
Recuperar ID del dispositivo
- Ejecuta el servidor de ADB con el siguiente comando:
$ adb start-server
- Conecta el teléfono a la computadora que ejecuta el servidor ADB.
Es posible que recibas en tu teléfono un mensaje de advertencia sobre la depuración por USB en el que se te pregunte si deseas permitir que la computadora acceda a información de tu teléfono:
- Si recibes este mensaje de advertencia, haz clic en Permitir.
- Ejecuta un comando de lista de dispositivos desde la terminal para verificar si tu computadora puede acceder al teléfono mediante adb con el siguiente comando:
$ adb devices
Debería obtener una respuesta similar a la siguiente:
List of devices attached <phone-id> device
El <phone-id> es una string alfanumérica que identifica tu dispositivo de forma única.
- Recuerda el valor
<phone-id>para usarlo en los próximos pasos.
Recopilar información del sistema
A continuación, debes verificar la información de la versión de las apps y el sistema en tu dispositivo.
- Para comprobar la versión del SO Android, haz lo siguiente:
$ adb -s <phone-id> shell getprop ro.build.version.release
- Para consultar la versión de la app de Google Home, haz lo siguiente:
$ adb -s <phone-id> shell dumpsys package com.google.android.apps.chromecast.app | grep versionName
- Para verificar la versión de los Servicios de Google Play, haz lo siguiente:
$ adb -s <phone-id> shell dumpsys package com.google.android.gms | grep "versionName"
- Para verificar si tienes los módulos de control de la página principal o Matter mediante los Servicios de Play, haz lo siguiente:
$ adb -s <phone-id> shell dumpsys activity provider com.google.android.gms.chimera.container.GmsModuleProvider | grep "com.google.android.gms.home"
Asegúrese de que estos valores que se muestran sean compatibles con nuestro ecosistema. Cuando se comunique con el equipo de asistencia para obtener información sobre errores de encargo, incluya siempre la información del sistema en sus tickets de asistencia.
Recopilar registros de errores
A continuación, inicia el proceso de recopilación de registros y, luego, sigue los pasos de asignación para generar los eventos de error que deseas depurar.
- Para ejecutar el siguiente comando, proporciona tu
<phone-id>, así como una<file-name>en la que se guardarán los registros en tu computadora (p. ej.,debug_file.txt).
$ adb -s <phone-id> logcat > <file-name>
Esto inicia inmediatamente el proceso de registro. Si aún no existe, se creará un archivo con el nombre proporcionado y los registros del teléfono se agregarán al archivo después de cada evento.
Sigue los pasos de la asignación con tu dispositivo Matter.
- Cuando llegues al error que deseas depurar, presiona
Control+Cen la ventana de la terminal en ejecución para detener el registro.
Tus registros ahora deben almacenarse en el archivo de registro <file-name>. Debido a que este proceso registra los registros de cada proceso en ejecución en el dispositivo, habrá muchos registros en este archivo. Es por eso que siempre debe usar estos registros buscando las entradas que necesita.
Analizar registros de errores
Los procesos de gestión se llevan a cabo a través de un subsistema llamado MatterCommissioner en GHA.
- De acuerdo con la estrategia principal que se utiliza cuando se analizan errores de asignación, puedes buscar errores generados por el subsistema de MatterCommissioner con el siguiente comando:
$ grep "MatterCommissioner" <file-name>
Esto genera un resultado que contiene los eventos del proceso de asignación.
- Si tu dispositivo Matter usa Thread, también puedes usar el siguiente comando para buscar errores generados por el subsistema de Thread:
$ grep -E "(ThreadNetworkManager|BorderAgentScannerImpl|ThreadBrSynchronizer)" <file-name>
A medida que analices el archivo de registro que genera el proceso de depuración de adb, también busca ciertos patrones. Muchos errores de asignación incluyen la string "commissioning failure" en su mensaje de error.
- Busca un mensaje de error de comisionado con el siguiente comando:
$ grep "SetupDevice" $phonelog | grep -A 20 "Commissioning failed"
4. Depura problemas de control de dispositivos
Una vez que los usuarios configuran y encargan dispositivos Matter al ecosistema de Google Home, pueden emitir comandos por voz con Asistente de Google (por ejemplo, "Hey Google, enciende las luces de la sala de estar") o mediante la IU en la app de Home o en los dispositivos de visualización Google Nest.
Como la especificación de control entre dispositivos finales y Google Hubs es mediada por Matter, se espera que tenga menos errores en el control de dispositivos. De todas formas, te proporcionamos métricas y registros para que depures estos tipos de problemas.
Usa métricas
En el panel de integración de Matter, verá varias métricas relacionadas con el control de dispositivos. Existen tres gráficos fundamentales para evaluar el rendimiento de tus dispositivos en el campo:
Durante los problemas de control, suele ver tendencias de descenso en el porcentaje de éxito y una tendencia a la baja en el gráfico de desglose de errores. El gráfico de desglose de errores te muestra los errores capturados por los Google Nest Hubs con respecto a por qué falló el intento de control del dispositivo.
Usa registros
Cada problema de control de dispositivos Matter también genera un registro de errores en el sistema. Estos errores se pueden filtrar desde el Explorador de registros si se busca “executionLog”.
Los registros de errores del control de dispositivos de Matter se ven de la siguiente manera:
{
"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"
}
Cada registro de errores contiene una marca de tiempo, un tipo de dispositivo y una característica, así como el error asociado con la solicitud de control en statusType. Muchos errores de control también incluyen un externalDebugString, un breve mensaje de error que explica de qué se trata el error.
5. Cómo depurar otras funciones
Hasta ahora, aprendiste a manejar los problemas de los encargos y el control de los dispositivos con Matter. También existen otras funciones dentro del ecosistema que puede utilizar con nuestras técnicas recomendadas para garantizar una integración de buena calidad.
Cómo hacer un seguimiento de las actualizaciones inalámbricas
Para realizar un seguimiento de las versiones de actualizaciones inalámbricas (OTA) para dispositivos Matter emitidos por Google Home, proporcionamos un conjunto de métricas que muestran las versiones de hardware y software para los dispositivos que se encuentran en el campo.
Una vez que emitas una actualización desde la consola, presta atención a las siguientes métricas:
Verás que en los días posteriores a la versión, cada vez más dispositivos en el campo obtendrán la nueva versión de software asociada con tu versión de software inalámbrica.
6. Buscar asistencia
Google proporciona herramientas y documentación para que depures tus problemas de Matter, pero debido a que el ecosistema de Matter es nuevo, habrá algunos problemas que estos recursos no cubrirán. En estos casos, puedes comunicarte con nosotros o con la comunidad para obtener asistencia.
Visitar canales para desarrolladores
Existen tres canales de desarrolladores que se supervisan activamente en Google:
Si bien cada uno de estos canales es supervisado por el mismo equipo de forma periódica, hay algunas diferencias clave en cuanto a cuándo usar cada uno.
- Stack Overflow: Comunícate con nosotros y con la comunidad de desarrolladores de Casa inteligente mediante preguntas sobre la implementación o orientación. Este canal es ideal para preguntar cómo solucionar problemas o implementar una función específica.
- Herramienta de seguimiento de errores: Es el sistema oficial de seguimiento de problemas administrado por Google, en el que públicos externos pueden informar errores del ecosistema. Proporciona herramientas web para adjuntar archivos y compartir información sensible cuando sea necesario. La herramienta de seguimiento de errores es la mejor para informar problemas del ecosistema o compartir solicitudes de funciones.
- Foro de desarrolladores: Para obtener orientación del equipo oficial de Atención al cliente de Google y de expertos de la comunidad, puedes comunicarte con el Foro de desarrolladores de Nest. Este foro es ideal para \ obtener orientación oficial para el desarrollo.
Regístrate para recibir el boletín informativo para desarrolladores
Además de visitar los canales para desarrolladores con preguntas, también publicamos un boletín informativo trimestral en el que se destacan funciones nuevas y se ofrecen noticias sobre el estado del ecosistema de Casa Inteligente de Google.
Puedes usar el formulario de registro para recibir el boletín informativo para desarrolladores.
7. Felicitaciones
Felicitaciones Aprendiste a depurar correctamente integraciones de Matter con las herramientas y técnicas que te recomendamos. Te deseamos un buen momento para crear integraciones de Matter con Google Home.
Próximos pasos
Prueba los siguientes ejercicios y explora los recursos adicionales:
- Además de usar las estadísticas para solucionar problemas, también puede usar Test Suite a fin de probar su integración en función de cualquier problema potencial.
- Una vez que tu integración esté lista para compartirse con el mundo, el siguiente paso es obtener la certificación WWGH de tu proyecto. Para ello, puede seguir los pasos que se indican en la página Certificación.