Depura integraciones de Matter

1. Antes de comenzar

Matter ofrece a los usuarios finales una experiencia de control y configuración de dispositivos multiplataforma fluida. Esto es principalmente posible debido 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 abrumadores 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 analizan tres componentes principales de Matter. Para cada uno de estos sistemas, Google proporciona a los desarrolladores un conjunto de estadísticas de solución de problemas recopiladas de teléfonos y concentradores:

Comisión, ejecución y actualización inalámbrica

Como desarrollador, es fundamental que puedas mitigar los problemas que experimentas 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 a través de actualizaciones de software. Este codelab abarca técnicas que puedes usar para ambos propósitos.

Requisitos previos

  • Completa la guía para comenzar a usar Matter con un proyecto de Matter en funcionamiento y la 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 herramientas de estadísticas para una casa inteligente a fin de supervisar problemas de Matter a gran escala.
  • Cómo clasificar errores mediante el acceso a 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

La supervisión del rendimiento es fundamental para una integración exitosa con el ecosistema de Google Home. Brindamos 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.

Accede a las métricas del proyecto

  • El primer paso para acceder a tus datos es verificar los paneles de Google Home. Para ello, accede a Google Cloud Console 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 un prefijo de Google Home Analytics.

Paneles de control de Analytics de Google Home

Actualmente, tenemos un panel general que cubre 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 cumple con las solicitudes.

Cuando abras uno de estos paneles, verás una serie de gráficos similares a los siguientes:

Desgloses por tipo de dispositivo, latencia y tasa de éxito

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 la tasa de éxito para 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 servicio, 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 los datos de métricas de 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 registros de eventos generados en un proyecto. Para acceder a ella en la consola de Google Cloud, navega a Operaciones > Logging > Explorador de registros.

Cuando abras el Explorador de registros, obtendrás una vista similar a la siguiente:

Explorador de registros

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 desees depurar. Hablaremos más sobre esto en las secciones de depuración.

3. Problemas con la comisión de depuración

El primer tipo de métrica que analizaremos se relaciona con los eventos de comisión de Matter. La comisión se refiere 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 el tejido Matter. En la siguiente imagen, se muestran algunos de estos eventos:

Eventos de comisión de Matter

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 de comisión.

Usa Analytics de Google Home

Creamos un conjunto de métricas para que investigues los problemas de comisión mediante el seguimiento de los eventos y para que comprendas 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 puesta en marcha de dispositivos:

Métricas de comisión de dispositivos

El gráfico Recuento de dispositivos muestra la cantidad de intentos de puesta en servicio por parte de los usuarios en una fecha determinada. La tasa de éxito muestra la tasa de éxito percibida para estos eventos en la plataforma. 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 > Logging > Explorador de registros. Para filtrar los errores de la comisión, puedes buscar “clientUpdateLog” junto con “severity>=ERROR” en el campo de búsqueda.

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 el 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 comisión comparte un sessionId.

Usar las métricas de las estadísticas de Google Home te da una idea inicial en qué etapa podría ocurrir el problema. Para encontrar la causa raíz de los errores de puesta en marcha del dispositivo, es posible que, en ocasiones, necesites realizar una depuración adicional con los registros generados por el dispositivo móvil que se usa en el proceso de puesta en marcha. Para ello, necesitas Android Debug Bridge.

Cómo usar Android Debug Bridge (ADB)

Otra forma de solucionar los problemas relacionados con la comisión es usar la herramienta de línea de comandos Android Debug Bridge (ADB). Dado que la asignación se realiza 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 todo el proceso de comisió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 sdkmanager.

Una vez que hayas instalado correctamente las herramientas de la plataforma en tu sistema, verifica ADB verificando el número de versión de la terminal con el siguiente comando:

$ adb -- version

Esto debería mostrar el número de versión de la utilidad de 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.

De esta manera, ADB puede acceder a los registros generados por apps que se ejecutan actualmente en el dispositivo.

Recuperar ID de dispositivo

  1. Ejecuta el servidor ADB con el siguiente comando:
$ adb start-server
  1. Conecta tu teléfono a la computadora que ejecuta el servidor ADB.

Es posible que recibas en el teléfono un mensaje de advertencia sobre la depuración por USB que te pregunte si quieres permitir que la computadora acceda a la información del teléfono:

Mensaje de depuración por USB

  1. Si recibes este mensaje de advertencia, haz clic en Permitir.
  2. Ejecuta el siguiente comando list devices desde la terminal para ver si la computadora puede acceder al teléfono mediante ADB:
$ adb devices

Se debería obtener una respuesta similar a la siguiente:

List of devices attached
<phone-id>    device

El <phone-id> es una cadena alfanumérica que identifica de manera única tu dispositivo.

  1. Recuerda el valor <phone-id> para usarlo en los próximos pasos.

