1. Antes de comenzar
Matter ofrece a los usuarios finales una experiencia de configuración y control de dispositivos multiplataforma fluida. Esto es posible principalmente debido a los múltiples componentes del ecosistema que trabajan en conjunto entre sí en segundo plano. Solucionar problemas de este tipo de sistemas 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.
Hay tres componentes principales de Matter que se abordan en este codelab. Para cada uno de estos sistemas, Google proporciona a los desarrolladores un conjunto de estadísticas de solución de problemas que se recopilan de 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 lances tu proyecto, debes monitorear las tendencias de problemas de los dispositivos en el campo de manera agregada y arreglarlas a través de actualizaciones de software. En este codelab, se abordan técnicas que puedes usar para ambos propósitos.
Requisitos previos
- Completa la guía Comienza a usar Matter con un proyecto de Matter en funcionamiento y una configuración del dispositivo.
- Tener un teléfono Android que puedas conectar a tu estación de trabajo (para registros de ADB)
Qué aprenderás
- Cómo usar las herramientas de estadísticas de casa inteligente para supervisar problemas de Matter a gran escala.
- Cómo clasificar errores mediante el acceso a los registros de errores y la recopilación de información
- Cómo acceder a la documentación y los recursos de asistencia de Matter para buscar ayuda
2. Ver estadísticas de Google Home
Supervisar el rendimiento es fundamental para lograr una integración exitosa con el ecosistema de Google Home. Ofrecemos un conjunto de herramientas de supervisión para 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 revisar los paneles de Google Home. Para ello, accede a la consola de Google Cloud y navega a Operaciones > Supervisión > Paneles de control.
Hay varios paneles disponibles para tu proyecto (incluidos otros productos de GCP). Los paneles proporcionados para las casas inteligentes incluyen un prefijo de Analytics de Google Home.
Actualmente, tenemos un panel general que cubre todo el 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 similares a los siguientes:
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 involucradas. Además, con Matter tienes un conjunto de gráficos que rastrean el éxito de la puesta en servicio, así como 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 casas inteligentes. 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 registros de eventos generados en un proyecto. Puedes acceder en la consola de Google Cloud navegando a Operaciones > Registro > Explorador de registros.
Cuando 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 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 comisiones de Matter Primer 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.
Usar Analytics de Google Home
Creamos un conjunto de métricas para que investigues los problemas de las comisiones mediante el seguimiento de los eventos y la comprensión 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 comisión de dispositivos:
En el gráfico de la cantidad de dispositivos, se muestra la cantidad de intentos de comisión por parte de los usuarios en una fecha determinada. La tasa de éxito muestra la tasa de éxito percibido para estos eventos por parte de Google. Cada intento de comisión genera un conjunto de eventos con estados asociados. Cuando ocurre 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" en combinación con "severity>=ERROR" en el campo de consulta.
Un registro de errores de comisión para 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 del 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 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 asignación de dispositivos, es posible que, a veces, debas realizar depuraciones adicionales con los registros generados por el dispositivo móvil que se usó en el proceso de comisión. Para estos casos, necesitas Android Debug Bridge.
Usa 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 puesta en servicio se controla principalmente entre el dispositivo móvil y el dispositivo Matter, es posible usar la herramienta ADB para acceder a los registros generados por la app de Google Home durante la puesta en servicio.
Instala las 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 número de versión desde la terminal con el siguiente comando para verificar ADB:
$ adb -- version
Esto 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, debes habilitar 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 de 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.
- Ejecuta un comando list devices desde la terminal 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
Tu <phone-id> es una cadena alfanumérica que identifica de forma exclusiva tu dispositivo.
- Recuerda el valor de
<phone-id>para usarlo en los próximos pasos.
Recopila información del sistema
A continuación, comprueba la información de la versión de las apps y el sistema de 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 Home y 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 te comuniques con asistencia sobre fallas de comisión, incluye siempre información del sistema en tus tickets de asistencia.
Recopilar registros de errores
A continuación, inicia el proceso de recopilación de registros y, luego, sigue los pasos de la asignación para generar los eventos de errores que deseas depurar.
- Ejecuta el siguiente comando proporcionando tu
<phone-id>, así como un<file-name>donde 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 para la puesta en marcha de tu dispositivo Matter.
- Una vez que llegues al error que deseas depurar, presiona
Control+Cen la ventana de terminal en ejecución para detener el registro.
Tus registros ahora deberían estar almacenados en el archivo de registro <file-name>. Debido a que este proceso registra los registros de cada proceso en ejecución que se realiza en el dispositivo, habrá muchos registros en este archivo. Por eso, siempre debes usar estos registros y buscar las entradas que necesitas.
Analiza los registros de errores
Los procesos de comisión se manejan a través de un subsistema llamado MatterCommissioner dentro de GHA.
- Sigue la estrategia principal que se usa para analizar los errores de comisión y busca errores generados por 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>
Cuando analices el archivo de registro generado por el proceso de depuración de ADB, busca también ciertos patrones. Muchos errores de comisión incluyen el “commissioning failure” cadena en su mensaje de error.
- Busca un mensaje de error de comisión con el siguiente comando:
$ grep "SetupDevice" $phonelog | grep -A 20 "Commissioning failed"
4. Cómo depurar problemas de los controles de dispositivos
Una vez que los usuarios configuran y asignan dispositivos Matter al 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 mediante la IU de la app de Home o las pantallas Google Nest.
Como la especificación de control entre dispositivos finales y Google Hub está mediada por Matter, se espera que tenga menos errores en el control del dispositivo. En cualquier caso, te proporcionamos métricas y registros para que también depures estos tipos de problemas.
Cómo usar métricas
En el panel de integración de Matter, verás varias métricas sobre 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 capturados por Google Nest Hubs en relación con los motivos por los que 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 buscando “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 mensaje de error breve que explica de qué se trata.
5. Cómo depurar otras funciones
Hasta ahora, aprendiste a abordar los problemas de control y puesta en marcha 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 realizar un seguimiento de las actualizaciones OTA
Para hacer un seguimiento de los lanzamientos de actualizaciones inalámbricas (OTA) de los dispositivos Matter que emite 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 inalámbrico.
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 para desarrolladores
Existen tres canales para desarrolladores que se supervisan activamente en Google:
Si bien el mismo equipo supervisa cada uno de estos canales de manera periódica, existen algunas diferencias clave en cuanto a cuándo se debe usar cada uno.
- Stack Overflow: Puedes comunicarte con nosotros y la comunidad de desarrolladores de casas inteligentes si tienes preguntas sobre la implementación o si necesitas orientación. Este canal es ideal para preguntar cómo solucionar problemas o implementar una función determinada.
- 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. La Herramienta de seguimiento de errores es la mejor opción para informar problemas del ecosistema o compartir solicitudes de funciones.
- Foro de desarrolladores: Para obtener orientación de la Atención al cliente oficial de Google y de los expertos de la comunidad, puedes comunicarte con ellos a través del 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 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. Te deseamos un buen momento para compilar 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 paquete de pruebas para probar tu integración con los posibles problemas.
- Una vez que tu integración esté lista para compartir con el mundo, el siguiente paso es obtener la certificación FCGH de tu proyecto. Para ello, puede seguir los pasos que se indican en la página Certificación.