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 gracias a los múltiples componentes del ecosistema que funcionan en conjunto en segundo plano. Los sistemas de solución de problemas como estos suelen ser intimidantes 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 forma agregada y corregirlos a través de actualizaciones de software. En este codelab, se explican las técnicas que puedes usar para ambos propósitos.
Requisitos previos
- Completar la guía Comienza a usar Matter con un proyecto de Matter y una configuración de dispositivo que funcionen
- 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 las herramientas de análisis de Smart Home para supervisar los problemas de Matter a gran escala
- Cómo priorizar 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. Cómo ver 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 para los desarrolladores de casas inteligentes en Google Cloud Platform. Puedes usar estas herramientas para obtener una medida del rendimiento de tu proyecto.
Accede a las métricas del proyecto
- El primer paso para acceder a tus datos es consultar 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 tienen el prefijo Google Home Analytics.
Actualmente, tenemos un panel general que abarca todo tu proyecto, así como paneles para tipos de integración (Cloud, Local, Matter) o dispositivos específicos (cámaras). Estos paneles solo contienen datos si tienes una integración del tipo correspondiente, junto con un proyecto que funciona y cumple con las solicitudes.
Cuando abras uno de estos paneles, verás una serie de gráficos similares a los siguientes:
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 procesó 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 y las características de los dispositivos involucrados. Además, con Matter, tienes un conjunto de gráficos que hacen un seguimiento del éxito de la puesta en marcha, 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 Google Home Analytics 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 una colección de herramientas para trabajar con los registros de eventos generados en un proyecto. Para acceder a él, navega a Operations > Logging > Logs Explorer en la consola de Google Cloud.
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 por todos los sistemas disponibles para tu proyecto, incluidos los registros que se generan fuera de Smart Home. Por eso, es fundamental usar estos registros filtrando los eventos que deseas depurar. Hablaremos más sobre esto en las secciones de depuración.
3. Cómo depurar problemas de puesta en marcha
El primer tipo de métrica que analizaremos se relaciona con los eventos de puesta en servicio de Matter. La puesta en marcha se refiere al conjunto de pasos que debe seguir un usuario para configurar 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 de la guía de Matter 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.
Cómo usar Google Home Analytics
Creamos un conjunto de métricas para que investigues los problemas de comisiones haciendo un seguimiento de los eventos y comprendiendo en qué etapa podrían 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 puesta en marcha de los dispositivos:
En el gráfico de recuento de dispositivos, se muestra la cantidad de intentos de puesta en servicio de los usuarios en una fecha determinada. La tasa de éxito muestra la tasa de éxito percibida para estos eventos en el extremo de Google. Cada intento de puesta en marcha genera un conjunto de eventos con estados asociados. Cuando se produce un error en cualquiera de estos estados, también se registra en el gráfico de desglose de errores.
Estados de la 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 > Logging > Explorador de registros. Para filtrar los errores de puesta en marcha, puedes buscar "clientUpdateLog" junto con "severity>=ERROR" en el campo de consulta.
Un registro de errores de puesta en marcha 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 puesta en marcha y un código de estado, un registro de errores contiene marcas de tiempo para el error capturado, así como el ID del producto 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 servicio comparte un sessionId.
Usar las métricas de Google Home Analytics te da una idea inicial de en qué etapa podría ocurrir el problema. Para encontrar la causa raíz de los errores de puesta en servicio del dispositivo, a veces es posible que debas realizar una depuración adicional con los registros generados por el dispositivo móvil que se usó en el proceso de puesta en servicio. Para ello, necesitas Android Debug Bridge.
Usa Android Debug Bridge (ADB)
Otra forma de solucionar problemas de puesta en marcha es usar la herramienta de línea de comandos de Android Debug Bridge (ADB). Dado que la puesta en marcha se maneja 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 puesta en marcha.
Instala las 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 ADB. Para ello, comprueba el número de versión desde la terminal con el siguiente comando:
$ adb -- version
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.
Esto permite que ADB acceda a los registros generados por las 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 de ADB.
Es posible que recibas un mensaje de advertencia en tu teléfono sobre la depuración por USB, en el que se te pregunte si quieres permitir que tu computadora acceda a la información de tu teléfono:
- Si recibes este mensaje de advertencia, haz clic en Permitir.
- Ejecuta un comando list devices desde la terminal para ver si tu computadora puede acceder al teléfono a través de ADB con el siguiente comando:
$ adb devices
Deberías obtener una respuesta similar a la siguiente:
List of devices attached <phone-id> device
Tu <phone-id> es una cadena alfanumérica que identifica tu dispositivo de forma única.
- Recuerda el valor de
<phone-id>para usarlo en los siguientes pasos.
Recopila información del sistema
A continuación, verifica la información de la versión de las apps y el sistema en tu dispositivo.
- Para verificar la versión del SO Android, haz lo siguiente:
$ adb -s <phone-id> shell getprop ro.build.version.release
- Para verificar 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 casa o de Matter a través de Play Services, 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 de devolución sean compatibles con nuestro ecosistema. Cuando solicites asistencia por fallas en la puesta en marcha, incluye siempre la 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 puesta en servicio para generar los eventos de error que deseas depurar.
- Ejecuta el siguiente comando y proporciona 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 el proceso de registro de inmediato. Si aún no existe, se crea un archivo con el nombre proporcionado y se agregan los registros del teléfono al archivo después de cada evento.
Continúa con los pasos de puesta en marcha del dispositivo Matter.
- Cuando llegues al error que quieres depurar, presiona
Control+Cen la ventana de la terminal en ejecución para detener el registro.
Tus 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 que se rastrea en el dispositivo, habrá muchos registros en este archivo. Por eso, siempre debes utilizar estos registros buscando las entradas que necesites.
Analiza los 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 puesta en marcha, 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 puesta en marcha.
- 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 puesta en servicio incluyen la cadena "commissioning failure" en su mensaje de error.
- Busca un mensaje de falla de puesta en servicio 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 configuran y ponen en funcionamiento los dispositivos Matter en el ecosistema de Google Home, pueden emitir comandos por voz con Asistente de Google (por ejemplo, "Hey Google, enciende las luces de mi sala de estar") o usar la IU en la app de Home o en los dispositivos de pantalla Google Nest.
Dado que Matter media la especificación de control entre los dispositivos finales y los Google Hubs, se espera que haya menos errores en el control de dispositivos. De todos modos, te proporcionamos métricas y registros para que también depures este tipo de problemas.
Métricas de uso
En el panel de integración de Matter, verás varias métricas relacionadas con el control de dispositivos. Hay tres gráficos fundamentales para evaluar el rendimiento de tus dispositivos en el campo:
Durante los problemas de control, es común ver tendencias a la baja en el porcentaje de éxito y tendencias al alza en el gráfico de desglose de errores. En el gráfico de desglose de errores, se muestran los errores que capturaron los dispositivos Google Nest Hub en relación con el motivo por el que falló el intento de control del dispositivo.
Registros de uso
Cada problema de control de dispositivos Matter también genera un registro de errores en el sistema. Estos errores se pueden filtrar en el Explorador de registros buscando "executionLog".
Los registros de errores de 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 error contiene una marca de tiempo, un tipo de dispositivo y un rasgo, así como el error asociado con la solicitud de control en statusType. Muchos errores de control también incluyen un externalDebugString, un mensaje de error breve que explica de qué se trata el error.
5. Depura otras funciones
Hasta ahora, aprendiste a controlar los problemas de puesta en marcha y control de dispositivos para Matter. También hay otras funciones dentro del ecosistema que puedes usar o técnicas recomendadas para garantizar una integración de buena calidad.
Realiza un seguimiento de las actualizaciones inalámbricas
Para hacer un seguimiento de los lanzamientos de actualizaciones inalámbricas (OTA) para dispositivos Matter emitidas 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 publiques 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 obtendrán la nueva versión de software asociada con tu lanzamiento de software OTA.
6. Buscar asistencia
Google 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 cubran. En estos casos, siempre puedes comunicarte con nosotros o con la comunidad para obtener asistencia.
Visita los canales para desarrolladores
En Google, se supervisan activamente tres canales para desarrolladores:
Si bien el mismo equipo supervisa periódicamente cada uno de estos canales, 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 casas inteligentes si tienes preguntas sobre la implementación o necesitas orientación. Este canal es ideal para preguntar cómo solucionar problemas o implementar una función determinada.
- Issue Tracker: Este es el sistema oficial de seguimiento de problemas que administra Google, en el que el público externo puede informar errores en el ecosistema. Proporciona herramientas web para adjuntar archivos y compartir información sensible cuando sea necesario. La mejor opción para informar problemas del ecosistema o compartir solicitudes de funciones es usar la herramienta de seguimiento de errores.
- Foro para desarrolladores: Para obtener orientación del equipo de asistencia oficial de Google y de los expertos de la comunidad, 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 si tienes preguntas, también publicamos un boletín informativo trimestral en el que destacamos las nuevas funciones y brindamos noticias sobre el estado del ecosistema de Google Smart Home.
Puedes usar el formulario de registro para recibir el boletín informativo para desarrolladores.
7. Felicitaciones
¡Felicitaciones! Aprendiste correctamente a depurar las integraciones de Matter con las herramientas y las técnicas que recomendamos. Esperamos que disfrutes la creación de 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 y detectar 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, puedes seguir los pasos que se indican en la página Certificación.