1. Antes de comenzar
Matter ofrece una experiencia de configuración y control de dispositivos fluida y multiplataforma para los usuarios finales. Esto es posible principalmente debido a los múltiples componentes del ecosistema que funcionan en conjunto en segundo plano. A menudo, la solución de problemas de sistemas como estos puede ser abrumador para los desarrolladores nuevos, por lo que desarrollamos una serie de herramientas y técnicas para facilitarte la vida como desarrollador de Matter con Google Home.
En este codelab, se abordan tres componentes principales de Matter. Para cada uno de estos sistemas, Google proporciona un conjunto de estadísticas de solución de problemas para desarrolladores recopiladas de teléfonos y concentradores:
Como desarrollador, es fundamental que puedas mitigar los problemas que experimentes durante el ciclo de desarrollo del dispositivo. Una vez que lances tu proyecto, deberás supervisar las tendencias de problemas de los dispositivos en el campo de manera agregada y solucionarlos mediante actualizaciones de software. En este codelab, se abordan técnicas que puedes usar para ambos fines.
Requisitos previos
- Completa la guía Cómo comenzar a usar Matter con un proyecto de Matter y una configuración de dispositivos en funcionamiento
- Tener un teléfono Android que puedas conectar a tu estación de trabajo (para los registros de ADB)
Qué aprenderás
- Cómo usar herramientas de análisis para la casa inteligente para supervisar los 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 de Matter y a los recursos de asistencia para obtener ayuda
2. Consulta las estadísticas de Google Home
Supervisar el rendimiento es fundamental para lograr una integración exitosa con el ecosistema de Google Home. Proporcionamos un conjunto de herramientas de supervisión a los desarrolladores de casas inteligentes en Google Cloud Platform. Puedes usar estas herramientas para obtener una medición del rendimiento de tu proyecto.
Cómo acceder a las métricas del proyecto
- El primer paso para acceder a tus datos es revisar los paneles de Google Home. Para ello, accede a la consola de Google Cloud y navega a Operaciones > Monitoring > Paneles.
Hay varios paneles disponibles para tu proyecto (incluidos otros productos de GCP). Los paneles proporcionados para la casa inteligente incluyen el prefijo Google Home Analytics.
Actualmente, tenemos un panel general que abarca todo tu proyecto, así como paneles para integraciones específicas (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 completa las solicitudes.
Cuando abras uno de estos paneles, verás una serie de gráficos que se ven de la siguiente manera:
Los paneles de Google Home contienen varios gráficos que muestran detalles de los eventos asociados con tu proyecto. En 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 el porcentaje de éxito de ese tipo de integración y varios gráficos que muestran los tipos de dispositivos y las características involucradas. Además, con Matter, tienes un conjunto de gráficos que hacen un seguimiento del éxito de la comisión, así como de los lanzamientos de actualizaciones en tus dispositivos.
Ten en cuenta que la vista predeterminada con los gráficos que ves en los paneles de Analytics de Google Home es solo una vista que creamos para tu proyecto con datos de métricas de la casa inteligente. También puedes usar el Explorador de métricas para crear tus propios gráficos a partir de las mismas métricas subyacentes y guardarlos en tus paneles personalizados.
Accede a los registros de errores
El Explorador de registros es un conjunto de herramientas para trabajar con registros de eventos generados en un proyecto. Para acceder a él en la consola de Google Cloud, navega a Operaciones > Registros > Explorador de registros.
Una vez que abras el Explorador de registros, verá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 desde todos los sistemas disponibles para tu proyecto, incluidos los que se generan fuera de la casa inteligente. Por eso, es clave usar estos registros filtrando los eventos que deseas depurar. Hablaremos más sobre esto en las secciones de depuración.
3. Depura los problemas de la comisión
El primer tipo de métrica que analizaremos se relaciona con los eventos de comisión de Matter. La comisión hace referencia al conjunto de pasos necesarios para que un usuario configure un dispositivo Matter por primera vez.
Durante la puesta en marcha del dispositivo, se produce 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:
Puedes consultar la página de puesta en marcha del primer libro de Matter para obtener más información sobre cada uno de estos pasos. En esta sección, abordaremos las herramientas y técnicas para depurar problemas relacionados con las comisiones.
Usa Google Home Analytics
Creamos un conjunto de métricas para que investigues los problemas de la comisión haciendo un seguimiento de los eventos y entendiendo en qué etapa pueden ocurrir los errores. Puedes encontrar estos datos en el panel de integración de Matter, como se explicó en la sección anterior.
Los gráficos de este panel proporcionan datos sobre la puesta en marcha de dispositivos:
El gráfico de recuento de dispositivos muestra la cantidad de intentos de puesta en servicio que realizaron los usuarios en una fecha determinada. El porcentaje de éxito muestra el porcentaje de éxito percibido para estos eventos de parte de Google. Cada intento de comisión genera un conjunto de eventos con estados asociados. Cuando se produce un error en cualquiera de estos estados, también se captura en el gráfico de desglose de errores.
Estados de comisión:
- COMMISSIONING_STARTED
- ONBOARDING_PAYLOAD_GENERATED
- LOCAL_DISCOVERY_SUCCESSFUL
- PASE_CONNECTION_SUCCESSFUL
- NOC_ADDED_SUCCESSFULLY
- COMMISSIONING_COMPLETE
Para ver una versión detallada de estos eventos, ve a Operaciones > Registro > Explorador de registros. Para filtrar los errores de comisión, puedes buscar “clientUpdateLog” junto con “severity>=ERROR” en el campo de consulta.
Un registro de errores de la comisión 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 de 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 comisión comparte un sessionId.
Las métricas de Analytics de Google Home te dan una idea inicial en qué etapa puede ocurrir el problema. Para encontrar la causa raíz de los errores de comisión de dispositivos, a veces es posible que debas realizar una depuración adicional con los registros que genera el dispositivo móvil que se usa en el proceso de comisión. Para ello, necesitas Android Debug Bridge.
Cómo usar Android Debug Bridge (ADB)
Otra forma de solucionar problemas de comisión es usar la herramienta de línea de comandos de Android Debug Bridge (ADB). Dado que la comisión se controla principalmente entre el dispositivo móvil y el dispositivo Matter, es posible usar la herramienta ADB para acceder a los registros que genera la app de Google Home durante la comisión.
Instala herramientas de la plataforma
ADB se incluye como parte de las Herramientas de la plataforma del SDK de Android, que se pueden instalar con Android Studio o a través de la herramienta de línea de comandos sdkmanager.
Una vez que hayas instalado correctamente las herramientas de la plataforma en tu sistema, verifica el número de versión desde la terminal con el siguiente comando para verificar ADB:
$ adb -- version
Se debería mostrar el número de versión de la utilidad de ADB instalada sin errores.
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.
De esta manera, se permite que ADB acceda a registros generados por apps que se ejecutan actualmente en el dispositivo.
Cómo recuperar el 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 un mensaje de advertencia en el teléfono sobre la depuración por USB, en el que se te pregunte si quieres permitir que la computadora acceda a la información de tu teléfono:
- Si recibes este mensaje de advertencia, haz clic en Permitir.
- En la terminal, emite el comando list devices para ver si tu computadora puede acceder al teléfono a través de ADB. Para ello, usa el siguiente comando:
$ adb devices
Esto debería mostrar una respuesta similar a la siguiente:
List of devices attached <phone-id> device
El <phone-id> es una cadena alfanumérica que identifica de forma única a tu dispositivo.
- Recuerda el valor de
<phone-id>para usarlo en los siguientes pasos.
Recopila información del sistema
A continuación, debes verificar la información de la versión de las apps y el sistema de tu dispositivo.
- Para verificar 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 Home o Matter a través de 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úrate de que estos valores que se muestren sean compatibles con nuestro ecosistema. Cuando solicites asistencia por fallas en la comisión, siempre incluye información del sistema en tus tickets de asistencia.
Recopila registros de errores
A continuación, inicia el proceso de recopilación de registros y, luego, sigue los pasos de la comisión para generar los eventos de error que deseas depurar.
- Ejecuta el siguiente comando proporcionando tu
<phone-id>, así como un<file-name>en el que se guardarán los registros en tu computadora (p. ej.,debug_file.txt).
$ adb -s <phone-id> logcat > <file-name>
Esto inicia de inmediato el proceso de registro. Se crea un archivo con el nombre proporcionado si aún no existe, y los registros del teléfono se agregan al archivo después de cada evento.
Continúa con los pasos de la comisión con tu dispositivo Matter.
- Una vez que llegues al error que deseas depurar, presiona
Control+Cen la ventana de la terminal en ejecución para detener el registro.
Los registros ahora deberían almacenarse en el archivo de registro <file-name>. Dado que este proceso registra los registros de cada proceso en ejecución del que se realiza un seguimiento en el dispositivo, habrá muchos registros en este archivo. Por eso, siempre debes usar estos registros buscando las entradas que necesitas.
Cómo analizar registros de errores
Los procesos de comisión se controlan a través de un subsistema llamado MatterCommissioner dentro de GHA.
- Siguiendo la estrategia principal que se usa cuando se analizan los errores de comisión, busca los errores que genera el subsistema MatterCommissioner con el siguiente comando:
$ grep "MatterCommissioner" <file-name>
Esto genera un resultado que contiene los eventos del proceso de comisión.
- Si tu dispositivo Matter usa Thread, también puedes buscar errores generados por el subsistema de Thread con el siguiente comando:
$ grep -E "(ThreadNetworkManager|BorderAgentScannerImpl|ThreadBrSynchronizer)" <file-name>
A medida que analizas el archivo de registro que genera el proceso de depuración de ADB, busca también ciertos patrones. Muchos errores de comisión incluyen la cadena "commissioning failure" en su mensaje de error.
- Busca un mensaje de falla de la comisión con el siguiente comando:
$ grep "SetupDevice" $phonelog | grep -A 20 "Commissioning failed"
4. Cómo depurar problemas de control de dispositivos
Una vez que los usuarios configuren y comisionen dispositivos Matter en el ecosistema de Google Home, podrán emitir comandos por voz con Asistente de Google (por ejemplo, "Hey Google, enciende las luces de la sala de estar") o con la IU de la app de Home o los dispositivos de pantalla Google Nest.
Dado que Matter media la especificación de control entre los dispositivos finales y los concentradores de Google, se espera que haya menos errores en el control de dispositivos. De cualquier manera, proporcionamos métricas y registros para que también depures este tipo de problemas.
Usa métricas
En el panel de integración de Matter, verás varias métricas relacionadas con el control de dispositivos. Existen tres gráficos fundamentales para evaluar el rendimiento de los dispositivos en el campo:
Durante los problemas de control, por lo general, observas una tendencia a la baja en el porcentaje de éxito y una tendencia al alza en el gráfico de desglose de errores. En el gráfico de desglose de errores, se muestran los errores que detectan los Google Nest Hubs sobre por qué falló el intento de control del dispositivo.
Cómo usar registros
Cada problema de control de dispositivos Matter también genera un registro de errores en el sistema. Para filtrar estos errores desde el Explorador de registros, busca "executionLog".
Los registros de errores del control de dispositivos 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 el statusType. Muchos errores de control también incluyen un externalDebugString, un mensaje de error breve que explica de qué se trata.
5. Cómo depurar otras funciones
Hasta ahora, aprendiste a controlar los problemas de comisión y control de dispositivos de Matter. También existen otras funciones en el ecosistema que puedes usar con nuestras técnicas recomendadas para garantizar una buena integración de calidad.
Cómo hacer un seguimiento de las actualizaciones OTA
Para hacer un seguimiento de los lanzamientos de actualizaciones inalámbricas (OTA) de dispositivos Matter emitidos por Google Home, proporcionamos un conjunto de métricas que muestran las versiones de hardware y software de los dispositivos 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 al lanzamiento, cada vez más dispositivos en el campo obtienen la nueva versión de software asociada con tu lanzamiento de software OTA.
6. Busca asistencia
Google te proporciona herramientas y documentación para que depures tus problemas de Matter, pero, como el ecosistema de Matter es nuevo, habrá problemas que estos recursos no cubren. Para estos casos, puedes comunicarte con nosotros o con la comunidad para solicitar asistencia.
Visita los canales de desarrolladores
Existen tres canales de desarrolladores que se supervisan de forma activa en Google:
Si bien el mismo equipo supervisa cada uno de estos canales de forma periódica, existen algunas diferencias clave en cuanto a cuándo usar cada uno.
- Stack Overflow: Puedes comunicarte con nosotros y con la comunidad de desarrolladores de Smart Home para obtener ayuda con la implementación o para solicitar orientación. Este canal es mejor para preguntar cómo solucionar problemas o implementar una función específica.
- Herramienta de seguimiento de errores: Es el sistema oficial de Google para la Herramienta de seguimiento de errores, en el que los públicos externos pueden informar errores en el ecosistema. Proporciona herramientas web para adjuntar archivos y compartir información sensible cuando sea necesario. El uso de la herramienta de seguimiento de errores es la mejor opción para informar problemas del ecosistema o compartir solicitudes de funciones.
- Foro para desarrolladores: Para obtener orientación de los expertos de la comunidad y de la asistencia oficial de Google, puedes comunicarte a través del Foro para 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 para hacer preguntas, también publicamos un boletín informativo trimestral en el que se destacan funciones nuevas y se proporcionan noticias sobre el estado del ecosistema de casas inteligentes de Google.
Puedes usar el formulario de registro para recibir el boletín informativo para desarrolladores.
7. Felicitaciones
¡Felicitaciones! Aprendiste a depurar integraciones de Matter con las herramientas y técnicas que recomendamos. Esperamos que disfrutes compilando integraciones de Matter con Google Home.
Próximos pasos
Prueba los siguientes ejercicios y explora recursos adicionales:
- Además de usar las estadísticas para solucionar problemas, también puedes usar el conjunto de pruebas para probar tu integración en busca de posibles problemas.
- Una vez que tu integración esté lista para compartirla con el mundo, el siguiente paso es obtener la certificación de WWGH para tu proyecto. Para ello, sigue los pasos que se indican en la página Certificación.