Cómo recopilar información del sistema

A continuación, comprueba la información de la versión de las apps y del 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 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 consultar 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 muestran sean compatibles con nuestro ecosistema. Cuando te comuniques para obtener asistencia con respecto a las fallas de la comisión, incluye siempre la 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 sigue los pasos de asignación para generar los eventos de error que deseas depurar.

  1. Ejecuta el siguiente comando proporcionando tu <phone-id> y un <file-name> donde se guardarán los registros en tu computadora (p. ej., debug_file.txt).
$ adb -s <phone-id> logcat > <file-name>

Esta acción inicia de inmediato el proceso de registro. Si aún no existe, se crea un archivo con el nombre proporcionado, y los registros del teléfono se agregan al archivo después de cada evento.

Sigue los pasos de puesta en marcha de tu dispositivo Matter.

  1. Cuando obtengas el error que deseas depurar, presiona Control+C en 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 rastreado en el dispositivo, habrá muchos registros en este archivo. Es por eso que siempre debes usar estos registros y buscar las entradas que necesitas.

Analiza registros de errores

Los procesos de comisión se manejan a través de un subsistema llamado MatterCommissioner dentro de GHA.

  1. Sigue la estrategia principal que se usa cuando se analizan los errores de puesta en servicio para 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 comisión.

  1. Si tu dispositivo Matter usa Thread, también puedes buscar errores generados por el subsistema Thread con el siguiente comando:
$ grep -E "(ThreadNetworkManager|BorderAgentScannerImpl|ThreadBrSynchronizer)" <file-name>

Mientras analices el archivo de registro generado por el proceso de depuración ADB, busca también ciertos patrones. Muchos errores de comisión incluyen la string "commissioning failure" en el mensaje de error.

  1. Busca un mensaje de error de comisión 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 ponen en marcha 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 la sala de estar") o mediante la IU en la app de Home o en las pantallas Google Nest.

Como la especificación de control entre los dispositivos finales y los concentradores de Google está mediada por Matter, se espera que haya menos errores en el control del dispositivo. Sin embargo, también proporcionamos métricas y registros para que depure estos tipos de problemas.

Cómo usar las métricas

En el panel de integración de Matter, verás varias métricas sobre el control de dispositivos. Hay tres gráficos fundamentales para evaluar el rendimiento de los dispositivos en el terreno:

Gráficos de desglose de éxito, latencia y errores

Durante los problemas de control, es común ver tendencias descendientes 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 los Google Nest Hub en relación con 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 buscando "executionLog".

Los registros de errores de 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 el statusType. Muchos errores de control también incluyen un externalDebugString, un mensaje de error corto que explica de qué se trata el error.

5. Depura otras funciones

Hasta ahora, aprendiste a manejar problemas de puesta en servicio y control de dispositivos de Matter. Además, hay otras funciones en el ecosistema con las que puedes usar nuestras técnicas recomendadas para garantizar una buena integración de calidad.

Realiza un seguimiento de las actualizaciones inalámbricas

Para hacer un seguimiento de las actualizaciones inalámbricas (OTA) de los 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:

Desgloses de software y hardware

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. Solicita asistencia

Google proporciona herramientas y documentación para que depuren los problemas de Matter, pero, como el ecosistema de Matter es nuevo, habrá problemas que estos recursos no abordarán. En estos casos, puedes comunicarte con nosotros o con la comunidad para obtener asistencia.

Visitar los canales para desarrolladores

Existen tres canales para desarrolladores que se supervisan activamente en Google:

Stack Overflow, Herramienta de seguimiento de errores, Foro de desarrolladores

Si bien el mismo equipo supervisa cada uno de estos canales de manera periódica, existen algunas diferencias clave respecto de cuándo usar cuál usar.

  • Stack Overflow: Puedes comunicarte con nosotros y con 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 seguimiento de problemas que ejecuta Google, en el que los públicos externos pueden informar errores sobre 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 en el ecosistema o compartir solicitudes de funciones.
  • Foro de desarrolladores: Para buscar orientación del equipo de asistencia oficial de Google y los expertos de la comunidad, puedes comunicarte 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 de desarrolladores para hacer preguntas, también lanzamos un boletín informativo trimestral en el que se destacan funciones nuevas y se brindan 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

Google Home

¡Felicitaciones! Aprendiste correctamente a depurar integraciones de Matter con las herramientas y técnicas que recomendamos. Te deseamos un buen momento para compilar las integraciones de Matter con Google Home.

Próximos pasos

Prueba los siguientes ejercicios y explora recursos adicionales:

  • Además de usar Analytics para solucionar problemas, también puedes usar el paquete de pruebas para probar tu integración y detectar cualquier problema potencial.
  • 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, sigue los pasos que se indican en la página Certificación.